Sidecar Proxy

The Vane sidecar is a local HTTP proxy that runs alongside any AI agent process. It intercepts outbound HTTP/HTTPS calls, attaches the agent’s Vane passport, and attests every call — all without changing a line of agent code.

How it works

Your agent process
    │
    │  HTTP_PROXY=http://127.0.0.1:8080
    │  HTTPS_PROXY=http://127.0.0.1:8080
    ▼
Vane Sidecar (:8080)
    ├── Outbound HTTP: injects Vane-Passport header, attests call
    ├── Outbound HTTPS: MITM → injects header → re-encrypts → forwards
    └── Inbound (/:path): verifies Vane-Passport, reverse-proxies to agent

For HTTPS, the sidecar performs transparent MITM using a locally-generated ECDSA P-256 root CA. The agent process must trust this CA certificate.

Configuration

All configuration is via environment variables. None have defaults except SIDECAR_PORT and SIDECAR_CA_CERT_FILE.

Variable	Required	Default	Description
`VANE_API_URL`	Yes	—	Base URL of the Vane server (e.g., `https://vane.build`).
`VANE_API_KEY`	Yes	—	Company-scoped API key.
`VANE_AGENT_ID`	Yes	—	Agent ID pre-registered on the Vane server.
`VANE_COMPANY_ID`	Yes	—	Company ID.
`SIDECAR_PORT`	No	`8080`	Port to listen on. Always binds to `127.0.0.1`.
`SIDECAR_AGENT_TARGET`	No	—	Where to forward verified inbound calls (e.g., `http://localhost:3001`). Required for inbound (reverse proxy) mode.
`SIDECAR_CA_CERT_FILE`	No	`./vane-ca.pem`	Path to write the MITM CA certificate.

Starting the sidecar

VANE_API_URL=https://vane.build \
VANE_API_KEY=vane_a1b2c3d4... \
VANE_AGENT_ID=researcher-1 \
VANE_COMPANY_ID=acme \
npx @vane.build/sidecar

On startup, the sidecar:

Fetches an agent passport from Vane (using POST /v1/agents/{agentId}/passport)
Generates a MITM CA certificate and writes it to SIDECAR_CA_CERT_FILE
Starts listening on 127.0.0.1:SIDECAR_PORT
Prints configuration instructions

Output:

[vane-sidecar] Proxy listening on http://127.0.0.1:8080
[vane-sidecar] Agent: researcher-1  Company: acme

[vane-sidecar] ── MITM CA certificate ───────────────────────────────────
[vane-sidecar] Written to: ./vane-ca.pem
[vane-sidecar] Fetch via:  GET http://127.0.0.1:8080/vane-ca-cert.pem
[vane-sidecar] Trust it with one of:
[vane-sidecar]   NODE_EXTRA_CA_CERTS=./vane-ca.pem          (Node.js)
[vane-sidecar]   REQUESTS_CA_BUNDLE=./vane-ca.pem           (Python/requests)
[vane-sidecar]   SSL_CERT_FILE=./vane-ca.pem                (OpenSSL-linked tools)
[vane-sidecar] ─────────────────────────────────────────────────────────

[vane-sidecar] Set on your agent process:
[vane-sidecar]   HTTP_PROXY=http://127.0.0.1:8080
[vane-sidecar]   HTTPS_PROXY=http://127.0.0.1:8080
[vane-sidecar]   NODE_EXTRA_CA_CERTS=./vane-ca.pem

Using the sidecar — outbound (forward proxy)

Configure your agent process to use the sidecar as its HTTP proxy. Every outbound call will automatically get the agent’s Vane-Passport header injected.

HTTP

HTTP_PROXY=http://127.0.0.1:8080 \
  python my_agent.py

HTTPS (Node.js agent)

Install the MITM CA cert, then set the proxy:

# Download the CA cert from the sidecar's built-in endpoint
curl http://127.0.0.1:8080/vane-ca-cert.pem -o vane-ca.pem

NODE_EXTRA_CA_CERTS=./vane-ca.pem \
HTTPS_PROXY=http://127.0.0.1:8080 \
  node my_agent.js

HTTPS (Python agent with requests)

REQUESTS_CA_BUNDLE=./vane-ca.pem \
HTTPS_PROXY=http://127.0.0.1:8080 \
  python my_agent.py

What happens on each outbound call

The sidecar intercepts the request.
It fetches the cached passport (refreshed automatically when < 5 minutes remain before expiry).
It injects Vane-Passport: <token> into the request headers.
If no Authorization header is already set, it also injects Authorization: Bearer <passport>.
It forwards the request to the real destination.
It sends an attestation record to Vane (fire-and-forget: actionType: "outbound-http", payload: { method, url, host, path }).

Using the sidecar — inbound (reverse proxy)

Set SIDECAR_AGENT_TARGET to your agent’s local address. The sidecar will verify incoming Vane-Passport (or Authorization: Bearer <cap-jwt>) headers before forwarding to your agent.

VANE_API_URL=https://vane.build \
VANE_API_KEY=vane_a1b2c3d4... \
VANE_AGENT_ID=researcher-1 \
VANE_COMPANY_ID=acme \
SIDECAR_AGENT_TARGET=http://localhost:3001 \
npx @vane.build/sidecar

Callers hit http://127.0.0.1:8080/... — the sidecar verifies the passport locally (no Vane server call) and forwards to http://localhost:3001/.... Requests without a valid passport receive:

HTTP/1.1 401 Unauthorized
{ "error": "Missing Vane passport", "hint": "Set \"Vane-Passport: <token>\" header or \"Authorization: Bearer <cap-jwt>\"" }

or:

HTTP/1.1 401 Unauthorized
{ "error": "Vane passport is invalid or has expired" }

Downloading the MITM CA certificate

The CA cert is always available at:

GET http://127.0.0.1:<SIDECAR_PORT>/vane-ca-cert.pem

No authentication required. This endpoint exists so agents can bootstrap trust at startup without needing the cert pre-baked into their environment.

Passport caching and refresh

The sidecar caches the agent passport and automatically refreshes it when fewer than 5 minutes remain before expiry. A new passport is fetched from POST /v1/agents/{agentId}/passport with scopes: ["tool:*", "attest:write"] and a 3600-second TTL. If the Vane server is unavailable when a refresh is needed, the sidecar returns 502 on the proxied request.

Notes

The sidecar always binds to 127.0.0.1 — it is not accessible from other machines.
The MITM CA uses ECDSA P-256 (not Ed25519) because the @peculiar/x509 library used to issue certificates uses WebCrypto for CA operations.
Leaf certificates per hostname are cached for 1 hour; the CA cert is valid for 1 year.
Only HTTP/1.1 is supported for HTTPS MITM. HTTP/2 upstream connections are not implemented.

Getting Started

API Reference

SDK & Integrations

Security

Deployment

Sidecar Proxy

How it works

Configuration

Starting the sidecar

Using the sidecar — outbound (forward proxy)

HTTP

HTTPS (Node.js agent)

HTTPS (Python agent with requests)

What happens on each outbound call

Using the sidecar — inbound (reverse proxy)

Downloading the MITM CA certificate

Passport caching and refresh

Notes

​How it works

​Configuration

​Starting the sidecar

​Using the sidecar — outbound (forward proxy)

​HTTP

​HTTPS (Node.js agent)

​HTTPS (Python agent with requests)

​What happens on each outbound call

​Using the sidecar — inbound (reverse proxy)

​Downloading the MITM CA certificate

​Passport caching and refresh

​Notes

How it works

Configuration

Starting the sidecar

Using the sidecar — outbound (forward proxy)

HTTP

HTTPS (Node.js agent)

HTTPS (Python agent with requests)

What happens on each outbound call

Using the sidecar — inbound (reverse proxy)

Downloading the MITM CA certificate

Passport caching and refresh

Notes