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 16 Oct 2026 14:37 UTC.
Upstream edited
Recorded here
Lines+7added
Lines−4removed
From line
16
where the diff opens
First seen
2 Sep 2026
this site's first read of the page
Recorded edits8to this page, all time
The whole hunk
from line 16, old and new numbered
/
from line 16
1616
1717With no proxy-related configuration, the app follows the operating system's proxy settings, including a PAC (proxy auto-configuration) script or automatic proxy detection if the OS is set up that way. PAC rules are evaluated per request, so different hosts can go to different proxies or connect directly, exactly as the script says.
1818
19The agent does not read the OS settings itself. When a session starts, the app asks the OS which proxy applies to your inference endpoint (your gateway URL, or the provider endpoint for Google Cloud's Agent Platform, Amazon Bedrock, and Microsoft Foundry) and hands that one proxy to the agent as `HTTPS_PROXY` and `HTTP_PROXY`, with `NO_PROXY` set to `localhost,127.0.0.1,::1,.local`. The agent then uses that proxy for all of its own traffic. If the OS answer for the inference endpoint is a direct connection, the agent gets no proxy variables and connects directly.
19The agent does not read the OS settings itself. When a session starts, the app asks the OS which proxy applies to your inference endpoint (your gateway URL, or the provider endpoint for Google Cloud's Agent Platform, Amazon Bedrock, and Microsoft Foundry) and hands that one proxy to the agent as `HTTPS_PROXY` and `HTTP_PROXY`, with `NO_PROXY` set to `localhost,127.0.0.1,::1,.local`. The agent then uses that proxy for all of its own traffic. If the OS answer for the inference endpoint is a direct connection, the agent gets no proxy variables and connects directly, unless the OS has named an `http://` or `https://` proxy for that endpoint since Claude Desktop started (see [Troubleshoot](#troubleshoot)).
2020
2121On macOS and Windows, Cowork's sandboxed shell also follows the OS proxy settings, including a PAC script, which the sandbox evaluates per request itself. On Linux, no proxy settings reach the sandboxed shell and its commands connect directly.
2222
2323A few limits apply to the agent regardless of how the proxy is chosen:
2424
25* Only `http://` and `https://` proxies are handed to the agent. If the OS or PAC answer is a SOCKS proxy, the app skips it and the agent connects directly.
25* Only `http://` and `https://` proxies are handed to the agent. If the OS or PAC answer is a SOCKS proxy, the app skips it, and the agent connects directly or through the last `http://` or `https://` proxy named for the inference endpoint since Claude Desktop started.
2626* There is no interactive proxy sign-in. If your proxy requires a username and password, neither the app nor the agent can prompt for them and requests fail. Run a local forwarding proxy that authenticates upstream on the device (for example, Cntlm or Px) and point the OS or the pinned key at it.
2727* If your proxy intercepts TLS, see [TLS-intercepting proxies](#tls-intercepting-proxies) below.
2828
from line 33
3333* **PAC script address on macOS.** macOS refuses the download of the sandboxed shell's copy from a plain `http://` address such as `http://pac.example.com/proxy.pac`. The app and the agent are then still proxied as the script directs, and the sandboxed shell gets no copy. macOS accepts plain `http://` only when 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`. Serve the script over `https://`.
3434* **Failed downloads.** The download can fail when the sandbox starts, for example right after a VPN change. For the address in the OS proxy settings, the app retries for about a minute and then again when new commands start in the sandbox. When a retry succeeds, commands that start afterward use the script without an app restart. A failed download leaves in place a script the shell already has from the same address. A response that isn't a PAC script, such as a sign-in page, counts as a failed download.
3535* **Host names with no dot.** Inside the sandbox, a host name with no dot in it is looked up under the device's DNS search domains when the name alone doesn't resolve. One example is a proxy that the PAC script names as `proxy-server`. A name with a dot in it is looked up as written.
36* **Rules that test the device's address.** Inside the sandbox, `myIpAddress()` returns the sandbox's internal address, not the device's, so a script that chooses a proxy by client subnet can give the shell a different answer than it gives the device.
3637
3738## Pin a proxy from managed configuration
3839
from line 68
6768
6869* If the pinned proxy is unreachable, requests fail. The app does not fall back to a direct connection.
6970* If a pinned PAC script cannot be downloaded, the app connects directly and the agent gets no proxy. Cowork's sandboxed shell gets its own copy of the script through a separate download when the sandbox starts. If that download fails, the shell connects directly too, and the download isn't tried again until the sandbox next starts. Combine the key with network-layer egress rules if a silent fallback to direct is not acceptable (see the warning below).
70* Inside Cowork's sandboxed shell, a pinned PAC script's `myIpAddress()` returns the sandbox's internal address rather than the device's, so a script that chooses a proxy by client subnet gives the shell its off-network answer.
71* Inside Cowork's sandboxed shell, a pinned PAC script's `myIpAddress()` returns the sandbox's internal address rather than the device's, so a script that chooses a proxy by client subnet can give the shell a different answer than it gives the device.
7172
7273## What is and is not routed
7374
from line 172
171172
172173**"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).
173174
174**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 …`). When a session starts, the log records the proxy handed to the agent, for example `Resolved system proxy for Code sessions: http://proxy.example.com:8080`, 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). 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.
175176
176177**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`.
178
179**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.
177180
178181**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).
179182
No line in this hunk matches that.