Proxy and VPN Configuration

Claude Code runs behind a corporate proxy once HTTPS_PROXY, plus NO_PROXY for exceptions, sits in the env block of a settings file. A TLS-inspecting proxy also needs its root certificate in the OS trust store or in NODE_EXTRA_CA_CERTS, and mTLS needs a client certificate and key. The firewall must allow api.anthropic.com, the sign-in hosts, and each feature’s hosts.

This page is for the developer whose first claude session fails on the corporate network, and for the platform engineer who has to make it work for the whole team. The usual picture: Claude Code works at home, but in the office it reports Unable to connect to API or SSL certificate verification failed. IT says “everything goes through Zscaler”, and the fix that worked on one laptop never reaches the background agents or the next hire.

What you’ll walk away with from corporate network setup

• A decision table that tells you which of the proxy, certificate, and mTLS settings your network needs
• A settings.json env block that reaches every session, including background agents
• The current host allowlist for Claude Code, split into required and optional hosts
• A managed-settings file that ships the same configuration to every machine
• A verification routine (claude --debug, /status, claude doctor) that proves the configuration loaded
• A failure table that maps each error message to its cause and its fix

Every variable, host, and error message on this page was checked against the Claude Code network configuration, environment variable, and error reference pages and the installed CLI, version 2.1.283, on 2026-09-26.

Which network settings do you need?

Ask IT three questions before you touch a config file: is there a proxy, does it inspect TLS, and does the gateway demand a client certificate? The answers map to settings like this:

Your network	What to set	Section
Direct internet access, or a split-tunnel VPN that does not route Anthropic hosts	Nothing	—
An HTTP or HTTPS proxy is required	HTTPS_PROXY, NO_PROXY	Point Claude Code at the proxy
The proxy decrypts TLS (Zscaler, Netskope, Palo Alto, Blue Coat, and similar)	Nothing if the root CA is in the OS trust store; otherwise NODE_EXTRA_CA_CERTS	Trust the proxy certificate
The gateway requires a client certificate	CLAUDE_CODE_CLIENT_CERT, CLAUDE_CODE_CLIENT_KEY	mTLS
The proxy only accepts NTLM or Kerberos	An LLM gateway or a local authenticating proxy	Authenticated proxies
Only a SOCKS proxy exists	Not supported by Claude Code (checked on v2.1.283); ask for an HTTP proxy or an LLM gateway	—
Firewall with an egress allowlist	The hosts in the allowlist table	—

Point Claude Code at the corporate proxy

Claude Code reads its network variables once, at startup. Put them in a settings file rather than a shell profile. A shell export reaches the terminal you launched from, but background agents run under a separate supervisor process that may never see that shell. The env block of ~/.claude/settings.json reaches every session.

1. Get the proxy URL from IT, including the scheme. Claude Code refuses to launch when it cannot parse the proxy URL, for example proxy.company.com:8080 without http://, and names the variable to fix.

2. Add the proxy to ~/.claude/settings.json:

   {
     "env": {
       "HTTPS_PROXY": "http://proxy.company.com:8080",
       "NO_PROXY": "localhost,127.0.0.1,.company.internal"
     }
   }

   HTTPS_PROXY is the recommended variable. Set HTTP_PROXY only when IT gives you no HTTPS proxy. Lowercase names work too, and Claude Code uses the first one it finds in the order https_proxy, HTTPS_PROXY, http_proxy, HTTP_PROXY. A stale lowercase value in your shell therefore wins over a correct uppercase one.

3. Set NO_PROXY for internal hosts that must not go through the proxy, such as an internal MCP server or package mirror. It accepts comma- or space-separated lists, a leading dot for subdomains (.company.internal), and * to bypass the proxy for everything. You do not need a loopback entry for Claude Code’s own WebSocket connections: they never go through the proxy.

4. Start a new session with claude. Running sessions do not pick up the change.

To try the proxy without editing a file, export the same variables in your shell and run claude. Move them into settings once they work.

Which proxy authentication works?

Basic authentication works through the URL: http://USERNAME:PASSWORD@proxy.company.com:8080. Keep that value in ~/.claude/settings.json or managed settings, never in the repository’s .claude/settings.json, which is committed to git.

Claude Code has no built-in NTLM or Kerberos support. The Claude Code documentation recommends an LLM gateway that speaks your authentication method. The other common option is a local authenticating proxy such as Px or Cntlm, which authenticates upstream with your Windows or Active Directory credentials and exposes a plain proxy on localhost that you put in HTTPS_PROXY. A gateway is the better choice for a team: one service to maintain instead of a shim on every laptop.

Trust a TLS-inspecting proxy certificate

A TLS-inspecting proxy re-signs every HTTPS connection with the company’s own root certificate. Claude Code rejects that certificate unless it trusts the root.

By default, Claude Code trusts both its bundled Mozilla CA set and the operating system’s certificate store (CLAUDE_CODE_CERT_STORE defaults to bundled,system). If IT has already pushed the corporate root into the OS trust store, which most managed laptops have, Claude Code works without any certificate setting. There is one condition: reading the OS store needs a runtime with tls.getCACertificates. The native installer always has it; npm installs need Node 22.15 or later. On an older Node, only the bundled set and NODE_EXTRA_CA_CERTS apply, which is a common reason one developer’s machine fails while the next one works.

When the root is not in the OS store, or you run on an older Node, point Claude Code at a PEM file:

{
  "env": {
    "NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/corp-root-ca.pem"
  }
}

To get the PEM file, ask IT for the root and any intermediate certificates, or export them yourself:

# macOS: export the corporate root by its name in Keychain Access
security find-certificate -a -c "Corp Root CA" -p /Library/Keychains/System.keychain > ~/corp-root-ca.pem

# Any OS: see which issuer the proxy presents for the API host
openssl s_client -connect api.anthropic.com:443 -proxy proxy.company.com:8080 -showcerts </dev/null 2>/dev/null | grep -E "s:|i:"

Replace Corp Root CA with the name of your company’s root certificate. If the openssl output shows your company as the issuer instead of a public CA, the proxy inspects TLS and you need this section.

NODE_EXTRA_CA_CERTS adds certificates; it does not replace the bundled set. Set CLAUDE_CODE_CERT_STORE=system only when policy says Claude Code must trust nothing beyond the OS store.

Never turn off certificate checks

NODE_TLS_REJECT_UNAUTHORIZED=0 disables certificate validation for every connection the process makes, so anyone on the network path can read and change your code and your API traffic. It is also ignored when it comes from a settings file in cloud sessions. Fix the trust store instead.

Present a client certificate for mTLS

NODE_EXTRA_CA_CERTS handles server trust. When the gateway also requires Claude Code to prove its identity, add the client certificate and key:

{
  "env": {
    "CLAUDE_CODE_CLIENT_CERT": "/etc/pki/claude/client-cert.pem",
    "CLAUDE_CODE_CLIENT_KEY": "/etc/pki/claude/client-key.pem"
  }
}

If the key is encrypted, set CLAUDE_CODE_CLIENT_KEY_PASSPHRASE as well, and deliver it from a secret store rather than a file in a repository.

Certificate rotation needs no restart. To rotate, replace the files at the same paths. Since v2.1.232, Claude Code re-reads both files when a request fails with a connection reset or a TLS handshake error, and retries with the new pair. It does not re-read when the gateway completes the handshake and answers with an HTTP error, and OpenTelemetry exporters keep their first certificate until you restart. To confirm a rotation, start the session with claude --debug and look in the debug log for Stale connection — reloaded rotated mTLS client material. The line is absent when the pair was reloaded while applying settings, so a missing line alone is not a failure. Replace the pair before the old one expires.

Which hosts must the firewall allow?

Allow these hosts through the proxy and firewall. The table is the Claude Code documentation’s list on 2026-09-26, grouped by what breaks without each host.

Host	Needed for	If blocked
api.anthropic.com	Model requests, the WebFetch domain safety check, feature flags, telemetry events	Nothing works
platform.claude.com	Sign-in and OAuth token refresh, for Console and claude.ai accounts	Cannot sign in
claude.ai, claude.com	claude.ai account sign-in	Cannot sign in with a claude.ai account
downloads.claude.ai	Native installer, auto-updates, plugin executables	No install or updates
registry.npmjs.org	npm installs, npx-launched MCP servers, plugin dependencies	MCP servers and plugins fail to start
github.com	Plugin marketplaces, including the official one	/plugin installs fail
mcp-proxy.anthropic.com	MCP connectors from claude.ai	Connectors missing
storage.googleapis.com	Plugin install counts in /plugin	Cosmetic
raw.githubusercontent.com	/release-notes changelog	Cosmetic
code.claude.com	Built-in documentation lookups	Claude cannot read its own docs
bridge.claudeusercontent.com	Claude in Chrome extension	Chrome extension cannot connect
*.frame.claudeusercontent.com	Reading artifact content, only when the Artifact tool is available for your account	Claude cannot open artifacts; CLAUDE_CODE_DISABLE_ARTIFACT=1 turns the tool off and drops the host
http-intake.logs.us5.datadoghq.com, browser-intake-us5-datadoghq.com	Optional operational telemetry and error reports (direct Anthropic API only)	Nothing breaks
formulae.brew.sh	Update checks on Homebrew installs	No update notice
*-review.googlesource.com	Gerrit change lookup, only for Claude Desktop Code tab sessions on googlesource.com checkouts	Nothing breaks (optional)

Older guides, including an earlier version of this page, list statsig.anthropic.com and sentry.io. Neither host is on the list for v2.1.283: feature flags and telemetry events now go to api.anthropic.com, and the optional telemetry goes to the two Datadog hosts. To drop the optional hosts entirely, set CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1. It also turns off auto-updates, /feedback, release notes, the fast mode availability check, and feature-flag fetching (which makes Remote Control unavailable), so decide it deliberately. The variable is unusual: 0 or false still disables the traffic, so unset it to turn the traffic back on.

If you use Amazon Bedrock, Google Cloud’s Agent Platform (formerly Vertex AI), Microsoft Foundry, or an LLM gateway, model traffic goes to that provider instead. WebFetch still calls api.anthropic.com for its domain safety check unless you set skipWebFetchPreflight: true in settings, and the fast mode availability check also calls api.anthropic.com through your proxy rather than the gateway. See LLM gateway configuration for the provider side.

Make background agents use the same network settings

Background agents started with claude --bg, claude agents, or /background run under one per-user supervisor process. The supervisor inherits the environment of whichever shell started it first. If your proxy lives only in ~/.zshrc, background agents work when that shell happened to start the supervisor and fail silently when an IDE terminal did.

The fix is the one from the first section: put every network variable in the env block of ~/.claude/settings.json or managed settings. After changing it, stop the running supervisor so the next background session picks up the change:

claude daemon stop --any

claude daemon stop also terminates the background sessions it hosts, so let running agents finish first or tell the team before you run it on a shared machine.

Split-tunnel and full-tunnel VPNs

A split-tunnel VPN routes only corporate address ranges through the tunnel. Claude Code’s hosts use the public internet, so you usually need no settings at all.

A full-tunnel VPN sends everything through corporate infrastructure. Expect all three: a proxy, TLS inspection, and corporate DNS. Configure them with the sections above. Two VPN-specific problems show up in the error reference: WSL can inherit an unreachable nameserver in /etc/resolv.conf, and on macOS a disconnected or uninstalled VPN client can leave a stale utun interface or routing rule behind.

Roll the configuration out to the whole team

One developer fixing their own laptop does not scale. Ship the network block as managed settings so it applies to every session on every machine and ranks above user and project settings:

{
  "env": {
    "HTTPS_PROXY": "http://proxy.company.com:8080",
    "NO_PROXY": "localhost,127.0.0.1,.company.internal",
    "NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/corp-root-ca.pem"
  }
}

Save it as its own drop-in file, managed-settings.d/20-network.json, next to managed-settings.json in the system directory. The platform team then owns the network block without editing the file that the security team owns. Claude Code merges managed-settings.json first and then every *.json file in managed-settings.d/ in alphabetical order, and it merges env blocks key by key. The system directories are:

• macOS: /Library/Application Support/ClaudeCode/
• Linux and WSL: /etc/claude-code/
• Windows: C:\Program Files\ClaudeCode\

Two traps make a correct file do nothing, or worse:

• Another managed source wins. By default (managedSourcesBehavior: "first-wins"), Claude Code uses the highest-ranked managed source and ignores the rest: server-managed settings from claude.ai first, then MDM or registry policy, then these files. If your organization already pushes a policy through the claude.ai console or MDM, put the network block there instead. /status names the managed source in use and the ones it skipped.
• Invalid JSON stops every session. A managed file that does not parse as a JSON object makes Claude Code refuse to start, with an error that names the file. Validate the file with jq . 20-network.json in the pipeline that ships it.

Deliver the certificate file to the same path on every machine with the tooling that already places files on your fleet, or the setting points at nothing. For MDM profiles, server-managed settings, and the rest of the baseline policy, see enterprise integration. For containers, bake the same values into the image; the dev container guide covers that and its default-deny firewall.

Note

In Claude Desktop sessions where the app manages the provider connection, Claude Code reads the proxy, CA, and mTLS variables only from managed settings and ~/.claude/settings.json, never from a repository’s settings. A checked-out repository therefore cannot redirect that traffic. Terminal sessions read them from every settings scope, which is one more reason to keep them out of repository settings.

Verify the network configuration without guessing

Claude Code validates only the proxy URL at startup. A wrong certificate path shows up later, as a failed request. Prove each piece loaded instead of waiting for the failure.

1. Start a session with debug logging written to a known file:

   claude --debug-file /tmp/claude-net.log

   Without --debug-file, claude --debug writes to ~/.claude/debug/<session-id>.txt, not the terminal.

2. Search the log for the lines that confirm each file loaded:

   grep -E "CA certs:|mTLS:|Failed to (read|load)" /tmp/claude-net.log

   A working setup prints CA certs: Appended extra certificates from NODE_EXTRA_CA_CERTS (...) and, with mTLS, mTLS: Loaded client certificate from CLAUDE_CODE_CLIENT_CERT and the matching key line. A Failed to read or Failed to load line gives the reason.

3. In the session, run /status. Check that it names the managed source you shipped. The Proxy row shows the active proxy URL and flags an unparseable value. The mTLS client cert and mTLS client key rows appear only when the files loaded. The Additional CA cert(s) row shows the path without checking the file, so trust the debug log for that one.

4. Run claude doctor from a terminal for an installation and settings health check.

5. Send one real prompt, such as Reply with OK. A reply proves the whole path: proxy, trust, and allowlist.

For a fleet, the platform team runs these steps on a canary machine after every change to the managed network block and signs off before the change reaches everyone. Developers run them only when a support ticket arrives.

Copy-paste prompts for network setup

These prompts need a working session, so run them on a machine that already connects: a home network, a colleague’s configured laptop, or a session that reaches the model through your gateway.

Copy-paste prompt: audit a machine's Claude Code network setup

Audit how Claude Code on this machine is configured for our corporate network.
Read ~/.claude/settings.json, .claude/settings.json and .claude/settings.local.json
in this repository, and the managed-settings.json and managed-settings.d/*.json for this OS if they exist.
Run: env | grep -iE "proxy|NODE_EXTRA_CA_CERTS|CLAUDE_CODE_CLIENT|CLAUDE_CODE_CERT_STORE|NODE_TLS"
Then report in a table: variable, value (mask passwords), where it is set, problem.
Flag: proxy URLs without a scheme, lowercase variables that shadow uppercase ones,
proxy credentials in a repository file, NODE_TLS_REJECT_UNAUTHORIZED set anywhere,
certificate paths that do not exist (check with ls), and network variables that live
only in the shell and so will not reach background agents.
Do not change any file.

Copy-paste prompt: write the firewall request for the security team

Write a firewall and proxy change request so our developers can use Claude Code.
We sign in with claude.ai accounts, use npx-launched MCP servers and the official
plugin marketplace, and do not use Claude in Chrome.
Use the "Network access requirements" table at
https://code.claude.com/docs/en/network-config.md as the only source of hosts.
Output: a table of host, port 443, purpose, required or optional, and what breaks
if it is blocked. Add a short paragraph on whether we should set
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC and what we lose if we do.
Quote the doc for every purpose; do not add hosts that are not in the doc.

Copy-paste prompt: build the managed network policy and its canary check

Create two files in ops/claude-code/:
1. managed-settings.d/20-network.json with an env block holding HTTPS_PROXY=http://proxy.company.com:8080,
   NO_PROXY=localhost,127.0.0.1,.company.internal and
   NODE_EXTRA_CA_CERTS=/etc/ssl/certs/corp-root-ca.pem. Nothing else.
2. verify-network.sh, a POSIX shell script for a canary machine that:
   - checks the certificate file exists and is valid PEM (openssl x509 -noout),
   - runs curl -sSI through the proxy to https://api.anthropic.com and
     https://platform.claude.com and prints the HTTP status for each,
   - starts claude -p "Reply with OK" --debug-file /tmp/claude-net.log,
   - greps the log for "CA certs:" and fails if it is missing,
   - exits non-zero on any failure with a one-line reason.
Validate the JSON file with jq, run shellcheck on the script if it is installed,
and show me both files.

When the corporate network breaks Claude Code

What you see	Likely cause	Recovery
Unable to connect to Anthropic services at first run, with A proxy is configured via HTTPS_PROXY	The proxy blocks api.anthropic.com or platform.claude.com	Ask IT to allow both hosts; test with curl -I https://api.anthropic.com from the same shell
Connection refused — a firewall or proxy may be blocking it	No proxy set on a network that requires one, or a wrong proxy port	Set HTTPS_PROXY; confirm the host and port with curl -x http://proxy.company.com:8080 -I https://api.anthropic.com
Couldn't connect through your proxy (ERR_PROXY_TUNNEL)	The proxy rejected the tunnel: wrong credentials or the host is not allowed	Fix the credentials in the URL, or ask IT to allow the host
SSL certificate verification failed (UNABLE_TO_GET_ISSUER_CERT_LOCALLY) or Self-signed certificate detected (SELF_SIGNED_CERT_IN_CHAIN)	TLS inspection with a root Claude Code does not trust	Add the root to the OS store or set NODE_EXTRA_CA_CERTS; on npm installs, check that Node is 22.15 or later
Claude Code will not launch and names a proxy variable	The proxy URL cannot be parsed, often a missing http://	Add the scheme
curl works but Claude Code does not	A leftover ANTHROPIC_BASE_URL pointing at a gateway that is not running, or a lowercase https_proxy shadowing the right value	Run echo $ANTHROPIC_BASE_URL, check settings env blocks, and unset stale lowercase variables
Interactive sessions work, background agents do not	Network variables exist only in a shell profile	Move them to ~/.claude/settings.json, then run claude daemon stop --any
Streaming response ended before any complete data was received. Retrying without streaming.	The proxy consumes or rewrites the streaming response body, so each request is sent twice	Ask IT to pass streaming response bodies and their headers through unmodified for the API host
Claude Code refuses to start and names a managed settings file	The managed file is not valid JSON	Fix the file on the machine, then add a jq check to the pipeline that ships it
The managed network block is on disk but /status shows no proxy	A higher-ranked managed source (claude.ai console or MDM) wins under first-wins	Move the env block into that source, or review managedSourcesBehavior with the owner of the policy
Only a SOCKS proxy is available	Claude Code does not support SOCKS (v2.1.283)	Request an HTTP proxy rule or route through an LLM gateway

For failures that are not network-related, start from Claude Code troubleshooting.

Using Codex or Cursor on the same network

This page covers Claude Code only. Codex has read the system proxy configuration, including PAC and WPAD, since release 0.143.0 (per its GitHub release notes); see Codex configuration. Cursor’s network settings could not be verified against cursor.com on 2026-09-26, so check its own documentation before you write them into a rollout. The host allowlist above is specific to Claude Code: each tool needs its own vendor’s hosts.

Where to go next with Claude Code networking

• LLM gateway configuration: route model traffic through Bedrock, Google Cloud, Foundry, or your own gateway, the answer for NTLM or Kerberos proxies
• Enterprise integration: deliver managed settings by MDM or server-managed settings and prove the policy is in force
• Dev containers for Claude Code: the same network settings inside a container with an egress firewall
• Monitoring Claude Code: send telemetry to your own collector through the proxy
• Team and enterprise overview: the rest of the team rollout