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

# infisical secrets agent-proxy

> Run the Infisical Agent Proxy and connect agents to it

<Tabs>
  <Tab title="Local proxy (run)">
    ```bash theme={"dark"}
    infisical secrets agent-proxy run [options] -- [agent start command]

    # Example
    infisical secrets agent-proxy run --projectId=<project-id> --env=dev --path=/coding-agent -- claude
    ```

    `run` on its own is the whole setup.
  </Tab>

  <Tab title="Standalone proxy (start + connect)">
    ```bash theme={"dark"}
    # On the proxy host
    infisical secrets agent-proxy start [options]

    # On each agent host
    infisical secrets agent-proxy connect [options] -- [agent start command]

    # Examples
    infisical secrets agent-proxy start --port 17322
    infisical secrets agent-proxy connect --proxy=<proxy-host>:17322 --projectId=<project-id> --env=prod --path=/ai-agents -- claude
    ```

    `start` and `connect` work as a pair, on different hosts.
  </Tab>
</Tabs>

## Description

These subcommands run the [Infisical Agent Proxy](/docs/documentation/platform/agent-proxy/overview), which brokers real credentials onto your agents' traffic on the wire. Which you use depends on where the agent runs:

* `run` is for an agent on your own computer. It does the proxy's work and the agent's launch in one process, authenticating as your logged-in user, and sandboxes the agent. It always starts its own proxy, so `--proxy` is rejected rather than ignored. See [Local Agent Proxy](/docs/documentation/platform/agent-proxy/local-agent-proxy).
* `start` runs the proxy as a long-running service on a host of its own, serving agents across your network.
* `connect` launches an agent behind a proxy **already running elsewhere**, setting up proxy routing, CA trust, and placeholder credentials. It needs a proxy address, which is why it goes with `start`. Both authenticate with a [machine identity](/docs/documentation/platform/identities/machine-identities) via [Universal Auth](/docs/documentation/platform/identities/universal-auth), and the proxy's is always separate from your agents'; see [Standalone Agent Proxy](/docs/documentation/platform/agent-proxy/standalone-agent-proxy).

Each arrangement stands on its own: `run` is complete by itself, and a deployed proxy pairs only with `connect`. All three read the same [proxied services](/docs/documentation/platform/agent-proxy/proxied-services) and secrets from Infisical.

## Subcommands & flags

### Local proxy, on your own computer

<Accordion title="infisical secrets agent-proxy run" defaultOpen="true">
  Launch an agent on your own computer, sandboxed, with credentials brokered on the wire. Everything after `--` is the agent's own start command. `run` starts a proxy alongside the agent, authenticating as your logged-in user, and stops it when the agent exits. See [Local Agent Proxy](/docs/documentation/platform/agent-proxy/local-agent-proxy) for the full picture.

  Because the proxy and the agent share a machine, the sandbox is the boundary: the agent cannot read your keyring, your credential files, or the proxy's CA key, and its only route to the network is the proxy. Real secret values are never placed in the agent's environment, and it gets no Infisical token, only proxy routing, CA trust, and the placeholders for [secret-substitution](/docs/documentation/platform/agent-proxy/proxied-services#secret-substitution) services.

  Requires macOS, or Linux with `bubblewrap` installed; see [Requirements](/docs/documentation/platform/agent-proxy/local-agent-proxy#requirements) for the per-distribution command. Where no OS sandbox is available, `run` refuses to start unless you pass `--no-sandbox`.

  <Note>
    `--proxy` is rejected: `run` always starts its own proxy. To route through a proxy on another host, use `agent-proxy connect --proxy=<host>:<port>`.
  </Note>

  ```bash theme={"dark"}
  $ infisical secrets agent-proxy run --projectId=<project-id> --env=<env-slug> --path=<secret-path> -- [agent start command]

  # Example
  $ infisical secrets agent-proxy run --projectId=<project-id> --env=dev --path=/coding-agent -- claude

  # Example (project, environment, and path from .infisical.json)
  $ infisical secrets agent-proxy run -- claude
  ```

  ### Environment variables

  <Accordion title="INFISICAL_PROJECT_ID / INFISICAL_ENVIRONMENT / INFISICAL_SECRET_PATH">
    The project, environment slug, and secret path to fetch proxied services from. Alternatives to `--projectId`, `--env`, and `--path`, and to the `workspaceId`, `defaultEnvironment`, and `defaultSecretPath` fields in `.infisical.json`.

    ```bash theme={"dark"}
      # Example
      export INFISICAL_PROJECT_ID=<project-id>
      export INFISICAL_ENVIRONMENT=dev
      export INFISICAL_SECRET_PATH=/coding-agent
    ```
  </Accordion>

  <Accordion title="INFISICAL_AGENT_PROXY_SANDBOX">
    Set to `0`, `false`, or `off` to disable the OS sandbox, the same as `--no-sandbox`. Deliberately cannot be set from `.infisical.json`, so a committed file cannot silently disable the boundary.

    ```bash theme={"dark"}
      # Example
      export INFISICAL_AGENT_PROXY_SANDBOX=0
    ```
  </Accordion>

  <Accordion title="INFISICAL_DOMAIN">
    Point the CLI to your Infisical instance. Alternative to the `--domain` flag.

    ```bash theme={"dark"}
      # Example
      export INFISICAL_DOMAIN=https://eu.infisical.com
    ```
  </Accordion>

  ### Flags

  <Accordion title="--env">
    The environment slug to fetch proxied services from (for example `dev`, `staging`, `prod`). Falls back to `INFISICAL_ENVIRONMENT`, then to `defaultEnvironment` in `.infisical.json`; required otherwise.

    ```bash theme={"dark"}
    # Example
    infisical secrets agent-proxy run --env=dev -- claude
    ```
  </Accordion>

  <Accordion title="--path">
    The secret path (folder) to scope to. Proxied services are fetched from this folder. Falls back to `INFISICAL_SECRET_PATH`, then to `defaultSecretPath` in `.infisical.json`.

    ```bash theme={"dark"}
    # Example
    infisical secrets agent-proxy run --env=dev --path=/coding-agent -- claude
    ```

    Default value: `/`
  </Accordion>

  <Accordion title="--projectId">
    The project to fetch proxied services from. Falls back to `INFISICAL_PROJECT_ID`, then to `.infisical.json`.

    ```bash theme={"dark"}
    # Example
    infisical secrets agent-proxy run --env=dev --projectId=<project-id> -- claude
    ```
  </Accordion>

  <Accordion title="--token">
    Broker using this token instead of your logged-in session. Also picked up from `INFISICAL_TOKEN` or `INFISICAL_UNIVERSAL_AUTH_ACCESS_TOKEN` in your own environment (these are read by the CLI and scrubbed from the agent's environment). Activity records attribute requests to `token` rather than your email.

    ```bash theme={"dark"}
    # Example
    infisical secrets agent-proxy run --env=dev --token=<token> -- claude
    ```
  </Accordion>

  <Accordion title="--sandbox / --no-sandbox">
    Toggle the OS sandbox around the agent. With `--no-sandbox` credentials are still brokered and the environment is still scrubbed, but the agent runs uncontained: it can read your keyring and credential files and reach the network directly, bypassing the proxy. `run` warns when it starts this way. Can also be set via `INFISICAL_AGENT_PROXY_SANDBOX`.

    ```bash theme={"dark"}
    # Example
    infisical secrets agent-proxy run --env=dev --no-sandbox -- claude
    ```

    Default value: `--sandbox` (the sandbox is on)
  </Accordion>

  <Accordion title="--allow-read">
    Allow the agent to read a path the sandbox denies by default, read-only. The exception is exact: naming a file inside a denied directory leaves everything else in that directory denied. Repeatable. Prefer this to `--no-sandbox` when an agent needs one config file. `run` prints what was re-opened.

    ```bash theme={"dark"}
    # Example
    infisical secrets agent-proxy run --env=dev --allow-read ~/.aws/config -- claude
    ```
  </Accordion>

  <Accordion title="--allow-write">
    Allow the agent to write a path, in addition to the working directory, `/tmp`, and the supported agents' own state directories. Repeatable.

    ```bash theme={"dark"}
    # Example
    infisical secrets agent-proxy run --env=dev --allow-write ~/scratch -- claude
    ```
  </Accordion>

  <Accordion title="--allow-host">
    Let the agent reach a host that has no proxied service, without a credential, even under `--unmatched-host=block`. Repeatable. Has no effect under the default `allow` policy, where unmatched hosts already pass through.

    ```bash theme={"dark"}
    # Example
    infisical secrets agent-proxy run --env=dev --unmatched-host=block --allow-host=registry.npmjs.org -- claude
    ```
  </Accordion>

  <Accordion title="--pass-env">
    Pass one of your own environment variables through to the agent. The child environment is scrubbed of credential-shaped names (anything containing `TOKEN`, `SECRET`, `PASSWORD`, `API_KEY`, and similar), Infisical's own variables, and agent-socket addresses such as `SSH_AUTH_SOCK`; this re-admits a specific one. Repeatable.

    ```bash theme={"dark"}
    # Example
    infisical secrets agent-proxy run --env=dev --pass-env ANTHROPIC_API_KEY -- claude
    ```
  </Accordion>

  <Accordion title="--set-env">
    Set an environment variable in the agent as `KEY=VALUE`. Applied last, so it overrides anything else `run` sets. Repeatable.

    ```bash theme={"dark"}
    # Example
    infisical secrets agent-proxy run --env=dev --set-env GH_CONFIG_DIR=/tmp/gh-cfg -- claude
    ```
  </Accordion>

  <Accordion title="--unmatched-host">
    Policy for requests to hosts with no matching proxied service: `allow` forwards them untouched with no credentials applied; `block` rejects them with `403`, restricting the agent to the services you have defined plus any `--allow-host` entries.

    ```bash theme={"dark"}
    # Example
    infisical secrets agent-proxy run --env=dev --unmatched-host=block -- claude
    ```

    Default value: `allow`
  </Accordion>

  <Accordion title="--poll-interval">
    Seconds between permission and credential refreshes. Changes to proxied services, permissions, and secret values take effect within one interval; if your authorization lapses, cached credentials are dropped on the same cycle.

    ```bash theme={"dark"}
    # Example
    infisical secrets agent-proxy run --env=dev --poll-interval 30 -- claude
    ```

    Default value: `60`
  </Accordion>

  <Accordion title="--log-file">
    Write the proxy's [per-request activity](/docs/documentation/platform/agent-proxy/activity-logs) to this path. Without it nothing is logged, since the agent owns the terminal: warnings and errors still print there, but the per-request trail is dropped. The path is appended to on every run and never rotated for you, so use `logrotate` (`copytruncate`) if you keep one. `--log-level` filters which decisions are recorded, the same as on `start`.

    ```bash theme={"dark"}
    # Example
    infisical secrets agent-proxy run --env=dev --log-file=/tmp/broker.log -- claude
    ```
  </Accordion>
</Accordion>

### Standalone proxy, on a host of its own

These two are used together, on different hosts: `start` on the proxy host, `connect` on each agent host.

<Accordion title="infisical secrets agent-proxy start">
  Start the agent proxy, an HTTP(S) forward proxy that brokers credentials for the agents that connect to it. Requires machine identity credentials with read access to the secrets your proxied services reference.

  Agents reach HTTPS services through standard `CONNECT` tunnels and plain-HTTP services through regular forward-proxy requests; credentials are brokered on both. Requests for `https://` URLs sent as plain forward-proxy requests (rather than `CONNECT`) are rejected so the proxy can never be used to downgrade TLS.

  ```bash theme={"dark"}
  $ infisical secrets agent-proxy start

  # Example
  $ infisical secrets agent-proxy start --port 17322 --unmatched-host=block
  ```

  ### Environment variables

  <Accordion title="INFISICAL_UNIVERSAL_AUTH_CLIENT_ID / INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET">
    The Universal Auth credentials of the agent proxy's machine identity. Alternative to passing `--client-id` and `--client-secret`.

    ```bash theme={"dark"}
      # Example
      export INFISICAL_UNIVERSAL_AUTH_CLIENT_ID=<agent-proxy-client-id>
      export INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET=<agent-proxy-client-secret>
    ```
  </Accordion>

  <Accordion title="INFISICAL_DOMAIN">
    Point the CLI to your Infisical instance (for example `https://eu.infisical.com` for EU Cloud, or your self-hosted URL). Alternative to the `--domain` flag.

    ```bash theme={"dark"}
      # Example
      export INFISICAL_DOMAIN=https://eu.infisical.com
    ```
  </Accordion>

  ### Flags

  <Accordion title="--port">
    Port for the agent proxy to listen on.

    ```bash theme={"dark"}
    # Example
    infisical secrets agent-proxy start --port 18000
    ```

    Default value: `17322`
  </Accordion>

  <Accordion title="--unmatched-host">
    Policy for requests to hosts with no matching proxied service: `allow` forwards them untouched with no credentials applied (the normal mode: documentation, package registries, and services the agent authenticates to itself pass straight through); `block` rejects them with `403`, restricting agents to the services you have defined.

    ```bash theme={"dark"}
    # Example
    infisical secrets agent-proxy start --unmatched-host=block
    ```

    Default value: `allow`

    <Note>
      `block` blocks every host without a matching proxied service, including your Infisical instance itself. Since agent traffic routes through the proxy, Infisical CLI commands run from inside the agent (using the `INFISICAL_TOKEN` from its environment) will also be rejected in this mode.
    </Note>
  </Accordion>

  <Accordion title="--poll-interval">
    Seconds between permission and credential refreshes for active agents. Changes to proxied services, permissions, and secret values (for example, after a rotation) take effect within one interval.

    ```bash theme={"dark"}
    # Example
    infisical secrets agent-proxy start --poll-interval 30
    ```

    Default value: `60`
  </Accordion>

  <Accordion title="--client-id / --client-secret">
    Universal Auth credentials for the agent proxy's machine identity. Alternative to the `INFISICAL_UNIVERSAL_AUTH_CLIENT_ID` / `INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET` environment variables.

    ```bash theme={"dark"}
    # Example
    infisical secrets agent-proxy start --client-id=<client-id> --client-secret=<client-secret>
    ```
  </Accordion>

  <Accordion title="--log-format">
    Output format for the proxy's logs, including [per-request activity](/docs/documentation/platform/agent-proxy/activity-logs): `console` (human-readable, colorized in a terminal and plain otherwise) or `json` (machine). Logs are written to stderr.

    ```bash theme={"dark"}
    # Example
    infisical secrets agent-proxy start --log-format=json
    ```

    Default value: `console`
  </Accordion>

  <Accordion title="--log-file">
    Also write logs as `json` to this file, in addition to the console/json stream. Lets you watch the console and persist machine-readable logs at the same time. Rotate it with `logrotate` (`copytruncate`) or restart the proxy.

    ```bash theme={"dark"}
    # Example
    infisical secrets agent-proxy start --log-file=/var/log/infisical/agent-proxy.log
    ```
  </Accordion>

  <Accordion title="--log-level">
    Controls how much is logged. Each [activity decision](/docs/documentation/platform/agent-proxy/activity-logs) maps to a level (`passthrough`=debug, `canceled`=debug, `brokered`=info, `blocked`=warn, `error`=error), so this doubles as the activity filter: `debug` shows everything, the default `info` hides passthrough and canceled requests, `warn` shows only blocked and errors.

    ```bash theme={"dark"}
    # Example
    infisical secrets agent-proxy start --log-level=warn
    ```

    Default value: `info`
  </Accordion>
</Accordion>

<Accordion title="infisical secrets agent-proxy connect">
  Set up the environment and launch an agent behind the agent proxy. Everything after `--` is the agent's own start command. The wrapper authenticates the agent's machine identity, then starts the agent process with:

  * `HTTPS_PROXY` / `HTTP_PROXY` pointing at the agent proxy, plus `NO_PROXY` (always includes `localhost,127.0.0.1`, merged with any `NO_PROXY` already in your environment and the `--no-proxy` flag).
  * The organization's root CA written to `~/.infisical/agent-proxy/mitm-ca.pem` and trusted via `SSL_CERT_FILE`, `NODE_EXTRA_CA_CERTS`, `REQUESTS_CA_BUNDLE`, `CURL_CA_BUNDLE`, `GIT_SSL_CAINFO`, and `DENO_CERT`.
  * Dummy placeholder environment variables for credential-substitution services the agent has **Proxy** access to.
  * Real values for regular secrets the agent has **Read Value** on in the scoped folder, including secrets imported into it (similar to `infisical run`). This is opt-in; an agent identity scoped to just the proxy permission has no read access, and brokered credentials never appear in the agent's environment. If the agent can read a secret that a proxied service brokers to it, `connect` refuses to start, since the agent would receive the real value directly and bypass the proxy; fix the permissions or pass `--allow-readable-brokered-secrets` to override.
  * `INFISICAL_TOKEN` set to the agent's access token, so the agent can run Infisical CLI commands itself.

  The client ID and client secret used to authenticate are stripped from the child environment. The wrapper forwards signals to the agent process and exits with its exit code.

  <Note>
    Every input below resolves from the same sources, in order: **the flag → an environment variable → `.infisical.json` → the built-in default.** An explicitly-passed flag always wins. This is why, where the environment variables are already set on the host, the command collapses to `infisical secrets agent-proxy connect -- claude`.
  </Note>

  ```bash theme={"dark"}
  $ infisical secrets agent-proxy connect --proxy=<host>:<port> --projectId=<project-id> --env=<env-slug> -- [agent start command]

  # With flags
  $ infisical secrets agent-proxy connect --proxy=<proxy-host>:17322 --projectId=<project-id> --env=prod --path=/ai-agents -- claude

  # With configuration from environment variables (see below) or .infisical.json
  $ infisical secrets agent-proxy connect -- claude
  ```

  ### Environment variables

  <Accordion title="INFISICAL_UNIVERSAL_AUTH_CLIENT_ID / INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET">
    The Universal Auth credentials of the agent's machine identity. Alternative to passing `--client-id` and `--client-secret`.

    ```bash theme={"dark"}
      # Example
      export INFISICAL_UNIVERSAL_AUTH_CLIENT_ID=<agent-client-id>
      export INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET=<agent-client-secret>
    ```
  </Accordion>

  <Accordion title="INFISICAL_PROJECT_ID">
    The project to fetch proxied services and secrets from. Alternative to the `--projectId` flag or the `workspaceId` field in `.infisical.json` (created by `infisical init`).

    ```bash theme={"dark"}
      # Example
      export INFISICAL_PROJECT_ID=<project-id>
    ```
  </Accordion>

  <Accordion title="INFISICAL_ENVIRONMENT">
    The environment slug to fetch proxied services and secrets from. Alternative to the `--env` flag or the `defaultEnvironment` field in `.infisical.json`.

    ```bash theme={"dark"}
      # Example
      export INFISICAL_ENVIRONMENT=prod
    ```
  </Accordion>

  <Accordion title="INFISICAL_SECRET_PATH">
    The secret path (folder) to scope to. Alternative to the `--path` flag or the `defaultSecretPath` field in `.infisical.json`.

    ```bash theme={"dark"}
      # Example
      export INFISICAL_SECRET_PATH=/ai-agents
    ```
  </Accordion>

  <Accordion title="INFISICAL_AGENT_PROXY_ADDRESS">
    Address of the agent proxy as `host:port`. Alternative to the `--proxy` flag.

    ```bash theme={"dark"}
      # Example
      export INFISICAL_AGENT_PROXY_ADDRESS=<proxy-host>:17322
    ```
  </Accordion>

  <Accordion title="INFISICAL_DOMAIN">
    Point the CLI to your Infisical instance. Alternative to the `--domain` flag.

    ```bash theme={"dark"}
      # Example
      export INFISICAL_DOMAIN=https://eu.infisical.com
    ```
  </Accordion>

  ### Flags

  <Accordion title="--proxy">
    Address of the agent proxy as `host:port`. Required, unless provided via `INFISICAL_AGENT_PROXY_ADDRESS`.

    ```bash theme={"dark"}
    # Example
    infisical secrets agent-proxy connect --proxy=<proxy-host>:17322 --env=prod -- claude
    ```
  </Accordion>

  <Accordion title="--env">
    The environment slug to fetch proxied services and secrets from (for example `dev`, `staging`, `prod`). Falls back to `INFISICAL_ENVIRONMENT`, then to the `defaultEnvironment` (and git-branch mapping) in `.infisical.json`; required otherwise.

    ```bash theme={"dark"}
    # Example
    infisical secrets agent-proxy connect --proxy=<proxy-host>:17322 --env=staging -- codex
    ```
  </Accordion>

  <Accordion title="--path">
    The secret path (folder) to scope to. Proxied services and secrets are fetched from this folder. Falls back to `INFISICAL_SECRET_PATH`, then to the `defaultSecretPath` field in `.infisical.json`.

    ```bash theme={"dark"}
    # Example
    infisical secrets agent-proxy connect --proxy=<proxy-host>:17322 --env=prod --path=/ai-agents -- claude
    ```

    Default value: `/`
  </Accordion>

  <Accordion title="--no-proxy">
    Additional comma-separated hosts that should bypass the proxy. Always merged with `localhost,127.0.0.1` and any `NO_PROXY` already set in your environment.

    ```bash theme={"dark"}
    # Example
    infisical secrets agent-proxy connect --proxy=<proxy-host>:17322 --env=prod --no-proxy=internal.corp.com -- claude
    ```
  </Accordion>

  <Accordion title="--projectId">
    The project to fetch proxied services and secrets from. Falls back to the `INFISICAL_PROJECT_ID` environment variable, then to `.infisical.json`.

    ```bash theme={"dark"}
    # Example
    infisical secrets agent-proxy connect --proxy=<proxy-host>:17322 --env=prod --projectId=<project-id> -- claude
    ```
  </Accordion>

  <Accordion title="--client-id / --client-secret">
    Universal Auth credentials for the agent's machine identity. Alternative to the `INFISICAL_UNIVERSAL_AUTH_CLIENT_ID` / `INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET` environment variables.

    ```bash theme={"dark"}
    # Example
    infisical secrets agent-proxy connect --proxy=<proxy-host>:17322 --env=prod --client-id=<client-id> --client-secret=<client-secret> -- claude
    ```
  </Accordion>

  <Accordion title="--token">
    Authenticate with a pre-fetched machine identity access token instead of client credentials.

    ```bash theme={"dark"}
    # Example
    infisical secrets agent-proxy connect --proxy=<proxy-host>:17322 --env=prod --token=<access-token> -- claude
    ```
  </Accordion>

  <Accordion title="--allow-readable-brokered-secrets">
    Start even if the agent can **Read Value** on a secret that a proxied service brokers to it. By default `connect` refuses to start in that case, since the agent would receive the real value directly and bypass the proxy, defeating the point of brokering it. This is a misconfiguration guardrail, not a security boundary: the real fix is to not grant the agent read access to brokered secrets. Use this flag only for the rare intentional case. Can also be set via `INFISICAL_AGENT_PROXY_ALLOW_READABLE_BROKERED_SECRETS`.

    ```bash theme={"dark"}
    # Example
    infisical secrets agent-proxy connect --proxy=<proxy-host>:17322 --env=prod --allow-readable-brokered-secrets -- claude
    ```

    Default value: `false`
  </Accordion>
</Accordion>

### Shared

<Accordion title="Flags accepted by every subcommand">
  <Accordion title="--domain">
    Point the CLI to your Infisical instance (for example `https://eu.infisical.com` for EU Cloud, or your self-hosted URL). Can also be set via the `INFISICAL_DOMAIN` environment variable or the `domain` field in `.infisical.json`. Required for non-US Cloud users.

    ```bash theme={"dark"}
    # Example
    infisical secrets agent-proxy start --domain=https://your-instance.com
    ```

    Default value: `https://app.infisical.com`
  </Accordion>
</Accordion>