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). Each holds a single instance role — owner, admin, or agent — and is granted scope on the vaults it can touch. Effective power inside each vault comes from the agent’s instance role, not a per-vault role. See Permissions for the full model.

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. vault run also pre-configures HTTPS_PROXY/HTTP_PROXY and the CA trust chain on the child, so the agent calls upstream URLs directly (over https:// or http://) and Agent Vault transparently injects credentials at the proxy boundary.

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 authenticated requests and raise proposals.

vault run is a convenience wrapper, not a sandbox. A child process can unset HTTPS_PROXY/HTTP_PROXY or bypass the injected CA and reach the network directly — local credentials and network access are still fully available to the agent. Stronger isolation for local development is on the roadmap.

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 agent instance role (proxy-only on scoped vaults). Use --role to pick a different role; only owners can mint owner-tier invites, and admins cannot grant a role higher than their own.

# Proxy-only: can use the proxy and raise proposals.
agent-vault agent invite my-agent --role agent

# Scoped admin: full vault management on the listed vaults.
agent-vault agent invite my-agent --role admin --vault default

# Owner: god mode. Owner-only.
agent-vault agent invite my-agent --role owner

Vault pre-assignments

Optionally attach vault scope at invite time using the --vault flag (repeatable). The agent’s instance role decides what it can do inside each vault.

# Scope an agent-role bot to two vaults.
agent-vault agent invite my-agent --vault default --vault payments

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 --vault default
agent-vault vault agent add my-agent --vault payments

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 (owner | admin | agent)
agent-vault agent set-role my-agent --role admin

# 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 with access to a specific vault
agent-vault vault agent list --vault my-vault

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

# Remove an agent's access from a vault
agent-vault vault agent remove my-agent --vault my-vault

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, /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. Call upstream URLs directly (over https:// or http://) — HTTPS_PROXY/HTTP_PROXY routes the request through Agent Vault transparently
3. Raise proposals when access to a new service is needed