Skip to content

0028: The agent daemon process, local transport and wire protocol

  • Status: accepted
  • Date: 2026-10-03
  • Supersedes: 0020 (in-process unlock is now only the fallback when no daemon can be used)

Context

ADR 0011 makes a long-running agent daemon the only long-lived holder of unlocked key material, and ADR 0012 makes it the enforcement point for AI agent sessions. Until add-agent-daemon the CLI unlocked a passphrase identity in-process for every command (ADR 0020). Building the daemon needed answers that ADR 0011 left open: which process is the daemon, how clients reach it on each OS, how a client is identified, and what goes on the wire. openspec/changes/add-agent-daemon/design.md records every decision taken while building it, group by group; this record lifts out the durable ones.

Decision

One daemon, in the CLI binary

  • The daemon is the vaultfold agent run process of the CLI binary, one per user per machine, holding keys for every registered vault. It is not part of the desktop app: the CLI must work on servers and in terminals with no desktop app, one binary means one caller identity to trust by default and one code path for key handling, and a GUI that owned keys would have to stay running for every terminal use. The desktop app (a later change) is a client that can register as the preferred approval endpoint (prompter-register, accepted only from a project-signed caller) and take over starting the daemon at login.
  • The CLI starts the daemon on demand: a vault command that finds no daemon runs <exe> agent run --detached in a new session, appends its output to <runtime>/agent.log and waits up to 5 seconds for it to answer. VAULTFOLD_NO_AGENT=1, agent.autostart = false in profile.toml, VAULTFOLD_IDENTITY, or (outside macOS and Windows) no user runtime directory turn auto-start off. A daemon that already answers is used whatever the environment says; while one answers, commands on registered vaults never unlock in-process.
  • Without a daemon the CLI falls back to ADR 0020's single-command in-process unlock, after a one-line notice once per terminal. init, hosted init and adding a hosted vault always unlock in-process (the daemon serves registered vaults only), as does key rotate (the supersession record is signed by both keys, which no daemon verb offers). In a session the CLI classifies as an agent session, in-process unlock of an OS keychain identity is refused (exit 4), because a keychain that does not prompt would otherwise remove the human gate.
  • Single instance: <runtime>/agent.lock (the vault lock primitive, so a killed daemon never leaves an effective lock) and <runtime>/agent.pid. A stale socket is removed only by the lock holder.
  • Machine identity mode exists in the daemon (VAULTFOLD_IDENTITY names an external identity file, or - for file descriptor 3; refused with a terminal): sessions are machine, no prompt is ever raised, and a request that would need one is refused. Vault commands still refuse VAULTFOLD_IDENTITY themselves, so the CLI side of machine identities is a later change.
  • OS login-launch registration (launchd, systemd user units, Task Scheduler) is not done by the CLI; it belongs to the desktop app.

Local transport

  • Unix (Linux, macOS): a socket at <runtime>/agent.sock in a 0700 directory owned by the user and not a symlink, created under umask(0177) and then chmod 0600. When the path would exceed sun_path (103 bytes on darwin, 107 on Linux) the endpoint is <$TMPDIR or /tmp>/vaultfold-<uid>/agent.sock with the same checks.
  • Windows: a named pipe \\.\pipe\vaultfold-agent-<user SID> created with go-winio and the protected DACL D:P(A;;GA;;;<SID>)(A;;GA;;;SY) (the user and SYSTEM only), first instance exclusive so a squatter makes the daemon fail loudly, remote clients rejected.
  • Every connection's peer credentials are read from the kernel (Linux SO_PEERCRED and, from kernel 6.5, SO_PEERPIDFD; macOS LOCAL_PEERCRED, LOCAL_PEERPID and the LOCAL_PEERTOKEN audit token; Windows the client pid and its token's user SID). A peer of another user is refused and audited, whatever the endpoint's permissions say.
  • VAULTFOLD_AGENT_SOCK overrides discovery (an absolute path, or a \\.\pipe\ name); an explicit endpoint that does not answer is an error (exit 3) and no daemon is started for it, except by agent start.
  • Remote transports (SSH forwarding as a recognised source, the relay, Tailscale) are not built; the daemon has a seam for them and pair answers unsupported.

Caller verification

The daemon identifies the connecting process itself and never trusts the client's word: on Linux the image opened through /proc/<pid>/exe and its SHA-256, with the start time checked before and after; on macOS the kernel's code directory hash (cdhash) read against the connection's audit token, plus, in a cgo build, an Apple-anchored signer; on Windows the image path, opened without write or delete sharing and re-checked against the process, its hash and an Authenticode signer. Default trust is the project's signing identity or the daemon's own executable; any other caller is refused (caller-unverified) until a human approves it on first contact, and the approval is stored in data/agent-trust.bin, sealed under a key derived from the machine key. No project signing identity is pinned yet (it waits for the Developer ID and Authenticode certificates), so today default trust is the daemon's own executable only. The per-OS rules and their residual limits are in docs/threat-model.md.

Wire protocol (core/agentproto)

  • Framing: a 4-byte big-endian length, then a payload of at most 1 MiB. A fixed prefix lets a reader refuse a huge frame before allocating, and matches browser native messaging's framing.
  • Encoding: canonical CBOR through core/canon, integer-keyed maps, strict decoding of the envelope (unknown keys, floats, tags and non-canonical input refused). Envelope keys: 1 version, 2 request id, 3 kind (1 request, 2 response, 3 notification), 4 verb, 5 session id (16 bytes, omitted when zero), 6 args, 7 result, 8 error ({1 code, 2 message, 3 approval id, 4 versions}). Absent keys are omitted, never null. Unknown keys inside args, results and notification bodies are ignored so older daemons interoperate.
  • Versioning: the first frame is hello, at envelope version 1, carrying the versions the client speaks, its role (client or browser-host) and its build; the daemon picks the highest common version and every later frame carries it. A change to the envelope, the framing or the meaning of a verb bumps the version; a new verb, argument or optional result key does not (an old daemon answers unknown-verb). Version 1 is the only version. A CLI that shares no version with a running daemon never replaces it: it exits 3 telling the user to run vaultfold agent stop, which stops such a daemon by signal while it holds the lock.
  • Requests are independent and answered in completion order. A request that needs a human answers at once with approval-pending and an approval id that pending can poll; a notification announces the outcome. Nothing blocks on a human.
  • One protocol only: the daemon reads only these frames. The browser extension's native host (add-browser-extension) translates its JSON native messaging into this protocol with role browser-host.
  • Error codes are stable strings that the CLI maps to its exit codes: policy refusals to 2, locked, backend-unavailable, touch-cancelled, approval-pending and rate-limited to 3.
  • Secret-bearing answers (resolve, unwrap-kek) are encoded into buffers the call owns and zeroed after the write; key material in the daemon lives in locked, zeroed-on-release memory (secmem).

Consequences

  • The per-command passphrase prompt is gone wherever a daemon runs: a vault is unlocked once and stays unlocked until its TTL (8 hours by default), 60 minutes without a request, 15 minutes of system idle, a screen lock, sleep, vaultfold agent lock or the daemon stopping. These defaults are in profile.toml's [agent] table. System idle counts from the later of the last input event and the most recent unlock of any vault (openspec change idle-lock-after-unlock, design.md decisions 1-7).
  • The agent-session policy of ADR 0012 is enforced by a separate process that holds the keys, not by the CLI's own check (ADR 0029).
  • The CLI and the daemon must agree on the machine key: both use one platform provider (Secure Enclave, DPAPI or Secret Service with a file fallback). A binary from before the daemon, run after the machine key migrated into the OS store, creates a machine.key beside it, which is then reported as a conflict until one is moved aside.
  • A daemon started from an agent inherits the agent's environment; the approval dialogs therefore never use PATH or the inherited environment to find their tools (ADR 0033).
  • Upgrading the binary while an old daemon runs keeps the old daemon in use until it is stopped; with a protocol version in common it keeps serving. Users run vaultfold agent stop after upgrading.
  • Windows paths (the pipe DACL check against a real pipe, client process lookup, the terminal key) are cross-compiled and vetted, but have not run on a Windows host while this change was built.

Alternatives considered

  • The desktop app as the daemon. Rejected: servers and terminals without the app would have no daemon, and the app would have to stay running.
  • JSON lines or length-less CBOR sequences. Rejected: JSON has number and escape ambiguity and a second encoder; a CBOR sequence without a length cannot be refused before reading it.
  • Varint lengths. Rejected: a fixed prefix is trivially checked and matches native messaging.
  • Accepting a second encoding from the native host. Rejected: one protocol keeps one parser on the trusted side.
  • Trusting client-reported identity or relying on socket permissions alone. Rejected: any same-user process can connect to the socket; the daemon must identify the executable itself.
  • Hand-rolled CreateNamedPipe on Windows. Rejected for go-winio, the named-pipe layer of containerd and Docker, which takes an SDDL string and integrates with net.Listener.