Connect a coding agent

Connect Claude Code, Cursor, or any chat-based coding agent to Agent Vault.

This guide covers connecting coding agents like Claude Code, Cursor, or any agent that accepts prompts in a chat interface. These agents handle the Agent Vault protocol automatically — you just paste a prompt and they take care of the rest.

For agents that don’t have a chat interface or need raw environment variables, see Connect a custom agent.

Prerequisites

• A running Agent Vault server (installation)
• A user account with vault access (member or admin)

Option 1: Wrap with agent-vault vault run

The simplest approach for local development. Wraps your 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 either http:// or https://) and Agent Vault transparently injects credentials.

agent-vault vault run -- claude    # Claude Code
agent-vault vault run -- agent     # Cursor
agent-vault vault run -- codex     # Codex
agent-vault vault run -- hermes    # Hermes Agent
agent-vault vault run -- opencode  # OpenCode

The agent can immediately make authenticated requests and raise proposals.

Use --vault to target a specific vault:

agent-vault vault run --vault my-vault -- claude

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.

Option 2: Create a named agent

For agents you can’t wrap with vault run (e.g. cloud-hosted agents, or when you want to connect an agent on a different host).

Web UI

1. Open the Agents tab

   Navigate to the Agents tab in the home view.

2. Add the agent

   Click Add agent, enter a name, and optionally pre-assign vault access. The modal advances to Connect Your Agent with a three-step walkthrough.

3. Install the CLI on the agent host

   Step 1 of the modal shows a Shell or Dockerfile snippet to install the agent-vault binary in the environment where your agent runs.

4. Set environment variables

   Step 2 shows the AGENT_VAULT_ADDR, AGENT_VAULT_TOKEN, and AGENT_VAULT_VAULT exports for the agent’s environment. The token is pre-filled. Set AGENT_VAULT_ADDR on the server to also pre-fill the address.

5. Run the agent under agent-vault

   Step 3 shows agent-vault run -- <your-agent> (or an ENTRYPOINT for Dockerfile flows). The CLI pre-sets HTTPS_PROXY and HTTP_PROXY on the child so both HTTPS and plain HTTP calls route through Agent Vault.

CLI

agent-vault agent create my-agent

This prints an agent token and copies it to your clipboard. Set AGENT_VAULT_TOKEN and AGENT_VAULT_ADDR in the agent’s runtime.

Pre-assign vault access with --vault:

agent-vault agent create my-agent --vault default:proxy

What happens next

Once connected, the agent follows the Agent Vault protocol automatically:

1. Calls upstream APIs normally over http:// or https:// — HTTPS_PROXY/HTTP_PROXY and CA trust are pre-wired so Agent Vault transparently intercepts the call
2. If a service isn’t configured yet, the agent creates a proposal and shares an approval link
3. You click the link, provide any required credentials, and approve
4. The agent retries and the request succeeds

You don’t need to pre-configure anything. The agent discovers what it needs, asks for approval, and handles the rest.

For long-lived agents

Named agents are instance-level entities that persist across sessions. You can manage vault access, rotate agent tokens, and revoke agents at any time. See Agents overview for the full lifecycle.

Next steps

Agents overview

How agents work, vault access, and management commands.

Proposals

How agents request access to new services.