Network and Proxy

These variables control how Claude Code reaches the network. They set the API base URL, proxies, custom certificates, timeouts, and retry counts. Use them behind a company proxy or when you route traffic through a gateway.

This page lists 64 variables. HTTPS_PROXY, NO_PROXY, and ANTHROPIC_BASE_URL are the usual ones. Project settings cannot set some endpoint variables before you trust the folder.

Example

export HTTPS_PROXY="http://proxy.example:8080"
export NO_PROXY="localhost,127.0.0.1"
export API_TIMEOUT_MS=1200000
claude

API calls go through the proxy and wait up to 20 minutes.

Variables

The table is sorted by name. See Environment Variables for what each column and badge means.

Variable	Status	What it does	Values and default	Notes
all_proxy	Undocumented	Lower case proxy variable. It is the last fallback after HTTPS_PROXY and ALL_PROXY for git proxy settings.	Text. Non-empty string. Also listed with proxy names	All sessions
ANTHROPIC_BASE_URL	Documented	Overrides the API endpoint. A non-first-party host changes first-party checks, such as Remote Control. Since 2.1.304 tool search stays on behind a custom URL, and a 400 or 422 from the gateway is retried without it.	Text. An unset value or an Anthropic host counts as first party	All sessions. Not set from project env before trust
ANTHROPIC_CUSTOM_HEADERS	Documented	Adds custom request headers.	Text. Split on new lines, each Name: Value at the first colon. Bad header names or values are dropped with a warning	All sessions. Not set from project env before trust
ANTHROPIC_UNIX_SOCKET	Documented	Sends first-party API requests over this Unix socket path.	Text. Passed as the unix fetch option. Also in the host-managed provider list with CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST	First-party API client, all. Not set from project env before trust
API_FORCE_IDLE_TIMEOUT	Documented	Forces the streaming body idle timeout on or off.	A number. A true value forces it on and a false value (0) turns the fetch timeout off	Anthropic API client, all. Not set from project env before trust
API_TIMEOUT_MS	Documented	Sets the API request timeout in milliseconds.	A number of milliseconds, 600000 (10 minutes) by default. Whole number. Errors show a hint to raise it	All sessions. Not set from project env before trust
CARGO_HTTP_CAINFO	Undocumented	Names the CA bundle file for Cargo. Claude Code sets it to the sandbox CA bundle for sandboxed commands, next to SSL_CERT_FILE and others.	Text. Also in a list of CA env names	Sandboxed commands and remote sessions
CLAUDE_AGENT_SDK_CLIENT_APP	Documented	Names the client app of an Agent SDK host. Claude Code adds it to the user agent as client-app/<value>.	Text	SDK hosts. Not set from project env before trust
CLAUDE_AGENT_SDK_VERSION	Undocumented	Reports the Agent SDK version. Claude Code adds it to the user agent as agent-sdk/<value>.	Text. The SDK host sets it	SDK hosts. Not set from project env before trust
CLAUDE_BG_GATEWAY_WITHHELD	Undocumented	Names a gateway setting that the dispatcher did not pass to a background session. The session then prints a no-gateway hint.	Text. Active only when ANTHROPIC_BASE_URL is unset. Scrubbed from child env	Background sessions. Not set from project env before trust
CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS	Documented	Sets the idle timeout of the byte-level streaming watchdog.	A number of milliseconds. Whole number of 1 or more, clamped to 10000-1800000. Else a first-party default of 180000 from a feature flag	API streaming. Not set from project env before trust
CLAUDE_CODE_ADDITIONAL_PROTECTION	Undocumented	Adds the x-anthropic-additional-protection: true header to API requests.	On or off. Read when Claude Code builds the API client	API requests. Not set from project env before trust
CLAUDE_CODE_API_BASE_URL	Undocumented	Gives a fallback API base URL. The Files API uses it when ANTHROPIC_BASE_URL is unset. Default https://api.anthropic.com.	Text. ANTHROPIC_BASE_URL wins when both are set. Credential checks also treat it as a base URL source	First-party API and Files API. Not set from project env before trust
CLAUDE_CODE_ATTRIBUTION_HEADER	Documented	Controls the attribution block at the start of the system prompt. A falsy value such as 0 omits it.	Text. Policy settings have a rule for it. Repo-committed settings may not re-point it	First-party API, not CLAUDE_CODE_REMOTE
CLAUDE_CODE_CERT_STORE	Documented	Chooses the CA certificate sources for TLS.	A comma-separated list, bundled,system by default	All sessions
CLAUDE_CODE_CLIENT_CERT	Documented	Gives the path of the client certificate file for mTLS.	Text. Claude Code reads the file and skips a cert and key that do not match	All sessions
CLAUDE_CODE_CLIENT_KEY	Documented	Gives the path of the client private key file for mTLS.	Text. Claude Code reads the file	All sessions
CLAUDE_CODE_CLIENT_KEY_PASSPHRASE	Documented	Gives the passphrase of an encrypted client key.	Text. Used for the key check and the TLS agent	All sessions
CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTION	Documented	Stops the re-read of the mTLS client cert and key after a connection-level API error.	On or off. Only matters when CLAUDE_CODE_CLIENT_CERT is set	MTLS setups
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC	Documented	Turns off nonessential network traffic such as updates, telemetry and error reporting.	On or off	All sessions
CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK	Documented	Stops the non-streaming retry after a stream fails mid-stream.	On or off	All sessions. Project env can set it before trust
CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING	Documented Gated	Forces tool input streaming on or off. Code matches the docs.	On, off, or unset. 0 is off. Else first party needs a feature flag, Vertex and Bedrock need model support and no custom base URL, 1 forces on	All sessions. Project env can set it before trust
CLAUDE_CODE_EXTRA_BODY	Documented	Merges a JSON object into the top level of every API request body.	JSON text. Ignored when org policy blocks experimental betas. Passed on to background sessions	All sessions
CLAUDE_CODE_EXTRA_METADATA	Undocumented	Merges a JSON object into the metadata of API requests.	JSON text. A bad value logs an error and is ignored	All sessions
CLAUDE_CODE_GATEWAY_HINT_HEADERS	Documented Gated	Sends or stops the gateway hint headers such as x-claude-code-request-class.	On, off, or unset. Unset sends them on some connections and else uses a feature flag on first party	All sessions
CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS	Documented	Sets the timeout of the gateway /v1/models discovery request.	A number of milliseconds, 3000 by default. Whole number from 1 to 2147483647, plain digits	Gateway setups with discovery on
CLAUDE_CODE_GZIP_CCR_REQUEST_BODIES	Undocumented	Turns gzip of CCR worker request bodies on or off.	On, off, or unset. Used only for the ccr_worker source	Remote worker sessions
CLAUDE_CODE_GZIP_DATADOG_LOGS	Undocumented	Turns gzip of Datadog log batches on or off.	On, off, or unset. Unset is on only in Anthropic-hosted remote sessions (CLAUDE_CODE_REMOTE set, CLAUDE_CODE_ENVIRONMENT_KIND unset, so not BYOC), else off. If Datadog refuses a gzipped batch, gzip is off for the rest of the process	All sessions
CLAUDE_CODE_GZIP_REQUEST_BODIES	Documented	Turns gzip of request bodies to Anthropic on or off. Set 0 for a TLS-inspecting proxy.	On, off, or unset. Compression is skipped for a proxy, mTLS, a custom CA, or a Unix socket. Level comes from CLAUDE_CODE_GZIP_REQUEST_BODY_LEVEL	Direct Anthropic connections
CLAUDE_CODE_GZIP_REQUEST_BODY_BLOCKS	Undocumented Gated	Sets the blocks gzip mode for large request bodies, from 524288 chars up.	A number, 0 by default. Whole number from 0 to 2, plain digits. Only 1 and 2 act	Messages API requests
CLAUDE_CODE_GZIP_REQUEST_BODY_LEVEL	Undocumented Gated	Sets the gzip level for request bodies.	A number, 0 by default. Whole number from 0 to 9, plain digits. Only 1 to 9 act	All API requests
CLAUDE_CODE_HTTP_PROXY	Undocumented	Fallback HTTP proxy. Used when HTTP_PROXY and http_proxy are empty to build the proxy vars of child tools.	Text. Fills YARN_*, npm_config_*, and GLOBAL_AGENT_* proxy vars that are unset	All sessions, child process env
CLAUDE_CODE_HTTPS_PROXY	Undocumented	Fallback HTTPS proxy. Used when HTTPS_PROXY and https_proxy are empty to build the proxy vars of child tools.	Text. Fills YARN_*, npm_config_*, and GLOBAL_AGENT_* proxy vars that are unset	All sessions, child process env
CLAUDE_CODE_MAX_RETRIES	Documented	Sets how many times a failed API request is retried.	A number. Whole number, 0 or more. Above the cap it is clamped with a warning unless the retry watchdog is on	All sessions
CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES	Documented	Limits the re-sends of a non-streaming request that times out. 0 fails on the first timeout.	A number. Whole number min 0, digits only. Unset uses a built-in count only when the retry watchdog is on	All sessions
CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS	Documented	Sets the first delay of the exponential backoff for retries of an overloaded API error.	A number of milliseconds. Whole number from 500 to 32000 in plain digits, else unset. Used only on the overloaded branch of the retry loop	All API requests
CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS	Documented	Sets the ceiling of the backoff for retries of an overloaded API error.	A number of milliseconds. Whole number from 32000 to 64000 in plain digits, else unset. A longer wait than the ceiling plus a margin raises a retry-after error	All API requests
CLAUDE_CODE_PROXY_RESOLVES_HOSTS	Documented	Lets the proxy resolve DNS names.	On or off. When set the proxy agent lookup returns the host name as is	HTTP proxy setups
CLAUDE_CODE_RETRY_WATCHDOG	Documented	Retries 429 and 529 capacity errors without end for unattended sessions. Docs match the code path that reads it.	On or off. The self-hosted runner sets it to 1 and also clears CLAUDE_CODE_MAX_RETRIES. Docs also cover the spend-limit rule	Unattended runs, CI, remote workers. Set by Claude Code for self-hosted runners
CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS	Undocumented	Caps the total ms the retry watchdog waits out usage-limit 429 errors. When the wait is longer than what is left, the request fails.	A number of milliseconds. Integer 1 or more, digits only. Unset means no limit	Sessions with the retry watchdog on
CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS	Documented	Caps the ms each API request spends waiting out 429 and 529 errors under the watchdog. After that the next error ends the request.	A number of milliseconds. Integer 1 or more, digits only. Unset means no limit	Sessions with CLAUDE_CODE_RETRY_WATCHDOG. Docs say v2.1.295 or later
CLAUDE_ENABLE_BYTE_WATCHDOG	Documented	Forces the byte-level streaming idle watchdog on or off.	On, off, or unset, on by default. Unset uses a feature flag with default true. Direct, AWS, and gateway only	Anthropic API, AWS, gateway
CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK	Documented	Enables the byte-level streaming idle watchdog for Bedrock event streams.	On or off. Off by default. Needs the main watchdog to be on	Amazon Bedrock
CLAUDE_ENABLE_STREAM_WATCHDOG	Documented	Forces the event-level streaming idle watchdog on or off. It also sets the async agent stall time.	On, off, or unset, on by default	All sessions
CLAUDE_SLOW_FIRST_BYTE_MS	Undocumented	Sets the wait before Claude Code logs a slow first byte on a stream. It does not abort.	A number of milliseconds	-
CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS	Documented	Sets the first-byte deadline of a streaming request in ms.	A number of milliseconds	-
CLAUDE_STREAM_IDLE_TIMEOUT_MS	Documented	Sets the idle timeout of the stream watchdogs in ms.	A number of milliseconds	-
CLOUDSDK_CORE_CUSTOM_CA_CERTS_FILE	Undocumented	Names a CA bundle file for gcloud. The Bash sandbox treats it as a CA bundle variable.	A path	-
CURL_CA_BUNDLE	Undocumented	Names a CA bundle for curl. The Bash sandbox treats it as a CA bundle variable.	-	-
DENO_CERT	Undocumented	Names a CA bundle for Deno. The Bash sandbox treats it as a CA bundle variable.	-	-
GIT_SSL_CAINFO	Documented	Git CA bundle path. Claude Code names it in CA hints and in runner messages saying a server value replaces it in a session.	Text. Use is mostly by name in text and lists	Git. Self-hosted runner. Not set from project env before trust
HTTP_PROXY	Documented	Sets the HTTP proxy for Claude Code network traffic.	-	-
http_proxy	Documented	Lower case HTTP proxy URL. Claude Code reads it as an alternative to HTTP_PROXY.	Text. Non-empty string. Order is HTTP_PROXY, this, then CLAUDE_CODE_HTTP_PROXY for the sandbox proxy	All sessions
HTTPS_PROXY	Documented	Sets the HTTPS proxy for Claude Code network traffic.	-	-
https_proxy	Documented	Lower case HTTPS proxy URL. Claude Code reads it as an alternative to HTTPS_PROXY.	Text. Non-empty string. Order is HTTPS_PROXY, this, then CLAUDE_CODE_HTTPS_PROXY for the sandbox proxy	All sessions
NIX_SSL_CERT_FILE	Undocumented	Set by Claude Code in sandboxed commands to the CA bundle path, with other CA vars.	A path	-
NO_PROXY	Documented	Lists hosts that skip the proxy. * skips it for all.	On or off	-
no_proxy	Documented	Lower case proxy bypass list. Claude Code reads it with NO_PROXY.	A comma-separated list. If both are set and differ, Claude Code joins them with a comma	All sessions
NODE_EXTRA_CA_CERTS	Documented	Adds extra CA certificates from a PEM file to the trusted set.	-	-
NODE_TLS_REJECT_UNAUTHORIZED	Documented	Set to 0 to turn off TLS certificate checks (Bun). Claude Code counts any value except 1 as a trust override.	-	-
NODE_USE_ENV_PROXY	Undocumented	Bun http client: a value other than empty or 0 makes it use HTTP_PROXY and HTTPS_PROXY. A bundled proxy tip names it for Node 22.21 and later.	-	-
NODE_USE_SYSTEM_CA	Undocumented	Bun runtime: 1 adds the OS CA store to the default CA list.	-	-
SSL_CERT_DIR	Undocumented	Directory of CA certificates. Claude Code counts it as a custom CA setting.	Text. Raw string (rawStr). Together with NODE_EXTRA_CA_CERTS and SSL_CERT_FILE, it makes the TLS setup treat custom certs as set	All sessions
SSL_CERT_FILE	Documented	CA bundle file path. Claude Code treats it as a custom CA setting, and passes it to proxy helpers and the MCP agent proxy.	Text. Raw string. The MCP agent proxy fallback reads the file as PEM	All sessions

How It Works

Claude Code reads shell variables once at startup, so restart after a change. Values in a settings env block are reapplied when the file changes, except for features that read their variables only at startup. Numeric variables such as timeouts accept forms like 2e3 and 64_000 in addition to plain digits, except where a row says digits only.

Related Pages

• Environment Variables: how Claude Code reads variables and which value wins.
• Cloud Providers
• System and Third-Party: ALL_PROXY and CA bundle names owned by other tools.
• Undocumented Items: every item that only the program shows.

Source: the program (variable names found in the 2.1.304 binary) and the Environment Variables page of the official docs.