> ## Documentation Index > Fetch the complete documentation index at: https://infisical.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # 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](/docs/documentation/platform/agent-vault/services). 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 In Agent Vault, go to **Proxies** and select **Create Proxy**. Enter a **Name**. To set the [traffic policy](#traffic-policy), [exceptions](#exceptions), or [poll interval](#poll-interval) now, expand **Advanced Options**. You can change them later. The Create Proxy dialog with the two traffic policy options and the poll interval 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. The Enrollment Token dialog with CLI, Docker, and systemd tabs and the one-hour countdown Run one of the commands on the machine where the proxy will run. The commands look like this: ```bash theme={"dark"} infisical agent-vault proxy \ --enrollment-token \ --domain ``` ```bash theme={"dark"} 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 \ --domain ``` The volume holds the state directory, so a re-created container resumes instead of needing a new token. ```ini theme={"dark"} [Unit] Description=Infisical Agent Vault proxy After=network-online.target [Service] ExecStart=/usr/local/bin/infisical agent-vault proxy --enrollment-token --domain 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`](/docs/cli/commands/agent-vault#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](#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=` 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`: ```bash theme={"dark"} infisical agent-vault proxy --domain ``` 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](#re-enroll-a-proxy). ## 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](#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](#exceptions) 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: ```text theme={"dark"} 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](/docs/documentation/platform/agent-vault/services#host-patterns) 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](/docs/documentation/platform/agent-vault/services#methods-and-paths), 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](/docs/documentation/platform/agent-vault/services#default-port) 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](/docs/documentation/platform/agent-vault/services#pass-through) 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. 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: ```bash theme={"dark"} curl -s http:///_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: ```bash theme={"dark"} export HTTPS_PROXY="http://x-agent-vault:@" 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](/docs/documentation/platform/agent-vault/sessions#revoke-a-session). 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`: ```bash theme={"dark"} infisical agent-vault run --session-token --proxy --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 ### 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](#poll-interval)) | | **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](#re-enroll-a-proxy).