This page explains how an AI agent uses your vault: its own identity, the six words you compare when you approve it, the projects and permissions you grant it, and the only ways Klav returns a secret value to it. It is written for you and for the agent itself.
An agent has its own identity
An agent is a program that acts for you: Claude Code, Codex, Cursor, a script or a server. It never knows your master password or your Secret Key. Instead:
- It makes its own key pair and asks your account for access. It gets nothing yet.
- You approve it: you compare six words and choose which projects it can use and what it can do there. That choice, signed by your account, is its grant.
- It receives the keys of those projects only, and signs every request with its own key.
On a Mac its private key goes in the login keychain; elsewhere, in a file only you can read. A container can pass it in the KLAV_AGENT_KEY environment variable.
The six words
When an agent registers, it prints six pairing words. You see the same six words when you approve it, in the Mac app’s Requests, on the iPhone or in klav agent list. If they match, the request you are approving is the one that agent made; if they don’t, deny it.
AGENT STATUS PAUSED PROJECTS WORDS ID
claude-code pending ferocity mothproof bolt cassette gleeful seizing …The account has six words of its own too. klav status shows them on your devices (words:), and klav agent status shows them to the agent (account:): they must match. The agent pins your account’s identity the first time it sees it, and stops with exit code 3 if it ever changes.
The grant: projects and permissions
A grant names the projects (or whole vaults) the agent can use, and a policy that says allow, ask or deny for each permission. ask means the request waits for your approval.
| Permission | What it lets the agent do | Default |
|---|---|---|
list |
See items’ metadata: title, URL, username, kind. Never secrets | allow |
fill |
Type a login or card into a browser page, without the value coming back | allow |
inject |
Put secrets into a command’s environment or a new file (run, inject) |
allow |
create |
Create items | allow |
totp |
Get a one-time code | ask |
update |
Edit items | ask |
reveal |
Get a value in clear text: the only way a secret enters the agent’s context | deny |
delete |
Move items to the trash | deny |
passkey |
Sign in with your passkey through your browser | Only inside an approved task |
rotate |
Change a password in your browser (assisted password change) | Only inside an approved task |
When you approve an agent you can change any default, limit fill to some sites (--fill-domain), allow it only at certain hours (--hours) and set an end date (--expires). A deny rule always wins. To change a grant later, see Pause, change or revoke an agent.
Actions, not values
By default an agent gets actions, not values. Klav puts the secret where it is used, and the agent gets back only what it needs to go on:
| The agent asks to… | It gets back |
|---|---|
Find items (search_items, get_item) |
Titles, references, kinds and field names. Never values |
Fill a login or card (fill_login, fill_card, klav agent fill) |
The names of the fields it filled and, after a submit, the origin the page reached |
Run a command (run_with_secrets, klav agent run) |
The command’s output, with each value replaced by [redacted by klav] |
Write a file (inject_file, klav agent inject) |
The file’s path, never its content |
Create an item with a generated password (create_item with generate) |
The item’s metadata and the password’s strength, never the password |
Klav returns a value to the agent in only two ways:
reveal, denied by default. An agent asks for it withrequest_access, and you decide.- A one-time code, from
get_totpwithout atargetor fromklav agent totp.totpisaskby default. Withtarget, the code is typed into the page instead.
inject and fill hand the value to a command, a file or a page, and an agent that writes the command, reads the file or controls the browser can get it. Grant inject only to agents you would trust with those values.
Every request carries a reason the agent writes, and goes to the activity log with it.
When the answer is not a yes
The klav agent commands exit with these codes, and klav mcp answers with the same meaning:
| Exit code | klav mcp answer |
Meaning | What the agent does |
|---|---|---|---|
| 3 | an error | A security check failed: words that don’t match, an account identity that changed, a grant or log that was tampered with | Stop and tell you |
| 4 | status: "pending" |
Waiting for your approval | Tell you what it asked for, wait in the background, retry with the approval |
| 5 | denied: … |
The policy or you denied it | Don’t work around it; explain why it needs it, or use request_access |
| 6 | — | The request expired without a decision, or the task ended | Tell you |
| 7 | status: "paused" |
You paused agents (agents_paused) |
Stop and tell you it needs Klav |
| 8 | status: "account_deleting" |
You asked to delete the account | Stop and tell you; don’t retry |