Proxies

Run the proxy that attaches credentials, set its traffic policy, and understand how agents trust it.

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 on the same machine as one agent.

You create a proxy in Infisical, enroll it once from the CLI, and change its settings in Infisical afterwards.

Create and enroll a proxy

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

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

   
3. Select Create. The Enrollment Token dialog shows a one-time token that expires in an hour, and commands for the CLI, Docker, and systemd with your token and instance filled in.

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

The commands look like this:

CLI

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

Docker

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

The volume holds the state directory, so a re-created container resumes instead of needing a new token.

systemd

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

[Service]
ExecStart=/usr/local/bin/infisical agent-vault proxy --enrollment-token <enrollment-token> --domain <your-instance-url>
Restart=always

[Install]
WantedBy=multi-user.target

Save it as /etc/systemd/system/agent-vault-proxy.service, then run sudo systemctl enable --now agent-vault-proxy.

Command flags

Here’s a list of available flags for the infisical agent-vault proxy command:

Option	What it sets
--enrollment-token	The one-time token from the Enrollment Token dialog. You can set INFISICAL_AGENT_VAULT_ENROLLMENT_TOKEN instead
--domain	Your Infisical instance URL. It defaults to Infisical Cloud (US), and the commands in the dialog already include your instance’s URL
--port	The port the proxy listens on. It defaults to 17323
--data-dir	Where the proxy keeps its state. See state directory

Other users on the machine can read anything on a command line. To keep the enrollment token off it, put INFISICAL_AGENT_VAULT_ENROLLMENT_TOKEN=<enrollment-token> in a file with mode 0600, and pass the file with --env-file for Docker or EnvironmentFile= for systemd. You can delete the file once the proxy has enrolled.

State directory

When the proxy enrolls, it generates its own certificate authority and saves it with its enrollment in a state directory at ~/.infisical/agent-vault (or /etc/infisical/agent-vault if you run the proxy as the root user on the machine).

The enrollment token only works once. After the first run, the proxy reads its enrollment from the state directory, so you can restart the proxy without --enrollment-token:

infisical agent-vault proxy --domain <your-instance-url>

If the state directory is empty, the proxy can’t start without a new token. Select New Enrollment Token on the proxy’s menu and enroll again.

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

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). Each proxy generates its own self-signed CA when it enrolls.

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

Without the CLI

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

1. Download the certificate from the proxy:

   curl -s http://<proxy-address>/_agent-vault/ca | jq -r .certificate > ca.pem
   
2. 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.

3. 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"
   

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.

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.

Re-enroll a proxy

To re-enroll a proxy, select New Enrollment Token on the proxy’s menu and run the new command. The proxy keeps its name, settings, and history, but gets a new certificate authority.

After you re-enroll a proxy:

• Restart every agent that uses the proxy, because those agents still trust the old certificate
• Update any --ca-fingerprint pin
• Replace any mounted copy of the certificate
• On macOS, replace the certificate in your login keychain

Revoke or delete a proxy

Both actions are on the proxy’s menu:

Action	What happens
Revoke Access	The proxy’s token stops working right away. Every agent using the proxy loses its credentials, and the proxy answers requests with a 503. The proxy process exits after two failed check-ins in a row (one to two poll intervals)
Delete	Infisical removes the proxy. If the proxy is running, it stops working and exits the same way as a revoked proxy

Revoke access if you think the proxy’s host is compromised. To bring a revoked proxy back, re-enroll it.