Permissions

Understand how instance roles and vault roles control access across Agent Vault.

Agent Vault separates permissions into two independent axes: instance roles and vault roles. Instance roles control who can manage the Agent Vault server itself (users, agents, global settings, resets). Vault roles control who can operate within a specific vault, approving proposals, managing members, and configuring credentials. The two axes are fully independent, so having one does not imply the other.

Instance roles

Instance-level roles govern administrative operations across the entire Agent Vault instance. Both users and agents have instance-level roles. There are two roles: owner and member.

Capability	Owner	Member
Instance settings (invite-only, domains)	Yes	No
Manage users (list, remove, set-role)	Yes	No
Manage agents (invite, list, revoke, rotate, rename, set-role)	Yes	Yes
List / delete all vaults	Yes	No
See all vaults & join as admin	Yes	No
Send test emails	Yes	No
Reset instance	Yes	No
Access vault contents	Only if member	Only if member

Owners can see every vault and join any vault as admin, but they are not automatic members. Until an owner explicitly joins a vault (via agent-vault owner vault join or the web UI), they cannot view its credentials or approve proposals. This lets owners recover orphaned vaults while keeping vault contents access-controlled.

Vault roles

Vault-level roles govern what users and agents can do inside a vault they belong to. There are three roles: admin, member, and proxy.

Capability	Admin	Member	Proxy
Use proxy	Yes	Yes	Yes
Discover services	Yes	Yes	Yes
Raise proposals	Yes	Yes	Yes
View credential names	Yes	Yes	Yes
Set / delete credentials directly	Yes	Yes	No
Approve / reject proposals	Yes	Yes	No
Manage vault services	Yes	Yes	No
Add agents to vault (proxy only)	Yes	Yes	No
Add agents to vault (any role)	Yes	No	No
Invite users to vault	Yes	No	No
Manage vault users (remove, set-role)	Yes	No	No
Manage vault agents (remove, set-role)	Yes	No	No
Delete vault	Yes	No	No

The proxy role is the most restricted, ideal for agents that only need to proxy requests and raise proposals for human review. The member role adds the ability to manage credentials, approve proposals, and configure vault services. The admin role has full control, including inviting users and agents with any role.

Vault admins and members can both review agent proposals. When an agent raises a proposal, vault members receive the approval link (via email if SMTP is configured) and can approve or reject from the browser or CLI.

How the two axes interact

The two permission axes are fully independent. An instance owner who has not joined a vault cannot see its credentials or approve proposals. A vault admin who is not an instance owner cannot manage users or reset the instance.

Example: Alice is an instance owner but has not joined the payments vault. She can see it in her vault list and join it at any time, but she cannot approve proposals or proxy requests through payments until she does. Meanwhile, Bob is a vault admin on payments but a regular instance member. He can approve proposals and manage agents within payments, but he cannot create new users or reset the instance.

The first user

1. Start the server

   bash agent-vault server
2. Register

   The first user to register becomes the instance owner and is automatically granted vault admin on the default vault. bash agent-vault register

3. Start working

   The owner can immediately invite agents, set credentials, and configure services on the default vault. No further setup is needed.

A default vault is created automatically at startup. The first user is granted admin on this vault as part of registration.

Change roles

Instance role

Only instance owners can change instance-level roles. Both users and agents can be promoted or demoted.

# Change a user's instance role
agent-vault owner user set-role [e-mail] --role owner

# Change an agent's instance role
agent-vault agent set-role my-agent --role owner

Vault role

Vault admins (and instance owners for any vault) can change vault-level roles.

agent-vault vault user set-role [e-mail] --role proxy --vault my-vault
agent-vault vault agent set-role my-agent --role member --vault my-vault

The last instance owner cannot be demoted. Agent Vault blocks set-role if it would leave the instance with zero owners. This applies across both users and agents.

Owner-level vault operations

Instance owners have a set of cross-vault operations that do not require vault membership:

• See all vaults: Owners see every vault in their vault list, including vaults they have not joined.
• Join any vault: agent-vault owner vault join <name> grants the owner admin access to a vault. Useful for recovering orphaned vaults.
• Delete any vault: agent-vault owner vault delete <name> deletes a vault regardless of membership.
• Manage agents: agent-vault agent list, info, delete, rotate, rename, and set-role are instance-level operations. Any authenticated user can invite agents; vault admins control per-vault agent access.

These operations affect vault existence and agent lifecycle. To access vault contents (credentials, proposals, proxy), the owner must first join the vault.