Follow Discord
Sweep 03 Nov 2026 · 22:27Z Build v2.1.318 536 read Stable v2.1.311 Latest v2.1.318 Next v2.1.318 Feeds RSS JSON llms.txt llms-full.txt Unofficial
HomeDocsClaude Documentation 30 Oct 2026
One change · claude-docs

Network proxy changedthird-party/claude-desktop/network-proxy

Nearest release: v2.1.315, published 2 hours after upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.

Upstream edited this page at 30 Oct 2026 18:36 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 30 Oct 2026 18:37 UTC.

Upstream edited
Recorded here
Lines+25added
Lines−9removed
From line 2 where the diff opens
First seen 2 Sep 2026 this site's first read of the page
Recorded edits17to this page, all time

The whole hunk

from line 2, old and new numbered
/
lines
from line 2
22 
33> How Claude Desktop on 3P and the Claude Code engine it runs use your network proxy: the default behavior, pinning a proxy from managed configuration, what is and is not routed through it, and how to troubleshoot.
44 
5Claude Desktop on 3P works behind a corporate HTTP proxy without extra configuration in most environments. This page explains which proxy each part of the product uses, how to pin a specific proxy from managed configuration, which traffic does not go through the proxy at all, and how a separately deployed Claude Code policy interacts with it.
5Claude Desktop on 3P works behind a corporate HTTP proxy without extra configuration in most environments.
66 
77Three parts of the product make network connections, and they do not all resolve the proxy the same way:
88 
from line 48
4848| `egressProxyUrl` | An `http://` or `https://` proxy URL, for example `http://proxy.example.com:8080` | The app sends its traffic through this proxy, and the agent receives it as `HTTPS_PROXY` and `HTTP_PROXY` in every session on the device. On macOS and Windows, commands in Cowork's sandboxed shell receive the same variables. Loopback and `.local` hosts still connect directly. |
4949| `egressProxyPacUrl` | An `http://` or `https://` URL to a PAC script, for example `http://wpad.example.com/proxy.pac` | The app evaluates the script per request. The agent receives the single proxy the script returns for your inference endpoint. On macOS and Windows, Cowork's sandboxed shell is handed a copy of the script when the sandbox starts and evaluates it per request itself. If both keys are set, this one wins. |
5050 
51Both keys are read once at launch; a change takes effect the next time the app starts. While either key is set, the OS proxy settings are ignored for the app, the agent, and (on macOS and Windows) Cowork's sandboxed shell; with neither key set, the sandboxed shell keeps following the OS settings as described under [Default behavior](#default-behavior). SOCKS URLs and URLs with embedded credentials (`user:password@`) are rejected.
51Both keys are read once at launch; a change takes effect the next time the app starts. While either key is set, the OS proxy settings are ignored for the app, the agent, and (on macOS and Windows) Cowork's sandboxed shell. SOCKS URLs and URLs with embedded credentials (`user:password@`) are rejected.
5252 
53If you point the key at a local forwarding proxy on the device, give it as `http://127.0.0.1:<port>`. Cowork's sandboxed shell reaches the device's loopback address through a host alias, so an `https://` loopback proxy cannot pass TLS verification from inside the sandbox and the shell's commands fail to connect; the app logs a warning at sandbox start when it sees that combination.
53If you point the key at a local forwarding proxy on the device, give it as `http://127.0.0.1:<port>`. An `https://` loopback proxy cannot pass TLS verification from inside Cowork's sandboxed shell, so the shell's commands fail to connect. The app logs a warning at sandbox start when it sees that combination.
5454 
5555These keys are read from an MDM profile, registry policy, or local configuration file only; they are ignored if returned from a bootstrap server. They also follow the same precedence rule as the update keys: when an MDM profile or registry policy sets any key in that group, values for these keys in a local configuration file are ignored. See [Update keys and managed precedence](https://claude.com/docs/third-party/claude-desktop/mdm.md#update-keys-and-managed-precedence).
5656 
from line 95
9595 
9696## Traffic that bypasses the app proxy
9797 
98Some traffic never uses the pinned key or the proxy the app resolved, and it is worth being explicit about each case and what you can do about it.
98Some traffic never uses the pinned key or the proxy the app resolved.
9999 
100100* **App updates.** Checking for and downloading Claude Desktop updates is handled by the OS-native updater on macOS and Windows, which follows the OS proxy settings only. This is the one app-controlled path with no admin-side option other than the OS proxy: neither the pinned key nor Claude Code managed settings reach it. If updates must not traverse a direct path, configure the OS proxy on the device or distribute updates yourself with [`disableAutoUpdates`](https://claude.com/docs/third-party/claude-desktop/configuration) and your software-distribution tool. On Linux, updates come from your package manager, which has its own proxy configuration.
101101* **Commands in Cowork's sandboxed shell.** No proxy settings reach the Cowork sandbox on Linux, so `curl`, `pip`, `npm`, `git`, and anything else the agent runs there connect directly. On macOS and Windows those commands follow the pinned key, or the OS proxy settings when no key is set. When the key or the OS settings name a PAC script, the commands follow it only while the sandbox has [its copy of the script](#pac-script-for-the-sandboxed-shell). If the download of a pinned PAC script fails when the sandbox starts, the commands connect directly until the sandbox next starts. On every platform, [`coworkEgressAllowedHosts`](https://claude.com/docs/third-party/claude-desktop/web-tools) still applies inside the sandbox and sits in front of any proxy.
from line 104
104104* **SSH remote Code sessions.** When a user runs a Code session on another machine through [`sshHostAllowlist`](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions), the agent runs on that host and connects to the inference endpoint from there. Claude Desktop passes the endpoint address to the remote agent but not the pinned key, the device's OS proxy settings, or proxy variables from Claude Code managed settings on the device. The host's own network route and any Claude Code managed settings installed on the host apply instead. See [Inference credentials on the remote host](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions.md#inference-credentials-on-the-remote-host).
105105* **Pages opened in the system browser.** Some sign-in flows open your default browser. That traffic follows the browser's proxy settings, which normally track the OS; pin it with the browser's own policy (for example, the Chrome or Edge `ProxySettings` policy) or the device's network profile.
106106* **Brokered Microsoft Entra sign-in.** When [brokered authentication](https://claude.com/docs/third-party/claude-desktop/entra-broker.md) is in use, the token request is made by Company Portal (macOS) or Web Account Manager (Windows), not by the app. Those components follow the OS proxy settings; configure them through the same MDM that manages the device.
107* **Helper scripts.** An `inferenceCredentialHelper` or MCP `headersHelper` script runs with the app's environment and no injected proxy variables, because helpers typically talk to internal vaults or identity providers that should not go through the inference proxy. If a helper needs a proxy, set it inside the script.
107* **Helper scripts.** An `inferenceCredentialHelper` or MCP `headersHelper` script runs with the app's environment and no injected proxy variables. If a helper needs a proxy, set it inside the script.
108108* **Programs that ignore proxy variables.** The agent passes `HTTPS_PROXY`, `HTTP_PROXY`, and `NO_PROXY` to the programs it launches on the device, but a program that does not honor those variables connects directly if the network allows it. The only complete control for this case is blocking direct egress at the network layer.
109109 
110110> [!WARNING]
from line 128
128128>
129129> The precedence described here requires Claude Desktop 1.44121.1 or later, the same release as the pinned-proxy keys above.
130130 
131If you deploy Claude Code [managed settings](https://code.claude.com/docs/en/settings#settings-files) on the device (a `managed-settings.json` file or an OS-level Claude Code policy) and its `env` block sets `HTTPS_PROXY`, `HTTP_PROXY`, or `NO_PROXY`, those values apply to the agent in Chat, Cowork, and Code sessions alike and take precedence over what the app would have supplied. Precedence is per variable: a managed `HTTPS_PROXY` replaces the app's proxy while the app's loopback `NO_PROXY` entries stay in place, and a managed `NO_PROXY` replaces the app's list (the loopback entries are appended for you when the app is also supplying the proxy). See Claude Code's [network configuration](https://code.claude.com/docs/en/network-config) page for the variables themselves.
131In Claude Code [managed settings](https://code.claude.com/docs/en/settings#settings-files) on the device (a `managed-settings.json` file or an OS-level Claude Code policy), you can set `HTTPS_PROXY`, `HTTP_PROXY`, or `NO_PROXY` in the `env` block. Those values apply to the agent in Chat, Cowork, and Code sessions and take precedence over what the app would have supplied. Precedence is per variable:
132132 
133* A managed `HTTPS_PROXY` replaces the app's proxy, and the app's loopback `NO_PROXY` entries stay in place.
134* A managed `NO_PROXY` replaces the app's list. When the app is also supplying the proxy, the loopback entries are appended.
135 
136See Claude Code's [network configuration](https://code.claude.com/docs/en/network-config) page for the variables themselves.
137 
133138```json managed-settings.json theme={null}
134139{
135140 "env": {
from line 180
175180 
176181**"Can't reach" banner.** The app could not get a response from the inference host the banner names. Behind a proxy this usually means the proxy resolved for that host is unreachable, requires a sign-in the app cannot perform, or does not allow the host. Use **Copy report for IT** on the banner to capture the details, confirm the device's OS proxy settings (or the pinned key) point at a reachable HTTP proxy, and confirm the proxy allows the inference host listed in [Required egress paths](https://claude.com/docs/third-party/claude-desktop/telemetry.md#required-egress-paths).
177182 
178**Confirm which proxy is in effect.** Open `main.log` in the app's [logs directory](https://claude.com/docs/third-party/claude-desktop/data-storage.md). When a key is pinned, startup logs `[egress-proxy] pinned to fixed proxy at proxy.example.com:8080; OS proxy settings ignored` (or `pinned to PAC script at …`). The log records the proxy handed to the agent the first time and whenever it changes, for example `Resolved system proxy for Code sessions: http://proxy.example.com:8080`, a `Keeping system proxy` line when the app reuses the last proxy because the OS answer was direct, SOCKS, or missing, and a `Skipping SOCKS proxy entry` line if the OS answer was SOCKS. If Claude Code managed settings supplied any proxy variable, a line names the variables it set or replaced and the settings file they came from. For Cowork's sandboxed shell, `cowork_vm_node.log` in the same directory records `[VM:start] guest egress pinned to fixed proxy at …` (or `PAC script at …`) when the sandbox starts with a key pinned, and `[VM:start] PAC fetch from … failed (…); guest connects directly` if the sandbox's copy of the script could not be downloaded.
183**Confirm which proxy is in effect.** Open `main.log` in the app's [logs directory](https://claude.com/docs/third-party/claude-desktop/data-storage.md) and look for these lines:
179184 
185* **Key pinned**: at startup, `[egress-proxy] pinned to fixed proxy at proxy.example.com:8080; OS proxy settings ignored` (or `pinned to PAC script at …`)
186* **Proxy handed to the agent**: logged the first time and whenever it changes, for example `Resolved system proxy for Code sessions: http://proxy.example.com:8080`
187* **Last proxy reused**: a `Keeping system proxy` line, when the OS answer was direct, SOCKS, or missing
188* **SOCKS answer from the OS**: a `Skipping SOCKS proxy entry` line
189* **Proxy variables from Claude Code managed settings**: a line that names the variables set or replaced, and the settings file they came from
190 
191For Cowork's sandboxed shell, open `cowork_vm_node.log` in the same directory and look for these lines:
192 
193* **Key pinned when the sandbox starts**: `[VM:start] guest egress pinned to fixed proxy at …` (or `PAC script at …`)
194* **Sandbox's copy of the script not downloaded**: `[VM:start] PAC fetch from … failed (…); guest connects directly`
195 
180196**Agent connects directly while the app is proxied.** The OS or PAC answer for the inference endpoint was `DIRECT` or SOCKS-only. Adjust the PAC rule for the inference host, or pin `egressProxyUrl`.
181197 
182198**New sessions keep using a proxy after the device leaves its network.** Once the app has been given a proxy for the inference endpoint, it keeps handing that proxy to new sessions while the OS or PAC answer is a direct connection, a SOCKS proxy, or no answer. Quit and reopen Claude Desktop.
183199 
184**Cowork's sandboxed shell has no proxy on macOS while the app is proxied.** Check the PAC address in the OS proxy settings. The sandboxed shell uses its own copy of the PAC script. macOS refuses the download of that copy from a plain `http://` address unless the host is a name with no dot in it, a `.local` name, a loopback address, or a private-network IPv4 address such as `10.0.0.5`. The app's logs then record `PAC fetch from … refused: macOS requires https for this address (App Transport Security)`, which you can search for in the [logs directory](https://claude.com/docs/third-party/claude-desktop/data-storage.md). Serve the script over `https://`. See [PAC script for the sandboxed shell](#pac-script-for-the-sandboxed-shell).
200**Cowork's sandboxed shell has no proxy on macOS while the app is proxied.** Check the PAC address in the OS proxy settings. The sandboxed shell uses its own copy of the PAC script. macOS refuses the download of that copy from a plain `http://` address unless the host is one of the exceptions listed under [PAC script for the sandboxed shell](#pac-script-for-the-sandboxed-shell). The app's logs then record `PAC fetch from … refused: macOS requires https for this address (App Transport Security)`, which you can search for in the [logs directory](https://claude.com/docs/third-party/claude-desktop/data-storage.md). Serve the script over `https://`.
185201 
186202**Web fetches or MCP connections fail in Code sessions but inference works.** Either the proxy resolved for the inference endpoint does not carry that traffic, or the answer for the inference endpoint was `DIRECT` and the agent has no proxy. See [The agent uses one proxy](#the-agent-uses-one-proxy).
187203 
Feedback