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, member, or no-access) 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 creating a named agent and supplying its token to a remote runtime.

Wrapping with vault run

The simplest approach for local development. Wraps a local agent process with the environment variables it needs — no token to manage. 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.

Creating an agent

For agents you can’t wrap (cloud-hosted agents, existing sessions, CI pipelines), create a named agent. The server returns a long-lived agent token; supply it to the agent’s runtime via AGENT_VAULT_TOKEN.

agent-vault agent create my-agent

Prints the agent token (and copies it to your clipboard). Set AGENT_VAULT_TOKEN and AGENT_VAULT_ADDR wherever the agent runs.

Instance role

By default, agents are created with the no-access instance role — they cannot perform instance-scoped actions and must be granted vault access to do anything. Use --role to widen this:

# Create an agent as an instance owner
agent-vault agent create my-agent --role owner

# Create an agent as an instance member (can list users/agents, create vaults)
agent-vault agent create my-agent --role member

See Permissions for what each role can do.

Vault pre-assignments

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

# Create with proxy access to the default vault
agent-vault agent create my-agent --vault default:proxy

# Create with access to multiple vaults
agent-vault agent create 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

Invalidates the agent’s existing token and prints a new one. Update AGENT_VAULT_TOKEN wherever the agent runs — the previous token stops working immediately.

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_TOKEN}
X-Vault: my-vault

This applies to /discover and /v1/proposals. (Endpoints like /v1/credentials resolve the vault from a ?vault= query parameter or request body instead.)

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 create	Named identity, supply token via env
CI/CD pipeline	agent-vault agent create	Named identity, survives restarts
Always-on assistant	agent-vault agent create	Multi-vault access, token 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