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.
Prerequisites
Section titled “Prerequisites”- 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.
How an agent is recognized
Section titled “How an agent is recognized”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.
vaultfold agent-mode statusvaultfold agent-help --detectionWhat the agent uses instead of get
Section titled “What the agent uses instead of get”get, get --copy and inject without a child command are refused with exit
2. The agent uses references with run.
vaultfold agent-helpvaultfold run --env-file .env -- npm testRendering 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.
Approve what the agent asks for
Section titled “Approve what the agent asks for”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:
vaultfold agent approvevaultfold agent approve ABCD-1234vaultfold agent approve ABCD-1234 --for-sessionvaultfold agent approve ABCD-1234 --denyAn 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:
vaultfold agent-mode allow-read vault://app/db#password --for 10mIf your agent is not detected, mark the terminal with vaultfold agent-mode on.
It cannot be turned off from that terminal.
Review and revoke
Section titled “Review and revoke”vaultfold agent statusvaultfold agent log --since 1hvaultfold agent trust listvaultfold agent lockCurrent limitations
Section titled “Current limitations”- 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=1stops 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 statusif requests start waiting again. inject --to-fileneeds a person to typewriteon a terminal.- Approvals,
allow-readandagent stopwork 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 pairis not available), and no harness hooks.