Skip to main content
run on its own is the whole setup.

​
Description

These subcommands run the Infisical Agent Proxy, 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.
  • 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 via Universal Auth, and the proxy’s is always separate from your agents’; see 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 and secrets from Infisical.

​
Subcommands & flags

​
Local proxy, on your own computer

infisical secrets agent-proxy run

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 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 services.Requires macOS, or Linux with bubblewrap installed; see Requirements for the per-distribution command. Where no OS sandbox is available, run refuses to start unless you pass --no-sandbox.
--proxy is rejected: run always starts its own proxy. To route through a proxy on another host, use agent-proxy connect --proxy=<host>:<port>.

​
Environment variables

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.
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.
Point the CLI to your Infisical instance. Alternative to the --domain flag.

​
Flags

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.
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.
Default value: /
The project to fetch proxied services from. Falls back to INFISICAL_PROJECT_ID, then to .infisical.json.
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.
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.
Default value: --sandbox (the sandbox is on)
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.
Allow the agent to write a path, in addition to the working directory, /tmp, and the supported agents’ own state directories. Repeatable.
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.
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.
Set an environment variable in the agent as KEY=VALUE. Applied last, so it overrides anything else run sets. Repeatable.
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.
Default value: allow
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.
Default value: 60
Write the proxy’s per-request activity 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.

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

​
Environment variables

The Universal Auth credentials of the agent proxy’s machine identity. Alternative to passing --client-id and --client-secret.
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.

​
Flags

Port for the agent proxy to listen on.
Default value: 17322
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.
Default value: allow
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.
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.
Default value: 60
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.
Output format for the proxy’s logs, including per-request activity: console (human-readable, colorized in a terminal and plain otherwise) or json (machine). Logs are written to stderr.
Default value: console
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.
Controls how much is logged. Each activity decision maps to a level (passthrough=debug, brokered=info, blocked=warn, error=error), so this doubles as the activity filter: debug shows everything, the default info hides passthrough, warn shows only blocked and errors.
Default value: info
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.
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.

​
Environment variables

The Universal Auth credentials of the agent’s machine identity. Alternative to passing --client-id and --client-secret.
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).
The environment slug to fetch proxied services and secrets from. Alternative to the --env flag or the defaultEnvironment field in .infisical.json.
The secret path (folder) to scope to. Alternative to the --path flag or the defaultSecretPath field in .infisical.json.
Address of the agent proxy as host:port. Alternative to the --proxy flag.
Point the CLI to your Infisical instance. Alternative to the --domain flag.

​
Flags

Address of the agent proxy as host:port. Required, unless provided via INFISICAL_AGENT_PROXY_ADDRESS.
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.
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.
Default value: /
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.
The project to fetch proxied services and secrets from. Falls back to the INFISICAL_PROJECT_ID environment variable, then to .infisical.json.
Universal Auth credentials for the agent’s machine identity. Alternative to the INFISICAL_UNIVERSAL_AUTH_CLIENT_ID / INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET environment variables.
Authenticate with a pre-fetched machine identity access token instead of client credentials.
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.
Default value: false

​
Shared

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.
Default value: https://app.infisical.com