Connect a custom agent

Wire up a custom agent or script to Agent Vault through HTTPS_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 and the CA trust chain so standard HTTP clients transparently route through the broker. 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
• proxy_url — the explicit proxy endpoint fallback

Invited agents don’t get HTTPS_PROXY auto-configured. You can either set it yourself (see Set HTTPS_PROXY manually) or use the explicit endpoint.

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
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, HTTPS traffic already routes through Agent Vault transparently. Call the real API URL — standard HTTP clients honor HTTPS_PROXY automatically. Agent Vault intercepts the CONNECT, matches the host against the vault’s services, and injects the stored credential into the auth header for that service over HTTPS.

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 HTTPS_PROXY 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.

# 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 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.

Explicit proxy endpoint (fallback)

For clients that can’t honor HTTPS_PROXY — HTTP/2-only runtimes, sandboxes without CA-mounting, or minimal environments — Agent Vault exposes an explicit endpoint. Rewrite the upstream URL to:

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

curl

curl "${AGENT_VAULT_ADDR}/proxy/api.stripe.com/v1/charges?limit=10" \
  -H "Authorization: Bearer ${AGENT_VAULT_SESSION_TOKEN}"

Instance-level agent tokens must also include X-Vault: {vault_name}.

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",
  "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 configured in the vault. Requests to unlisted hosts go direct.
• available_credentials lists credential key names in the vault (values are never exposed).
• proxy_url is the explicit endpoint fallback.

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	Create a proposal to request access, or ask the vault admin to add it.
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.