docs(daemon): explain attachment and local startup
Describe the restart choice, daemon-owned defaults, and the connection contract for future clients.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990# Daemon attachment and local startup
Albedo's API connection and its local process launcher have separate jobs. Aclient can attach to a supplied endpoint without reading local installationfiles, starting a process, or replacing one.
## Before
The CLI's connection helper read `daemon.json`, checked health, compared therunning build with the bundled executable, and could start or replace the daemon.Many discovery failures looked like absence. The launcher also supplied thetoken and VM defaults, so starting the daemon independently behaved differently.
## After
1. `Discover` reads the local record and probes its authenticated health endpoint. It reports absence, a proven stale record, or a running daemon. Invalid records, authentication failures, unreachable endpoints, and unhealthy daemons return actionable errors. A failed health check does not authorize another launch.2. `Attach` validates the protocol and required capabilities, then returns an API connection. Build identity is update information. A different build with the required API remains usable.3. The ordinary interactive CLI offers to restart a running daemon once per invocation. Keeping it is the default. The prompt warns that restarting interrupts active work across sessions. Scripts keep a compatible daemon and report incompatibility instead of replacing it.4. `Launch` starts a local daemon only under the application's policy. Concurrent launchers coordinate through a persistent advisory `launcher.lock`; the daemon's storage lock remains the authority for home ownership.5. `Upgrade` requires the exact snapshot approved by the caller. It validates the replacement executable before stopping anything, rechecks the approved target, drains the supported daemon, and launches its replacement. If the target changed, the caller must obtain fresh approval. Unknown protocols cannot authorize shutdown.
`albedo daemon --stop` inspects the existing daemon without prompting or startingone. An absent or stale daemon needs no shutdown. Discovery failures are reported.
## Authentication and defaults
Bearer authentication remains the same. The daemon owns its home directory andtoken: by default it uses `~/.albedo` and generates a random token. It publishes`daemon.json` atomically with mode `0600` inside the private home directory. Therecord contains the endpoint, PID, protocol, token, and optional build identity.It is a local discovery file, not an API compatibility contract.
The shared `priv/bin/albedo-daemon` bootstrap installs VM defaults before Erlangstarts. Source, test snapshots, and packaged startup use that bootstrap. Deliberate`ALBEDO_HOME`, `ALBEDO_TOKEN`, `ALBEDO_BUILD`, and `ERL_FLAGS` overrides remainavailable; operator VM flags follow the defaults and take precedence. The locallauncher filters provider overrides so saved daemon configuration remains thesource of provider settings.
Cancellation ends discovery, lock acquisition, startup waits, shutdown waits,and the restart prompt. It does not kill a detached daemon that has alreadystarted. A client disconnect cannot stop a daemon shared by other clients.
## Client development
Use `Attach(ctx, snapshot, rediscovery)` for a validated API connection. Supply norediscovery callback when the endpoint is fixed. A local client can supply`Rediscover`, which looks for a verified replacement without launching one.API recovery uses the supplied callback and validates the new endpoint beforeinstalling it. It does not know the client's home directory or executable.
Attachment currently requires protocol 2 and the `operation_receipts`,`session_stream_generation`, and `agents_stream_overflow` capabilities. Optionalfeatures check their own capabilities. Authentication, malformed health, andcapability lookup failures propagate to callers.
## Implementation ownership and verification
The API agent owns connection extraction, health validation, explicit recovery,and controlled transport tests. The launcher agent owns local discovery,launch/upgrade coordination, daemon defaults, bootstrap, and packaging. Thevalidation agent owns isolated real-daemon lifecycle scenarios. The lead ownsCLI policy, confirmation, integration, documentation, and final review. Sharedfiles have one writer, and daemon builds run serially.
Correctness tests cover independent startup and startup parity, protected records,operator overrides, compatible different builds, attachment failures withoutprocess changes, canceled waits, concurrent starters, interactive keep/restart,approval races, and upgrade during active sessions. Transport tests cover healthvalidation and recovery boundaries that the real daemon cannot intentionallyviolate. No obsolete wire-format readers or compatibility fixtures are retained.
After focused tests, verification runs Go race tests, Gleam checks, Erlangcompilation with warnings treated as errors, Go vet, and `./test.sh`. Cross-reviewchecks ownership boundaries, cancellation and resource cleanup, error handling,unnecessary forwarding helpers, and tests that only mirror implementation.1234567# OverviewAlbedo is an agentic coding harness that can act on your device and soon able to manage sessions on other devices with agents that can act remotely on different machines or within containers. Our hope is that it being built on BEAM allows it to maintain low memory usage while running many concurrent agents and subagents across devices.
Albedo is daemonized with the CLI and (future) WebUI being clients of this daemon. This ensures the agents can be programatically created, controlled, and even stopped all while still providing an experience similar to other harnesses like Claude Code and Codex. Albedo provides a Python REPL for the agents to use as a scratchpad and data manipulation allowing them to experiment, reason, and play with code before actually writing it down. This is similar to what other harnesses call CodeMode and is based on [prime-agent's](https://github.com/PrimeIntellect-ai/prime-agent/)'s Python REPL and design.
[Daemon attachment and local startup](daemon-lifecycle.md) explains how clientsdiscover, attach to, start, and explicitly restart a daemon.