Claude Code Proxies: How to Set Up and Use an AI Coding Agent with a Proxy

A proxy lets the claude code CLI send its requests through a controlled exit point instead of your raw connection. This matters for corporate compliance, stable automation, and consistent regional performance. This guide explains which proxy types fit, how to configure them step by step with screenshots, and how to verify the result. It also covers a quick browser setup for the claude.ai web app, so both the terminal agent and the browser can share the same controlled egress.

A claude code proxy is a network server that sits between the Claude Code CLI and the internet and forwards its HTTPS requests through one controlled exit point. Claude Code reads the endpoint from the HTTPS_PROXY, HTTP_PROXY and NO_PROXY environment variables at startup, or from the env block of a settings file. SOCKS is not supported natively.

What a claude code proxy is, and when you need one

The phrase covers two different things, and confusing them causes most setup mistakes. A network proxy forwards Claude Code's traffic unchanged to Anthropic's API and changes only the route and the exit IP. A software gateway replaces the destination itself, so the model traffic goes to a backend you control. Both are legitimate; they solve different problems.

Proxys.io provides the first type: dedicated and shared IPv4, IPv6, residential, and dynamic endpoints over HTTPS, HTTP, and SOCKS, across many regions. For controlled, stable egress from your automation hosts, it is a solid starting point worth trying.

How claude code routes traffic (and where a proxy fits)

The CLI runs on Node.js and sends each request to the model API over HTTPS. A network proxy intercepts those calls and forwards them upstream. The model still runs on Anthropic's infrastructure; only the route changes. Your egress IP, monitoring, and certificate handling move to the proxy, which is exactly what regulated environments require. In practice the CLI reaches more than the model endpoint alone: authentication, plugin downloads, MCP connector traffic and optional telemetry each go to their own host, and all of it flows through the same proxy.

Which hosts to allowlist on the proxy

Allowlist Claude Code by domain, not by IP address. The API endpoint api.anthropic.com resolves to rotating anycast addresses, so a pinned firewall rule breaks without warning. Anthropic documents the hosts the CLI needs and, separately, the fixed ranges its own services use for inbound and outbound connections.

The hosts a minimal terminal setup needs: api.anthropic.com for model requests, claude.ai and platform.claude.com for sign-in and token exchange, claude.com for the browser step of a claude.ai login, downloads.claude.ai for the native installer and updates, and registry.npmjs.org for npm installs and npx-launched MCP servers. Add mcp-proxy.anthropic.com if your team uses claude.ai connectors, and code.claude.com for documentation lookups. Two Datadog intake hosts carry optional operational telemetry only, and CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC switches both off.

Where a firewall restricts inbound traffic from Anthropic, such as a self-hosted Git server or an MCP server you run yourself, the published ranges apply instead: inbound 160.79.104.0/23 and 2607:6bc0::/48, outbound 160.79.104.0/21. Five older 34.162.x.x/32 addresses have been retired and should be removed from existing rules.

Network proxy or LLM gateway: which one you actually need

Pick a network proxy when you need a controlled, auditable exit IP and the requests themselves stay unchanged. Pick an LLM gateway when you need central budgets, per-team rate limits or multi-provider routing, and set ANTHROPIC_BASE_URL to a host that speaks Anthropic's message format. The two are not interchangeable, and they can run together.

The gateway route has a cost the vendor guides skip. Pointing ANTHROPIC_BASE_URL at a non-first-party host disables MCP tool search by default, and it takes ENABLE_TOOL_SEARCH=true to bring it back, which is only safe if the gateway forwards tool_reference blocks. Remote Control switches off entirely on any base URL other than api.anthropic.com. Neither is announced at startup; you find out when a feature quietly stops working. A network proxy costs you nothing here, because the destination never changes.

Legitimate use cases and when you don't need a proxy

Common reasons include forcing all agent traffic through one auditable egress, meeting corporate network policy, and getting stable latency from automation hosts. A proxy also gives a consistent source IP for legitimate automation such as web scraping, market research, ad verification, and SEO monitoring. If you run the CLI locally with no compliance need, you do not need one.

One case people miss: organizations on the Enterprise plan can restrict Claude access to a list of approved CIDR ranges, and every authenticated request from outside that list is blocked. Remote developers and contractors then need a fixed, allowlisted address to work at all, which is a straightforward job for a static dedicated IP. Confirm the current list covers offices and VPN exits before the policy is switched on, or people get locked out.

Proxy types and protocols for claude code

For a single interactive claude code session, a static datacenter IPv4 endpoint over HTTPS is the right default: lowest latency, lowest price, and one stable exit the CLI can hold for the whole session. Residential and mobile IPs are worth their premium only when the destinations you automate check IP reputation. SOCKS needs a local converter.

Datacenter, residential, and mobile: which fits which workload

Datacenter IPs are fast and cheap, ideal for a single session or internal CI jobs, though they carry lower reputation on strict third-party sites. Residential IPs balance trust and cost for automation that touches demanding sites. Mobile IPs have the highest trust and the highest price, reserved for the most sensitive workloads.

Static or dedicated vs rotating, and why CLI sessions want a sticky IP

For interactive CLI sessions, use a static, dedicated IP. A stable exit point avoids re-authentication and dropped sessions. Use rotating IPs only for automation that issues many requests across destinations, where varying the source address is the point. Mixing the two is a frequent cause of instability.

HTTP(S) vs SOCKS5 and IPv4 vs IPv6: Node.js support and compatibility

claude code reads HTTP(S) proxy settings natively, so an HTTPS endpoint is the simplest and most reliable path. It has no native SOCKS5 support; to use SOCKS, run a local converter and point the CLI at it. IPv4 has the broadest compatibility, while IPv6 and dynamic pools are cheaper for high-volume jobs when the whole path supports them. When in doubt, an authenticated HTTPS IPv4 endpoint is the safest default for the CLI.

Comparison table: proxy types for claude code

How to choose the right proxy (quick checklist)

• Single interactive session: a static datacenter IP near you is fastest and cheapest.
• Automation on strict sites: residential, or mobile for the most demanding targets.
• High request volume on a budget: IPv6 or dynamic pools, if your path supports them.
• Compliance or audit need: a dedicated IP that gives one fixed, loggable egress.
• On a tight budget: start with one shared or datacenter IP, and trial it before scaling.
• Always match the proxy region to the location your workload expects.

How to set up a proxy for claude code (step by step)

Setting up a proxy for claude code takes one variable and one restart: export HTTPS_PROXY with your endpoint, then launch the CLI in the same shell. Claude Code reads proxy variables once at startup, so a running session ignores a later change. Version 2.1.246 accepts the same values from a settings file.

Step 1: Confirm Node.js and the claude code CLI

Check your runtime with node -v. The npm package declares engines: node >=22.0.0, so anything older will not install cleanly. Reading the operating system certificate store additionally needs Node 22.15 or later on npm installs. Below that, only the bundled Mozilla set and NODE_EXTRA_CA_CERTS apply, which matters the moment a TLS-inspecting proxy is in the path. Confirm the CLI itself with claude --version before changing any network settings.

Step 2: Get your proxy details from proxys.io

• Copy the host, port, login, and password from your proxys.io dashboard.
• Pick a location close to your team for the lowest added latency.
• If your plan uses IP whitelisting, add your current address instead of embedding credentials.

Step 3: Set HTTPS_PROXY and HTTP_PROXY

• Export HTTPS_PROXY with your endpoint, and HTTP_PROXY only if a plaintext channel is needed.
• Define the variables before launching, because the CLI reads them once at startup.
• Start the agent in the same shell so it inherits the values.

NO_PROXY works and takes three forms: space-separated, comma-separated, or * to bypass the proxy for everything. Lowercase spellings are read as well, and the first variable that is set wins, in the order https_proxy, HTTPS_PROXY, http_proxy, HTTP_PROXY. A lowercase leftover in a shell profile therefore beats the uppercase one you just exported. Check that first when the endpoint looks right and the traffic still goes somewhere else.

The proxy URL is the one network setting validated at launch. A value missing its http:// scheme stops startup with an error naming the variable, rather than failing later on the first request.

Proxy variables claude code reads

Step 4: Or scope the configuration to the project

• Place the values in the env block of the settings file instead of exporting globally.
• This keeps the setup scoped to the project and leaves other tools untouched.
• Commit a template without secrets, and keep real credentials out of version control.

Shell or settings.json: which one wins

When the same variable is set in both your shell and the env block of a settings file, the settings file wins. Claude Code writes each env entry into the process environment at startup, and again whenever the file changes, replacing whatever the shell passed in. That order catches people out while debugging a stale endpoint.

A settings file can set a variable but cannot remove one. To neutralize something you do not control, such as a stale export in a shared profile, set it to an empty string in the env block. Background agents make the settings file the better home anyway: they run in a supervisor process that outlives your terminal and inherits whichever shell happened to start it first, so a shell-only export reaches them by accident or not at all.

Step 5: Authenticated and SOCKS5 endpoints

• For authenticated endpoints, embed the user and password in the URL, or read them from a secret manager.
• SOCKS5 is not native: run a local HTTP-to-SOCKS forwarder and point HTTPS_PROXY at the local listener.

Step 6: Corporate proxy and custom CA certificates

Point NODE_EXTRA_CA_CERTS at the PEM bundle your security team provides. Recent versions trust both the bundled Mozilla set and the operating system trust store, so inspection products such as Zscaler and CrowdStrike Falcon often work with no extra configuration once their root certificate is installed at the OS level and the runtime can read it. CLAUDE_CODE_CERT_STORE narrows that to bundled or system if you need one or the other; the default is both.

Two things worth knowing before you debug this. A certificate validation failure is not retried. It surfaces on the first attempt, unlike a dropped connection, which gets up to ten attempts with backoff. And NODE_TLS_REJECT_UNAUTHORIZED=0 is not a fix: it hands your prompts and your credentials to whoever operates the proxy. Get the bundle from your infrastructure team instead.

• For NTLM or Kerberos, place a gateway that handles the enterprise scheme between the CLI and the network.

Pitfall: Child processes, including MCP servers, may not inherit these values. If a tool call fails with a certificate error while the main session works, set them in that server's environment.

Per-OS notes (macOS, Linux, Windows)

On macOS and Linux, export HTTPS_PROXY="http://user:pass@host:port" in the same shell, and add the line to ~/.bashrc or ~/.zshrc to make it permanent. In PowerShell, $env:HTTPS_PROXY = "http://..." covers the current session, and [Environment]::SetEnvironmentVariable("HTTPS_PROXY", "http://...", "User") makes it stick; in CMD, set and setx do the same. Both Windows forms need a new terminal afterwards. The assignment prints nothing on success, so echo the variable back before launching the CLI.

Using a proxy in CI/CD and containers

Automation magnifies small mistakes. The same variables apply in pipelines and containers, but credential handling and inheritance need extra discipline to keep builds reproducible and secure.

Docker and CI pipelines (GitHub Actions, GitLab CI)

• A container does not inherit the host shell, so pass the variables at runtime with the -e flag.
• Bake the certificate bundle into the image if needed, but never the credentials.
• In CI, define the endpoint as a masked secret and inject it as an environment variable for the job.
• Every runner then reaches the API through the same controlled egress.
• For unattended runs, set CLAUDE_CODE_RETRY_WATCHDOG=1 so capacity errors retry instead of failing the job after the default ten attempts.

Keeping credentials out of logs

Treat the endpoint URL as a secret whenever it contains a username and password. Store it in the platform secret store, mask it in output, and prefer IP whitelisting where the provider supports it, so the value never reaches a log file.

For CI/CD and container workloads, proxys.io supports IP whitelisting and username-and-password authentication across its HTTPS, HTTP, and SOCKS plans. For scaling claude code automation across many runners, it is a practical, cost-effective backend to standardize on.

Why a long agent turn drops through a proxy

Claude Code aborts a streaming response when the connection goes quiet, and three separate timers watch for that. The byte-level watchdog fires after 180 seconds on a direct connection to the Anthropic API and 300 seconds elsewhere. An agent turn can think for minutes without sending a byte, so a proxy that closes idle sockets after 60 seconds will cut it off first.

Streaming timers and the variables that move them

Raise the proxy's own idle timeout above the watchdog you keep, rather than only raising the client side. Whichever end gives up first wins, and a proxy that drops the socket produces the same symptom as a slow model: the answer stops arriving mid-sentence.

One trap in the numeric variables. They accept scientific notation and digit separators, so 2e3 reads as 2000. On versions before 2.1.211 the parsing was different, and a value like 1e6 could silently set a timeout of 1 millisecond instead of about seventeen minutes. Write plain digits and check with /status.

How to test your proxy with claude code

Three checks confirm a working setup: the exit IP reported by an IP service matches your endpoint, /status shows that endpoint in its Proxy row, and a real request completes. Run them in that order. The first two take seconds and catch the majority of failures before you spend a token.

Verify exit IP and check for DNS leaks

• Enable routing, then query an IP-reporting service and confirm it shows the exit IP, not your origin address.
• If your own address still appears, a variable is missing or the shell did not inherit it; re-export it and relaunch.
• Run a DNS leak check and confirm every resolver belongs to the configured path, not your local provider.

Check latency, stability, and that claude code actually uses the proxy

Run /status in an interactive session and read the Proxy row: it prints the active endpoint, and marks a value it cannot parse as invalid and ignored. For anything the row does not cover, start the CLI with claude --debug. Output goes to ~/.claude/debug/<session-id>.txt rather than the terminal, and lines such as CA certs: Appended extra certificates from NODE_EXTRA_CA_CERTS confirm each file actually loaded. A Failed to read line gives the reason instead.

• Compare response times with and without routing; a well-placed datacenter endpoint adds only tens of milliseconds for a smooth claude code cli experience.
• Run several requests in a row to check stability and watch for dropped sessions. 

Common issues and how to fix them

Proxy problems surface as a small set of named errors: Couldn't connect through your proxy, proxy refused the connection, SSL certificate verification failed, Connection dropped, and The response stopped arriving. Each points somewhere specific: the first two at the endpoint or its credentials, the third at certificates, the last two at idle timeouts.

Proxy variables ignored, TLS and authentication errors

If routing seems ignored, the shell likely did not inherit the variables; export them and relaunch in the same session. TLS errors usually mean the inspecting authority is not trusted, so set NODE_EXTRA_CA_CERTS to the right bundle. Authentication failures point to wrong credentials or an address that is not whitelisted. When only some calls fail, suspect a child process that did not inherit the same settings.

Before blaming the endpoint, check for a competing definition. A settings file env block overrides the shell, and a lowercase https_proxy overrides the uppercase form. If a banner reading Waiting for API response, will retry in ..., check your network appears on every attempt, and it shows after 20 seconds without data, the path is the problem, not the credentials.

Timeouts, dropped sessions and wrong region: rotation vs sticky IP

Mid-session drops have two distinct causes, and the fix differs. Rotating IPs on interactive work break authentication, so switch to a static, sticky address. But a session that dies partway through a long answer is usually an idle timeout on the proxy, not rotation. Check the timeouts section above before you change endpoints. A wrong region usually means the endpoint location does not match what the workload expects, so pick a proxy in the right country. If a single IP starts getting throttled, a fresh dedicated address from the same region usually restores normal behavior.

Best practices and responsible use

Use a dedicated IP for interactive sessions and reserve rotation for high-volume automation. Keep credentials in a secret manager, never in committed files or logs. Match the proxy region to your workload, and prefer the cheapest type that meets the reputation requirement. Monitor your egress so you can spot a failing or throttled endpoint early, and give each automation only the access it needs. Use proxies only for legitimate work such as compliance, performance testing, and authorized data collection, and respect the terms of the services you reach.

Bonus: quick browser setup for claude.ai (ProxyControl)

If you also use claude.ai in the browser, the ProxyControl extension from proxys.io routes it without touching system-wide network settings, which is ideal for quick testing and a separate, controlled exit point for the web app.

Step 1: Install ProxyControl

• Open your browser's extension store, find ProxyControl by proxys.io, and add it.
• Pin the icon so the on and off toggle stays one click away.

Step 2: Add your proxy profile

• Enter the host, port, login, and password from your proxys.io dashboard, or import many endpoints with your API key.
• Select the protocol your plan provides; HTTP(S) endpoints work directly.

Tip: If your plan uses IP whitelisting, enable the IP-based option and whitelist your current address in the proxys.io dashboard.

Step 3: Route only claude.ai, keep other sites direct

• Open Settings, find Whitelist of sites, and add claude.ai and *.claude.ai.
• Save the whitelist. Only listed sites are routed; everything else stays on a direct connection, keeping browsing fast.

Step 4: Turn routing on and confirm it works

• Select the endpoint in the list, set it as the current proxy, and toggle ProxyControl on.
• Open claude.ai to confirm it loads, then check an IP site to confirm the address changed.

SOCKS5 note: The extension handles HTTP(S) directly. For SOCKS5 with login, pair it with a local helper, the same forwarder pattern used for the CLI.

ProxyControl is free with any proxys.io plan, and a static foreign IPv4 starts from about 1.47 USD per month. It is a quick, low-cost way to give claude.ai a stable exit point worth setting up alongside your CLI configuration.

FAQ

Free trial, free proxy, static vs rotating, and speed

Many providers, proxys.io included, let you trial an endpoint before committing; check the current terms. Be wary of fully free public proxies, which tend to be slow, unstable, and shared with unknown users, a poor fit for steady CLI work. For the CLI, a static IP is almost always better than rotation, which suits high-volume automation. Speed depends mostly on distance, so a nearby datacenter endpoint keeps latency low.

Multiple machines, and why it works sometimes but not always

You can reuse one endpoint across machines, but each shell still needs the variables set. Setup that works in one terminal but not another usually means the second session did not inherit them, or a child process did not receive the certificate settings. Set them explicitly where needed.

Does claude code support SOCKS5 proxies?

No. Claude Code reads HTTP and HTTPS proxy variables only, and ignores a SOCKS endpoint placed in them. To use a SOCKS5 plan, run a local HTTP-to-SOCKS forwarder and point HTTPS_PROXY at the local listener. The CLI then sees an ordinary HTTP proxy and the forwarder handles the rest.

Does claude code support NO_PROXY?

Yes. NO_PROXY accepts a space-separated list, a comma-separated list, or * to bypass the proxy entirely. Entries match an exact hostname, a domain suffix written with a leading dot, or a host and port. Older guidance saying the variable is ignored describes an earlier version and no longer applies.

Why does my proxy work in the terminal but not for background agents?

Background agents run in a supervisor process that outlives your shell and inherits the environment of whichever terminal started it first. A variable exported only in your profile reaches them inconsistently. Put proxy, CA and certificate variables in the env block of a settings file, which every background session reads.

Which Node.js version does claude code need in 2026?

The npm package requires Node 22.0.0 or later. Behind a TLS-inspecting proxy you want 22.15 or later, because reading the operating system certificate store depends on it; on anything older, only the bundled Mozilla certificates and NODE_EXTRA_CA_CERTS are trusted. The native installer has no such restriction.

Configuration verified against Claude Code 2.1.246 and Anthropic's documentation, August 2026. The CLI shipped between 23 and 30 npm releases per month through 2026, so re-check version-specific behavior against the current release before rolling a setup out across a team.