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.
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 listThen 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/mevenom 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.comdoes not coverhttp://api.github.com,https://api.github.com:8443orhttps://api.github.com.evil.example.https://*.example.comcoversexample.comand its subdomains over https on the default port. The wildcard goes before a domain name, never an IP address.- Plain
httpandwsare 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
bashandweb_fetchdo;write,editand others are refused), or the secret's--toolsleave it out; - the call reaches an origin the secret isn't bound to.
curl api.github.com/useris read ashttp://api.github.comand refused for a secret bound tohttps://api.github.com: write thehttps://. 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.
Related
- Guardrails: the
GR-ME-CRED-900code. - Sandbox: the egress allowlist.
- Audit, signed actions and compliance.