Agent Vault

Give your AI agent the ability to use secrets without ever letting it see them.

Agent Vault is a local credential vault for AI agents. Your agent references a secret by name (e.g. stripe_key) and never sees its value: the vault injects the real credential outside the model's context, enforces per-secret rules about which hosts each secret may travel to, scrubs secret values out of everything the agent reads back, and writes an append-only audit log of every use.

Think of it as a hotel front desk — the agent is a guest who can ask for doors to be opened but never holds the master key.

        AI agent  ──"use vault:stripe_key on api.stripe.com"──▶  Agent Vault
        (sees only names)                                        │
                                                                 ├─ inject real value
                                                                 ├─ check host allowlist
                                                                 ├─ scrub the response
                                                                 └─ append to audit log

Table of contents

• Why

• Features

• Install

• Quick start

• How it works

• Agent setup (MCP)

• Security model

• Audit log

• Environment variables

• Project layout

• Contributing

• Security policy

• License

Why

To do real work, agents need credentials — a Stripe key, a GitHub token, a database password. The naive approach is to paste those secrets into the agent's context. That is dangerous:

• The secret ends up in the model's conversation, which is sent to a provider and often stored in logs and transcripts.

• A prompt-injection payload in a web page or document the agent reads can trick it into exfiltrating the key.

• Once a secret is in the chat history, you cannot un-expose it.

Agent Vault keeps the real values in a locked box on your machine. The agent operates on secrets by name, and a normal process — outside the model — plugs in the real value, does the thing, scrubs the value from anything the agent sees, and records it.

Features

• Reference by name. Agents use stripe_key; they never receive the value.

• Two doors, one core. An MCP server for agent-native API calls and a run command wrapper for any CLI tool.

• Per-secret host allowlist. A secret can only be sent to the hosts you approve — a hijacked agent can't POST your key to evil.com.

• Output scrubbing. Secret values (and their base64 / percent-encoded forms) are replaced with {{vault:NAME}} before the agent sees them.

• Whole-vault authenticated encryption. Values and metadata (including each secret's allowlist) are encrypted and MAC'd with Fernet, so on-disk tampering is detected and rejected.

• Append-only audit log. Every injection, request, and denial is recorded — names and hosts, never values.

• Local-only. No cloud, no sync, no telemetry. The master key lives in your OS keychain.

Install

uv tool install agent-vault
# or
pipx install agent-vault

For development against a clone of this repo:

uv sync

Quick start

# Create the vault and store the master key in your OS keychain.
agent-vault init

# Add a secret. You're prompted for the value with hidden input;
# --host limits where the secret may be sent over MCP HTTP.
agent-vault add stripe_key --host api.stripe.com

# List secret names and metadata — never values.
agent-vault list

# Run a tool with a secret injected as an environment variable.
agent-vault run --env GITHUB_TOKEN -- gh pr list

# Or interpolate a secret into command arguments with a {{vault:NAME}}
# placeholder. The value is substituted before exec and scrubbed from output.
agent-vault run -- curl -H "Authorization: Bearer {{vault:stripe_key}}" https://api.stripe.com/v1/charges

{{vault:NAME}} placeholders in the command are replaced with the real value just before the child process is exec'd, and every stored secret value is scrubbed back to {{vault:NAME}} in the child's stdout and stderr before you (or your agent) see it. agent-vault run exits with the child's own exit code.

How it works

Agent Vault is one core exposed through two thin frontends, so it covers both things agents actually do — call APIs and run shell tools.

                 ┌───────────────── Agent Vault ─────────────────┐
   MCP tools ───▶│  server.py   ┐                                │
                 │              ├─▶  core: store · policy ·       │
   shell     ───▶│  runner.py   ┘        scrub · audit · keys     │
   (agent-vault run)             │                                │
                 └──────────────────────┬────────────────────────┘
                                        ▼
                          ~/.agent-vault/vault.json   (one Fernet-authenticated blob)
                          ~/.agent-vault/audit.jsonl  (append-only, 0600)
                          OS keychain                 (master key)

• store — load/save the encrypted vault, add/get/remove secrets.

• keys — master key from the OS keychain (or AGENT_VAULT_KEY for CI).

• policy — host-allowlist checks (exact + single-level wildcard).

• scrub — replace secret values (and encoded forms) with placeholders.

• audit — append-only JSONL log of every use and denial.

Agent setup (MCP)

Agent Vault ships an MCP server so agents can use secrets without ever handling their values. Add it to your agent's MCP configuration (for Claude Code, in .mcp.json or your MCP settings):

{"mcpServers": {"agent-vault": {"command": "agent-vault", "args": ["mcp"]}}}

The server exposes two tools: vault_list_secrets, which returns secret names and metadata (never values), and vault_http_request, which performs an authenticated HTTP call by injecting a named secret server-side, enforcing the secret's host allowlist, and scrubbing the response before returning it.

Security model

Agent Vault provides five guarantees:

1. Secret values never appear in agent-visible output. MCP responses and agent-vault run output are scrubbed: every stored value is replaced with its {{vault:NAME}} placeholder before the agent sees it. MCP response scrubbing also covers the base64 and percent-encoded forms of a value, so a reflected basic-auth or query credential is caught. Wrapped run children do not inherit the AGENT_VAULT_KEY master key in their environment.

2. Per-secret host allowlist on MCP HTTP. Each secret carries an allowed_hosts list. A prompt-injected agent cannot exfiltrate stripe_key to evil.com via vault_http_request — off-allowlist hosts are denied before any request is made, agent-supplied routing headers (Host, :authority, forwarded, and the X-Forwarded-Host/For/Proto/Port/Server, X-Real-IP, X-Original-Host, X-Host family) are rejected so they can't reroute an allowlisted request, and any request in which a raw secret value itself appears in method/url/headers/body is denied.

3. Every use and every denied attempt is audit-logged. Injections, HTTP requests, and policy denials are all recorded (names and hosts, never values). The audit log is symlink-safe, fsync-durable, and tolerant of a corrupt line.

4. Local-only, with the whole vault authenticated at rest. There is no cloud service, sync, or telemetry. The entire vault file — secret values and metadata, including each secret's allowed_hosts — is encrypted and authenticated with Fernet (AES-128-CBC + HMAC), so any on-disk tampering (e.g. an agent editing allowed_hosts to widen a secret's policy) fails the MAC and is rejected on load. The master key lives in your OS keychain (with an AGENT_VAULT_KEY environment-variable fallback for headless use). Vault writes are atomic (temp-file + fsync + rename), locked against concurrent writers, and symlink-safe (O_EXCL/O_NOFOLLOW).

5. Honest limitations, documented rather than hidden:

   • agent-vault run has no host policy, and by design hands the real secret to the child process (that is how the child authenticates). Once a process legitimately holds a secret it can do anything with it — transform it, forward it, or store it — and no amount of output scrubbing can prevent that. run will inject a secret into any command you ask it to. Host allowlists apply only to MCP HTTP requests.

   • Scrubbing is best-effort and matches secret values literally (plus their base64/percent-encoded forms on MCP responses). If a tool transforms a secret some other way (hashing, reversing, splitting), the transformed form is not recognized or scrubbed. run output scrubbing is additionally line-based: a secret straddling a line boundary, or one containing a newline, is not scrubbed.

   • Substituted {{vault:NAME}} values appear in the child command's argv, visible in ps and other process listings on the same machine for the child's lifetime. Prefer --env NAME injection where the tool accepts credentials from the environment.

   • Authentication detects tampering but not rollback. An attacker who can overwrite vault.json cannot forge new policy, but can restore a previous valid copy of the whole file (reverting a tightened allowlist or a rotated secret). Protect the vault directory with filesystem permissions; anti- rollback is out of scope for this local-file design.

   • Confidentiality assumes the agent is confined to the vault's tools. Agent Vault protects secret values from an agent that can only reach them through vault_http_request and run. It does not defend against a process running as your own user that can execute arbitrary code — such a process can read the master key from your OS keychain (subject to the OS's own prompts) or from AGENT_VAULT_KEY in the environment, and decrypt the whole vault directly, with no scrubbing, allowlist, or audit entry. If you pair Agent Vault with a shell-capable agent, the vault raises the bar and gives you an audit trail for tool-mediated use, but it is not a sandbox and cannot contain an agent that already has same-user code execution.

Exit codes follow Click's convention: 0 on success, 1 on a user or validation error, 2 on a usage error. Policy denials are surfaced as structured MCP errors, not exit codes; agent-vault run passes through the child command's exit code unchanged.

Found a vulnerability? Please read SECURITY.md — do not open a public issue for security reports.

Audit log

The audit log lives at ~/.agent-vault/audit.jsonl (or $AGENT_VAULT_HOME/audit.jsonl). It is append-only, written with mode 0600, and stored as one JSON object per line. Each entry records a timestamp, an event type (add, remove, run_inject, http_request, or denied), the secret name, a target (a command or host), whether the action was allowed, and a short detail string. It never contains secret values.

agent-vault audit --tail 20

Environment variables

• AGENT_VAULT_HOME — override the vault directory (default ~/.agent-vault). Useful for isolating vaults per project or in tests.

• AGENT_VAULT_KEY — a base64 Fernet key used instead of the OS keychain. Set this for headless or CI environments where no keychain is available.

Project layout

agent_vault/
  cli.py            # Typer CLI: init / add / list / remove / audit / run / mcp
  runner.py         # `agent-vault run` — placeholder + env injection, output scrubbing
  server.py         # MCP server: vault_list_secrets, vault_http_request
  core/
    store.py        # encrypted vault storage (whole-file authenticated)
    keys.py         # master-key management (keychain + AGENT_VAULT_KEY fallback)
    policy.py       # host allowlist checks
    scrub.py        # replace secret values with {{vault:NAME}}
    audit.py        # append-only audit log
tests/              # pytest suite (unit + CLI + runner + MCP)
docs/               # design spec and implementation plan

Contributing

Contributions are welcome. Start with CONTRIBUTING.md for development setup, the test workflow, and the (higher-than-usual) bar for changes that touch the security-sensitive core. By participating you agree to the Code of Conduct.

Security policy

Please report vulnerabilities privately as described in SECURITY.md, not via public issues.

License

MIT. See LICENSE.