Proxies

A proxy intercepts your agents’ requests to the APIs they call, then attaches the necessary API credential to each request that matches a service. Run the proxy where agent traffic leaves your network, either on its own host that several agents share, or next to each agent, such as in a sidecar container. You create a proxy in Infisical, start it with the proxy token that Infisical shows you, and change its settings in Infisical afterwards. You can run the same proxy on as many machines as you need with one token, such as several machines behind a load balancer.

Choose where to run the proxy

While you can technically run the agent and the proxy on a single machine, we recommend running the proxy on a different machine from the agent. If the agent and the proxy run on the same machine, the agent could read the proxy token and the private key of the proxy’s certificate authority.

We also recommend keeping both machines on the same private network. This is because every request the agent makes goes through the proxy, and a round trip between networks adds latency to every request.

Supported connections

The proxy attaches credentials to HTTP/1.1 requests, over both HTTPS and plain HTTP. These connections fail through the proxy:

WebSocket connections, such as to a wss:// URL
Clients that only speak HTTP/2, such as gRPC clients

If an API offers both, configure the agent to use its plain HTTPS requests. Many SDKs fall back to HTTPS when a WebSocket connection fails.

Create a proxy and start it

In Agent Vault, go to Proxies and select Create Proxy.

Enter a Name. To set the traffic policy, exceptions, or poll interval now, expand Advanced Options. You can change these settings later.

The Create Proxy dialog with the two traffic policy options and the poll interval

Select Create. The Proxy Token dialog shows the proxy token, and commands for the CLI, systemd, Docker, and Kubernetes with your token and instance filled in.

Run one of the commands on each machine where the proxy will run.

The commands look like this:

CLI
Docker
Kubernetes
systemd

INFISICAL_AGENT_VAULT_PROXY_TOKEN=<proxy-token> \
infisical agent-vault proxy \
  --domain <your-instance-url>

docker run -d --name agent-vault-proxy \
  -p 17323:17323 \
  -v agent-vault-proxy:/etc/infisical/agent-vault \
  -e INFISICAL_AGENT_VAULT_PROXY_TOKEN=<proxy-token> \
  infisical/cli agent-vault proxy \
  --domain <your-instance-url>

The volume keeps the proxy’s cache, so the proxy can start even if Infisical is unreachable.

apiVersion: v1
kind: Secret
metadata:
  name: agent-vault-proxy
type: Opaque
stringData:
  INFISICAL_AGENT_VAULT_PROXY_TOKEN: <proxy-token>
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: agent-vault-proxy
spec:
  replicas: 2
  selector:
    matchLabels:
      app: agent-vault-proxy
  template:
    metadata:
      labels:
        app: agent-vault-proxy
    spec:
      containers:
        - name: agent-vault-proxy
          image: infisical/cli
          args: ["agent-vault", "proxy", "--domain", "<your-instance-url>"]
          envFrom:
            - secretRef:
                name: agent-vault-proxy
          ports:
            - containerPort: 17323
---
apiVersion: v1
kind: Service
metadata:
  name: agent-vault-proxy
spec:
  selector:
    app: agent-vault-proxy
  ports:
    - port: 17323
      targetPort: 17323

The manifest in the dialog has no Service. Add the Service from the end of this example so that agents in the cluster can reach the proxy at agent-vault-proxy:17323.

Save the token in /etc/infisical/agent-vault-proxy.env:

INFISICAL_AGENT_VAULT_PROXY_TOKEN=<proxy-token>

Run sudo chmod 600 /etc/infisical/agent-vault-proxy.env so that only root can read the file. Then save this unit as /etc/systemd/system/agent-vault-proxy.service:

[Unit]
Description=Infisical Agent Vault proxy
After=network-online.target
Wants=network-online.target

[Service]
EnvironmentFile=/etc/infisical/agent-vault-proxy.env
ExecStart=/usr/local/bin/infisical agent-vault proxy --domain <your-instance-url>
Restart=always

[Install]
WantedBy=multi-user.target

Run sudo systemctl enable --now agent-vault-proxy to start the proxy now and every time the machine boots.

Command flags

The commands use these settings:

INFISICAL_AGENT_VAULT_PROXY_TOKEN or --proxy-token: the proxy token (prefer the environment variable, because other users on the machine can read anything on a command line)
--domain or INFISICAL_DOMAIN: your Infisical instance URL (required for EU Cloud and self-hosted instances, because the default is Infisical Cloud in the US)

Each time the proxy starts, it loads its settings and certificate authority from Infisical and, if it can, saves a copy in its data directory (~/.infisical/agent-vault, or /etc/infisical/agent-vault as root, or --data-dir). If it can’t reach Infisical for 60 seconds, it starts from that copy, or exits if there isn’t one.

For the proxy’s other flags, such as the port and the data directory, check out the agent-vault proxy CLI reference.

Settings

To change a setting, select Edit Settings on the proxy’s menu. If the proxy is running, it applies the change within one poll interval (60 seconds by default).

Traffic policy

The Traffic Policy setting controls which hosts agents can reach through the proxy:

Any host (default): the proxy forwards every request, and attaches a credential only for hosts covered by a service
Access bundle hosts only: the proxy refuses requests to hosts that no service in the session’s access bundle covers, unless the host is an exception

Use Access bundle hosts only if the proxy can reach systems that agents shouldn’t have access to, such as internal services on the same network.

Blocked requests

If the policy blocks a request, the proxy still accepts the connection and completes the TLS handshake, so the agent gets a 403 response instead of a connection error:

HTTP/1.1 403 Forbidden

no service covers host "internal.example.com": host blocked by policy

The proxy also returns a 403 for:

A request to a port the service’s host pattern doesn’t name, such as example.com:8443 for a service on example.com, which only covers port 443
A request that breaks the service’s method or path rules, under either traffic policy
A request to a service that needs the session owner’s personal values, before they set them up

Exceptions

Exceptions allow your agents to access hosts that aren’t covered by any service in an access bundle, even when your proxy uses Access bundle hosts only. Use exceptions for hosts every agent needs, such as a package registry or a documentation site. To add exceptions, select the policy and enter the hosts in Exceptions as a comma-separated list. The field doesn’t appear under Any host, because that policy already lets every host through. Exception hosts behave differently from hosts that are covered by services:

Credentials: The proxy never attaches a credential to requests to an exception host
Ports: An exception with no port matches the host on every port, while a service’s host pattern with no port only matches port 443
Interception: The proxy still decrypts requests to an exception host, but doesn’t block them
Scope: An exception applies to every agent that uses the proxy

To let only one access bundle reach a host, add a pass-through service to that bundle instead of adding an exception to the proxy.

Poll interval

The poll interval is how often, in seconds, the proxy re-checks each active session with Infisical and applies settings changes. It defaults to 60 and can be set from 10 to 300. If the proxy can’t reach Infisical:

The proxy keeps using the session data it last fetched for five poll intervals
After that, the proxy refuses the affected requests with a 502 until it reaches Infisical again, instead of forwarding them without their credentials
The Proxies page marks the proxy Unreachable after three missed check-ins

Certificate trust

The proxy decrypts HTTPS traffic to attach the credential, so each agent has to trust the proxy’s certificate authority (CA). Infisical generates a self-signed CA for each proxy when you create the proxy, and a new one each time you rotate the proxy’s token.

With the CLI
Without the CLI

If you start the agent with infisical agent-vault run, the CLI sets up trust for you. On every run, it fetches the certificate from the proxy and sets these variables for the agent: SSL_CERT_FILE, NODE_EXTRA_CA_CERTS, REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE, GIT_SSL_CAINFO, and DENO_CERT.On macOS, if you run the CLI in a terminal, it also adds the certificate to your login keychain for tools such as gh and docker that read the system trust store. macOS asks you to approve the change. To skip this step on a machine that already trusts the proxy, pass --no-ca-trust.

If you start the agent another way, such as in a container that sets HTTPS_PROXY itself, set up trust yourself:

Download the certificate from the proxy:

curl -s http://<proxy-address>/_agent-vault/ca | jq -r .certificate > ca.pem

Mount ca.pem where the agent can read it, and point the agent’s CA variables at it, such as SSL_CERT_FILE and NODE_EXTRA_CA_CERTS.

Route the agent through the proxy, with the session token as the password:

export HTTPS_PROXY="http://x-agent-vault:<session-token>@<proxy-address>"
export HTTP_PROXY="$HTTPS_PROXY"

To set the proxy and the certificate in your own agent’s code instead, see Connect your own agent.

Agents send their session token to the proxy unencrypted with every request. If someone can read that traffic and reach the proxy, they can use the token to call every API in the session’s access bundle with its real credentials. The token keeps working until the session expires or you revoke it.For this reason, we recommend running the proxy where only your agents can reach it, such as on the same host, a private network, or a container network.

Pin the proxy’s certificate

If the agent runs on a network you don’t fully control, pin the proxy’s certificate so the agent only talks to your proxy. Copy the fingerprint from the Certificate Authority column on the Proxies page, and pass it with --ca-fingerprint:

infisical agent-vault run --session-token <session-token> --proxy <proxy-address> --ca-fingerprint SHA256:9F:2C:... -- claude

If the proxy’s certificate doesn’t match, the CLI stops before starting the agent.

The Proxies page showing two healthy proxies with their traffic policy and certificate authority fingerprints

Use your own certificate authority

To serve your own CA instead of the one Infisical generates, pass it to the proxy with --ca-cert and --ca-key, or with the INFISICAL_AGENT_VAULT_CA_CERT and INFISICAL_AGENT_VAULT_CA_KEY environment variables. Each value can be the PEM text, the PEM encoded as base64, or the path to a PEM file. The key has to be an ECDSA P-256 key.

INFISICAL_AGENT_VAULT_PROXY_TOKEN=<proxy-token> \
infisical agent-vault proxy --ca-cert ./ca.crt --ca-key ./ca.key

The Proxies page shows the fingerprint of the CA that the proxy reported the last time it started. Pass the same CA to every machine that runs this proxy, for example in a high availability setup. Your own CA stays the same when you rotate the proxy’s token. To use the CA Infisical generates again, leave out these flags.

APIs with a private certificate authority

The proxy checks the certificate of each API it connects to, the way any HTTPS client does. If an API uses a private certificate authority, the machine running the proxy has to trust that authority. The agent’s machine doesn’t need to trust it.

Rotate a proxy’s token

Rotate the token if it leaked, or to bring back a proxy whose access you revoked:

On the Proxies page, select Rotate Proxy Token on the proxy’s menu, then select Rotate.

Store the new token from the Proxy Token dialog somewhere safe.

Restart the proxy with the new token on every machine where it runs.

The current token will stop working, and the proxy gets a new certificate authority. After you rotate the token:

Restart every agent that uses the proxy, because those agents still trust the old certificate
Update any --ca-fingerprint pin
Replace any ca.pem file you mounted for an agent
On macOS, replace the certificate in your login keychain

If you use your own certificate authority, only the token changes, so your agents don’t need these updates.

Revoke or delete a proxy

Both actions are on the proxy’s menu:

Action	What happens
Revoke Access	The proxy will stop adding credentials to requests. To bring it back, rotate its token
Delete	Infisical removes the proxy, and the proxy will stop adding credentials to requests. You can’t undo this

Revoke access if you think a machine running the proxy is compromised.

High availability

To keep the proxy available when one machine goes down, run it on several machines with the same proxy token and put a load balancer in front of them. Every machine serves the same certificate authority, so agents trust whichever machine they reach.

Load balancer type: use a TCP (layer 4) load balancer, because agents send CONNECT requests that most HTTP load balancers don’t forward. You don’t need sticky sessions
Health checks: send an HTTP GET to /_agent-vault/ca on each machine, which returns 200 while the proxy is serving
Your own certificate authority (optional): if you want to use your own, pass the same --ca-cert and --ca-key to every machine

Point agents at the load balancer’s address instead of a single machine. On Infisical Cloud, every machine running a proxy shares that proxy’s rate limits.

Get started

Guides

Concepts

Choose where to run the proxy

Supported connections

Create a proxy and start it

Command flags

Settings

Traffic policy

Blocked requests

Exceptions

Poll interval

Certificate trust

Pin the proxy’s certificate

Use your own certificate authority

APIs with a private certificate authority

Rotate a proxy’s token

Revoke or delete a proxy

High availability

​Choose where to run the proxy

​Supported connections

​Create a proxy and start it

​Command flags

​Settings

​Traffic policy

​Blocked requests

​Exceptions

​Poll interval

​Certificate trust

​Pin the proxy’s certificate

​Use your own certificate authority

​APIs with a private certificate authority

​Rotate a proxy’s token

​Revoke or delete a proxy

​High availability

Choose where to run the proxy

Supported connections

Create a proxy and start it

Command flags

Settings

Traffic policy

Blocked requests

Exceptions

Poll interval

Certificate trust

Pin the proxy’s certificate

Use your own certificate authority

APIs with a private certificate authority

Rotate a proxy’s token

Revoke or delete a proxy

High availability