Agent setup
An agent never uses your login. It gets its own client: an identity with its own scopes, IP allow-list and read quota. Every action it takes is logged under its name. You create the client in the vault, then enroll clavitor-cli with it on the machine where the agent runs.
1. Put the entries in a scope
A scoped client reaches only entries that share one of its scopes. Open an entry, click edit next to Scopes, then pick a scope or type a new name and click New. Smart import also assigns scopes. An entry with no scope is visible only to you and to clients with full read access.
2. Create the client
In the vault, go to Clients and click + New client.
| Setting | What to choose |
|---|---|
| Name | Something you will recognise in the audit log, for example "Claude Code" or "Deploy CI". |
| Client type | CLI for agents that run shell commands. |
| Access level | Scoped (only assigned entries) or Full read access (all entries). Scoped clients need at least one scope. |
| Scopes | Click the scopes this client may read. |
| IP whitelist | Addresses, CIDR ranges or host names, separated by commas. Leave it empty and the client is pinned to the first address it connects from. |
| Rate limits | Distinct entries per minute and per hour. The defaults are 3 and 10. |
Click Create client. The vault shows the client's blob and key, once, and does not keep them. The blob is safe to paste anywhere. The key is the secret: deliver it separately, and never on a command line.
3. Enroll the CLI
On the agent's machine, install the CLI, then:
clavitor-cli init
Paste the blob, then the key at the Enrollment key: prompt. The CLI writes its config to ~/.config/clavitor/config and is ready. Test it with clavitor-cli find <name>.
Every agent on that machine shares this one config, and with it one identity. To give two agents different access, run them under different user accounts (or with a different XDG_CONFIG_HOME), each enrolled with its own client.
Read quota
The quota counts distinct entries a client reads in a rolling minute and a rolling hour. Reading the same entry again is free, and so is repeating the same search. Each new search by part of a name counts as one.
- Going over the per-minute limit refuses reads of new entries until the window allows them again.
- Going over the per-hour limit also records a strike. A second strike within two hours locks the client. The vault refuses every request from a locked client until you unlock it.
To unlock, open the client in Clients and click Unlock. Reset rate limit does the same for a client that is not locked: it clears the counters and any strike.
What an agent can and cannot do
- It reads entries in its scopes by exact title, with get and render.
- It finds titles with
find, but cannot list the vault: a name search shows at most five matching titles, and only a count above that. - It decrypts L2 fields on its own machine. L3 fields stay closed: they open only in your browser, with your device.
- It can create entries with put. They get the client's scopes.
- It cannot change its own scopes, quota or IP list.
Managing a client later
Open the client in Clients:
- Edit changes its access level, scopes and IP list.
- Issue enrollment makes a new blob and key, for example after you rebuilt the agent's machine.
- Revoke stops its blob from working, at once. This cannot be undone.
The audit log shows everything a client did, including refused attempts.