Permissions

Understand how the unified instance role system controls access across Agent Vault.

Agent Vault has a single permission tier: instance roles. Each user or agent holds exactly one role — owner, admin, or agent — and that role, together with the actor’s set of scoped vaults, determines everything they can do. There is no separate per-vault role to keep in sync.

The three roles

Role	Who can hold it	Effective power
owner	Users and agents	God mode. Auto-accesses every vault. Can manage instance settings, users, agents, and every vault.
admin	Users and agents	Manages scoped vaults end-to-end (services, credentials, proposal approval). Can create new vaults. Can invite other admins or agents — but cannot grant a role higher than their own and cannot pre-assign vaults outside their own scope.
agent	Programmatic agents only	Proxy-only on scoped vaults. Can use the proxy and raise proposals; cannot reveal credentials, approve/reject proposals, or mutate services. Humans cannot hold this role.

Vault scope

Owners auto-access every vault — there is no “join” step. Admin and agent actors carry an explicit list of vaults they can touch (their scope). Adding a user or agent to a vault simply attaches that vault to their scope; effective power inside the vault still comes from their instance role.

Operation	Owner	Admin (in scope)	Agent (in scope)
Use the proxy	Yes	Yes	Yes
Discover services	Yes	Yes	Yes
Raise proposals	Yes	Yes	Yes
List credential names	Yes	Yes	Yes
Reveal credential values	Yes	Yes	No
Set / delete credentials	Yes	Yes	No
Approve / reject proposals	Yes	Yes	No
Manage vault services	Yes	Yes	No
Add or remove vault scope (users / agents)	Yes	Yes	No
Delete vault	Yes	Yes	No
Manage instance settings, users, agents, all vaults	Yes	Limited (see below)	No

An admin with zero scoped vaults is still useful: they can create a new vault, which auto-grants them scope on it.

Inviting other actors

Admins can invite users and agents, with two safety rails:

• Cannot escalate. An admin can only create invites for admin or agent. Only owners can mint owner-tier invites.
• Cannot widen scope. Pre-assigned vaults on an admin’s invite must be a subset of the inviter’s own scope. Owners are unrestricted.

Owners have no such restrictions.

How proposals stay safe

Agents can raise proposals but cannot approve them. Approval requires the instance admin (with vault scope) or owner role. This is the same self-approval block the previous “proxy” tier provided, now structural — agents simply lack the verb.

The first user

1. Start the server

   bash agent-vault server
2. Register

   The first user to register becomes the instance owner and auto-accesses every vault, including the default vault that the server seeds at startup. bash agent-vault register

3. Start working

   The owner can immediately invite admins or agents, set credentials, and configure services. No further setup is needed.

Changing roles

Only instance owners can change roles, and the last owner cannot be demoted. Both users and agents accept the role flag.

# Promote a user to owner.
agent-vault owner user set-role [e-mail] --role owner

# Set an agent's role.
agent-vault agent set-role my-agent --role agent   # owner | admin | agent

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.

Adding or removing vault scope

Adding scope replaces the old “vault role” assignment — there is no role to pick.

# Grant an existing user access to a vault.
agent-vault vault user add [e-mail] --vault payments

# Grant an existing agent access to a vault.
agent-vault vault agent add my-agent --vault payments

# Remove access.
agent-vault vault user remove [e-mail] --vault payments
agent-vault vault agent remove my-agent --vault payments

Owners auto-access every vault and do not appear in scope lists.