How to Use a Proxy With Claude Code

Claude Code reads HTTPS_PROXY exactly once, at process start. That one detail explains a large share of the threads about the CLI hanging for thirty seconds and then dying on a corporate network: the variable was exported after the agent was already running, or in a different shell, or in a shell that never started the background supervisor. Most guides on how to use a proxy with Claude Code open with the export line, and the export line is almost never the part that fails. It is a Node application following standard proxy conventions. What breaks is where the value lives and what the proxy does to TLS.

Two Different Things Get Called a Proxy Here

Search results for how to use a proxy with Claude Code mix two unrelated setups, and the confusion is expensive.

The first is a network proxy: a forward proxy the CLI dials through, set with HTTPS_PROXY, so every request leaves the machine from one controlled exit point. The second is an Anthropic-compatible API proxy, usually called an LLM gateway, set with ANTHROPIC_BASE_URL, which terminates the request and forwards it to a different model backend, or holds the API key centrally and applies per-team budgets.

They solve different problems and they stack. A laptop can point ANTHROPIC_BASE_URL at an internal gateway and still need HTTPS_PROXY to reach that gateway. When a setup works for one developer and fails for the rest of the team, this mix-up is the usual reason.

Set the Variables Where Claude Code Will Actually Read Them

The basic form, exported before the agent starts:

export HTTPS_PROXY=http://gw.corp.example:8080
export HTTP_PROXY=http://gw.corp.example:8080
export NO_PROXY="localhost,127.0.0.1,.corp.example"

NO_PROXY accepts comma-separated or space-separated entries, and an asterisk to bypass everything. Set the uppercase and lowercase spellings identically on a machine you did not build yourself, because different tools in the same shell disagree about which one wins. One caveat worth knowing: an earlier revision of Anthropic's own corporate-proxy page stated that NO_PROXY was not supported at all. Proxys.io's setup guide for Claude Code reports the same behaviour from the field on recent CLI builds, with every request leaving through the configured endpoint regardless of the exclusion list. Treat selective routing as something to prove rather than assume. Point NO_PROXY at an internal host, run one request through the agent, and check whether the call still shows up in the proxy log before you write the behaviour into a network policy.

Shell Exports Do Not Reach Background Agents

Background sessions started with claude agents, --bg or /background do not run in the terminal that dispatched them. A per-user supervisor process hosts them, it outlives your shell, and it inherits the environment of whichever shell happened to cold-start it first. A supervisor installed as an OS service gets no shell environment at all. The result is interactive sessions going through the proxy while background jobs quietly do not, which is a miserable thing to debug from the symptom end.

Put the values in the env block of ~/.claude/settings.json, or in managed settings for a fleet:

{
  "env": {
    "HTTPS_PROXY": "http://svc-claude:s3cr3t@gw.corp.example:8080",
    "NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/corp-root.pem"
  }
}

An already-running supervisor keeps the configuration it started with, so run claude daemon stop --any afterwards and let the next background session start a fresh one.

Credentials, and the SOCKS Gap

Basic auth goes in the URL as http://user:pass@host:port. Percent-encode the password. An unescaped @ or # produces a malformed host and a 407 that looks like a permissions problem for an hour before anyone checks the string. For NTLM or Kerberos, Anthropic's own guidance points at a gateway that speaks your auth method rather than a local shim; cntlm and px do work, but you have taken ownership of another daemon.

Claude Code does not support SOCKS proxies at all. Providers that sell HTTP(S) and SOCKS on the same order, which includes Proxys.io, Webshare and IPRoyal, let you sidestep this by pointing the CLI at the HTTP endpoint. Otherwise you need a proxifier in front of the process.

TLS Inspection Is Where Most Setups Break

A plain forwarding proxy issues an HTTP CONNECT and then gets out of the way. TLS stays end to end, the proxy sees a hostname and a port, and no certificate work is needed. A TLS-inspecting proxy such as Zscaler, Netskope, CrowdStrike Falcon or a Palo Alto decryption policy terminates that session and re-signs it with a private root. Node does not read the operating system trust store by default, which is why unable to get local issuer certificate appears on a machine where every browser is perfectly happy.

Current builds trust both the bundled Mozilla CA set and the OS store, but reading the OS store requires tls.getCACertificates in the runtime. The native installer always has it; npm installs need Node 22.15 or later. On anything older the OS store is invisible and the only route is an explicit bundle:

export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/corp-root.pem

CLAUDE_CODE_CERT_STORE narrows the sources to bundled, system, or both, and defaults to both. Client-certificate networks use CLAUDE_CODE_CLIENT_CERT, CLAUDE_CODE_CLIENT_KEY and CLAUDE_CODE_CLIENT_KEY_PASSPHRASE for mTLS. Those files are re-read whenever settings are applied, including mid-session, so rotation means replacing the files at the same paths rather than restarting every machine.

Do not reach for NODE_TLS_REJECT_UNAUTHORIZED=0. It switches off verification for every connection the process opens, including the ones your agent makes to npm and GitHub, and converts a fixable trust problem into a permanent exposure.

Verify the Claude Code Proxy Path Before Blaming the CLI

1. Confirm the value is in the process and not only in a file: run env | grep -i proxy in the same shell you will launch from.
2. Reach the endpoint with Claude Code out of the way: curl -x http://gw.corp.example:8080 -sS -o /dev/null -w '%{http_code} %{time_total}' https://api.anthropic.com/v1/messages. A 401 is a pass; you got through and were rejected for having no key.
3. Confirm the egress IP the API will see, through the same proxy: curl -x http://gw.corp.example:8080 https://api.ipify.org.
4. Only then run claude, and if it still fails, claude --debug names the host that failed.

Step two separates a network fault from a CLI fault in about ten seconds, and it is the step people skip.

What Actually Breaks, and What Fixes It

Latency, Streaming and Idle Timeouts

Latency is physics plus routing. A signal moves through fibre at roughly 200,000 km/s, so every 1,000 km between the developer and the exit node costs about 10 ms round trip before a single router touches the packet. A New York engineer exiting through Frankfurt, about 6,200 km away, pays a 62 ms floor on every request and typically 75 to 95 ms in practice. On a chat interface that is invisible. On an agent firing dozens of tool calls per task, it compounds into whole seconds per turn, which is the argument for putting the exit node near the developer rather than near anything else.

Streaming is the second trap. Claude Code consumes server-sent events, and a long turn with extended thinking can hold a connection open for minutes with sizeable gaps between chunks. A forwarding proxy passes this without noticing, because the tunnel is opaque to it. A TLS-inspecting proxy or a buffering gateway does not: the request starts, output stops partway, and the socket eventually hangs up. Idle timeouts of 60 or 120 seconds are common defaults and they will cut long responses. Ten minutes is a safer floor.

Choosing an Egress IP for an Agent Workload

Bandwidth is the part people get wrong at the purchase stage. Claude Code talks to a stateless API, so every turn resends the whole conversation. At roughly four characters per token, a request carrying 100,000 tokens of context is on the order of 400 KB of JSON on the wire. Even an aggressive day of agentic work, hundreds of turns with large diffs and verbose tool output, lands in the hundreds of megabytes rather than gigabytes. Buying a rotating residential plan at $7 to $8 per GB to move 300 MB of JSON is paying for a fingerprint the workload does not need.

What matters instead is that the address is dedicated, because a shared exit attaches somebody else's reputation to your requests; that it is static, so it can go into a firewall allowlist or a GitHub Enterprise Cloud IP allow list; that the endpoint speaks HTTP(S) rather than SOCKS alone; and that it bills per IP rather than per gigabyte.

Proxys.io fits that shape. Dedicated foreign IPv4 starts at $1.47 per IP per month across locations including the United States, Germany, the United Kingdom, France, the Netherlands and Poland, with HTTPS, HTTP and SOCKS on the same order and both password and IP-whitelist authentication. The IPv6 line at $0.13 per address is the cheapest thing on the price list and irrelevant here unless every hop and endpoint on the path answers over IPv6, worth checking before the order.

It does not win on every axis. Webshare's dedicated datacenter IP is cheaper per unit at $0.77, and for a residential-classified address in a country outside the premium list, Bright Data and Oxylabs have wider coverage at $1.30 to $3.20 per IP. The gap that decides most of these purchases is the billing model: an agent moving 300 MB a month should never sit on a per-GB meter.

For the browser side of the same account, the ProxyControl extension covers Chrome, Opera and Firefox and switches endpoints with a hotkey. It is HTTP(S) only, with the same SOCKS caveat as the CLI.

The Allowlist for a Locked-Down Network

• api.anthropic.com carries API requests, the WebFetch domain safety check, feature flag fetches and telemetry.
• claude.ai, claude.com and platform.claude.com handle sign-in and OAuth token exchange, refresh and revocation.
• downloads.claude.ai serves the native installer, the auto-updater and plugin executables.
• registry.npmjs.org is required for npm and bun installs unless your organisation mirrors it.
• raw.githubusercontent.com feeds the changelog behind /release-notes.

Two Datadog intake hosts carry optional operational telemetry and can be switched off with CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC. If Claude Code on the web or Code Review reaches your repositories, the published Anthropic API IP ranges need allowlisting on the GitHub side as well.

Routing Through a Gateway Instead

Pointing ANTHROPIC_BASE_URL at a gateway moves model traffic off api.anthropic.com entirely, which is what you want for central key custody, per-team budgets, or routing to Bedrock, Vertex or Foundry. Two calls still go to Anthropic and both catch people out. WebFetch runs a domain safety check against api.anthropic.com before it fetches a URL, on every backend, unless skipWebFetchPreflight is set. The fast-mode availability check also calls api.anthropic.com rather than the gateway base URL, though it does honour a configured HTTP proxy, so allowlisting that host in the proxy is usually the fix. If the check still fails while the host is reachable, the gateway credential is being rejected and no allowlist entry will change that.

Where a Proxy Does Not Help

A proxy changes the IP that Anthropic sees. It does not change what an account is entitled to. Routing the CLI through another country to reach a service that is not offered there is a terms problem rather than an engineering one, and the failure mode is account termination, not a 403 you can debug.

It also will not hide agent traffic from the team running the proxy, which is usually the point of the deployment.

A working baseline for how to use a proxy with Claude Code in most teams: one dedicated static IPv4 in the region closest to the developers, set through the env block of settings.json rather than a shell profile, with the corporate root in NODE_EXTRA_CA_CERTS if TLS is inspected and the proxy's idle timeout raised to ten minutes. Verify with curl -x before running the agent. If curl gets a 401 from api.anthropic.com and claude still fails, the problem has stopped being the network.