Connect a custom agent

Wire up a custom agent or script to Agent Vault using environment variables and the HTTP protocol.

This guide walks through connecting a custom agent to Agent Vault. Use this when you’re building your own sandboxed agent, a CI pipeline, or any process that needs to make authenticated API calls through Agent Vault.

If you’re using Claude Code, Cursor, or another supported agent, see the Quickstart guides instead. Those agents handle the connection protocol automatically.

Prerequisites

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

Get connection credentials

vault run (simplest)

For local development, wrap your agent process directly:

agent-vault vault run -- my-agent

This sets AGENT_VAULT_ADDR, AGENT_VAULT_SESSION_TOKEN, and AGENT_VAULT_VAULT in the child process automatically. No invite needed.

Agent invite

For CI pipelines, cloud-hosted agents, or when you need the agent to redeem an invite via HTTP:

agent-vault agent invite my-agent --vault default:proxy

This prints an invite prompt. The agent redeems it via POST {invite_url} and receives:

• av_addr — the Agent Vault server URL
• av_agent_token — bearer token for all requests
• vaults — list of accessible vaults

Instance-level agent tokens require the X-Vault header on every vault-scoped request.

Environment variables

Your agent needs these values to operate:

Variable	Required	Description
AGENT_VAULT_ADDR	Yes	Base URL of the Agent Vault server (e.g. http://127.0.0.1:14321)
AGENT_VAULT_SESSION_TOKEN	Yes	Bearer token for authenticating all requests to Agent Vault

For instance-level agent tokens (from agent invites), the agent must also send the X-Vault header on every vault-scoped request. For vault-scoped sessions (from vault run), the vault is embedded in the session.

Make proxied requests

The core of Agent Vault is the proxy. Your agent makes HTTP requests to Agent Vault, which injects the real credentials and forwards to the target service over HTTPS. Your agent never sees or handles the actual API keys.

The proxy URL format is:

{AGENT_VAULT_ADDR}/proxy/{target_host}/{path}[?query]

Every request to the proxy must include your agent token in the Authorization header. Agent Vault strips it before forwarding and replaces it with the real credentials from the vault’s services.

Python

import os, requests

ADDR = os.environ["AGENT_VAULT_ADDR"]
TOKEN = os.environ["AGENT_VAULT_SESSION_TOKEN"]

headers = {"Authorization": f"Bearer {TOKEN}"}

# GET request through the proxy
charges = requests.get(
    f"{ADDR}/proxy/api.stripe.com/v1/charges",
    params={"limit": 10},
    headers=headers,
)
print(charges.json())

# POST request through the proxy
new_charge = requests.post(
    f"{ADDR}/proxy/api.stripe.com/v1/charges",
    headers={**headers, "Content-Type": "application/x-www-form-urlencoded"},
    data="amount=2000&currency=usd",
)
print(new_charge.json())

Any HTTP method works (GET, POST, PUT, DELETE, PATCH). Query parameters, request bodies, and headers (other than Authorization) are forwarded as-is.

Discover available services

Your agent can call /discover to check which hosts have credentials configured before making proxy requests.

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" },
    { "host": "api.github.com", "description": "GitHub API" }
  ],
  "available_credentials": ["STRIPE_KEY", "GITHUB_TOKEN"]
}

• services lists the hosts your agent can route through the proxy.
• available_credentials lists credential key names in the vault (values are never exposed).
• Requests to hosts not in this list should go direct, not through the proxy.

Discovery is optional. If your agent already knows which hosts are configured, it can skip straight to proxying. If it hits a host that isn’t configured, Agent Vault returns a 403 with a proposal_hint.

Handle errors

Status	Meaning	What to do
401	Invalid or expired token	Re-authenticate. Contact the operator for a token rotation.
403	Host not allowed	The service isn’t configured in the vault. Create a proposal to request access, or ask the vault admin to add it. The response body includes a proposal_hint.
429	Too many pending proposals	Wait for existing proposals to be reviewed before creating new ones.
502	Missing credential or upstream error	A credential may need to be added to the vault. Inform the user.

Next steps

Agent protocol

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

Proposals

Request access to new services via the proposal API.

Credentials

Managing secrets in Agent Vault.

Agents overview

Agent lifecycle, vault access, and management.