OmniscioGuidesCorporate proxy and SSL
Claude Code behind a corporate proxy and a TLS-inspecting firewall
Three things have to be true before Claude Code works on a locked-down network. Your proxy variables are set, your organization's root certificate is somewhere Claude Code trusts it, and the hosts it calls are allowed through the firewall.
If you arrived from an SSL certificate verification error, the cause is almost always the second one. Install your organization's root certificate in the operating system trust store, or point NODE_EXTRA_CA_CERTS at it. The rest of this page is how to do that, and what else has to be true.
If you want to know what a message means rather than how to fix the setup behind it, the connection errors guide covers the catalogue.
Sources read November 10, 2026. By the Omniscio team. Updated .
The three parts, and which one fails
Claude Code reaches Anthropic over ordinary HTTPS and reads the standard proxy variables. On a corporate network it also has to trust whatever certificate authority your security appliance uses when it opens those connections. The appliance re-signs the traffic as it passes through.
Anthropic documents all three parts on one page. Each part fails differently enough to diagnose from the message you get.
| Part | What to set | How it fails |
|---|---|---|
| The route out | HTTPS_PROXY, HTTP_PROXY, NO_PROXY | Connection refused, a timeout, or a proxy tunnel refusal |
| The trust | NODE_EXTRA_CA_CERTS, or the OS trust store | A certificate verification error, reported on the first attempt |
| The allowlist | The hosts in Anthropic's table | A connection that dies with no TLS conversation, or a sign-in that loops |
The one detail that shortens the diagnosis: a certificate validation failure is not retried. Since v2.1.199 Claude Code reports it on the first attempt, so a certificate error arrives immediately, while a network problem arrives after some waiting. If the message showed up the moment you ran the command, look at the certificate first.
The hosts Claude Code has to reach
Anthropic publishes the full list in its enterprise network configuration page, and it is longer than most people expect. These are the ones most installs need. The full table also lists optional hosts, and each of those drops out of the requirement when you turn its feature off. Allowlist them at the proxy and in the firewall rules.
| Host | What it carries |
|---|---|
api.anthropic.com | Model requests, the WebFetch domain safety check, feature flag fetches and telemetry |
claude.ai | Sign-in with a claude.ai account |
claude.com | The browser page sign-in opens before it redirects to claude.ai |
platform.claude.com | Console sign-in, plus the OAuth token exchange, refresh and revocation for claude.ai accounts |
sso.claude.com | The single sign-on leg of the browser sign-in flow |
mcp-proxy.anthropic.com | MCP connectors configured on claude.ai |
downloads.claude.ai | Plugin executables, the native installer and update checks |
registry.npmjs.org | npm and bun installs of Claude Code itself, npm-source plugins, and npx-launched MCP servers |
storage.googleapis.com | Plugin install counts and metadata shown in /plugin |
code.claude.com | Documentation lookups only, by the claude-code-guide agent and pre-approved WebFetch requests |
github.com and raw.githubusercontent.com | Marketplace clones over HTTPS or SSH, and the changelog feed behind /release-notes |
*.frame.claudeusercontent.com | Artifact content reads, only when the Artifact tool is available |
bridge.claudeusercontent.com | The Claude in Chrome extension's WebSocket bridge |
Anthropic's list gives hosts, not ports, so there is no port number on that page to look up. The rule your firewall team writes is outbound HTTPS to each host, with github.com as its own case because plugin installs can reach it over SSH as well.
Several entries are optional and disappear when the feature behind them is turned off. The two Datadog intake hosts, for example, are not in the table above: they carry only operational telemetry, and both go quiet with CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC set.
Two hosts behave differently from the rest. platform.claude.com handles the OAuth token exchange, refresh and revocation, so both sign-in methods need it, and a proxy that blocks it can fail sign-in for either one. A blocked sso.claude.com can likewise fail single sign-on.
Where the corporate root certificate goes
By default Claude Code trusts two certificate sources: the Mozilla CA set bundled with it, and your operating system's trust store.
Reading the OS store takes a runtime with tls.getCACertificates. The native installer always has it, and an npm install needs Node 22.15 or later. On an older Node, only the bundled set and NODE_EXTRA_CA_CERTS apply, which is worth knowing before you conclude the OS install did nothing.
That default is why some corporate machines need no configuration at all. Anthropic's own wording is that an enterprise TLS-inspection proxy works without additional setup when its root certificate is installed in the OS trust store and the runtime can read that store.
So the first thing to check is whether IT already pushed the root to the machine. The second is whether your Claude Code is a native install or an npm one on an old Node, which node --version answers on an npm install.
One follow-up belongs to this same case. If the inspecting proxy mishandles gzip-compressed request bodies, set CLAUDE_CODE_GZIP_REQUEST_BODIES=0 to turn compression off for API, telemetry and artifact-publish requests. Claude Code already skips compression when it sends through a proxy, sees a client certificate or has NODE_EXTRA_CA_CERTS set. The variable is for the case where those signals did not reach it.
The explicit route: NODE_EXTRA_CA_CERTS
When the OS store is not an option, or you want the trust to be explicit, point Claude Code at a PEM bundle:
NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pemThe file is appended to what Claude Code already trusts rather than replacing it. If part of the bundle cannot be read, Claude Code says so and carries on with the certificates it could read in full. A connection that needs a skipped certificate still fails.
Two warnings name that case: one for a partly read file, and one for a file it could read nothing from. Each says how to fix the file.
A certificate that is skipped but also present in the CA certificate store Claude Code is configured to use still works.
Choosing which stores count: CLAUDE_CODE_CERT_STORE
This variable takes a comma-separated list of sources.
bundledis the Mozilla set shipped with Claude Code.systemis the operating system store.- The default is
bundled,system. Setting it tosystemalone is the usual choice for a machine whose trust is managed centrally, because it makes the OS store the single authority.
It has no dedicated key in the settings schema, so it goes in the env block of ~/.claude/settings.json or straight into the process environment.
Confirming it loaded
Claude Code does not check most of these settings when it reads them, so the confirmation is the debug log. Start with claude --debug and look for the line that says the extra certificates were appended, naming the path. The log goes to ~/.claude/debug/<session-id>.txt, not the terminal.
/status shows the path in its Additional CA cert(s) row, but that row prints the path without checking that the file loaded. The log is what settles it.
A file it could not read appears there as a Failed to read or Failed to load line with the reason.
Why NODE_TLS_REJECT_UNAUTHORIZED=0 is the wrong shortcut
It turns up throughout the discussion of this error, and it is the one step Anthropic names explicitly as something not to do. It turns certificate validation off entirely instead of teaching Claude Code who to trust.
The connection starts working, so the symptom goes away. What also goes away is the check that told you a proxy was opening your traffic, which is the check you were trying to satisfy in the first place.
There is a practical cost too. With validation off, any certificate on the path is accepted, including one that does not belong to the host you asked for. The two messages you are trying to clear, UNABLE_TO_GET_ISSUER_CERT_LOCALLY and SELF_SIGNED_CERT_IN_CHAIN, both end by naming NODE_EXTRA_CA_CERTS and the network configuration page, which is the road Anthropic intends you to take.
The proxy variables, and the one place they have to live
Claude Code reads the standard variables:
HTTPS_PROXYfor an HTTPS proxy, andHTTP_PROXYwhen there is no HTTPS one.NO_PROXYfor hosts that should skip it, as a space-separated or comma-separated list.
Lowercase spellings work, and when more than one is set the first in the order https_proxy, HTTPS_PROXY, http_proxy, HTTP_PROXY wins.
You do not need a loopback entry in NO_PROXY, because WebSocket connections to localhost are never sent through the proxy.
Two limits are worth knowing before you debug a proxy that looks correct.
- No SOCKS proxies. Claude Code does not support them.
- Basic authentication goes in the URL itself, which Anthropic pairs with a warning not to hardcode a password in a script. For NTLM or Kerberos, Anthropic points at an LLM gateway instead, because the CLI has no way to negotiate those.
Where you set them decides whether they reach every session. Claude Code reads these variables once at startup, so a running session never sees a later change to your shell.
The sharper trap is background agents. A per-user supervisor process hosts every background session. It outlives your shell, and it is shared by every terminal, so it inherits the environment of whichever shell happened to start it first. A proxy exported in your shell therefore reaches a background agent only sometimes.
Put the proxy and certificate variables in the env block of ~/.claude/settings.json, or in managed settings. Managed settings means the settings file your IT department deploys to the machine, rather than the one you own.
Settings are the configuration that reaches every session on every machine.
{
"env": {
"HTTPS_PROXY": "http://proxy.example.com:8080",
"NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/corp-root.pem"
}
}If your network hands out a proxy auto-config file rather than fixed variables, note what Anthropic's page covers: it documents the variables and does not mention PAC files at all. The proxy address the script would pick is the value to put in HTTPS_PROXY.
If your organization also requires every process to start through a corporate launcher, that launcher needs the same treatment. The supervisor starts Claude Code from a fixed path rather than looking it up on PATH, so a wrapper placed earlier on PATH is bypassed by every background agent.
The processWrapper setting, or CLAUDE_CODE_PROCESS_WRAPPER, prefixes those processes with your launcher. It has to be delivered through managed settings or the user settings file.
The variable needs v2.1.208 or later and the setting v2.1.210, and the variable is ignored on Windows.
After deploying it, an already-running supervisor keeps the configuration it started with. Stop it with claude daemon stop --any, and let the next background session start a new one.
One proxy setting is checked at launch. A proxy URL Claude Code cannot parse, such as one missing the http:// scheme, stops the launch with an error naming the variable.
Anthropic's wording for the rest is that it does not validate most of these settings when it reads them. A wrong value therefore tends to surface as a failed request, not as a complaint at launch.
When the proxy wants a client certificate
Some corporate proxies authenticate the client rather than the user, using mutual TLS. Claude Code takes the pair through three variables: CLAUDE_CODE_CLIENT_CERT for the certificate, CLAUDE_CODE_CLIENT_KEY for the private key, and CLAUDE_CODE_CLIENT_KEY_PASSPHRASE when the key is encrypted.
Rotation is handled without a restart, with one condition. Since v2.1.232, Claude Code re-reads both files when a request fails at the connection level. That covers a reset, a TLS handshake error, or a gateway that has stopped accepting the old pair.
Before v2.1.232 it never re-read them on a connection error, and kept the pair it had loaded until the next settings change or restart.
It does not re-read when the handshake succeeds and the answer is an HTTP error. That is the case that surprises people, so a gateway that rejects an expired certificate politely needs a restart or the next settings change.
The debug log shows Stale connection — reloaded rotated mTLS client material when the reload happens. That line is absent when the rotation was picked up while applying settings instead, so a missing line on its own proves nothing.
Cloud sessions are the exception to this whole page. In a cloud session the hosting environment manages the connection, so NODE_EXTRA_CA_CERTS, NODE_TLS_REJECT_UNAUTHORIZED and the three client-certificate variables do not take effect when a settings file sets them. Claude Code notes each ignored key in the debug log.
Claude Desktop sessions where the app manages the connection are narrower in a different way. They read the proxy and certificate variables only from managed settings and ~/.claude/settings.json, never from a repository's own settings files.
How a gateway changes the list
If you reach Claude Code through Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry or a signed-in Claude apps gateway, the host list shifts rather than disappears. Model traffic and authentication go to that provider or gateway instead of to api.anthropic.com, claude.ai and platform.claude.com.
A plain gateway reached by ANTHROPIC_BASE_URL moves the model traffic too. Without a gateway credential, though, the saved claude.ai login stays the active credential, so authentication still reaches Anthropic.
That is the part people expect. The parts that stay are the ones that catch a firewall change.
- WebFetch keeps calling Anthropic. Its domain safety check goes to
api.anthropic.comeven behind a gateway, unless you setskipWebFetchPreflight: truein settings. - The fast mode check never reaches the gateway. When it is sent, it calls
api.anthropic.comdirectly through any configured HTTP proxy, so on a network that blocks direct egress fast mode can report a connectivity error while inference through the gateway keeps working. Claude Code skips the check altogether in some gateway setups, such as whenCLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICis set, and a check that succeeded before keeps working from its cached result. - The connection-warming probe is skipped when you have a proxy. An Anthropic-format gateway normally receives a
HEAD /api/helloprobe, and Claude Code skips it when an HTTP proxy or a client certificate is configured. - A gateway session is not eligible for the HIPAA configuration. If your compliance story depends on that, the gateway route changes it.
The gateway itself has requirements on the response side that matter on a locked-down network. It has to forward the event stream rather than buffer it, and it has to keep the keep-alive pings that the streaming watchdog counts as traffic.
A gateway that holds a response until it is complete makes Claude Code stall. One that strips the pings trips the idle timeout partway through a reply.
Four checks that separate the three parts
- Does the shell reach the API at all? Run
curl -I https://api.anthropic.comin the same shell you start Claude Code from. On Windows PowerShell usecurl.exeso the built-inInvoke-WebRequestalias is not used instead, because the alias fails differently and reads like a different problem. - Does the proxy reach it? Add the proxy explicitly:
curl -x http://proxy.example.com:8080 -I https://api.anthropic.com. If that fails while the direct check passes, the proxy is the problem, not the certificate. - Did the certificate load? Start with
claude --debugand read the CA line. A path that is set but unreadable looks exactly like a path that is wrong until you read the log. - Is a settings file overriding you? When the launch environment already sets a variable, Claude Code ignores the settings file's value and names the variable in the debug log. That log line is the fastest way to find out that the value you edited is not the value in use.
There is one dead end worth naming so you do not spend a day on it. If the network is open and the first-run connectivity check still fails, Anthropic's own answer is that Claude Code may not be available in your country. That is a policy limit, not a proxy or certificate problem, and no variable fixes it.
Where Omniscio fits, and where it does not
On this problem, almost nowhere, and it is worth saying so rather than stretching a connection. Omniscio is the desktop app we make for running several Claude Code sessions at once in one window.
It does not sit between Claude Code and the network, and it does not change which certificate authority signs your traffic. A proxy or an inspecting appliance treats the app's sessions exactly as it treats the CLI.
The one setting here that the app touches is NO_PROXY. When it gives a session its hook host, it keeps the entries you set and adds the loopback names, because a proxy cannot reach this machine's own address.
What it changes is where you notice the failure. When a network change breaks several sessions, the app shows them as failed rows in one list instead of leaving you to check each window.
That is a small thing next to a certificate that will not validate. The features page lists what the app does, and the download page has the installers.
Sources
Every setting, warning and behaviour on this page comes from one of these, read in Markdown form on November 10, 2026. Anthropic publishes the network material on one page; the error wording lives on another, and the two are cross-referenced.
- Enterprise network configuration, for the proxy variables and their order, basic authentication, the SOCKS limit, the CA certificate store and
CLAUDE_CODE_CERT_STORE,NODE_EXTRA_CA_CERTSand its two warnings, mTLS and rotation, the verification steps, background agents and the launcher, the streaming watchdogs, and the required host table. Read November 10, 2026. - Errors, for the certificate message wording, the note that a validation failure is not retried since v2.1.199, the sign-in and first-run variants, and the statement not to set
NODE_TLS_REJECT_UNAUTHORIZED=0. Read November 10, 2026. - Environment variables, for
CLAUDE_CODE_GZIP_REQUEST_BODIES,CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICandCLAUDE_CODE_PROCESS_WRAPPER. Read November 10, 2026. - Gateway compatibility guide, for what moves to a gateway, the WebFetch and fast mode calls that stay on
api.anthropic.com, theHEAD /api/helloprobe, gateway streaming requirements, and the HIPAA note. Read November 10, 2026.
Two things on this page are ours rather than Anthropic's: the order the checks are in, and the statement that Omniscio plays no part beyond the NO_PROXY loopback entries. Nothing here was tested against a specific appliance, because a corporate proxy is not something we can reproduce, and the page does not claim otherwise.
Common questions
What does SSL certificate verification failed mean in Claude Code?
A proxy or security appliance on your network is opening the TLS connection and presenting its own certificate, and Claude Code does not trust the authority that signed it. The fix is to give Claude Code that authority: set NODE_EXTRA_CA_CERTS to your organization's CA bundle, or install the root certificate in the operating system trust store. Do not turn certificate checking off.
Where do I put a corporate CA certificate for Claude Code?
Two places work. Set NODE_EXTRA_CA_CERTS to the path of a PEM bundle, which Claude Code appends to the certificates it already trusts, or install the root in the operating system trust store, which Claude Code reads by default when its runtime supports it. CLAUDE_CODE_CERT_STORE chooses between the bundled Mozilla set, the system store, and both.
How do I turn the certificate IT gave me into a PEM file?
Claude Code is given a path to a PEM file, so the certificate has to be in that format: one or more blocks that begin with a BEGIN CERTIFICATE line. When IT hands you a .cer or .crt file, the OpenSSL tool rewrites it with openssl x509 -in corp-root.crt -out corp-root.pem, and PEM is that tool's default output format. If you were given a .p7b bundle or a DER file, ask for the certificate exported as PEM instead. Whichever road you take, check the load in the claude --debug log, because a file Claude Code cannot read whole is reported there.
Is NODE_TLS_REJECT_UNAUTHORIZED=0 a safe way past the certificate error?
No. Anthropic says not to set it, because it disables certificate validation entirely rather than fixing the trust. Claude Code keeps working with a certificate it cannot verify, so a real interception on the path becomes invisible too. Use NODE_EXTRA_CA_CERTS instead.
Which ports must be open for Claude Code?
Anthropic publishes a list of hostnames, not port numbers, so the port is your firewall team's rule rather than a value on that page. Ask for outbound HTTPS to each host in the list, and treat github.com as its own case, because plugin installs can reach it over HTTPS or SSH.
Does a gateway mean api.anthropic.com can stay blocked?
Not always. Model traffic and authentication move to the gateway, but the WebFetch domain safety check still calls api.anthropic.com unless skipWebFetchPreflight is set, and when the fast mode availability check is sent it calls that host directly through your proxy rather than the gateway. Claude Code skips the check in some gateway setups, so a blocked host costs you less than it looks, and a check that succeeded before keeps working from its cache.
Why does Claude Code work in my terminal but fail in a background agent?
Background agents run under a per-user supervisor process that outlives your shell and is shared by every terminal. It inherits the environment of whichever shell started it first, so a proxy or CA path exported in your own shell reaches a background session only sometimes. Put those variables in the env block of ~/.claude/settings.json or managed settings instead.