Agents

Understand how agents connect to Agent Vault and how to manage them.

An Agent is any AI-powered process that connects to Agent Vault to proxy requests and raise proposals. Agents are instance-level entities (like users) with an instance-level role (owner or member) and can be granted access to multiple vaults with independent roles per vault.

There are two ways to connect an agent: wrapping a local process or inviting any agent via a prompt.

Wrapping with vault run

The simplest approach for local development. Wraps a local agent process with the environment variables it needs — no invite, no token management.

agent-vault vault run -- claude    # Claude Code
agent-vault vault run --vault my-vault -- claude

The agent receives a temporary, vault-scoped session and can immediately make proxied requests and raise proposals.

Inviting an agent

For agents you can’t wrap (cloud-hosted agents, existing sessions, CI pipelines), create an invite. The agent redeems the invite via HTTP and receives an agent token.

agent-vault agent invite my-agent

Outputs a prompt with the invite URL. Paste it into the agent’s chat. The agent redeems the invite and receives an instance-level agent token.

Instance role

By default, invited agents are created with the member instance role. Use --role to set a different instance-level role:

# Invite an agent as an instance owner
agent-vault agent invite my-agent --role owner

Vault pre-assignments

Optionally pre-assign vault access at invite time using the --vault flag (repeatable):

# Invite with proxy access to the default vault
agent-vault agent invite my-agent --vault default:proxy

# Invite with access to multiple vaults
agent-vault agent invite my-agent --vault default:member --vault payments:proxy

The format is vault_name:role where role is proxy, member, or admin (defaults to proxy if omitted).

Agent names must be 3-64 characters, lowercase alphanumeric and hyphens only, and globally unique across the instance.

Adding vaults after creation

You can also grant vault access after the agent has been created:

agent-vault vault agent add my-agent --role proxy
agent-vault vault agent add my-agent --vault payments --role member

Managing agents

Agents are managed at two levels: instance-level (the agent identity) and vault-level (per-vault access).

Instance-level commands

# List all agents across the instance
agent-vault agent list

# View agent details (vaults, status, active sessions)
agent-vault agent info my-agent

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

# Delete an agent and all its sessions
agent-vault agent delete my-agent

# Rename an agent
agent-vault agent rename my-agent new-name

Vault-level commands

# List agents in a specific vault
agent-vault vault agent list --vault my-vault

# Add an existing agent to a vault
agent-vault vault agent add my-agent --role proxy

# Change an agent's vault role
agent-vault vault agent set-role my-agent --role member

# Remove an agent from a vault
agent-vault vault agent remove my-agent

Rotating an agent token

agent-vault agent rotate my-agent

This creates a rotation invite. Paste the prompt into the agent’s chat. The agent redeems it and receives a new agent token. Old tokens are invalidated when the rotation invite is redeemed.

Managing invites

# List pending invites
agent-vault agent invite list --status pending

# Revoke a pending invite
agent-vault agent invite revoke <token_suffix>

The X-Vault header

Instance-level agent tokens are not scoped to a single vault. Instead, agents select a vault per-request using the X-Vault header:

GET /discover
Authorization: Bearer {AGENT_VAULT_SESSION_TOKEN}
X-Vault: my-vault

This applies to all vault-scoped requests: /discover, /proxy/..., /v1/proposals, and /v1/credentials.

Agents created via agent-vault vault run receive vault-scoped sessions and do not need the X-Vault header — the vault is embedded in the session.

Choosing the right approach

Scenario	Approach	Why
Local dev with Claude Code or Cursor	agent-vault vault run	Simplest setup, no tokens to manage
Cloud-hosted agent (e.g. Devin)	agent-vault agent invite	Paste a prompt, agent connects itself
CI/CD pipeline	agent-vault agent invite	Named identity, survives restarts
Always-on assistant	agent-vault agent invite	Multi-vault access, session rotation

When in doubt, start with agent-vault vault run. You can always create a named agent later.

What happens after connecting

Regardless of how an agent connects, it follows the same protocol:

1. Call /discover to learn which services are available
2. Route requests through the proxy at /proxy/{host}/{path}
3. Raise proposals when access to a new service is needed