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 runprocess 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 --detachedin a new session, appends its output to<runtime>/agent.logand waits up to 5 seconds for it to answer.VAULTFOLD_NO_AGENT=1,agent.autostart = falseinprofile.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, hostedinitand adding a hosted vault always unlock in-process (the daemon serves registered vaults only), as doeskey 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_IDENTITYnames an external identity file, or-for file descriptor 3; refused with a terminal): sessions aremachine, no prompt is ever raised, and a request that would need one is refused. Vault commands still refuseVAULTFOLD_IDENTITYthemselves, 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.sockin a 0700 directory owned by the user and not a symlink, created underumask(0177)and then chmod 0600. When the path would exceedsun_path(103 bytes on darwin, 107 on Linux) the endpoint is<$TMPDIR or /tmp>/vaultfold-<uid>/agent.sockwith the same checks. - Windows: a named pipe
\\.\pipe\vaultfold-agent-<user SID>created with go-winio and the protected DACLD: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_PEERCREDand, from kernel 6.5,SO_PEERPIDFD; macOSLOCAL_PEERCRED,LOCAL_PEERPIDand theLOCAL_PEERTOKENaudit 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_SOCKoverrides 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 byagent start.- Remote transports (SSH forwarding as a recognised source, the relay,
Tailscale) are not built; the daemon has a seam for them and
pairanswersunsupported.
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 (clientorbrowser-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 answersunknown-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 runvaultfold 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-pendingand an approval id thatpendingcan 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 lockor the daemon stopping. These defaults are inprofile.toml's[agent]table. System idle counts from the later of the last input event and the most recent unlock of any vault (openspec changeidle-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.keybeside 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
PATHor 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 stopafter 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
CreateNamedPipeon Windows. Rejected for go-winio, the named-pipe layer of containerd and Docker, which takes an SDDL string and integrates withnet.Listener.