Using itSecrets
Secrets
Agents and Vendetta’s own plugins can use passwords and tokens from your password manager. You decide which agent reads what, and for how long. A value reaches only the command or plugin that uses it: never an agent’s transcript, a chat, a screen, a log, or Vendetta’s state.
Turn it on
Section titled “Turn it on”A password manager plugin serves your vaults to the worker. Vendetta ships one for Proton Pass:
[plugins.proton-pass]It signs in with a Proton Pass token of its own; Plugins lists its
settings. Any other password manager plugin is asked nothing until you confirm it with
vendetta secret confirm, as below, and again whenever its command changes. Check it:
vendetta secret status # each password manager, its state, and its vaultsReferences
Section titled “References”A secret is named by a reference, SCHEME://VAULT/ITEM[/FIELD]:
pass://Agents/GitHub PAT # the item's password
pass://Agents/npm/token # its field "token"
pass://Agents/CI%2FCD # a "/" in a name is %2FThe scheme picks the password manager (pass is Proton Pass). VAULT and ITEM are names
or the manager’s ids. A name that matches two vaults or two items is refused; use the
id that vendetta secret search prints. A reference may be shown anywhere; it holds no
value.
In your config
Section titled “In your config”Every setting that takes a token as { env = … } or { command = [...] } also takes a
reference: Telegram’s and Discord’s tokens, the APNs key, webhooks’ secrets, the Claude
proxy’s git hosts, speech, and ntfy.
[plugins.telegram]
token = { secret = "pass://Vendetta/Telegram bot" }A reference is used only after you confirm the config that names it. Until then the plugin can’t start and you get an alert. Confirm in a terminal:
vendetta secret confirmor with Confirm in Settings → Secrets. Restarts read a confirmed reference without
asking. Pointing a plugin at another item, naming a new one, or changing the command
of a table that names one waits for you again. A plugin reads only the references in its
own table.
What agents see
Section titled “What agents see”Agents see nothing until you name vaults:
[secrets]
agent_vaults = ["pass://Agents"] # vaults agents search and ask for; "pass://*" for all
save_vaults = ["pass://Agents"] # agents save new items here without asking
[[secrets.allow]]
item = "pass://Agents/GitHub PAT" # read without asking
projects = ["vendetta"] # every project when left outSettings → Secrets edits the same list; the two add up. An agent asking for an item in another vault is told it doesn’t exist, and you see no card.
Changes to [secrets] that let agents do more (a vault, an allow entry, YOLO) wait for
vendetta secret confirm, as references do. Changes that let them do less apply at
once.
Approving
Section titled “Approving”When an agent asks, a card shows in its chat in the apps, in its Telegram topic or Discord channel, and on its card in the chooser, with an alert:
Release (Claude, vendetta) asks for GitHub PAT · password, Agents · Proton Pass “publish v1.2”
gh release create v1.2[This session] [Once] [Project, 8 h] [Always] [Deny]
The reason and command are the agent’s own words. Your choice:
| Covers | Until | |
|---|---|---|
| This session | this conversation | it is deleted, you revoke it, or 7 days |
| Once | this one command | it runs |
| Project | every agent of the project | the hours you pick, 7 days at most |
| Always | every agent of the project | you remove it from the allow list |
A save shows the vault it goes to; pick another before you approve. A card nobody answers expires after 10 minutes. From a terminal:
vendetta secret requests # open cards
vendetta secret decide ID --allow --scope once
vendetta secret decide ID --denyTelegram and Discord show cards unless their table says secret_approvals = false.
[secrets]
yolo = trueGrants everything agents ask for in agent_vaults, at once. Every read is still in the
audit, values still go only to commands, and nothing outside agent_vaults is reachable.
With agent_vaults = ["pass://*"] that is every vault.
Grants and the audit
Section titled “Grants and the audit”vendetta secret grants # who may read what, and until when
vendetta secret revoke ID
vendetta secret audit # newest first: reads, saves, requests, decisions, revokesThe audit names the agent, its project, the item and field, how it was allowed, the program that got the value (never its arguments), and the agent’s reason. Settings → Secrets → Activity shows the same.
What agents run
Section titled “What agents run”The vendetta skill teaches agents these:
vendetta secret search github
vendetta secret exec --env GH_TOKEN="pass://Agents/GitHub PAT" -- gh release create v1.2
vendetta secret exec --stdin pass://Agents/npm/token -- npm login --auth-type=legacy
vendetta secret exec --file KUBECONFIG=pass://Agents/k8s/config -- kubectl get pods
vendetta secret save --vault Agents --title "CI token" --from -- ./mint-token.shexec hands the value to the command in an environment variable, on stdin, or in a
private file removed when it ends, and replaces it with [secret] in what the command
prints. save puts a new token in your vault without the agent seeing it.
Your own vendetta secret exec, in a terminal you see, needs no card in the vaults agents
see and is audited as yours; in any other vault it shows you a card first. A script or
timer with no terminal is refused.
Limits
Section titled “Limits”Approval is what protects a value. Once a command has it, an agent that wants to can
still get it out (exec -- sh -c 'echo $T | rev'); [secret] catches accidents only.
Grant what a task needs, for as long as it needs it, and read the audit.