Skip to main content

​
Prerequisites

​
Quick start

The simplest way to connect a custom agent is with vault run, which sets up the environment variables automatically: 
agent-vault vault run -- my-agent
This sets AGENT_VAULT_ADDR, AGENT_VAULT_SESSION_TOKEN, and AGENT_VAULT_VAULT in your agent’s environment.

​
Target a specific vault

agent-vault vault run --vault myproject -- my-agent

​
Alternative: agent invite

For agents that can’t be wrapped with vault run (e.g. cloud-hosted or CI pipelines), create an invite: 
agent-vault agent invite my-agent --vault default:proxy
The agent redeems the invite via HTTP and receives an agent token. See Connect a custom agent for the full walkthrough.

​
Try it out

Have your agent make a request through the proxy. The proxy URL format is: 
{AGENT_VAULT_ADDR}/proxy/{target_host}/{path}
For example, to call Stripe: 
curl "${AGENT_VAULT_ADDR}/proxy/api.stripe.com/v1/charges?limit=10" \
  -H "Authorization: Bearer ${AGENT_VAULT_SESSION_TOKEN}"
If the service isn’t configured yet, Agent Vault returns a 403 with a proposal_hint. Your agent can use this to create a proposal requesting access.
Your agent never sees or handles credentials. Agent Vault strips the agent’s token and injects the real API key before forwarding to the target service.

​
Discover available services

Call /discover to check which hosts have credentials configured: 
curl ${AGENT_VAULT_ADDR}/discover \
  -H "Authorization: Bearer ${AGENT_VAULT_SESSION_TOKEN}"
Response
{
  "vault": "default",
  "proxy_url": "http://127.0.0.1:14321/proxy",
  "services": [
    { "host": "api.stripe.com", "description": "Stripe API" }
  ],
  "available_credentials": ["STRIPE_KEY"]
}
Requests to hosts not in this list should go direct, not through the proxy.

​
Next steps

Connect a custom agent

Full guide with error handling and proposals.

Agent protocol

HTTP reference for sessions, discovery, proxy, and proposals.