Skip to content

Work with AI coding agents

vaultfold treats an AI coding agent as a caller that may use secrets but may not see them. Commands that would print a value are refused, and anything else that touches a collection waits for you.

  • A vault with entries and vault:// references linked into the project files (see link config files).
  • Your own terminal, outside the agent, to answer approvals.
  • The vault unlocked by you first (any vault command, or vaultfold agent unlock). If it is locked, the agent's request becomes an unlock approval that only a person can satisfy.

A session counts as an agent session when it carries an explicit signal (VAULTFOLD_AGENT=1, or vaultfold agent-mode on in that terminal) or two independent signals (a harness's environment marker and a harness among the process's ancestors). One signal alone prints a warning and the command runs.

Terminal window
vaultfold agent-mode status
vaultfold agent-help --detection

get, get --copy and inject without a child command are refused with exit 2. The agent uses references with run.

Terminal window
vaultfold agent-help
vaultfold run --env-file .env -- npm test

Rendering to a file with inject --to-file ... --ephemeral always needs you to type write on a terminal, so an agent without a terminal is refused. Run it yourself, or have the agent use run.

Output of run is always masked in an agent session, and --no-mask is refused there.

The first time an agent session needs a collection, the command exits 3 and says to run vaultfold agent approve outside the agent session. You answer in a system dialog, or in your own terminal:

Terminal window
vaultfold agent approve
vaultfold agent approve ABCD-1234
vaultfold agent approve ABCD-1234 --for-session
vaultfold agent approve ABCD-1234 --deny

An approval covers the collection of the first reference asked for, once or for the agent's session (8 hours); unanswered requests expire after 5 minutes. After --for-session, the agent runs the refused command again and it goes through.

Under Claude Code and Goose the agent's session follows the harness: every command it runs, each in a process group of its own, belongs to one session for as long as that harness process runs, so one --for-session approval covers its retries. The daemon reads the harness's session variable (CLAUDE_CODE_SESSION_ID, AGENT_SESSION_ID) itself and accepts it only from a command that runs under that harness process. Clearing the conversation (/clear) or restarting the harness starts a new session, which asks again. Under other harnesses an approval reaches later commands only from the same terminal or process group; vaultfold agent-help --detection lists the harness session variables.

To let an agent read one value, run this in the terminal it uses; it lasts at most an hour:

Terminal window
vaultfold agent-mode allow-read vault://app/db#password --for 10m

If your agent is not detected, mark the terminal with vaultfold agent-mode on. It cannot be turned off from that terminal.

Terminal window
vaultfold agent status
vaultfold agent log --since 1h
vaultfold agent trust list
vaultfold agent lock
  • Vault commands start the agent daemon and unlock once, and the daemon is what enforces these rules for every caller. Without it (VAULTFOLD_NO_AGENT=1 stops auto-start, though a daemon that is already running is still used) the CLI still refuses value-returning commands, but nothing stands between an agent and an OS keychain identity, so that unlock is refused in an agent session.
  • When the vault is locked, the agent's request becomes an unlock approval, so a person must unlock the vault first. Vaults also lock on idle and screen lock, so check vaultfold agent status if requests start waiting again.
  • inject --to-file needs a person to type write on a terminal.
  • Approvals, allow-read and agent stop work only from a human session with a terminal.
  • A same-user process can still attack the daemon in ways it cannot fully prevent; see the threat model.
  • No remote transports yet (agent pair is not available), and no harness hooks.