Claude Code Behind a Corporate Proxy: Proxy, CA Certs and Fixes

To run Claude Code behind a corporate proxy, you need three things from your network team: the proxy URL, your company's root CA certificate if the proxy inspects TLS, and confirmation that the hosts Claude Code talks to are allowed. Put HTTPS_PROXY and, if needed, NODE_EXTRA_CA_CERTS in the env block of ~/.claude/settings.json, start a new session, and run /status to check the Proxy row. That covers most company networks.

The rest of this guide is the detail that makes the difference between "works on my laptop at home" and "works on the office network on day one": which surface reads which file, what to allowlist, and what each error actually means.

Claude Code respects the standard proxy environment variables. HTTPS_PROXY is the one to set. HTTP_PROXY is the fallback if your proxy does not offer HTTPS. NO_PROXY lists hosts that should skip the proxy, and it accepts either spaces or commas between entries. Lowercase versions work too, and Claude Code uses the first one it finds in this order: https_proxy, HTTPS_PROXY, http_proxy, HTTP_PROXY.

If the proxy asks for a username and password, put them in the URL: http://username:password@proxy.example.com:8080. Do not paste that into a script or a committed file. Keep it in your user settings, or have your IT team push it through managed settings. You do not need a NO_PROXY entry for localhost to keep Claude Code's own local connections working, since those never go through the proxy.

Many corporate proxies inspect TLS traffic. They decrypt and re-encrypt it with a certificate signed by your company's own certificate authority. Any tool that does not trust that authority sees a certificate it cannot verify and refuses to connect.

Claude Code trusts two certificate sources by default: the Mozilla CA set it ships with, and your operating system's certificate store. If your IT team has installed the company root certificate on your laptop, which is normal on managed machines, Claude Code installed with the native installer usually works with no extra setup. npm installs need Node 22.15 or later to read the operating system store. On older Node versions, only the bundled set and NODE_EXTRA_CA_CERTS apply.

If you still get certificate errors, ask IT for the company CA bundle as a .pem file and set NODE_EXTRA_CA_CERTS to its path. If your company also requires client certificates (mutual TLS), set CLAUDE_CODE_CLIENT_CERT and CLAUDE_CODE_CLIENT_KEY to the certificate and key files, plus CLAUDE_CODE_CLIENT_KEY_PASSPHRASE if the key is encrypted. When IT rotates those files, replace them at the same paths: Claude Code re-reads them and retries after a TLS or connection failure, so a running session usually picks up the new pair without a restart.

This is the step most guides skip, and it is the one that causes the "it works in my terminal but not in the app" reports. Claude Code reads shell variables once, at startup. Different surfaces start from different places, so a proxy exported in your .zshrc is not guaranteed to reach all of them.

The background agents row is worth explaining. Background sessions run under a shared supervisor process that inherits the environment of whichever shell started it first. Export the proxy in one terminal and not another, and your background agents work some days and fail on others. The settings file removes the guesswork.

So my default is simple: one env block in ~/.claude/settings.json holding HTTPS_PROXY, NO_PROXY and NODE_EXTRA_CA_CERTS. It covers the desktop app, which is where I tell most people to start, plus the terminal and every background agent. The settings.json guide shows where the env block goes, and Claude Code environment variables covers the other places you can set them.

Start with curl from the same shell: curl -x with your proxy URL and -I https://api.anthropic.com. On Windows PowerShell use curl.exe so the built-in alias is not used. If that fails, the problem is the proxy or the network, not Claude Code, and no setting inside Claude Code will fix it.

Then start a new Claude Code session and run /status. Three rows matter. Proxy shows the active proxy URL and marks a value it cannot parse as invalid. The mTLS client cert and key rows only appear if those files loaded, so a missing row means the load failed. Additional CA cert(s) shows the NODE_EXTRA_CA_CERTS path but does not prove the file loaded.

For that last one, start Claude Code with claude --debug. The log goes to a file under ~/.claude/debug rather than your terminal. Look for a line saying it appended extra certificates from NODE_EXTRA_CA_CERTS. A Failed to read or Failed to load line tells you exactly which file is wrong. One more useful detail: a proxy URL missing its http:// scheme stops Claude Code at launch with an error naming the variable, so that mistake at least announces itself.

If your company blocks by default, send IT this list. All traffic is HTTPS on port 443 unless you configure a custom port for something like an LLM gateway or an MCP server.

The desktop app needs more than the terminal does, because it loads its own interface from the content hosts: anthropic.com, claude.ai, claude.com and claude.app with their subdomains, plus *.claudeusercontent.com and *.claudemcpcontent.com. Allow claude.ai but block those and you get a blank window, not an error message, which is a miserable thing to debug. If the app opens to a blank screen on the office network but works at home, check this first.

If you run Claude Code through Amazon Bedrock or another cloud provider, model traffic goes to that provider instead of api.anthropic.com. The Bedrock guide covers that route, and the same proxy and CA settings apply to it.

If curl works but Claude Code does not, the cause is usually something local. A disconnected VPN can leave a stale tunnel interface on macOS, WSL can inherit a broken DNS resolver from Windows, and Docker Desktop can intercept outbound traffic. Rule those out before you open a ticket. Claude Code doctor is the quickest way to see what your install thinks is wrong, and the MCP troubleshooting guide covers MCP servers that fail for network reasons.