---
title: Secrets vault
description: Store tokens once with venom secrets set, let the agent use them as {{secret:NAME}} without ever seeing the value, and bind each one to the origins it may reach.
section: security
order: 50
audience: [user, operator, builder, agent]
sources: [packages/harness/src/secrets, packages/harness/src/extensions/secrets.ts, cli/src/secrets-cli.ts, docs/secrets.md]
features: [security.secrets]
---

The agent uses your secrets by reference. You store a value once; the agent writes `{{secret:NAME}}` where a call
needs it; venom puts the value in when the call runs, after the permission check. The model, the transcript, the
permission prompt, hooks, the audit log, the signed action log and session shares only ever hold the reference. The
vault works offline and makes no network calls.

## Quick start {#quick-start}

```bash
venom secrets set GH_TOKEN --origin https://api.github.com     # hidden prompt for the value
gh auth token | venom secrets set GH_TOKEN --tools bash --origin https://api.github.com
venom secrets list
```

Then ask the agent to use it. It writes, for example:

```bash
GH_TOKEN={{secret:GH_TOKEN}} gh pr list
curl -H "Authorization: Bearer {{secret:API}}" https://api.example.com/me
```

`venom secrets set NAME VALUE` is refused: a value on the command line ends up in shell history and `ps`.

## Commands {#commands}

| Command | What it does |
|---|---|
| `venom secrets set NAME [--project] [--tools …] [--origin …]` | Store a secret; the value comes from stdin or a hidden prompt |
| `venom secrets list [--json]` | Names, scopes and limits, never values. Warns about secrets bound to no origin |
| `venom secrets rm NAME [--project]` | Delete one |
| `venom secrets log [--json] [-n N]` | Uses and refusals: time, name, tool, origins reached, outcome |
| `venom secrets reset` | Delete the vault and its key |

| Flag | Default | What it does |
|---|---|---|
| `--project` | off (a user secret) | Only for this project's git root, and only while the project is [trusted](/docs/security/trust.md). Wins over a user secret of the same name. Stored in your vault, never in the repository |
| `--tools` | any of `bash`, `web_fetch`, `mcp` | The tools that may use it |
| `--origin` | none (any host) | `scheme://host[:port]` origins a call using it may reach. Repeat it, or give a comma-separated list |
| `--hosts` | | The older form: each host is stored as `https://host` |

Exit codes: 0 success, 1 failure, 2 usage.

## Origins {#origins}

A secret bound to origins is put in only when the call's target matches one in scheme, host and port. Any other
target gets no credential: the call is refused with the reason.

```bash
venom secrets set API --origin https://api.example.com:8443 --origin https://*.example.org
venom secrets set DEV_TOKEN --origin http://localhost:8080
venom secrets set DATABASE_PASSWORD --project --origin postgres://db.example.com:5432
```

- Origins are stored normalised: lowercase, no trailing dot, punycode for IDNs, the scheme's default port dropped.
- `https://api.github.com` does not cover `http://api.github.com`, `https://api.github.com:8443` or
  `https://api.github.com.evil.example`.
- `https://*.example.com` covers `example.com` and its subdomains over https on the default port. The wildcard goes
  before a domain name, never an IP address.
- Plain `http` and `ws` are refused unless the host is loopback (`localhost`, `*.localhost`, `127.0.0.0/8`, `::1`).
  A loopback origin may take any port: `http://127.0.0.1:*`.
- Other schemes (`postgres://`, `ssh://`) match the same way.

A secret with no origin goes to any host a call names. `venom secrets set`, `venom secrets list` and `venom doctor`
warn about it. Bind every secret.

## Where a reference works {#use}

| Tool | How |
|---|---|
| `bash` | An env assignment (`TOKEN={{secret:X}} cmd`) or an argument. Each reference becomes an environment variable (`VENOM_SECRET_<NAME>`) set on that one process, quoted to match where it stands, so the value never appears in the command line. The same inside the sandbox |
| `web_fetch` | A header: `{"url": "https://api.example.com/me", "headers": {"Authorization": "Bearer {{secret:API}}"}}`. Sent only to the URL's origin; a redirect to another origin is fetched without it. A reference in the URL is refused |
| MCP config | `env` and `headers` of a server you configured, or of a trusted project's `.mcp.json`. Only remote servers whose URL origin the secret allows; never a stdio server |

When the vault holds secrets, the system prompt gets a short `secrets` section with their names. It is read once per
session, so the prompt cache holds; a secret added mid-session shows up in the next session.

## Refusals {#refusals}

The call is refused before the permission prompt, with guardrail code `GR-ME-CRED-900`, when:

- the name isn't in the vault (the message lists the names this session has);
- the tool doesn't substitute (only `bash` and `web_fetch` do; `write`, `edit` and others are refused), or the
  secret's `--tools` leave it out;
- the call reaches an origin the secret isn't bound to. `curl api.github.com/user` is read as
  `http://api.github.com` and refused for a secret bound to `https://api.github.com`: write the `https://`. A URL
  whose port is a variable (`https://host:$PORT`) is refused too;
- a bash command would print or write it out: `echo`, `printf`, `cat`, `tee`, `base64`, `xxd`, clipboard tools,
  `env`, `printenv`, `set`, a heredoc, a redirect target;
- it would be pasted into inline interpreter code (`python -c`, `node -e`, `bash -c`). Pass it as an environment
  variable instead: `TOKEN={{secret:X}} python script.py`.

These checks are heuristics. Scrubbing keeps the value out of the model and the logs; `--origin` and the sandbox's
egress allowlist keep it from going to the wrong place.

## Scrubbing {#scrubbing}

Once a session has used a secret, every later tool result is scrubbed, whatever the tool: the value itself, its URL
encoding, JSON escape and hex, any base64 encoding of text containing it, and a fragment of six characters or more at
the start or end of a result (a value cut by truncation or split across streamed chunks). The replacement is
`[secret:NAME]`, and you see a quiet line such as "Scrubbed a secret value from bash output before the model saw it
(GH_TOKEN)." The scrubber runs before anything stores the result, so compaction, saved sessions, shares and the
egress map only see the placeholder.

## Storage {#storage}

| File | What |
|---|---|
| `~/.venom/secrets/vault.enc` | AES-256-GCM. Names, scopes and limits are stored in the clear (listing needs no key) and bound to the ciphertext, so widening a secret's origins by editing the file makes it fail to decrypt |
| OS keychain entry | The vault key: the macOS login Keychain, or the Secret Service through `secret-tool` on Linux |
| `~/.venom/secrets/vault.key` | The key, 0600, where there is no keychain, or with `VENOM_KEYSTORE=file` |
| `~/.venom/secrets/uses.jsonl` | The use log (0600): one line per use and refusal, never the value |

`VENOM_KEYSTORE` (`file`, `keychain` or `secret-service`) picks where the key is kept.

A vault written before origins existed opens and is resealed in the new format the first time a value is read.
Older venom versions can't read the new format (`unknown format v2`), on purpose: they would ignore the origins.

Org secrets from the Venom Cloud vault are not synced to developer machines.

## Related {#related}

- [Guardrails](/docs/security/guardrails.md#codes): the `GR-ME-CRED-900` code.
- [Sandbox](/docs/security/sandbox.md#network): the egress allowlist.
- [Audit, signed actions and compliance](/docs/security/audit.md).
