Connect a custom agent

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 with the transparent proxy enabled (default)
A user account with vault access (member or admin)

Get connection credentials

vault run (simplest)
agent create

For local development, wrap your agent process directly:

agent-vault vault run -- my-agent

vault run sets AGENT_VAULT_ADDR, AGENT_VAULT_TOKEN, and AGENT_VAULT_VAULT on the child, then pre-configures HTTPS_PROXY/HTTP_PROXY and the CA trust chain so standard HTTP clients route both HTTP and HTTPS traffic through the broker transparently.

For CI pipelines, cloud-hosted agents, or any agent that lives outside vault run:

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

Prints the agent’s token (copies to clipboard). The response also includes:

av_agent_token — bearer token for all requests
name, role, created_at — the agent identity the server persisted
vaults — list of accessible vaults

Set AGENT_VAULT_TOKEN and AGENT_VAULT_ADDR in the agent’s runtime. The agent doesn’t get HTTPS_PROXY/HTTP_PROXY auto-configured — set them yourself (see Set the proxy env vars manually) or launch the agent under agent-vault run.Instance-level agent tokens require the X-Vault header on /discover and /v1/proposals requests.

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_TOKEN`	Yes	Bearer token for authenticating control-plane requests (`/discover`, proposals)

For instance-level agent tokens (from agent create), the agent must also send the X-Vault header on /discover and /v1/proposals requests. For vault-scoped sessions (from vault run), the vault is embedded in the session. When the agent is launched via vault run, these additional variables are also set automatically on the child:

Variable	Purpose
`HTTPS_PROXY`	Routes HTTPS traffic through the transparent proxy (CONNECT)
`HTTP_PROXY`	Same URL as `HTTPS_PROXY` — plain `http://` upstreams route through the same listener via absolute-form forward-proxy requests
`NO_PROXY`	`localhost,127.0.0.1` — so agent-to-vault traffic skips the proxy
`NODE_USE_ENV_PROXY`	Enables Node.js 22.21+ built-in proxy support
`SSL_CERT_FILE`, `NODE_EXTRA_CA_CERTS`, `REQUESTS_CA_BUNDLE`, `CURL_CA_BUNDLE`, `GIT_SSL_CAINFO`, `DENO_CERT`	Trust the Agent Vault root CA from standard HTTP libraries

Make requests

When your agent is launched via vault run, HTTP and HTTPS traffic both route through Agent Vault transparently. Call the real API URL — standard HTTP clients honor HTTPS_PROXY/HTTP_PROXY automatically. Agent Vault intercepts the CONNECT (for https:// upstreams) or the absolute-form forward-proxy request (for http:// upstreams), matches the host against the vault’s services, and injects the stored credential into the auth header for that service.

import os, requests

# Authorization intentionally omitted — Agent Vault injects the real credential.
charges = requests.get(
    "https://api.stripe.com/v1/charges",
    params={"limit": 10},
)
print(charges.json())

new_charge = requests.post(
    "https://api.stripe.com/v1/charges",
    data={"amount": 2000, "currency": "usd"},
)
print(new_charge.json())

// fetch() in Node.js v22.21+ honors HTTPS_PROXY/HTTP_PROXY when NODE_USE_ENV_PROXY=1.
const charges = await fetch("https://api.stripe.com/v1/charges?limit=10");
console.log(await charges.json());

const newCharge = await fetch("https://api.stripe.com/v1/charges", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: "amount=2000&currency=usd",
});
console.log(await newCharge.json());

curl "https://api.stripe.com/v1/charges?limit=10"

curl -X POST "https://api.stripe.com/v1/charges" \
  -d "amount=2000&currency=usd"

Any HTTP method works (GET, POST, PUT, DELETE, PATCH). Query parameters, request bodies, and headers flow through unchanged.

Leave the upstream Authorization header blank or set it to a placeholder — Agent Vault strips whatever the client sends and attaches the real credential at the proxy boundary.

Set the proxy env vars manually

If your agent wasn’t launched via vault run (e.g. an agent created via agent create, a Docker container, a sandboxed runtime), configure the proxy yourself. The MITM listener is plain HTTP — deploy on a trusted/private network. Set HTTPS_PROXY and HTTP_PROXY to the same URL — the listener handles CONNECT (for https:// upstreams) and absolute-form forward-proxy requests (for http:// upstreams) on the same port.

# 1. Fetch the CA certificate
agent-vault ca fetch -o /etc/ssl/certs/agent-vault-ca.pem

# 2. Build the proxy URL (basic auth: token:vault)
export HTTPS_PROXY="http://${AGENT_VAULT_TOKEN}:[email protected]:14322"
export HTTP_PROXY="$HTTPS_PROXY"
export NO_PROXY="localhost,127.0.0.1"
export NODE_USE_ENV_PROXY=1

# 3. Point standard HTTP libraries at the CA
export SSL_CERT_FILE=/etc/ssl/certs/agent-vault-ca.pem
export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/agent-vault-ca.pem
export REQUESTS_CA_BUNDLE=/etc/ssl/certs/agent-vault-ca.pem
export CURL_CA_BUNDLE=/etc/ssl/certs/agent-vault-ca.pem
export GIT_SSL_CAINFO=/etc/ssl/certs/agent-vault-ca.pem
export DENO_CERT=/etc/ssl/certs/agent-vault-ca.pem

For containerized agents, the TypeScript SDK provides buildProxyEnv(), which returns the complete environment block from a session’s containerConfig.

Discover available services

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

curl ${AGENT_VAULT_ADDR}/discover \
  -H "Authorization: Bearer ${AGENT_VAULT_TOKEN}"

Response

{
  "vault": "default",
  "services": [
    { "name": "stripe", "host": "api.stripe.com" },
    { "name": "github", "host": "api.github.com" }
  ],
  "available_credentials": ["STRIPE_KEY", "GITHUB_TOKEN"]
}

services lists the services configured in the vault. Each entry has a canonical name (slug) and a host pattern (which may carry an inline path glob like slack.com/api/*). Requests not matching any service go direct.
available_credentials lists credential key names in the vault (values are never exposed).

Discovery is optional. If your agent already knows which hosts are configured, it can skip straight to making requests. 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 (only fires when the vault is in strict deny mode)	Create a proposal to request access, or ask the vault admin to add the service.
429	Too many requests	Respect the `Retry-After` header.
502	Missing credential or upstream error	A credential may need to be added to the vault.

Next steps

Deploy your agent in a container

Ship your agent as a container image (k8s, Fly, ECS) using a pre-supplied AGENT_VAULT_TOKEN instead of an interactive auth login.

Agent protocol

Full HTTP reference for sessions, discovery, 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.

Getting Started

Quickstart

Guides

Learn

Resources

Connect a custom agent

Prerequisites

Get connection credentials

Environment variables

Make requests

Set the proxy env vars manually

Discover available services

Handle errors

Next steps

Deploy your agent in a container

Agent protocol

Proposals

Credentials

Agents overview

​Prerequisites

​Get connection credentials

​Environment variables

​Make requests

​Set the proxy env vars manually

​Discover available services

​Handle errors

​Next steps

Deploy your agent in a container

Agent protocol

Proposals

Credentials

Agents overview

Prerequisites

Get connection credentials

Environment variables

Make requests

Set the proxy env vars manually

Discover available services

Handle errors

Next steps