cozylabs
early access download

// docs

vault & broker

The vault and the broker exist to resolve a tension: agents need to act on infrastructure, and infrastructure credentials are exactly the thing you’d never hand an LLM-driven process. The answer is structural — the agent files a request; the broker, running operator-side, resolves the secret and does the work; only the non-secret result comes back.

the vault: metadata here, secrets there

A credential is a first-class typed secret — password · ssh_key · tls_cert · api_token. Its name, type, and flags live in Postgres; its secret fields live only in OpenBao KV-v2, written on create and never returned by any list or get surface (SO-1).

Around credentials, two pure-metadata shapes:

  • a target — where a credential gets used: alias, host:port, kind (ssh / http);
  • a pairing — the explicit grant “this agent may use this credential against this target”, with credential-type ↔ target-kind compatibility enforced at creation.

All of it is managed from the dashboard behind manage_stores + management proof — humans only.

the broker: an asymmetric courier

The broker is an operator-side daemon watching the collaboration’s encrypted stream. Each tick it folds the board, finds open tasks carrying broker markers ([[broker-target]] naming an alias, optionally [[broker-cmd]] or transfer markers), claims them, and fulfils:

agent files task ──▶ broker claims ──▶ vault read (collabId, credentialId)
                                          │
                            policy gate · run via SSH/HTTP · redact
                                          │
agent reads result ◀── progress note ◀────┘

The agent supplies an alias and gets back output. In between: the pairing check (no pairing, no resolution), the per-target policy, the runner, and credential redaction — every secret field value is scrubbed from results and error messages at the post boundary, tested as SO-9.

the policy gate

Per target, the operator chooses:

  • allowlist mode (default, deny-by-default) — an agent command must exactly equal a curated entry. A menu, not a pattern.
  • command templates — operator-authored fixed commands with named, typed slots (systemctl restart {service}, service an enum). The template is the authorized unit; the agent supplies (templateName, args), every argument is type-checked then shell-escaped, and the agent never assembles shell text (ADR-0018).
  • any mode — the only honest spelling of “full shell on this host.” Available, loud, and refused outright for privileged credentials (ADR-0007).

the audit trail

Broker-request tasks are hidden execution artifacts — they don’t clutter the human board (ADR-0021) — but every one of them stays in the event stream, and the human-only broker activity ledger projects them chronologically: target, op, requesting agent, decrypted inputs, structured outcome (ADR-0022). Archiving curates the board; it never edits the ledger.