Skip to content
Docs menu

Secrets vault

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.

View .md

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

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:

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

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. 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

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.

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

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

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

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

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.