Network proxy changedthird-party/claude-desktop/network-proxy
Nearest release: v2.1.302, 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 16 Oct 2026 14:21 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 22 Oct 2026 18:07 UTC.
Upstream edited
Recorded here
Lines+14added
Lines−14removed
From line
10
where the diff opens
First seen
2 Sep 2026
this site's first read of the page
Recorded edits12to this page, all time
The whole hunk
from line 10, old and new numbered
/
from line 10
1010* **The agent**: the Claude Code engine the app runs for every Chat, Cowork, and Code session. It sends inference requests and, in Code sessions, also makes its own web fetches, remote MCP connections, and plugin installs.
1111* **Cowork's sandboxed shell**: the isolated environment where commands the agent runs in a Cowork session (`curl`, `pip`, `npm`, and so on) execute.
1212
13With [Unified Claude](/docs/third-party/claude-desktop/unified-claude) on, a Cowork session started from the home screen runs its commands in Cowork's sandboxed shell.
13With [Unified Claude](/docs/third-party/claude-desktop/unified-claude.md) on, a Cowork session started from the home screen runs its commands in Cowork's sandboxed shell.
1414
1515## Default behavior
1616
from line 52
5252
5353If 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.
5454
55These 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](/docs/third-party/claude-desktop/mdm#update-keys-and-managed-precedence).
55These 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](/docs/third-party/claude-desktop/mdm.md#update-keys-and-managed-precedence).
5656
5757On Linux, or wherever you deploy the local configuration file, the key sits alongside your other settings:
5858
from line 62
6262}
6363```
6464
65In a macOS configuration profile the same key is a `<key>egressProxyUrl</key><string>http://proxy.example.com:8080</string>` pair in the `com.anthropic.claudefordesktop` payload, and on Windows it is a `REG_SZ` value named `egressProxyUrl` under `HKLM\SOFTWARE\Policies\Claude`. See [Value types](/docs/third-party/claude-desktop/configuration#value-types) and [Deploy with MDM](/docs/third-party/claude-desktop/mdm) for the surrounding profile and registry structure.
65In a macOS configuration profile the same key is a `<key>egressProxyUrl</key><string>http://proxy.example.com:8080</string>` pair in the `com.anthropic.claudefordesktop` payload, and on Windows it is a `REG_SZ` value named `egressProxyUrl` under `HKLM\SOFTWARE\Policies\Claude`. See [Value types](/docs/third-party/claude-desktop/configuration.md#value-types) and [Deploy with MDM](/docs/third-party/claude-desktop/mdm.md) for the surrounding profile and registry structure.
6666
6767Three behaviors to plan for:
6868
from line 86
8686| OpenTelemetry export to your collector | App proxy for the app's own events; the same single proxy as inference for Claude Code metrics and logs |
8787| Commands in Cowork's sandboxed shell on macOS and Windows | The pinned key if one is set (a pinned PAC script is evaluated per request inside the sandbox), otherwise the OS proxy settings |
8888| Commands in Cowork's sandboxed shell on Linux | None; commands connect directly |
89| The agent in an [SSH remote Code session](/docs/third-party/claude-desktop/ssh-remote-sessions) | None from the device; the remote host's own network route applies |
89| The agent in an [SSH remote Code session](/docs/third-party/claude-desktop/ssh-remote-sessions.md) | None from the device; the remote host's own network route applies |
9090| App update check and download | OS proxy settings only |
9191| Credential helper and header helper scripts you configure | None injected; the script's own environment applies |
9292| Brokered Microsoft Entra sign-in (Company Portal on macOS, Web Account Manager on Windows) | The OS broker's own settings |
from line 98
9898
9999* **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`](/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.
100100* **Commands in Cowork's sandboxed shell on Linux.** 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, and are not a bypass. On every platform, [`coworkEgressAllowedHosts`](/docs/third-party/claude-desktop/web-tools) still applies inside the sandbox and sits in front of any proxy, so an allowed host is then reached through the proxy.
101* **SSH remote Code sessions.** When a user runs a Code session on another machine through [`sshHostAllowlist`](/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](/docs/third-party/claude-desktop/ssh-remote-sessions#inference-credentials-on-the-remote-host).
101* **SSH remote Code sessions.** When a user runs a Code session on another machine through [`sshHostAllowlist`](/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](/docs/third-party/claude-desktop/ssh-remote-sessions.md#inference-credentials-on-the-remote-host).
102102* **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.
103* **Brokered Microsoft Entra sign-in.** When [brokered authentication](/docs/third-party/claude-desktop/entra-broker) 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.
103* **Brokered Microsoft Entra sign-in.** When [brokered authentication](/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.
104104* **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.
105105* **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.
106106
from line 137
137137}
138138```
139139
140Set `parentSettingsBehavior` to `"merge"` whenever you deploy a Claude Code managed-settings file alongside Claude Desktop on 3P: without it, the presence of that file makes Claude Code ignore the policy Claude Desktop supplies (network and filesystem sandbox, allowed MCP servers), even if the file only sets proxy variables. [Claude Code in Claude Desktop on 3P](/docs/third-party/claude-desktop/code#interaction-with-claude-code%E2%80%99s-own-managed-settings) explains the merge behavior.
140Set `parentSettingsBehavior` to `"merge"` whenever you deploy a Claude Code managed-settings file alongside Claude Desktop on 3P: without it, the presence of that file makes Claude Code ignore the policy Claude Desktop supplies (network and filesystem sandbox, allowed MCP servers), even if the file only sets proxy variables. [Claude Code in Claude Desktop on 3P](/docs/third-party/claude-desktop/code.md#interaction-with-claude-code%E2%80%99s-own-managed-settings) explains the merge behavior.
141141
142142`NO_PROXY` matching in the agent follows these rules:
143143
from line 170
170170
171171## Troubleshoot
172172
173**"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** 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](/docs/third-party/claude-desktop/telemetry#required-egress-paths).
173**"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** 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](/docs/third-party/claude-desktop/telemetry.md#required-egress-paths).
174174
175**Confirm which proxy is in effect.** Open `main.log` in the app's [logs directory](/docs/third-party/claude-desktop/data-storage). 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.
175**Confirm which proxy is in effect.** Open `main.log` in the app's [logs directory](/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.
176176
177177**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`.
178178
179179**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.
180180
181**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](/docs/third-party/claude-desktop/data-storage). Serve the script over `https://`. See [PAC script for the sandboxed shell](#pac-script-for-the-sandboxed-shell).
181**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](/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).
182182
183183**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).
184184
from line 186
186186
187187## Related
188188
189* [Configuration reference](/docs/third-party/claude-desktop/configuration) for `egressProxyUrl`, `egressProxyPacUrl`, and `coworkEgressAllowedHosts`
190* [Telemetry and egress](/docs/third-party/claude-desktop/telemetry#required-egress-paths) for the hosts your proxy must allow
191* [Claude Code in Claude Desktop on 3P](/docs/third-party/claude-desktop/code) for how Claude Code managed settings combine with Claude Desktop policy
192* [Web tools](/docs/third-party/claude-desktop/web-tools) for `coworkEgressAllowedHosts`
189* [Configuration reference](/docs/third-party/claude-desktop/configuration.md) for `egressProxyUrl`, `egressProxyPacUrl`, and `coworkEgressAllowedHosts`
190* [Telemetry and egress](/docs/third-party/claude-desktop/telemetry.md#required-egress-paths) for the hosts your proxy must allow
191* [Claude Code in Claude Desktop on 3P](/docs/third-party/claude-desktop/code.md) for how Claude Code managed settings combine with Claude Desktop policy
192* [Web tools](/docs/third-party/claude-desktop/web-tools.md) for `coworkEgressAllowedHosts`
193193
No line in this hunk matches that.