albedo docs

Daemon attachment and local startup

Albedo's API connection and its local process launcher have separate jobs. A client can attach to a supplied endpoint without reading local installation files, starting a process, or replacing one.

On this page: Connection flow, Daemon service, Authentication and defaults, Build identity, Client development, and Implementation and verification.

The localdaemon package owns discovery and launch. The API adapter owns attachment and compatibility checks. HTTP API behavior defines the public operations.

Connection flow

  1. Discover reads the local record and probes its authenticated /server resource. 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 when the candidate build may differ from the running one: the content digests decide when both sides hashed their code trees, the build labels otherwise, and an unprovable comparison keeps the offer. Proven sameness attaches without asking. Keeping the daemon 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 starting one. An absent or stale daemon needs no shutdown. Discovery failures are reported. Its Python kernels keep running for the next daemon to attach to. --kernels ends them as well, after each session saves its variables.

SIGTERM to the PID in daemon.json runs the same shutdown as albedo daemon --stop: it interrupts turns and cells, stops shell commands, and keeps Python kernels for reconnection. Repeated SIGTERMs do not restart shutdown. The daemon bounds the drain and has a fallback VM stop. Those deadlines do not guarantee that every external effect has stopped. Early in startup, SIGTERM can bypass the drain or be lost. Service managers that also kill the kernel processes prevent reconnection.

A protocol 2 daemon has no /server resource. When that route returns 404 and daemon.json reports a different protocol, discovery reports incompatibility. It preserves the record and does not authorize attachment, shutdown, or launch. Stop that daemon with its matching client, then launch the protocol 4 client. The current client does not call older API routes.

Daemon service

External declarations

Home-manager and other declaration owners can supply a supported native service. For the default home, declarative services use albedo.service on Linux or systems.albedo.daemon on macOS. CLI-installed services retain their per-home names. If both are registered, clients may attach but refuse service mutations until the registrations are reconciled. Custom homes retain their per-home names. For the two stable names Albedo reads the loaded registration, not the service file. It starts a loaded idle registration with supported command arguments, the matching daemon home, and supported lifecycle settings. For a shell wrapper, Albedo recognizes the argument layout without interpreting the shell command. The declaration owner is responsible for that command. It stops that registration's authenticated daemon over HTTP. A file must still exist under the stable name, and Albedo checks only that it exists. Albedo never installs, rewrites, reloads, enables, disables, bootstraps, or uninstalls an external declaration. Reconcile or remove it through its owner. See Manage albedo with home-manager for configuration and migration.

On macOS, file edits do not change the loaded registration until its owner activates them. On Linux a changed referenced unit reports NeedDaemonReload=yes, and Albedo refuses to start it until the owner reloads. Albedo does not detect a declaration replaced after its last observation. The manager starts whatever it holds. Unsupported service control still permits compatible authenticated attachment.

Linux services installed by the CLI

On Linux, the first albedo daemon install creates, starts and enables a systemd user service. Running it again refreshes the definition without restarting the daemon or starting a stopped service. Installation requires a packaged daemon selected by ALBEDO_DAEMON. Checkout and AppImage launchers are unsupported. Stop a running standalone daemon before first installation.

Clients start an installed service through systemd. albedo daemon --stop uses the existing HTTP shutdown and leaves the service stopped until a client or the user manager starts it. Add --kernels to try saving variables before ending the kernels. albedo daemon uninstall removes the service and keeps kernels for reconnection. Use albedo daemon status to inspect it, or status --json for structured output.

The unit uses KillMode=process so daemon stops leave kernels alive, and Restart=on-failure so crashes restart. Two refusals do not restart, through RestartPreventExitStatus=75 78. Exit 75 means storage is held elsewhere. Exit 78 means a newer Albedo upgraded the home past what this build reads (see downgrades). The CLI reports either refusal with what the daemon logged, and does not retry it. A unit installed before exit 78 existed exempts only 75. It stays owned, and albedo daemon install rewrites it. Kernels end when the user manager exits or the host reboots. A managed build mismatch prints a notice instead of offering a restart, because the CLI cannot establish which build the service would start.

The CLI can attach to a compatible daemon beside an edited or unsupported unit, but refuses lifecycle changes. Fedora's unmodified global timeout-abort drop-in is supported. Other drop-ins are refused. On a systemd host, an unreachable user manager also prevents launch and shutdown. A host with no service file and no registration keeps standalone launch. The verification sources distinguish policy tests from native-manager checks.

A failed or cancelled install can leave a running service or enablement links. Inspect its status before changing anything by hand. Before trying start or enable, the installer may restore its unchanged file if the original process is unchanged and no job appeared. After either attempt, it leaves configuration in place and reports what it could observe.

macOS agents installed by the CLI

On macOS, install creates one LaunchAgent per Albedo home. It requires an exec-only packaged or sealed launcher and a captured PATH. Albedo checks the loaded launchd configuration and refuses service changes when it cannot safely interpret the output. Compatible attachment still works, and a home with no service file or registration runs standalone. The agent starts at load and restarts after a failed exit. Rapid failures are throttled, with no start limit. launchd's KeepAlive cannot exempt an exit status, so it keeps relaunching a daemon that refused its home with exit 75 or 78. The CLI reports the refusal with what the daemon logged instead of waiting on the retries. After exit 78, update Albedo or remove the agent with albedo daemon uninstall to stop them. Clients bootstrap an owned agent that is not loaded, or kickstart a loaded idle one. They never replace a loaded registration.

daemon --stop sends the authenticated shutdown to that one daemon instance. It never asks launchd to end the service. The agent stays loaded and idle, and kernels survive for the next start. --kernels ends the kernels too, and it needs a running daemon to ask. A daemon that keeps failing at startup stays in a retry loop. Status reports it as retrying, and stop cannot end it because no daemon is ready to ask. For a CLI-owned agent, albedo daemon uninstall removes the registration. For a home-manager agent, disable services.albedo.enable and activate the configuration. The agent lives in the GUI user domain. Without a GUI session, a home that has a service file refuses service changes. A home without one still runs standalone.

Running install again on a loaded agent rewrites only its file. There is no reload step. The loaded registration keeps its old definition, a running daemon keeps running, and an idle agent stays stopped. For a CLI-owned agent, attach still works when the file and the loaded definition differ, but start refuses. Run uninstall, then install, to reconcile a supported difference. An edited file, a different loaded path, or a loaded definition outside the supported shape refuses every service change to a CLI-owned agent. Inspect those by hand instead. For an external declaration a failed activation can leave the old registration loaded, and Albedo starts what launchd holds. A disabled override blocks install and start, and Albedo never changes it. Status prints the launchctl enable command to run by hand. Uninstall still works while disabled and leaves the override in place.

uninstall asks a managed daemon to stop first, so kernels normally survive. If that shutdown fails, the uninstall ends there and forces nothing down. Otherwise it removes the registration with one label-level bootout at this home's label. A replacement that arrives after the last check can be ended by that bootout, work in progress included. The checks keep every replacement they can see, but the last check and the removal are not atomic. A failed or cancelled change leaves the service file in place. Albedo does not roll it back by deleting state. The loaded-registration checks are not a guarantee against changes the manager does not report. Native-manager checks are platform-specific, as described under verification.

Authentication and defaults

The daemon owns its home directory and token: by default it uses ~/.albedo and generates a random token. It publishes daemon.json atomically with mode 0600 inside the private home directory. The record contains the endpoint, PID, protocol, token, and optional build identity: an ALBEDO_BUILD label plus a content build identity. It is a local discovery file, not an API compatibility contract. Discovery checks the recorded PID against the authenticated /server response when the daemon reports one.

The shared apps/albedo/priv/bin/albedo-daemon bootstrap installs VM defaults before Erlang starts. Source, test snapshots, and packaged startup use that bootstrap. Deliberate ALBEDO_HOME, ALBEDO_TOKEN, ALBEDO_BUILD, and ERL_FLAGS overrides remain available. Operator VM flags follow the defaults and take precedence. The local launcher filters provider overrides so saved daemon configuration remains the source of provider settings. From a source checkout the bootstrap first builds through apps/albedo/priv/bin/albedo-build, which rebuilds albedo's application when it still holds a module that has since moved into a workspace package.

The bootstrap also starts the daemon at a lower CPU priority, raising its niceness by ALBEDO_DAEMON_NICE (default 5; 0 turns it off), so a busy turn yields to games and other foreground work. It exports ALBEDO_DAEMON_NICE=0 to the daemon, so kernels, jobs, and any daemon they launch inherit the lowered priority without lowering it again. run() jobs add their own niceness on top.

Cancellation ends discovery, lock acquisition, startup waits, shutdown waits, and the restart prompt. It does not kill a detached daemon that has already started. A client disconnect cannot stop a daemon shared by other clients.

Build identity

build_identity owns the digest recipe, shared with the CLI candidate reader. Both hash compiled runtime output, not source files. A package edit becomes visible after rebuild.

The output is the directory containing the albedo application and its sibling applications. Discovery selects every immediate child with an ebin directory, matching the shipment and snapshot launchers' */ebin code paths. This includes workspace packages, extensions, and third-party dependencies. Development output also includes compiled test applications. OTP's installed runtime outside this output and arbitrary extra code paths supplied through ERL_FLAGS are outside this identity. The ALBEDO_BUILD label remains available for launcher identity.

Each application's ebin and optional priv trees contribute every regular file. This includes application metadata, Python files, native helpers, and other assets. Symlinks are followed, including directory links and external helper targets, but their logical relative paths are hashed. Paths use /, start with the output application name, and sort by UTF-8 bytes. SHA-256 consumes each path's bytes followed immediately by that file's bytes, in that order, without separators, timestamps, permissions, or absolute paths. The shared fixtures pin this recipe in Go and Gleam with package changes, additions, deletions, and linked helper assets.

Missing optional roots contribute nothing. Entries without an ebin directory are not applications. An absent albedo ebin, empty application discovery, unreadable path or file, or broken link within a tree returns an unknown identity, never a digest of a readable subset. Special files are ignored. Traversal fails beyond 256 directory levels, which also bounds directory-link cycles. Builders must provide readable, stable trees without cycles while hashing.

Builders write .build-digest-v2 beside albedo's ebin after all application contents and helper fixups are final. The seal contains exactly 64 lowercase hexadecimal digits and a newline. Readers ignore old .build-digest files and malformed seals, then hash the output. A valid seal is trusted builder output, not authentication or a check for later tampering. Never retain a seal or extension-cache sidecars when changing a sealed tree. Source albedo-build removes them before compiling. seal_build removes old sidecars, calculates the application digest once, writes the extension cache with that key, and publishes the seal last. Sidecars are outside ebin and priv and do not hash themselves. Nix seals after fixup, release packaging after helper installation and Python bytecode compilation, and test snapshots after copying all applications.

The daemon captures its identity once before moving code paths into code-cache, including an unknown identity if hashing fails. It keeps that boot identity for its lifetime. Standbys accept only the versioned seal and retain their captured identity through handover. The CLI uses the same seal validation and recipe. Older running daemons still report their old root-only digest, so an updated CLI sees a difference and uses the existing restart confirmation. This does not change service ownership, ACP attachment, nonterminal attachment, or restart recovery. Restart interrupts active work and preserves saved sessions through the existing recovery flow.

Client development

Use Attach(ctx, snapshot, rediscovery) for a validated API connection. Supply no rediscovery 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 before installing it. It does not know the client's home directory or executable.

Attachment requires protocol 4 and the durable_inputs, session_replay, collection_invalidation, and tool_progress capabilities. session_replay requires version 2. The other required capabilities use version 1. Optional features check their own capabilities. Authentication, malformed server responses, and capability lookup failures propagate to callers.

Implementation and verification

These sources define the behavior described above:

BoundaryImplementation and evidence
Discovery, launcher lock, approved replacementlocaldaemon/lifecycle.go, lifecycle_test.go, and startup_test.go.
Compatibility and attachmentdaemon/server.go and server_test.go.
Native service classification and safe controllocaldaemon/service.go and service_test.go.
Declarative versus CLI-owned registrationsloginservice/daemon_selection.go and daemon_selection_test.go.
launchd parsing and mutation policydaemon_launchd.go, its parser tests, and launchd policy tests.
Real CLI lifecycle workflows against controlled service managersdaemon_service_test.go and daemon_service_darwin_test.go.

Controlled-manager tests establish Albedo's policy under their supplied observations. They do not prove that every systemd or macOS release produces those observations.

The optional native procedures are service_linux.py and service_darwin.py. Their module instructions describe prerequisites and private test homes. They exercise installation, shutdown, kernel survival, and service removal against the host's real manager. A result applies to the tested host and manager version. No universal version-compatibility guarantee follows from it.

For declarative activation, see home-manager verification. For client changes, follow Change the HTTP API and Client API ownership.

Previous remote, colab & ui Next home-manager