Network proxy

• The app: the Claude Desktop window itself, including sign-in, the connection test, Web Fetch in Chat and Cowork sessions, managed MCP servers the app connects to, and plugin marketplace sync.
• 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.
• Cowork’s sandboxed shell: the isolated environment where commands the agent runs in a Cowork session (curl, pip, npm, and so on) execute.

​

Default behavior

• 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.
• 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.
• If your proxy intercepts TLS, see TLS-intercepting proxies below.

​

Pin a proxy from managed configuration

{
  "egressProxyUrl": "http://proxy.example.com:8080"
}

• If the pinned proxy is unreachable, requests fail. The app does not fall back to a direct connection.
• 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. Combine the key with network-layer egress rules if a silent fallback to direct is not acceptable (see the warning below).
• 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.

​

What is and is not routed

​

Traffic that bypasses the app proxy

• 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 and your software-distribution tool. On Linux, updates come from your package manager, which has its own proxy configuration.
• 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 still applies inside the sandbox and sits in front of any proxy: a host must be on the allowlist to be reachable at all, and an allowed host is then reached through the proxy.
• SSH remote Code sessions. When a user runs a Code session on another machine through sshHostAllowlist, 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.
• 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.
• Brokered Microsoft Entra sign-in. When brokered authentication 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.
• 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.
• 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.

​

The agent uses one proxy

1. Let the proxy these devices use carry both kinds of traffic. Nothing else needs configuring.
2. Otherwise, list the domains that must connect directly in NO_PROXY through Claude Code managed settings (see the next section), using leading-dot suffixes such as .example.corp, and accept that everything not listed goes to the proxy.

​

Interaction with Claude Code managed settings

{
  "env": {
    "HTTPS_PROXY": "http://proxy.example.com:8080",
    "NO_PROXY": "localhost,127.0.0.1,::1,.example.corp"
  },
  "parentSettingsBehavior": "merge"
}

• A bare hostname matches that host exactly. To cover a domain and its subdomains, use a leading dot: .example.corp matches example.corp and api.example.corp.
• IP addresses match literally. CIDR ranges such as 10.0.0.0/8 are not supported.
• host:port entries match that host on that port only.
• * disables the proxy entirely, and only when it is the whole value; it is not a wildcard inside a list.

​

TLS-intercepting proxies

sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain /path/to/corp-ca.pem

security find-certificate -a -p /Library/Keychains/System.keychain > ~/corp-ca.pem
launchctl setenv NODE_EXTRA_CA_CERTS "$HOME/corp-ca.pem"

​

Troubleshoot

​

Related

• Configuration reference for egressProxyUrl, egressProxyPacUrl, and coworkEgressAllowedHosts
• Telemetry and egress for the hosts your proxy must allow
• Claude Code in Claude Desktop on 3P for how Claude Code managed settings combine with Claude Desktop policy
• Web tools for coworkEgressAllowedHosts