Connect a custom agent

Wire up a custom agent or script to Agent Vault through HTTPS_PROXY/HTTP_PROXY and the transparent CA.

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)

For local development, wrap your agent process directly:

agent-vault vault run -- my-agent

vault run sets AGENT_VAULT_ADDR, AGENT_VAULT_SESSION_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. 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

Invited agents don’t get HTTPS_PROXY/HTTP_PROXY auto-configured — set them yourself (see Set the proxy env vars manually).

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 control-plane requests (/discover, proposals)

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.

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 TLS-wrapped 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.

Python

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())

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 invited agent, a Docker container, a sandboxed runtime), configure the proxy yourself. The MITM listener is TLS-encrypted, so the proxy URL uses the https:// scheme and needs the root CA trusted. 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="https://${AGENT_VAULT_SESSION_TOKEN}:my-vault@127.0.0.1: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_SESSION_TOKEN}"

Response

{
  "vault": "default",
  "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 configured in the vault. Requests to unlisted hosts 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

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.