Claude Code proxy settings: corporate proxies, CA certificates and the network allowlist

To run Claude Code behind a corporate proxy, set HTTPS_PROXY to your proxy's URL before you launch claude, add hosts that should bypass it to NO_PROXY, and point NODE_EXTRA_CA_CERTS at your company's CA bundle if the proxy inspects TLS. Then allowlist the Anthropic hosts Claude Code needs, starting with api.anthropic.com, claude.ai and platform.claude.com.

This guide covers each setting, how to confirm it loaded, and the errors you'll see when something is off. It is based on Anthropic's enterprise network configuration page and the error reference, read on 26 October 2026. If you need to route model requests through a gateway rather than a plain proxy, see the LLM gateway guide.

How do you set a proxy for Claude Code?

Claude Code "respects standard proxy environment variables." Set them in the shell before launch:

# HTTPS proxy (recommended)
export HTTPS_PROXY=https://proxy.example.com:8080

# HTTP proxy, if HTTPS is not available
export HTTP_PROXY=http://proxy.example.com:8080

# Hosts that skip the proxy: comma- or space-separated
export NO_PROXY="localhost,192.168.1.1,example.com,.example.com"

claude

Details from the docs that save debugging time:

• Lowercase variants work too. Claude Code uses the first one that's set, in the order https_proxy, HTTPS_PROXY, http_proxy, HTTP_PROXY.
• NO_PROXY="*" bypasses the proxy for every request.
• Shell variables are read once at startup, so restart Claude Code after changing them.
• Claude Code never sends its WebSocket connections to localhost, ::1 or 127.0.0.0/8 through the proxy, so you don't need a loopback entry for those.
• "Claude Code does not support SOCKS proxies."

Proxies that need a password

For basic authentication, put the credentials in the URL:

export HTTPS_PROXY=http://username:password@proxy.example.com:8080

The docs warn against hardcoding passwords in scripts. For NTLM, Kerberos or other advanced schemes, Anthropic suggests considering an LLM gateway service that supports your authentication method.

Should you set the proxy in the shell or in settings.json?

Every variable on the network page can also go in the env block of a settings file:

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

Settings are the more reliable choice if you use background agents. The docs explain that claude agents, --bg and /background sessions run under a shared supervisor process that inherits the environment of whichever shell started it first. A proxy exported only in your shell may or may not reach those sessions. Putting it in ~/.claude/settings.json or managed settings means "settings are the only configuration that reaches every background session on every machine."

For rolling the same values out to a whole team, see the enterprise guide on managed settings. For where each settings file lives and which one wins, see the settings guide.

How do you trust a corporate CA certificate?

TLS-inspecting proxies re-sign traffic with their own certificate authority. By default Claude Code trusts both its bundled Mozilla CA set and your operating system's certificate store, so if IT has installed the proxy's root certificate in the OS store, it usually works with no extra setup. The native installer can always read the OS store; npm installs need Node 22.15 or later for that.

If it doesn't, point Claude Code at the CA file directly:

export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem

Two related controls:

• CLAUDE_CODE_CERT_STORE picks which stores to trust: bundled, system, or the default bundled,system. It has no dedicated settings key, so set it in the env block or your shell.
• If a TLS-inspecting proxy mishandles compressed request bodies, set CLAUDE_CODE_GZIP_REQUEST_BODIES=0.

The error reference is clear on one thing: don't set NODE_TLS_REJECT_UNAUTHORIZED=0, "which disables certificate validation entirely."

Client certificates (mTLS)

If your network requires client certificates, set:

export CLAUDE_CODE_CLIENT_CERT=/path/to/client-cert.pem
export CLAUDE_CODE_CLIENT_KEY=/path/to/client-key.pem
export CLAUDE_CODE_CLIENT_KEY_PASSPHRASE="your-passphrase"   # optional

To rotate them, replace the files at the same paths. Claude Code re-reads both files after a connection-level failure, such as a TLS handshake error, and when it next applies settings.

Which hosts does Claude Code need to reach?

Your proxy and firewall must allow the hosts in the network access requirements table. The core ones:

The full table adds optional hosts, including two Datadog intake hosts for operational telemetry, raw.githubusercontent.com for /release-notes, and formulae.brew.sh for Homebrew update checks. Setting CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC turns off telemetry and other nonessential traffic, but note that it also disables auto-updates.

On Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry, model traffic goes to your provider instead of api.anthropic.com, but the WebFetch tool still calls api.anthropic.com for its domain safety check unless you set skipWebFetchPreflight: true.

How do you check the proxy settings work?

Claude Code validates only one network setting at startup: a proxy URL it can't parse, such as one missing http://, stops launch with an error naming the variable. Everything else shows up later as a connection or certificate error, so check before you rely on it.

1. Test the network path from the same shell. curl -I https://api.anthropic.com should return headers. To test through the proxy explicitly, run curl -x http://proxy.example.com:8080 -I https://api.anthropic.com. On Windows PowerShell, use curl.exe.
2. Start with debug logging. Run claude --debug. The log goes to ~/.claude/debug/<session-id>.txt. Look for lines such as CA certs: Appended extra certificates from NODE_EXTRA_CA_CERTS and mTLS: Loaded client certificate from CLAUDE_CODE_CLIENT_CERT, or a Failed to read line with the reason.
3. Run /status. The Proxy row shows the active proxy URL and flags a value it can't parse. The mTLS client cert and mTLS client key rows appear only when those files loaded. The Additional CA cert(s) row shows the path without confirming the file loaded, so check the debug log for that one.

Which errors point to a proxy problem?

Login failures that aren't network related, such as expired tokens, are covered in the login troubleshooting guide.

How do you install Claude Code behind a proxy?

The installer itself needs the same path. Export both variables, then run the installer from that shell:

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash

If the download fails with a certificate error, pass your CA to curl with curl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash. To confirm you can reach the download server at all, curl -sI https://downloads.claude.ai/claude-code-releases/latest should return a 200 status. A 403 usually means a proxy or filter is blocking the host.

For containers on a locked-down network, the dev container guide covers limiting outbound traffic to the domains Claude Code needs.

Keep your network setup reusable

Once the variables work, save the exact env block and checks for the next laptop or teammate. Kipt keeps prompts and Agent Skills as Markdown in a private GitHub repo you own, so a "configure Claude Code for our proxy" prompt with a {{proxy_url}} blank stays one Cmd+K search away.