Skip to content
Docs0.9GitHubInstall

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.

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 vaults

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 %2F

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

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 confirm

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

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 out

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

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

Telegram and Discord show cards unless their table says secret_approvals = false.

[secrets]
yolo = true

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

vendetta secret grants          # who may read what, and until when
vendetta secret revoke ID
vendetta secret audit           # newest first: reads, saves, requests, decisions, revokes

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

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

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

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.