Skip to content

0011: The agent daemon owns key material; transports and the relay

  • Status: accepted
  • Date: 2026-09-22

Context

Secrets must be usable on machines that do not hold the user's private key: remote dev boxes, devcontainers, CI runners with a human on call, and servers being restarted over SSH. The private key must never move and no component may expose a "decrypt anything" oracle.

Decision

  • A long-running agent daemon on the trusted device holds unlocked identities (ADR 0009) for a session TTL. The CLI, TUI and GUI never touch key material; they ask the daemon. The daemon exposes a small, enumerated request API (see the agent-daemon spec): principally "unwrap the KEK for this collection and epoch" and "resolve this one reference", each scoped to a named session. No request returns private key material.
  • Every request carries the entry path or collection scope, the requesting host, and the session, so approval prompts are meaningful. Approvals are once, or for a session with a TTL, and are scoped to a collection or path prefix. Requests are logged locally in an append-only audit file.
  • Transports, in order of preference:
    1. Local Unix socket (mode 0600) or Windows named pipe. Default.
    2. SSH remote socket forwarding of the local socket. No accounts, no new network surface; the documented free path for remote work.
    3. Hosted relay. Both the daemon and the remote CLI connect outbound over WebSocket to the relay. The two ends run a Noise handshake with their own vaultfold device keys; the relay forwards opaque bytes and learns only that a request happened, never its content. Pairing uses the device-code pattern: the remote prints a vaultfold://unlock/<request id> link and a short code; whichever device claims the request shows the same code, the host, the session and the requested scope, and the human confirms the code matches before approving. URLs carry only a request id, never key material, because custom URL schemes can be registered by any application. A typed-code fallback covers terminals that cannot open links.
    4. Tailscale as bring-your-own-network: the daemon binds to the tailnet interface only and identifies peers through the local tailscaled LocalAPI whois. No embedded tsnet node.
    5. Public listeners: never.
  • Replay protection (nonce and counter), channel binding to the approved request, and rate limiting apply on every transport.
  • On the remote side, the session binding is per shell session: keyed by controlling tty for interactive use, by the MCP server instance and project for agent harnesses (ADR 0012), never stored in a shared home directory. Two people on one shared OS account therefore get two sessions routed to two devices.
  • Unattended processes (daemons, CI) never use a forwarded human identity; they get machine identities (ADR 0008) scoped to what they need.
  • Approvals may be answered from any of the member's devices, including a phone woken by a push notification from the hosted service.

Consequences

  • A compromised remote machine can request anything the human would approve; scoped, short-lived, explicit approvals are the mitigation and must be the default.
  • The relay is a hosted component with push credentials; it can be self hosted but the mobile approval path depends on APNs/FCM.
  • The relay learns which device keys connect and when, never which vault, entry, scope or value (see threat-model.md).

Alternatives considered

  • gpg-agent style key forwarding. Rejected: exposes a general signing and decryption oracle.
  • Embedding Tailscale (tsnet) in every client on a per-user tailnet. Rejected: requires operating a coordination server and relays, which is a larger trust and operations burden than a purpose-built relay.
  • Cloudflare quick tunnels (as nfi-tools does). Rejected: a public URL protected only by a token.