One read of Claude Documentationclaude-docs-20261022T180711Z
268 pages moved out of 279 read.
Pages moved
268
significant first
Pages read
279
in this capture
Captured
18:07 UTC
Corpus hash
510ab6f6a194
corpus-hash
What this read moved
226-250 of 268, page 10 of 11This capture is too large to show at once. Changes 226-250 of 268 are below, significant first; the rest are on the following screens.
third-party/claude-desktop/legal Changed · +5 / -5 lines
from line 14
1414
1515### Enterprise Admin Console for Desktop 3P
1616
17If your organization manages Claude Desktop on 3P from the [Enterprise Admin Console for Desktop 3P](/docs/third-party/claude-desktop/admin-console) (**Organization settings** on claude.ai), rather than authoring the configuration in MDM or hosting your own bootstrap server, Anthropic hosts that console. Your use of the Enterprise Admin Console for Desktop 3P is subject to Anthropic's [Commercial Terms of Service](https://www.anthropic.com/legal/commercial-terms). When you access Claude through a third-party provider (Google Cloud's Agent Platform, Amazon Bedrock, Microsoft Foundry, or a compatible gateway), the Commercial Terms apply only to your use of the Enterprise Admin Console, unless we've mutually agreed otherwise.
17If your organization manages Claude Desktop on 3P from the [Enterprise Admin Console for Desktop 3P](/docs/third-party/claude-desktop/admin-console.md) (**Organization settings** on claude.ai), rather than authoring the configuration in MDM or hosting your own bootstrap server, Anthropic hosts that console. Your use of the Enterprise Admin Console for Desktop 3P is subject to Anthropic's [Commercial Terms of Service](https://www.anthropic.com/legal/commercial-terms). When you access Claude through a third-party provider (Google Cloud's Agent Platform, Amazon Bedrock, Microsoft Foundry, or a compatible gateway), the Commercial Terms apply only to your use of the Enterprise Admin Console, unless we've mutually agreed otherwise.
1818
1919## Compliance
2020
from line 26
2626
2727Deployments hosted on Azure run inference in an Anthropic-operated service on Azure infrastructure, not in your Azure tenant, and prompts and completions remain within Azure. The only data the service sends out of Azure to Anthropic is usage metadata and any content that Anthropic's safety systems flag. Deployments hosted on Anthropic send prompts and completions to Anthropic's own infrastructure for inference. See [hosting options for Claude in Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options) for details.
2828
29See the [Overview](/docs/third-party/claude-desktop/overview) for the architecture and [Data handling by provider](/docs/third-party/claude-desktop/overview#data-handling-by-provider) for each provider's data path.
29See the [Overview](/docs/third-party/claude-desktop/overview.md) for the architecture and [Data handling by provider](/docs/third-party/claude-desktop/overview.md#data-handling-by-provider) for each provider's data path.
3030
3131For Anthropic's certifications and compliance reports, see the [Anthropic Trust Center](https://trust.anthropic.com).
3232
33For HIPAA, see [HIPAA](/docs/third-party/claude-desktop/overview#hipaa) on the Overview page. For Google Cloud's Agent Platform and Amazon Bedrock, Anthropic does not interact with PHI; the BAA relationship is between you and your cloud service provider, and any remote MCP servers you connect need your own HIPAA review. Anthropic's API accessed through Microsoft Foundry (Hosted on Anthropic or Hosted on Azure) is an Eligible Service, as long as you have the HIPAA configuration enabled. Either option requires a BAA with Anthropic. See our [Trust Center](https://trust.anthropic.com/resources?s=l1wrssd9hsbi4gak0tp5a6\&name=%5Banthropic%5D-hipaa-ready-offering-implementation-guide) for more detail on implementation.
33For HIPAA, see [HIPAA](/docs/third-party/claude-desktop/overview.md#hipaa) on the Overview page. For Google Cloud's Agent Platform and Amazon Bedrock, Anthropic does not interact with PHI; the BAA relationship is between you and your cloud service provider, and any remote MCP servers you connect need your own HIPAA review. Anthropic's API accessed through Microsoft Foundry (Hosted on Anthropic or Hosted on Azure) is an Eligible Service, as long as you have the HIPAA configuration enabled. Either option requires a BAA with Anthropic. See our [Trust Center](https://trust.anthropic.com/resources?s=l1wrssd9hsbi4gak0tp5a6\&name=%5Banthropic%5D-hipaa-ready-offering-implementation-guide) for more detail on implementation.
3434
3535## Usage policy
3636
from line 38
3838
3939## Privacy and telemetry
4040
41The Claude Desktop application sends operational telemetry (crash reports and product analytics) to Anthropic by default. This telemetry contains no prompt or response content. You can fully disable it through managed configuration, or from the console for an organization managed from the [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console). See [Telemetry and egress](/docs/third-party/claude-desktop/telemetry) for what each category contains and how to disable it.
41The Claude Desktop application sends operational telemetry (crash reports and product analytics) to Anthropic by default. This telemetry contains no prompt or response content. You can fully disable it through managed configuration, or from the console for an organization managed from the [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console.md). See [Telemetry and egress](/docs/third-party/claude-desktop/telemetry.md) for what each category contains and how to disable it.
4242
43An organization managed from the Enterprise Admin Console can also turn on usage analytics. Users' apps then report session, token, and estimated-cost counts to Anthropic, and the organization's administrators can see each user's sessions, tokens, and estimated cost. The reports contain no prompt, response, or file content. [Usage analytics](/docs/third-party/claude-desktop/admin-console#usage-analytics) lists who can see the counts and exactly what each report contains.
43An organization managed from the Enterprise Admin Console can also turn on usage analytics. Users' apps then report session, token, and estimated-cost counts to Anthropic, and the organization's administrators can see each user's sessions, tokens, and estimated cost. The reports contain no prompt, response, or file content. [Usage analytics](/docs/third-party/claude-desktop/admin-console.md#usage-analytics) lists who can see the counts and exactly what each report contains.
4444
4545Anthropic's [Privacy Policy](https://www.anthropic.com/legal/privacy) describes how Anthropic handles data it receives.
4646
third-party/claude-desktop/local-access Changed · +6 / -6 lines
from line 2
22
33> How Claude Desktop on 3P reads and writes files on the user's machine, and how to constrain it
44
5Like [Cowork](/docs/cowork/overview) in standard Claude Desktop, Claude Desktop on third-party (3P) works directly with files on the user's computer. Users attach one or more **workspace folders** to a session; the agent can then read, create, and modify files anywhere inside those folders, and run code against them inside the sandbox VM.
5Like [Cowork](/docs/cowork/overview.md) in standard Claude Desktop, Claude Desktop on third-party (3P) works directly with files on the user's computer. Users attach one or more **workspace folders** to a session; the agent can then read, create, and modify files anywhere inside those folders, and run code against them inside the sandbox VM.
66
77In Claude Desktop on 3P, administrators can constrain which folders users are allowed to attach.
88
99## Workspace folder allowlist
1010
11Set [`allowedWorkspaceFolders`](/docs/third-party/claude-desktop/configuration#allowedworkspacefolders) in the managed configuration to restrict which paths users may attach as workspace folders. The [Configuration reference](/docs/third-party/claude-desktop/configuration) covers where the managed configuration lives on each platform and how to deploy it.
11Set [`allowedWorkspaceFolders`](/docs/third-party/claude-desktop/configuration#allowedworkspacefolders) in the managed configuration to restrict which paths users may attach as workspace folders. The [Configuration reference](/docs/third-party/claude-desktop/configuration.md) covers where the managed configuration lives on each platform and how to deploy it.
1212
1313| Value | Behavior |
1414| - | - |
from line 16
1616| `["~/Documents/Claude", "/Volumes/Shared/Projects"]` | Users may attach only folders **inside** one of the listed roots. |
1717| `[]` | No folders may be attached. The agent can still create files in its own sandbox scratch space, but cannot read or write the user's filesystem. |
1818
19A leading `~` expands to the user's home directory, so a single profile can express per-user roots like `~/Documents/Claude` across the fleet. A path may also reference one of a fixed set of environment-variable tokens, such as `%OneDrive%` or `%USERNAME%`, listed in the [configuration reference](/docs/third-party/claude-desktop/configuration#allowedworkspacefolders). An entry that references any other `%VAR%`, or one that is unset on the device, is ignored.
19A leading `~` expands to the user's home directory, so a single profile can express per-user roots like `~/Documents/Claude` across the fleet. A path may also reference one of a fixed set of environment-variable tokens, such as `%OneDrive%` or `%USERNAME%`, listed in the [configuration reference](/docs/third-party/claude-desktop/configuration.md#allowedworkspacefolders). An entry that references any other `%VAR%`, or one that is unset on the device, is ignored.
2020
2121Each entry is either a plain path string or an object with these fields:
2222
from line 23
2323| Field | Description |
2424| - | - |
2525| `path` | The folder path (required). Subfolders are included. |
26| `mode` | `rw` (the default) or `ro`. The agent can view and search a read-only folder but cannot modify it in Cowork. In Code sessions other than SSH remote sessions, read-only applies to Claude's file tools only, and shell commands don't enforce it. For SSH remote sessions, see [Read-only folders on the remote host](/docs/third-party/claude-desktop/ssh-remote-sessions#read-only-folders-on-the-remote-host). |
26| `mode` | `rw` (the default) or `ro`. The agent can view and search a read-only folder but cannot modify it in Cowork. In Code sessions other than SSH remote sessions, read-only applies to Claude's file tools only, and shell commands don't enforce it. For SSH remote sessions, see [Read-only folders on the remote host](/docs/third-party/claude-desktop/ssh-remote-sessions.md#read-only-folders-on-the-remote-host). |
2727| `isDefaultSelected` | When `true`, the folder appears already selected on the new-task page and skips the trust prompt. Users can remove it. |
2828
2929For example, `[{"path": "~/Documents/Claude"}, {"path": "/Volumes/Shared/Reference", "mode": "ro"}]` lets users work in their own folder and consult the shared reference folder without changing it.
from line 32
3232
3333> [!NOTE]
3434>
35> The allowlist controls what users can **attach**. Within an attached read/write folder, the agent can read and write every file the user's OS account can reach. Data outside the allowed roots cannot be attached in Cowork and is out of reach of Claude's file tools in Code sessions. A Code session's shell commands are confined only by the sandbox described under [Code](/docs/third-party/claude-desktop/code#applied-as-managed-policy): where it applies they can change files only inside the roots and temporary locations but can still read outside them unless you also set [`blockReadsOutsideWorkingDirectories`](/docs/third-party/claude-desktop/configuration#blockreadsoutsideworkingdirectories), and where it does not apply (Windows devices, hosts without the sandbox dependencies) the allowlist does not confine them and that key can only turn such reads into approval prompts. To let the agent read data in Cowork without changing it, list the folder with `mode` set to `ro`.
35> The allowlist controls what users can **attach**. Within an attached read/write folder, the agent can read and write every file the user's OS account can reach. Data outside the allowed roots cannot be attached in Cowork and is out of reach of Claude's file tools in Code sessions. A Code session's shell commands are confined only by the sandbox described under [Code](/docs/third-party/claude-desktop/code.md#applied-as-managed-policy): where it applies they can change files only inside the roots and temporary locations but can still read outside them unless you also set [`blockReadsOutsideWorkingDirectories`](/docs/third-party/claude-desktop/configuration#blockreadsoutsideworkingdirectories), and where it does not apply (Windows devices, hosts without the sandbox dependencies) the allowlist does not confine them and that key can only turn such reads into approval prompts. To let the agent read data in Cowork without changing it, list the folder with `mode` set to `ro`.
3636
3737## Network drives on Windows
3838
from line 55
5555
5656## WSL
5757
58You do not need Windows Subsystem for Linux (WSL) to run Claude Desktop or Cowork. On Windows, Cowork's sandbox runs on the operating system's built-in virtualization, which the [readiness check](/docs/third-party/claude-desktop/installation#check-device-readiness) verifies. Install the macOS or Windows package (see [System requirements](/docs/third-party/claude-desktop/installation#system-requirements)); there is no installation path inside WSL. Run the Windows app and work with WSL files from there.
58You do not need Windows Subsystem for Linux (WSL) to run Claude Desktop or Cowork. On Windows, Cowork's sandbox runs on the operating system's built-in virtualization, which the [readiness check](/docs/third-party/claude-desktop/installation.md#check-device-readiness) verifies. Install the macOS or Windows package (see [System requirements](/docs/third-party/claude-desktop/installation.md#system-requirements)); there is no installation path inside WSL. Run the Windows app and work with WSL files from there.
5959
6060Windows exposes a WSL distribution's filesystem as a UNC path (`\\wsl$\<distro>` or `\\wsl.localhost\<distro>`). Like any other raw UNC path, these cannot be attached as workspace folders directly. To attach files that live inside WSL as a workspace folder, map the share to a drive letter and attach the mapped drive, or copy the files to a local Windows folder. [Network drives on Windows](#network-drives-on-windows) describes what the agent can do on a mapped drive.
6161
third-party/claude-desktop/mantle Changed · +8 / -8 lines
from line 2
22
33> Configure Claude Desktop on 3P to use Claude models through Amazon Bedrock Mantle's Anthropic-native API surface
44
5Amazon Bedrock Mantle is Amazon Bedrock's Anthropic-native API surface. Unlike the standard [Amazon Bedrock provider](/docs/third-party/claude-desktop/bedrock), Mantle speaks the Anthropic Messages API directly and authenticates with a bearer token rather than the AWS SigV4 credential chain, so no AWS CLI, named profile, or IAM Identity Center setup is needed on the device. In practice, Mantle is the Amazon Bedrock provider with a different runtime endpoint and a single bearer-token credential path.
5Amazon Bedrock Mantle is Amazon Bedrock's Anthropic-native API surface. Unlike the standard [Amazon Bedrock provider](/docs/third-party/claude-desktop/bedrock.md), Mantle speaks the Anthropic Messages API directly and authenticates with a bearer token rather than the AWS SigV4 credential chain, so no AWS CLI, named profile, or IAM Identity Center setup is needed on the device. In practice, Mantle is the Amazon Bedrock provider with a different runtime endpoint and a single bearer-token credential path.
66
77## Choose an authentication approach
88
9Mantle supports a bearer token only. There is no in-app AWS sign-in or named-profile support for this provider; if you need per-user IAM Identity Center authentication, use the standard [Amazon Bedrock provider](/docs/third-party/claude-desktop/bedrock) instead.
9Mantle supports a bearer token only. There is no in-app AWS sign-in or named-profile support for this provider; if you need per-user IAM Identity Center authentication, use the standard [Amazon Bedrock provider](/docs/third-party/claude-desktop/bedrock.md) instead.
1010
1111| Scenario | Use | Notes |
1212| - | - | - |
1313| Any Mantle deployment | [Bearer token](#bearer-token) (`inferenceBedrockBearerToken`) | A long-lived token distributed in the managed profile. |
14| Token must not be stored statically | [Credential helper](/docs/third-party/claude-desktop/configuration#inferencecredentialhelper) (`inferenceCredentialHelper`) | An executable that prints the bearer token to stdout at runtime. |
14| Token must not be stored statically | [Credential helper](/docs/third-party/claude-desktop/configuration.md#inferencecredentialhelper) (`inferenceCredentialHelper`) | An executable that prints the bearer token to stdout at runtime. |
1515
1616## Set up AWS
1717
18Enable Claude models in Amazon Bedrock for the region you will set as `inferenceBedrockRegion`, and obtain a Mantle bearer token for that account. See [Set up AWS](/docs/third-party/claude-desktop/bedrock#set-up-aws) on the Amazon Bedrock page for the model-access step; the IAM Identity Center steps there are not needed for Mantle.
18Enable Claude models in Amazon Bedrock for the region you will set as `inferenceBedrockRegion`, and obtain a Mantle bearer token for that account. See [Set up AWS](/docs/third-party/claude-desktop/bedrock.md#set-up-aws) on the Amazon Bedrock page for the model-access step; the IAM Identity Center steps there are not needed for Mantle.
1919
2020## Prepare devices
2121
from line 27
2727
2828## Configure the app
2929
30Open the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration#open-the-configuration-window) (**Developer → Configure Third-Party Inference…**). In the **Connection** section, set **Inference provider** to **Bedrock Mantle**, then fill in the credentials card:
30Open the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration.md#open-the-configuration-window) (**Developer → Configure Third-Party Inference…**). In the **Connection** section, set **Inference provider** to **Bedrock Mantle**, then fill in the credentials card:
3131
3232| Field | Value |
3333| - | - |
from line 39
3939
4040Under **Models**, add at least one **Model list** entry. Mantle has no model-list endpoint, so model discovery is not available and `inferenceModels` is required.
4141
42Then click **Export** to produce a `.mobileconfig` (macOS) or `.reg` (Windows) file for your MDM. See [Deploy with MDM](/docs/third-party/claude-desktop/mdm) for the export and deployment workflow.
42Then click **Export** to produce a `.mobileconfig` (macOS) or `.reg` (Windows) file for your MDM. See [Deploy with MDM](/docs/third-party/claude-desktop/mdm.md) for the export and deployment workflow.
4343
4444### Configuration keys
4545
from line 63
6363>
6464> Tier availability varies by model and region. Reserved capacity uses a provisioned-throughput ARN as the model ID instead of this setting. Older bundled Claude Code CLI versions ignore this key.
6565
66You must also set `inferenceModels`. As with the standard Amazon Bedrock provider, server-side Web Search is not supported. See the [Configuration reference](/docs/third-party/claude-desktop/configuration#inferencemodels).
66You must also set `inferenceModels`. As with the standard Amazon Bedrock provider, server-side Web Search is not supported. See the [Configuration reference](/docs/third-party/claude-desktop/configuration.md#inferencemodels).
6767
6868## What users experience
6969
from line 71
7171
7272## Troubleshoot
7373
74To confirm which keys the app read and whether the provider settings validated, use **Help → Troubleshooting → Generate Diagnostic Report**, export the report, and check `managed-config.txt` and `provider-status.txt`; see [Verifying the deployment](/docs/third-party/claude-desktop/installation#verifying-the-deployment) for that workflow and the common causes when the app does not enter 3P mode. Application log locations are listed in [User identity and local data](/docs/third-party/claude-desktop/data-storage#where-data-lives).
74To confirm which keys the app read and whether the provider settings validated, use **Help → Troubleshooting → Generate Diagnostic Report**, export the report, and check `managed-config.txt` and `provider-status.txt`; see [Verifying the deployment](/docs/third-party/claude-desktop/installation.md#verifying-the-deployment) for that workflow and the common causes when the app does not enter 3P mode. Application log locations are listed in [User identity and local data](/docs/third-party/claude-desktop/data-storage.md#where-data-lives).
7575
third-party/claude-desktop/mcp-sign-in Changed · +6 / -6 lines
from line 2
22
33> Decide whether a managed MCP server needs an OAuth client that you register and whether it also needs that client's secret, fill in the OAuth fields, and read the sign-in error messages.
44
5For a remote [managed MCP server](/docs/third-party/claude-desktop/extensions#managed-mcp-servers-admin) that uses OAuth, Claude Desktop signs each user in through the browser: the user clicks **Connect**, signs in to the server's identity provider (the OAuth service its vendor runs, for example Google or Box), and Claude Desktop stores the resulting token encrypted on the device. What you configure depends on that identity provider. Some register Claude Desktop as a client automatically, some require an OAuth client that you register, and some also require that client's secret.
5For a remote [managed MCP server](/docs/third-party/claude-desktop/extensions.md#managed-mcp-servers-admin) that uses OAuth, Claude Desktop signs each user in through the browser: the user clicks **Connect**, signs in to the server's identity provider (the OAuth service its vendor runs, for example Google or Box), and Claude Desktop stores the resulting token encrypted on the device. What you configure depends on that identity provider. Some register Claude Desktop as a client automatically, some require an OAuth client that you register, and some also require that client's secret.
66
7This page is for administrators who add servers on the **Connectors** page of the [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console). The [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration) has the same fields, and in an MDM or bootstrap configuration they are the `oauth` keys of a [`managedMcpServers`](/docs/third-party/claude-desktop/configuration#managedmcpservers) entry. For the redirect URI, discovery, and token handling in detail, see [OAuth sign-in](/docs/third-party/claude-desktop/extensions#oauth-sign-in).
7This page is for administrators who add servers on the **Connectors** page of the [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console.md). The [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration.md) has the same fields, and in an MDM or bootstrap configuration they are the `oauth` keys of a [`managedMcpServers`](/docs/third-party/claude-desktop/configuration#managedmcpservers) entry. For the redirect URI, discovery, and token handling in detail, see [OAuth sign-in](/docs/third-party/claude-desktop/extensions.md#oauth-sign-in).
88
99## Choose the OAuth setting
1010
from line 26
2626
2727Add a client secret only when the identity provider refuses sign-in without one. The console stores a value in **Client secret** only for a Google OAuth client of the **Desktop app** type: the value begins with `GOCSPX-`, **Authorization server** is exactly `["https://accounts.google.com"]`, and **Tenant ID** is empty. Google doesn't treat a Desktop-app client secret as confidential, so the console accepts it. A Google **Web application** client's secret has the same `GOCSPX-` prefix but is confidential, so always create a **Desktop app** client.
2828
29For every other identity provider the secret stays on the device. Install a script that prints the secret, at the same absolute path on every device, and enter that path in the **Client secret helper script** field. The script must print exactly one JSON object, `{"clientSecret": "…"}`, on stdout and exit with code `0` within 30 seconds. Claude Desktop runs it each time the server connects or refreshes its sign-in in the background. The console stores only the path, so distribute the script through your device management, as described under [When a helper script is the right choice](/docs/third-party/claude-desktop/admin-console#when-a-helper-script-is-the-right-choice), and see [Connect to Box](/docs/third-party/claude-desktop/connectors-box) for a minimal script. A configuration delivered by MDM or a bootstrap server can instead carry any identity provider's secret inline in `oauth.clientSecret`.
29For every other identity provider the secret stays on the device. Install a script that prints the secret, at the same absolute path on every device, and enter that path in the **Client secret helper script** field. The script must print exactly one JSON object, `{"clientSecret": "…"}`, on stdout and exit with code `0` within 30 seconds. Claude Desktop runs it each time the server connects or refreshes its sign-in in the background. The console stores only the path, so distribute the script through your device management, as described under [When a helper script is the right choice](/docs/third-party/claude-desktop/admin-console.md#when-a-helper-script-is-the-right-choice), and see [Connect to Box](/docs/third-party/claude-desktop/connectors-box.md) for a minimal script. A configuration delivered by MDM or a bootstrap server can instead carry any identity provider's secret inline in `oauth.clientSecret`.
3030
3131**Authorization server** is required whenever **Client secret** or **Client secret helper script** is set. Claude Desktop sends the secret only to the token endpoint of the issuer you name there, so a misconfigured or compromised MCP server can't redirect the token exchange, and the secret, to another server.
3232
from line 43
4343| **Authorization URL** and **Token URL** | The identity provider publishes no discovery document | Both HTTPS endpoints, always as a pair. Hidden when **Tenant ID** or **Authorization server** is set |
4444| **Tenant ID** | The client is a single-tenant Microsoft Entra app | Your Directory (tenant) ID. Requires **Scope** |
4545| **Scope** | Required with **Tenant ID**. Optional otherwise | Space-separated scopes for the authorize request. Leave empty to request the scopes the server advertises |
46| **Sign-in flow** | Shown after you enter **Tenant ID**. Set it when your devices have the [OS identity broker](/docs/third-party/claude-desktop/entra-broker) | **OS identity broker (WAM / Company Portal)**. The default is **System browser** |
46| **Sign-in flow** | Shown after you enter **Tenant ID**. Set it when your devices have the [OS identity broker](/docs/third-party/claude-desktop/entra-broker.md) | **OS identity broker (WAM / Company Portal)**. The default is **System browser** |
4747| **Callback host** and **Callback port** | The redirect URI you registered uses `localhost` or a port other than `53280` | The host and port from that registration. Microsoft Entra ID accepts any loopback port, so leave both empty for Entra |
4848| **Additional redirect referrer hosts** | The identity provider completes sign-in from a host other than the one in its authorization URL, and `main.log` names a rejected referrer host | That hostname. Separate several with spaces |
4949
from line 59
5959
6060## Troubleshoot sign-in
6161
62These messages appear in Claude Desktop, or in `main.log` in the [logs directory](/docs/third-party/claude-desktop/data-storage#where-data-lives) on the user's device.
62These messages appear in Claude Desktop, or in `main.log` in the [logs directory](/docs/third-party/claude-desktop/data-storage.md#where-data-lives) on the user's device.
6363
6464| What the user sees or `main.log` records | Cause | Fix |
6565| - | - | - |
from line 69
6969
7070## Related connector guides
7171
72[Connect to Google Cloud](/docs/third-party/claude-desktop/connectors-google-cloud) and [Connect to Box](/docs/third-party/claude-desktop/connectors-box) walk through two servers that need a client you register and its secret. [Connect to GitHub](/docs/third-party/claude-desktop/connectors-github) and [Connect to Microsoft 365](/docs/third-party/claude-desktop/connectors-m365) cover those connectors end to end, including the [built-in servers](/docs/third-party/claude-desktop/built-in-connectors) that run inside the app. [Connect to Salesforce](/docs/third-party/claude-desktop/connectors-salesforce) covers Salesforce's plugin marketplace and its hosted MCP server. Add other partners' plugin marketplaces on the **Plugins** page, as described under [Plugin marketplaces](/docs/third-party/claude-desktop/admin-console#plugin-marketplaces).
72[Connect to Google Cloud](/docs/third-party/claude-desktop/connectors-google-cloud.md) and [Connect to Box](/docs/third-party/claude-desktop/connectors-box.md) walk through two servers that need a client you register and its secret. [Connect to GitHub](/docs/third-party/claude-desktop/connectors-github.md) and [Connect to Microsoft 365](/docs/third-party/claude-desktop/connectors-m365.md) cover those connectors end to end, including the [built-in servers](/docs/third-party/claude-desktop/built-in-connectors.md) that run inside the app. [Connect to Salesforce](/docs/third-party/claude-desktop/connectors-salesforce.md) covers Salesforce's plugin marketplace and its hosted MCP server. Add other partners' plugin marketplaces on the **Plugins** page, as described under [Plugin marketplaces](/docs/third-party/claude-desktop/admin-console.md#plugin-marketplaces).
7373
third-party/claude-desktop/mdm Changed · +13 / -13 lines
from line 4
44
55On the MDM delivery model, the profile you deploy carries your organization's full configuration, and every device the profile targets gets the same settings. This page covers the workflow end to end: build the configuration in the app, export it, open the firewall, and deploy the profile and installer to your fleet.
66
7Before you start, install Claude Desktop on an admin workstation; see [Installation and setup](/docs/third-party/claude-desktop/installation). If you deliver configuration from a [bootstrap server](/docs/third-party/claude-desktop/bootstrap) instead, follow that page; your profile then carries only the bootstrap keys, but it is exported and deployed the same way described here.
7Before you start, install Claude Desktop on an admin workstation; see [Installation and setup](/docs/third-party/claude-desktop/installation.md). If you deliver configuration from a [bootstrap server](/docs/third-party/claude-desktop/bootstrap.md) instead, follow that page; your profile then carries only the bootstrap keys, but it is exported and deployed the same way described here.
88
99## Recommended rollout
1010
from line 12
1212
1313**1. Build a configuration in the app**
1414
15An admin builds and tests a working configuration in the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration) on their own device.
15An admin builds and tests a working configuration in the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration.md) on their own device.
1616
1717**2. Export the profile**
1818
from line 30
3030
3131Launch Claude Desktop. **Do not sign in or create an Anthropic account**; stay on the login screen. From the macOS menu bar (or on Windows, the application menu ☰ in the top-left of the login screen), go to **Help → Troubleshooting → Enable Developer Mode**, then **Developer → Configure Third-Party Inference…** to open the configuration window.
3232
33The window is organized into sections in the left sidebar. Work through them in order; each maps to a group of [configuration keys](/docs/third-party/claude-desktop/configuration), and the window validates values as you enter them.
33The window is organized into sections in the left sidebar. Work through them in order; each maps to a group of [configuration keys](/docs/third-party/claude-desktop/configuration.md), and the window validates values as you enter them.
3434
3535| Section | What you set |
3636| - | - |
from line 40
4040| **Telemetry & updates** | OpenTelemetry collector endpoint Whether auto-updates are blocked, and the enforcement window if not The three Anthropic-bound telemetry toggles (essential, nonessential, nonessential services) |
4141| **Limits** | Per-device token cap and its window length Retention periods after which idle chats, Cowork tasks, and Code sessions are deleted, and the hold that suspends deletion |
4242| **Appearance** | Persistent banner shown across the app window Deployment display name and subtitle Whether the signed-in user's identity is shown and exported (end-user attribution) Whether feature announcements are shown |
43| **Plugins** | [Plugin marketplaces](/docs/third-party/claude-desktop/extensions#plugin-marketplaces-admin), added by GitHub repo, git URL, or hosted `marketplace.json` URL Shows the org-plugins folder path for your platform; plugin bundles are mounted to that folder via your MDM, not through this window |
43| **Plugins** | [Plugin marketplaces](/docs/third-party/claude-desktop/extensions.md#plugin-marketplaces-admin), added by GitHub repo, git URL, or hosted `marketplace.json` URL Shows the org-plugins folder path for your platform; plugin bundles are mounted to that folder via your MDM, not through this window |
4444| **Egress** | A read-only firewall allowlist derived from everything you've entered above, grouped by feature **Copy hostnames**, **Download .txt**, and **Test connectivity** actions |
45| **Source** | The bootstrap keys, if you are using the [bootstrap server](/docs/third-party/claude-desktop/bootstrap) delivery model instead of a full MDM profile Bootstrap-delivered configuration takes priority over MDM-delivered values: it replaces them wholesale rather than merging key by key |
45| **Source** | The bootstrap keys, if you are using the [bootstrap server](/docs/third-party/claude-desktop/bootstrap.md) delivery model instead of a full MDM profile Bootstrap-delivered configuration takes priority over MDM-delivered values: it replaces them wholesale rather than merging key by key |
4646
47To turn on [Unified Claude](/docs/third-party/claude-desktop/unified-claude#enabling-unified-claude), set `desktopHome` to `standard` in your MDM profile.
47To turn on [Unified Claude](/docs/third-party/claude-desktop/unified-claude.md#enabling-unified-claude), set `desktopHome` to `standard` in your MDM profile.
4848
4949> [!NOTE]
5050>
from line 83
8383
8484> [!NOTE]
8585>
86> On Windows, check which registry hive your assignment rules write to. If your assignment rules deliver a profile in user context, it lands in user policy (`HKCU`), and the app ignores user policy entirely when machine policy is present; see [Deploy the configuration](#4-deploy-the-configuration). To vary configuration per user group on Windows, deliver every profile through user policy and keep `HKLM\SOFTWARE\Policies\Claude` empty, or serve per-user configuration from a [bootstrap server](/docs/third-party/claude-desktop/bootstrap).
86> On Windows, check which registry hive your assignment rules write to. If your assignment rules deliver a profile in user context, it lands in user policy (`HKCU`), and the app ignores user policy entirely when machine policy is present; see [Deploy the configuration](#4-deploy-the-configuration). To vary configuration per user group on Windows, deliver every profile through user policy and keep `HKLM\SOFTWARE\Policies\Claude` empty, or serve per-user configuration from a [bootstrap server](/docs/third-party/claude-desktop/bootstrap.md).
8787
8888## 3. Allow required network egress
8989
from line 91
9191
9292> [!WARNING]
9393>
94> `downloads.claude.ai` is required to run the app regardless of your configuration: it serves the VM workspace bundle and the Claude Code binary. Without it, Chat conversations, Cowork tasks, and Code sessions cannot start on a device that has not yet downloaded these components. App updates often change one or both of these components, and the app then downloads the new versions from the same host. The [offline installer variant](/docs/third-party/claude-desktop/installation#offline-installation) builds both components into the installer package, so Chat conversations, Cowork tasks, and Code sessions on the device start without this host. The app still requests the model catalog from `downloads.claude.ai` unless [`modelCatalogEnabled`](/docs/third-party/claude-desktop/configuration#modelcatalogenabled) is `false` or [`modelCatalogUrl`](/docs/third-party/claude-desktop/configuration#modelcatalogurl) names a mirror inside your network, and sessions start whether or not that request succeeds.
94> `downloads.claude.ai` is required to run the app regardless of your configuration: it serves the VM workspace bundle and the Claude Code binary. Without it, Chat conversations, Cowork tasks, and Code sessions cannot start on a device that has not yet downloaded these components. App updates often change one or both of these components, and the app then downloads the new versions from the same host. The [offline installer variant](/docs/third-party/claude-desktop/installation.md#offline-installation) builds both components into the installer package, so Chat conversations, Cowork tasks, and Code sessions on the device start without this host. The app still requests the model catalog from `downloads.claude.ai` unless [`modelCatalogEnabled`](/docs/third-party/claude-desktop/configuration#modelcatalogenabled) is `false` or [`modelCatalogUrl`](/docs/third-party/claude-desktop/configuration#modelcatalogurl) names a mirror inside your network, and sessions start whether or not that request succeeds.
9595
96Open these hosts on your perimeter firewall before rolling out to devices. See [Telemetry and egress](/docs/third-party/claude-desktop/telemetry#required-egress-paths) for the full list of hosts grouped by the setting that controls each one, and for the distinction between the perimeter firewall and the in-app sandbox allowlist.
96Open these hosts on your perimeter firewall before rolling out to devices. See [Telemetry and egress](/docs/third-party/claude-desktop/telemetry.md#required-egress-paths) for the full list of hosts grouped by the setting that controls each one, and for the distinction between the perimeter firewall and the in-app sandbox allowlist.
9797
9898## 4. Deploy the configuration
9999
from line 129
129129
130130When a managed source sets any key other than the [app-behavior keys](#update-keys-and-managed-precedence) listed below, the managed configuration takes effect, the in-app configuration window becomes read-only, and locally authored values in `configLibrary/` are ignored.
131131
132A user who signs in to any organization that uses the [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console) can move the device to that organization's configuration. To prevent that, set [`disableDeploymentModeChooser`](/docs/third-party/claude-desktop/configuration#disabledeploymentmodechooser) to `true`, as described under [Keep a device on its managed profile](/docs/third-party/claude-desktop/admin-console#keep-a-device-on-its-managed-profile).
132A user who signs in to any organization that uses the [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console.md) can move the device to that organization's configuration. To prevent that, set [`disableDeploymentModeChooser`](/docs/third-party/claude-desktop/configuration#disabledeploymentmodechooser) to `true`, as described under [Keep a device on its managed profile](/docs/third-party/claude-desktop/admin-console.md#keep-a-device-on-its-managed-profile).
133133
134134### Update keys and managed precedence
135135
from line 137
137137
138138* The update keys `disableAutoUpdates`, `autoUpdaterEnforcementHours`, `updateViaUpdatesHost`, and [`releaseChannel`](/docs/third-party/claude-desktop/configuration#releasechannel).
139139* The configuration lifecycle keys [`relaunchEnforcementHours`](/docs/third-party/claude-desktop/configuration#relaunchenforcementhours) and [`configRecheckIntervalMinutes`](/docs/third-party/claude-desktop/configuration#configrecheckintervalminutes), which MDM can set from version 1.46388.1.
140* The network proxy keys `egressProxyUrl` and `egressProxyPacUrl`. See [Network proxy](/docs/third-party/claude-desktop/network-proxy#pin-a-proxy-from-managed-configuration).
140* The network proxy keys `egressProxyUrl` and `egressProxyPacUrl`. See [Network proxy](/docs/third-party/claude-desktop/network-proxy.md#pin-a-proxy-from-managed-configuration).
141141
142142When a managed source sets only keys from this group (any of them), the device keeps its locally authored configuration and the configuration window stays editable. The group is still enforced as a unit: every key in it is resolved from the managed source alone, so a locally set or bootstrap-served value for any of them is ignored even if the profile sets only one. A profile that sets the update keys but not `relaunchEnforcementHours` or `configRecheckIntervalMinutes` therefore runs their defaults (24 hours and 10 minutes) on those devices, so set them in the same profile when you want other values.
143143
from line 149
149149
150150## 6. Deploy organization plugins (optional)
151151
152If you're distributing [organization plugins](/docs/third-party/claude-desktop/extensions#organization-plugins-admin), push the plugin bundles to the org-plugins directory on each device alongside the configuration profile. Plugins are picked up at the next app launch.
152If you're distributing [organization plugins](/docs/third-party/claude-desktop/extensions.md#organization-plugins-admin), push the plugin bundles to the org-plugins directory on each device alongside the configuration profile. Plugins are picked up at the next app launch.
153153
154154## Next steps
155155
156After deployment, confirm devices picked up the configuration with the checks in [Verifying the deployment](/docs/third-party/claude-desktop/installation#verifying-the-deployment).
156After deployment, confirm devices picked up the configuration with the checks in [Verifying the deployment](/docs/third-party/claude-desktop/installation.md#verifying-the-deployment).
157157
third-party/claude-desktop/models Changed · +7 / -7 lines
from line 2
22
33> Which models Claude Desktop on 3P offers, the default model and its starting effort level, per-model effort caps, display names, and 1M-context variants
44
5Claude Desktop on third-party (3P) builds the model picker in Chat, Cowork, and Code from your configuration. Your configuration decides which models the picker offers, which model and effort level each new conversation starts with, and which effort levels users can choose. You control all three with the keys under **Models** in the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration). The [configuration reference](/docs/third-party/claude-desktop/configuration#models) lists every field.
5Claude Desktop on third-party (3P) builds the model picker in Chat, Cowork, and Code from your configuration. Your configuration decides which models the picker offers, which model and effort level each new conversation starts with, and which effort levels users can choose. You control all three with the keys under **Models** in the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration.md). The [configuration reference](/docs/third-party/claude-desktop/configuration.md#models) lists every field.
66
77## Model list and default model
88
99[`inferenceModels`](/docs/third-party/claude-desktop/configuration#inferencemodels) lists the models the picker offers. Write each entry with the exact model ID your provider expects, such as `us.anthropic.claude-sonnet-5` on Amazon Bedrock or `claude-sonnet-5` on Google Cloud's Agent Platform. The first entry is the default model. New Chat conversations, Cowork sessions, and Code sessions start on the default model until a user picks another model. To control whether a user's choice carries over to later conversations and sessions, see [Start every conversation on the default model](#start-every-conversation-on-the-default-model).
1010
11If you leave `inferenceModels` unset and your provider supports [model discovery](/docs/third-party/claude-desktop/configuration#modeldiscoveryenabled), Claude Desktop fills the picker from the provider's model list at launch. The first discovered model is then the default model.
11If you leave `inferenceModels` unset and your provider supports [model discovery](/docs/third-party/claude-desktop/configuration.md#modeldiscoveryenabled), Claude Desktop fills the picker from the provider's model list at launch. The first discovered model is then the default model.
1212
1313Each entry is either a model ID string or an object. In an object, `name` holds the model ID and every other field is optional. Three of the optional fields change how the picker shows the model:
1414
1515* `labelOverride` sets the display name for an ID the picker can't turn into a readable name, such as a gateway routing alias or an Amazon Bedrock application inference profile ARN. Claude Desktop still sends `name` to your provider.
1616* `supports1m: true` adds a second entry that shows the same name with **1M context window** beneath it. Set it only when your deployment accepts 1M-token requests for that model. Otherwise, requests from the 1M entry fail at the provider.
17* `prefer1m: true`, with `supports1m: true`, shows the model as one entry. New conversations with it use the 1M context window. To do this for every entry that sets `supports1m`, set [`modelPrefer1mContext`](/docs/third-party/claude-desktop/configuration#modelprefer1mcontext) to `true`. When discovery fills the picker from a gateway, that key applies to every model the gateway [marks as supporting 1M](/docs/third-party/claude-desktop/gateway#models).
17* `prefer1m: true`, with `supports1m: true`, shows the model as one entry. New conversations with it use the 1M context window. To do this for every entry that sets `supports1m`, set [`modelPrefer1mContext`](/docs/third-party/claude-desktop/configuration#modelprefer1mcontext) to `true`. When discovery fills the picker from a gateway, that key applies to every model the gateway [marks as supporting 1M](/docs/third-party/claude-desktop/gateway.md#models).
1818
1919On any provider, a Chat conversation, Cowork session, or Code session on an entry without `supports1m` assumes a context window from the model ID:
2020
21* **An ID recognized as a model with a native 1M context window**, such as `us.anthropic.claude-opus-5`: you don't need `supports1m` or `prefer1m`. Setting them doesn't change the assumed window. For earlier Claude Desktop versions, see [Context window and compaction](/docs/third-party/claude-desktop/gateway#context-window-and-compaction) on the LLM gateway page. To check a model, see [Extended context](https://code.claude.com/docs/en/model-config#extended-context) in the Claude Code documentation, which lists the models that run with the 1M window by default.
21* **An ID recognized as a model with a native 1M context window**, such as `us.anthropic.claude-opus-5`: you don't need `supports1m` or `prefer1m`. Setting them doesn't change the assumed window. For earlier Claude Desktop versions, see [Context window and compaction](/docs/third-party/claude-desktop/gateway.md#context-window-and-compaction) on the LLM gateway page. To check a model, see [Extended context](https://code.claude.com/docs/en/model-config#extended-context) in the Claude Code documentation, which lists the models that run with the 1M window by default.
2222* **An ID for a model without a native 1M context window, or an unrecognized ID**, such as `us.anthropic.claude-opus-4-6-v1` or a gateway routing alias: the assumed window is 200K tokens. If your deployment accepts 1M-token requests for the model, set `supports1m` on its entry.
2323
2424## Effort levels
from line 37
3737
3838[`defaultModelEffort`](/docs/third-party/claude-desktop/configuration#defaultmodeleffort) sets the effort level the default model starts at, in place of its recommended level. Other models keep their recommended level. If you set a level the default model doesn't offer, or one above its `maxEffort`, the default model starts at the nearest lower level it offers.
3939
40`defaultModelEffort` also applies when [model discovery](/docs/third-party/claude-desktop/configuration#modeldiscoveryenabled) fills the picker instead of an `inferenceModels` list.
40`defaultModelEffort` also applies when [model discovery](/docs/third-party/claude-desktop/configuration.md#modeldiscoveryenabled) fills the picker instead of an `inferenceModels` list.
4141
4242### Models without an Effort control
4343
from line 51
5151
5252When you turn the setting on, Claude Desktop keeps the choices users saved earlier. If you later turn it off, those choices apply again.
5353
54`alwaysStartWithDefaultModel` also applies when [model discovery](/docs/third-party/claude-desktop/configuration#modeldiscoveryenabled) fills the picker instead of an `inferenceModels` list.
54`alwaysStartWithDefaultModel` also applies when [model discovery](/docs/third-party/claude-desktop/configuration.md#modeldiscoveryenabled) fills the picker instead of an `inferenceModels` list.
5555
5656## Example configuration
5757
from line 72
7272
7373In that session, the user can switch to Claude Opus 5, which starts at its recommended high effort, or raise Claude Sonnet 5 to high. The session keeps either choice. The user's next new conversation or session opens on Claude Sonnet 5 at medium effort again.
7474
75The example is plain JSON, which is the form a [bootstrap server](/docs/third-party/claude-desktop/bootstrap) response and the Linux managed file use. For a macOS profile or the Windows registry, encode the same values as the [Value types](/docs/third-party/claude-desktop/configuration#value-types) section describes.
75The example is plain JSON, which is the form a [bootstrap server](/docs/third-party/claude-desktop/bootstrap.md) response and the Linux managed file use. For a macOS profile or the Windows registry, encode the same values as the [Value types](/docs/third-party/claude-desktop/configuration.md#value-types) section describes.
7676
third-party/claude-desktop/move-to-claude-enterprise Changed · +4 / -4 lines
from line 49
4949
5050## What changes for your security controls
5151
52After the change, most of your cloud provider settings in the [configuration reference](/docs/third-party/claude-desktop/configuration) stop working without warning, even if their keys stay deployed, including permission, plugin, and browser limits. Set up replacements first:
52After the change, most of your cloud provider settings in the [configuration reference](/docs/third-party/claude-desktop/configuration.md) stop working without warning, even if their keys stay deployed, including permission, plugin, and browser limits. Set up replacements first:
5353
5454* Cowork's telemetry and network egress: your organization settings.
5555* Code sessions' telemetry, SSH host limits (any host is allowed until you set a list), and session retention (`cleanupPeriodDays`): Claude Code's managed settings.
56* Remote [managed MCP servers](/docs/third-party/claude-desktop/configuration#managedmcpservers): add them as connectors. The Microsoft 365 connector keeps working.
56* Remote [managed MCP servers](/docs/third-party/claude-desktop/configuration.md#managedmcpservers): add them as connectors. The Microsoft 365 connector keeps working.
5757
5858Telemetry opt-outs, the egress list for Code sessions, Cowork's session retention, and locally run managed MCP servers have no replacement. The command sandbox in Code sessions stays on only where [`allowedWorkspaceFolders`](/docs/third-party/claude-desktop/configuration#allowedworkspacefolders) is set. Migrated plugins aren't scanned. Migrated skills and plugins arrive on or off as before, with their hooks and tool permissions.
5959
6060## Migrate your fleet
6161
62Remove the old keys and set the new one in one change to the policy or profile that carries your Claude settings: an `HKEY_LOCAL_MACHINE` policy on Windows (not `HKEY_CURRENT_USER`), or a [configuration profile](/docs/third-party/claude-desktop/mdm) on macOS.
62Remove the old keys and set the new one in one change to the policy or profile that carries your Claude settings: an `HKEY_LOCAL_MACHINE` policy on Windows (not `HKEY_CURRENT_USER`), or a [configuration profile](/docs/third-party/claude-desktop/mdm.md) on macOS.
6363
6464**1. Remove the cloud provider keys**
6565
66Remove every key that puts the app in third-party mode, such as those that start with `inference` or `bootstrap`. Also remove [`disableDeploymentModeChooser`](/docs/third-party/claude-desktop/configuration#disabledeploymentmodechooser) and [`deploymentOrganizationUuid`](/docs/third-party/claude-desktop/configuration#deploymentorganizationuuid). Leave other keys in place. If your settings come from a [bootstrap server](/docs/third-party/claude-desktop/bootstrap), copy the keys you want to keep into the policy or profile itself.
66Remove every key that puts the app in third-party mode, such as those that start with `inference` or `bootstrap`. Also remove [`disableDeploymentModeChooser`](/docs/third-party/claude-desktop/configuration#disabledeploymentmodechooser) and [`deploymentOrganizationUuid`](/docs/third-party/claude-desktop/configuration#deploymentorganizationuuid). Leave other keys in place. If your settings come from a [bootstrap server](/docs/third-party/claude-desktop/bootstrap.md), copy the keys you want to keep into the policy or profile itself.
6767
6868The desktop extensions feature is on after the change unless [`isDesktopExtensionEnabled`](/docs/third-party/claude-desktop/configuration#isdesktopextensionenabled) is set to `false`.
6969
third-party/claude-desktop/network-proxy Changed · +14 / -14 lines
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
third-party/claude-desktop/overview Changed · +15 / -15 lines
from line 2
22
33> Run Claude Desktop against your own cloud inference provider
44
5Claude Desktop on third-party (3P) is a deployment mode of Claude Desktop that routes all model inference through a provider you configure: Google Cloud's Agent Platform, Amazon Bedrock, Microsoft Foundry, any compatible gateway you operate, or the Anthropic API directly. The app runs from a bundled local web application. Conversation history is stored on the user's device, and on the remote host for [SSH remote sessions](/docs/third-party/claude-desktop/ssh-remote-sessions).
5Claude Desktop on third-party (3P) is a deployment mode of Claude Desktop that routes all model inference through a provider you configure: Google Cloud's Agent Platform, Amazon Bedrock, Microsoft Foundry, any compatible gateway you operate, or the Anthropic API directly. The app runs from a bundled local web application. Conversation history is stored on the user's device, and on the remote host for [SSH remote sessions](/docs/third-party/claude-desktop/ssh-remote-sessions.md).
66
7You get the full Claude Desktop experience (Chat, Cowork, and Code, including file creation, multi-step research, and sub-agent coordination) with inference and billing handled by the provider you choose. You can also turn on [Unified Claude](/docs/third-party/claude-desktop/unified-claude), which combines Chat and Cowork into one experience.
7You get the full Claude Desktop experience (Chat, Cowork, and Code, including file creation, multi-step research, and sub-agent coordination) with inference and billing handled by the provider you choose. You can also turn on [Unified Claude](/docs/third-party/claude-desktop/unified-claude.md), which combines Chat and Cowork into one experience.
88
99## Who it's for
1010
from line 15
1515
1616How far a deployment is separated from Anthropic depends on the provider you choose. On Google Cloud's Agent Platform and Amazon Bedrock, the cloud provider processes conversation data in the region you select. On Microsoft Foundry, Anthropic operates the Claude models, and residency follows the Foundry deployment type. Review [Data handling by provider](#data-handling-by-provider) and [Data residency and international deployment](#data-residency-and-international-deployment) before choosing a provider.
1717
18If your organization can use Anthropic's first-party products directly, standard Claude Desktop with [Cowork](/docs/cowork/overview) on a Team or Enterprise plan is simpler to deploy and releases new features more quickly than Claude Desktop on 3P. Choose Claude Desktop on 3P when routing inference through Anthropic's API is not an option.
18If your organization can use Anthropic's first-party products directly, standard Claude Desktop with [Cowork](/docs/cowork/overview.md) on a Team or Enterprise plan is simpler to deploy and releases new features more quickly than Claude Desktop on 3P. Choose Claude Desktop on 3P when routing inference through Anthropic's API is not an option.
1919
2020## Architecture
2121
from line 26
2626| Model inference | Anthropic API | Your configured provider endpoint (Google Cloud's Agent Platform, Amazon Bedrock, Microsoft Foundry, or gateway), or the Anthropic API |
2727| Web application | Loaded from claude.ai | Bundled inside the desktop app |
2828| User identity | Anthropic account | Local device identity only (Anthropic account when managed from the claude.ai admin console) |
29| Conversation storage | Anthropic backend | Local disk on the user's machine, and the remote host for [SSH remote sessions](/docs/third-party/claude-desktop/ssh-remote-sessions) |
29| Conversation storage | Anthropic backend | Local disk on the user's machine, and the remote host for [SSH remote sessions](/docs/third-party/claude-desktop/ssh-remote-sessions.md) |
3030| Code execution sandbox | Local VM | Local VM (identical) |
3131| Configuration | Admin console at claude.ai | OS-native configuration (MDM-managed or per-user), a bootstrap server, or the claude.ai admin console |
3232
from line 34
3434
3535### Security posture
3636
37* **Conversation content goes only to your configured endpoint.** The app sends prompts, responses, files, and tool outputs only to your configured inference endpoint and stores them only on the local machine. If you enable [SSH remote sessions](/docs/third-party/claude-desktop/ssh-remote-sessions), Claude Code runs those sessions on a remote host, which also receives that content, sends it to your endpoint, and stores it. What happens to that content at the endpoint depends on the provider, as described under [Data handling by provider](#data-handling-by-provider).
38* **Sandboxed tool execution.** In Cowork, shell commands run in the hardened Cowork VM; file access is scoped to your allowed folders and web fetches to your egress allowlist. For Code sessions, see [Applied as managed policy](/docs/third-party/claude-desktop/code#applied-as-managed-policy).
37* **Conversation content goes only to your configured endpoint.** The app sends prompts, responses, files, and tool outputs only to your configured inference endpoint and stores them only on the local machine. If you enable [SSH remote sessions](/docs/third-party/claude-desktop/ssh-remote-sessions.md), Claude Code runs those sessions on a remote host, which also receives that content, sends it to your endpoint, and stores it. What happens to that content at the endpoint depends on the provider, as described under [Data handling by provider](#data-handling-by-provider).
38* **Sandboxed tool execution.** In Cowork, shell commands run in the hardened Cowork VM; file access is scoped to your allowed folders and web fetches to your egress allowlist. For Code sessions, see [Applied as managed policy](/docs/third-party/claude-desktop/code.md#applied-as-managed-policy).
3939* **Auditable telemetry.** Crash reports and product analytics are scrubbed of conversation and user data before being sent to Anthropic, and can be fully disabled via configuration keys. Independently, you can export session activity to your own OpenTelemetry collector. The export is metadata only by default, with prompt and tool content available as an explicit opt-in.
40* **Centrally managed.** Configuration is delivered through your existing MDM (Jamf, Intune, Workspace ONE, Group Policy), a [bootstrap server](/docs/third-party/claude-desktop/bootstrap), or the [admin console](/docs/third-party/claude-desktop/admin-console). End users can't edit a configuration that MDM delivers. They can leave it for standard Claude Desktop by signing in to claude.ai. On Claude Desktop 2.37337.0 or later, a user who signs in to any organization that uses the admin console can move the device to that organization's configuration. To prevent both, set [`disableDeploymentModeChooser`](/docs/third-party/claude-desktop/configuration#disabledeploymentmodechooser) to `true` in the MDM profile, as described under [Keep a device on its managed profile](/docs/third-party/claude-desktop/admin-console#keep-a-device-on-its-managed-profile).
40* **Centrally managed.** Configuration is delivered through your existing MDM (Jamf, Intune, Workspace ONE, Group Policy), a [bootstrap server](/docs/third-party/claude-desktop/bootstrap.md), or the [admin console](/docs/third-party/claude-desktop/admin-console.md). End users can't edit a configuration that MDM delivers. They can leave it for standard Claude Desktop by signing in to claude.ai. On Claude Desktop 2.37337.0 or later, a user who signs in to any organization that uses the admin console can move the device to that organization's configuration. To prevent both, set [`disableDeploymentModeChooser`](/docs/third-party/claude-desktop/configuration#disabledeploymentmodechooser) to `true` in the MDM profile, as described under [Keep a device on its managed profile](/docs/third-party/claude-desktop/admin-console.md#keep-a-device-on-its-managed-profile).
4141
4242For a detailed treatment of the threat model, sandbox boundaries, and data flows, request access to the [Claude Cowork Desktop Security Architecture Overview](https://trust.anthropic.com/resources?s=2a7bbzo1lyymvdt551q7kl\&name=claude-cowork-desktop-security-architecture-overview) on Anthropic's Trust Center. For architecture, telemetry, and controls information specific to Claude Desktop on 3P, see the [Claude Desktop Security Overview (Third-party platforms)](https://trust.anthropic.com/resources?s=0c8rx4s7mm5ierz8ppetfs\&name=claude-cowork-security-overview-\(third-party-platforms\)) on the Trust Center.
4343
from line 51
5151
5252Deployments hosted on Azure run inference in an Anthropic-operated service on Azure infrastructure, not in your Azure tenant, and prompts and completions remain within Azure. The only data the service sends out of Azure to Anthropic is usage metadata and any content that Anthropic's safety systems flag. Deployments hosted on Anthropic send prompts and completions to Anthropic's own infrastructure for inference. See [hosting options for Claude in Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options) for details.
5353
54For the Anthropic API, Anthropic processes conversation data under your Anthropic agreement, as described on the [Claude API](/docs/third-party/claude-desktop/claude-api) page. For an [LLM gateway](/docs/third-party/claude-desktop/gateway) you operate, data handling depends on the upstream provider your gateway routes each request to.
54For the Anthropic API, Anthropic processes conversation data under your Anthropic agreement, as described on the [Claude API](/docs/third-party/claude-desktop/claude-api.md) page. For an [LLM gateway](/docs/third-party/claude-desktop/gateway.md) you operate, data handling depends on the upstream provider your gateway routes each request to.
5555
5656## Data residency and international deployment
5757
from line 59
5959
60601. The cloud region you select for inference
61612. The physical location of the user's device, where conversations are persisted
623. The physical location of any [SSH remote session](/docs/third-party/claude-desktop/ssh-remote-sessions) host, which sends that session's inference requests and stores its conversation
623. The physical location of any [SSH remote session](/docs/third-party/claude-desktop/ssh-remote-sessions.md) host, which sends that session's inference requests and stores its conversation
6363
6464For multi-region organizations, deploy distinct MDM configuration profiles per geography so each user population points at an in-region endpoint. Google Cloud's Agent Platform and Amazon Bedrock each offer Claude models in the EU, UK, and Asia/Pacific regions; consult your provider's model-availability documentation for the current list.
6565
66**Microsoft Foundry:** Residency is set by the [hosting option and deployment type](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options) you select when you deploy the model in Microsoft Foundry. Deployments hosted on Azure offer two deployment types: Global Standard, which may run inference in any available region, and US Data Zone Standard, which keeps inference within the United States. Deployments hosted on Anthropic offer Global Standard only. Conversation history is stored on the user's device, and on the remote host for [SSH remote sessions](/docs/third-party/claude-desktop/ssh-remote-sessions). See [hosting options for Claude in Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options) for details.
66**Microsoft Foundry:** Residency is set by the [hosting option and deployment type](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options) you select when you deploy the model in Microsoft Foundry. Deployments hosted on Azure offer two deployment types: Global Standard, which may run inference in any available region, and US Data Zone Standard, which keeps inference within the United States. Deployments hosted on Anthropic offer Global Standard only. Conversation history is stored on the user's device, and on the remote host for [SSH remote sessions](/docs/third-party/claude-desktop/ssh-remote-sessions.md). See [hosting options for Claude in Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options) for details.
6767
6868## Public sector and highly regulated environments
6969
from line 71
7171
7272Because inference runs in your cloud tenant, Claude Desktop on 3P operates inside whatever compliance boundary your provider and region give you. The desktop application itself contacts Anthropic-operated hosts only to download the VM workspace bundle and Claude CLI binary (always required), and for crash reporting, product analytics, non-essential services (connector favicons, artifact previews, and MCP Apps widgets), auto-updates, and the published model catalog that labels the model picker. Each of the latter five can be disabled independently via managed configuration.
7373
74With Anthropic-bound telemetry, non-essential services, updates, and the [model catalog fetch](/docs/third-party/claude-desktop/configuration#modelcatalogenabled) all disabled, the only remaining Anthropic-operated egress is `downloads.claude.ai` for the VM workspace bundle and Claude CLI binary at session start. An app managed from the [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console) still contacts `api.anthropic.com` at launch and at each configuration re-check, and `claude.ai` at sign-in. If Code sessions can use Web Fetch, also set [`skipWebFetchPreflight`](/docs/third-party/claude-desktop/configuration#skipwebfetchpreflight) to `true` (or add `WebFetch` to `disabledBuiltinTools`), because Claude Code in [Code](/docs/third-party/claude-desktop/code) sessions otherwise checks each fetched domain with `api.anthropic.com`. Beyond that, the compliance posture of your deployment is determined by your inference provider. See [Telemetry and egress](/docs/third-party/claude-desktop/telemetry) for the full set of network paths and how to lock them down.
74With Anthropic-bound telemetry, non-essential services, updates, and the [model catalog fetch](/docs/third-party/claude-desktop/configuration.md#modelcatalogenabled) all disabled, the only remaining Anthropic-operated egress is `downloads.claude.ai` for the VM workspace bundle and Claude CLI binary at session start. An app managed from the [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console.md) still contacts `api.anthropic.com` at launch and at each configuration re-check, and `claude.ai` at sign-in. If Code sessions can use Web Fetch, also set [`skipWebFetchPreflight`](/docs/third-party/claude-desktop/configuration#skipwebfetchpreflight) to `true` (or add `WebFetch` to `disabledBuiltinTools`), because Claude Code in [Code](/docs/third-party/claude-desktop/code.md) sessions otherwise checks each fetched domain with `api.anthropic.com`. Beyond that, the compliance posture of your deployment is determined by your inference provider. See [Telemetry and egress](/docs/third-party/claude-desktop/telemetry.md) for the full set of network paths and how to lock them down.
7575
7676## HIPAA
7777
from line 81
8181
8282## Next steps
8383
84> **[Installation and setup](/docs/third-party/claude-desktop/installation)**
84> **[Installation and setup](/docs/third-party/claude-desktop/installation.md)**
8585>
8686> Roll out Claude Desktop on 3P to your organization with MDM, or configure a single machine for evaluation.
8787
88> **[Configuration reference](/docs/third-party/claude-desktop/configuration)**
88> **[Configuration reference](/docs/third-party/claude-desktop/configuration.md)**
8989>
9090> Every managed-configuration key, what it does, and recommended security profiles.
9191
92> **[Extensions](/docs/third-party/claude-desktop/extensions)**
92> **[Extensions](/docs/third-party/claude-desktop/extensions.md)**
9393>
9494> Deploy MCP servers, plugins, skills, and hooks across your fleet.
9595
96> **[Telemetry and egress](/docs/third-party/claude-desktop/telemetry)**
96> **[Telemetry and egress](/docs/third-party/claude-desktop/telemetry.md)**
9797>
9898> What the app sends to Anthropic, how to turn it off, and the firewall allowlist you'll need.
9999
third-party/claude-desktop/ssh-remote-sessions Changed · +35 / -35 lines
from line 2
22
33> How Code sessions run on a remote host over SSH in Claude Desktop on 3P, the sshHostAllowlist key that enables them, which inference credentials work on a remote host, and what to check before turning them on
44
5An SSH remote session is a [Code](/docs/third-party/claude-desktop/code) session whose Claude Code engine runs on another machine that the user reaches over SSH, while the session's interface stays in Claude Desktop on the user's device. Claude Desktop connects to the host, places the engine there, and starts the session with the inference credential and policy from your managed configuration. Users can work on code that lives on a development server, a build box, or a cloud workstation without copying it to their device. In Claude Desktop on third-party (3P), SSH remote sessions are off until you set the [`sshHostAllowlist`](/docs/third-party/claude-desktop/configuration#sshhostallowlist) key, because enabling them sends your inference credential to the hosts users connect to.
5An SSH remote session is a [Code](/docs/third-party/claude-desktop/code.md) session whose Claude Code engine runs on another machine that the user reaches over SSH, while the session's interface stays in Claude Desktop on the user's device. Claude Desktop connects to the host, places the engine there, and starts the session with the inference credential and policy from your managed configuration. Users can work on code that lives on a development server, a build box, or a cloud workstation without copying it to their device. In Claude Desktop on third-party (3P), SSH remote sessions are off until you set the [`sshHostAllowlist`](/docs/third-party/claude-desktop/configuration#sshhostallowlist) key, because enabling them sends your inference credential to the hosts users connect to.
66
77> [!NOTE]
88>
from line 12
1212
13131. **Connect.** The user picks an SSH host from the environment picker in Code, or adds one by entering its address, port, and an identity file. Claude Desktop connects through the device's OpenSSH client on macOS and Linux, or its built-in SSH client on Windows (see [Host requirements](#host-requirements) to change either default), applies the host's entry from the device's `~/.ssh/config` (see [SSH configuration on the device](#ssh-configuration-on-the-device)), and prompts in the app if the host asks for a password or a one-time code.
14142. **Deploy.** Claude Desktop places a remote server and the Claude Code engine under `~/.claude/remote/` in the SSH user's home directory on the host ([Host requirements](#host-requirements) lists every path) and reuses them on later connections.
153. **Run.** The remote server starts the engine on the host with the inference credential and policy from your managed configuration. Every file read, edit, shell command, and git operation runs on the host, in the working directory the user chose there. Claude Desktop connects to [managed MCP servers](/docs/third-party/claude-desktop/extensions#managed-mcp-servers-admin) from the device and exposes them to the engine as tools.
153. **Run.** The remote server starts the engine on the host with the inference credential and policy from your managed configuration. Every file read, edit, shell command, and git operation runs on the host, in the working directory the user chose there. Claude Desktop connects to [managed MCP servers](/docs/third-party/claude-desktop/extensions.md#managed-mcp-servers-admin) from the device and exposes them to the engine as tools.
16164. **Stream.** Claude's responses and tool output stream back to Claude Desktop. Permission prompts appear in Claude Desktop, and the engine waits on the host until the user answers.
1717
1818The engine keeps running on the host through a dropped SSH link, device sleep, or the user quitting Claude Desktop. It finishes the current turn, or stops at a permission prompt, then idles until the user reopens the session. While Claude Desktop is closed, no new turns run and the inference credential is not refreshed, so a turn that outlives the credential fails with an authentication error. A restart of the app for an update counts as a quit.
from line 100
100100
101101An MCP server in a remote session runs on the device or on the host, depending on how it was added.
102102
103* **[Managed MCP servers](/docs/third-party/claude-desktop/extensions#managed-mcp-servers-admin), and servers from plugins in the [`org-plugins` directory](/docs/third-party/claude-desktop/extensions#organization-plugins-admin)**: the device. Claude Desktop connects to the remote (HTTP or SSE) MCP servers and starts the local (stdio) ones on the device, and exposes them to the engine as tools.
103* **[Managed MCP servers](/docs/third-party/claude-desktop/extensions.md#managed-mcp-servers-admin), and servers from plugins in the [`org-plugins` directory](/docs/third-party/claude-desktop/extensions#organization-plugins-admin)**: the device. Claude Desktop connects to the remote (HTTP or SSE) MCP servers and starts the local (stdio) ones on the device, and exposes them to the engine as tools.
104104* **Local servers that a user adds under Settings > Developer**: the host, not the device. Claude Desktop sends the host a server's command, its arguments, and only those of its environment variables whose names start with `MCP_` or are one of a few fixed logging and runtime names, such as `DEBUG` and `NODE_ENV`. A secret in an argument or in an `MCP_` variable reaches the host. On a Linux or macOS host, Claude Desktop leaves out a server whose command is a path under a macOS or Windows folder, such as `/Applications/` or `C:\`.
105105* **Servers bundled in any other plugin that Claude Desktop copies to the host**: the host. The engine starts the plugin's local servers there, and connects to its remote MCP servers from there.
106106* **Servers in Claude Code's own configuration on the host**: the host. The engine reads files such as `~/.claude.json` in the SSH user's home directory and a project's `.mcp.json`, and starts their local servers and connects to their remote MCP servers from there.
107107
108[`isLocalDevMcpEnabled`](/docs/third-party/claude-desktop/configuration#islocaldevmcpenabled), `managedMcpServers`, `allowedPluginMcpServers`, and `deniedPluginMcpServers` decide which of these servers a remote session loads, as they do for a local Code session (see [Applied as managed policy](/docs/third-party/claude-desktop/code#applied-as-managed-policy)). If the host has its own Claude Code managed settings, those take precedence over the Claude Code policy these keys produce (see [Managed configuration on the remote host](#managed-configuration-on-the-remote-host)).
108[`isLocalDevMcpEnabled`](/docs/third-party/claude-desktop/configuration#islocaldevmcpenabled), `managedMcpServers`, `allowedPluginMcpServers`, and `deniedPluginMcpServers` decide which of these servers a remote session loads, as they do for a local Code session (see [Applied as managed policy](/docs/third-party/claude-desktop/code.md#applied-as-managed-policy)). If the host has its own Claude Code managed settings, those take precedence over the Claude Code policy these keys produce (see [Managed configuration on the remote host](#managed-configuration-on-the-remote-host)).
109109
110110## Enable SSH remote sessions
111111
112Set [`sshHostAllowlist`](/docs/third-party/claude-desktop/configuration#sshhostallowlist) in your managed configuration. It appears in the **Code surface** section of the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration) while Code is enabled.
112Set [`sshHostAllowlist`](/docs/third-party/claude-desktop/configuration#sshhostallowlist) in your managed configuration. It appears in the **Code surface** section of the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration.md) while Code is enabled.
113113
114114| Value | Behavior |
115115| - | - |
from line 140
140140}
141141```
142142
143In a `.mobileconfig` or registry policy, write the array as a JSON string as described under [Value types](/docs/third-party/claude-desktop/configuration#value-types). In a [bootstrap](/docs/third-party/claude-desktop/bootstrap) response, the key sits inside the `codeSurface` object.
143In a `.mobileconfig` or registry policy, write the array as a JSON string as described under [Value types](/docs/third-party/claude-desktop/configuration.md#value-types). In a [bootstrap](/docs/third-party/claude-desktop/bootstrap.md) response, the key sits inside the `codeSurface` object.
144144
145145### Interaction with Claude Code managed settings on the device
146146
147147Claude Code has its own `sshHostAllowlist` setting, which you can deploy on the device through a [Claude Code managed-settings file](https://code.claude.com/docs/en/settings#settings-files) or OS policy. The app resolves the two sources in this order:
148148
1491. `sshHostAllowlist` from the Claude Desktop configuration, when that configuration is delivered by an administrator: through machine-scoped device management (`HKLM` policy on Windows, a configuration profile on macOS, `/etc/claude-desktop` on Linux), through the [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console), or by a bootstrap server the app trusts (a `bootstrapUrl` set through device management or covered by `trustBootstrapDelivery`; see [Keys that require user consent](/docs/third-party/claude-desktop/bootstrap#keys-that-require-user-consent)). User-scope registry policy (`HKCU`) counts as applied locally.
1491. `sshHostAllowlist` from the Claude Desktop configuration, when that configuration is delivered by an administrator: through machine-scoped device management (`HKLM` policy on Windows, a configuration profile on macOS, `/etc/claude-desktop` on Linux), through the [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console.md), or by a bootstrap server the app trusts (a `bootstrapUrl` set through device management or covered by `trustBootstrapDelivery`; see [Keys that require user consent](/docs/third-party/claude-desktop/bootstrap.md#keys-that-require-user-consent)). User-scope registry policy (`HKCU`) counts as applied locally.
1501502. `sshHostAllowlist` from Claude Code's managed settings on the device.
1513. `sshHostAllowlist` from a Claude Desktop configuration the user applied locally in the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration#apply-locally-or-export-for-a-fleet).
1513. `sshHostAllowlist` from a Claude Desktop configuration the user applied locally in the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration.md#apply-locally-or-export-for-a-fleet).
1521524. Off.
153153
154On devices where users applied the configuration locally, deploy `sshHostAllowlist` in Claude Code's managed settings. That restricts SSH without an MDM profile taking ownership of the whole configuration (see [Update keys and managed precedence](/docs/third-party/claude-desktop/mdm#update-keys-and-managed-precedence)).
154On devices where users applied the configuration locally, deploy `sshHostAllowlist` in Claude Code's managed settings. That restricts SSH without an MDM profile taking ownership of the whole configuration (see [Update keys and managed precedence](/docs/third-party/claude-desktop/mdm.md#update-keys-and-managed-precedence)).
155155
156To turn off Code sessions that run on the device, so that users work in SSH remote sessions, set [`disableDesktopLocalSessions`](https://code.claude.com/docs/en/settings-reference#disabledesktoplocalsessions) to `true` in a [Claude Code managed-settings file](https://code.claude.com/docs/en/settings#settings-files) or OS policy on the device. Claude Desktop then refuses to start or resume a Code session that runs on the device. If the device already has Claude Code managed settings, add the key to those and leave `parentSettingsBehavior` as it is, set or unset. Changing it changes how those settings combine with the policy that Claude Desktop supplies. If the device has none yet, also set `parentSettingsBehavior` to `"merge"` in the managed settings that you create. Without `"merge"`, the new managed settings replace the policy that Claude Desktop supplies to Claude Code on the device (see [Interaction with Claude Code's own managed settings](/docs/third-party/claude-desktop/code#interaction-with-claude-code%E2%80%99s-own-managed-settings) on the Code page).
156To turn off Code sessions that run on the device, so that users work in SSH remote sessions, set [`disableDesktopLocalSessions`](https://code.claude.com/docs/en/settings-reference#disabledesktoplocalsessions) to `true` in a [Claude Code managed-settings file](https://code.claude.com/docs/en/settings#settings-files) or OS policy on the device. Claude Desktop then refuses to start or resume a Code session that runs on the device. If the device already has Claude Code managed settings, add the key to those and leave `parentSettingsBehavior` as it is, set or unset. Changing it changes how those settings combine with the policy that Claude Desktop supplies. If the device has none yet, also set `parentSettingsBehavior` to `"merge"` in the managed settings that you create. Without `"merge"`, the new managed settings replace the policy that Claude Desktop supplies to Claude Code on the device (see [Interaction with Claude Code's own managed settings](/docs/third-party/claude-desktop/code.md#interaction-with-claude-code%E2%80%99s-own-managed-settings) on the Code page).
157157
158158Before you deploy `disableDesktopLocalSessions`, make sure that the `sshHostAllowlist` that applies on the device, by [the order of its sources](#interaction-with-claude-code-managed-settings-on-the-device), allows the hosts that users need. While SSH remote sessions are off, a device that has `disableDesktopLocalSessions` set can start neither a local Code session nor an SSH remote session.
159159
160160### Devices that move to an admin console organization
161161
162A device that gets its SSH keys from a managed profile, a registry policy, or the profile's bootstrap server moves to the configuration from the [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console) when its user signs in to an organization that uses the console and chooses that organization in the dialog that follows. The app then restarts. A device that used such an organization before its profile arrived, and whose user hasn't signed out of the app since, moves back at its first launch on Claude Desktop 2.37337.0 or later, with no new sign-in and without asking the user, even if the stored sign-in has expired. To prevent that, add `disableDeploymentModeChooser` to the profile before devices update. `forceLoginOrgUUID` prevents it only for organizations it leaves out. Before Claude Desktop 2.37337.0, a device with such a profile ignores the admin console.
162A device that gets its SSH keys from a managed profile, a registry policy, or the profile's bootstrap server moves to the configuration from the [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console.md) when its user signs in to an organization that uses the console and chooses that organization in the dialog that follows. The app then restarts. A device that used such an organization before its profile arrived, and whose user hasn't signed out of the app since, moves back at its first launch on Claude Desktop 2.37337.0 or later, with no new sign-in and without asking the user, even if the stored sign-in has expired. To prevent that, add `disableDeploymentModeChooser` to the profile before devices update. `forceLoginOrgUUID` prevents it only for organizations it leaves out. Before Claude Desktop 2.37337.0, a device with such a profile ignores the admin console.
163163
164After the move, `sshHostAllowlist`, `sshTransport`, and `sshClientPath` from the profile, or from the profile's bootstrap server, don't apply, even where the console leaves them unset. For the profile's other settings, see [Which settings apply on a device with a managed profile](/docs/third-party/claude-desktop/admin-console#which-settings-apply-on-a-device-with-a-managed-profile).
164After the move, `sshHostAllowlist`, `sshTransport`, and `sshClientPath` from the profile, or from the profile's bootstrap server, don't apply, even where the console leaves them unset. For the profile's other settings, see [Which settings apply on a device with a managed profile](/docs/third-party/claude-desktop/admin-console.md#which-settings-apply-on-a-device-with-a-managed-profile).
165165
166166* **Which hosts**: the console's `sshHostAllowlist` applies. If the console leaves the key unset (**Not set**), or the app hasn't yet downloaded the console's configuration at this launch (the copy a device keeps of the last download holds no lists), `sshHostAllowlist` from Claude Code's managed settings on the device applies. With neither, SSH remote sessions are off.
167167* **Which SSH client**: the console's `sshTransport` and `sshClientPath` apply. A key that the console leaves unset takes its default under [Host requirements](#host-requirements). Until the app has downloaded the console's configuration at a launch, both keys count as unset.
from line 171
171171* **Keep the device on its profile**: set [`disableDeploymentModeChooser`](/docs/third-party/claude-desktop/configuration#disabledeploymentmodechooser) to `true`. The app ignores the admin console, and the sign-in screen doesn't offer **Or sign in with Claude.ai**. A device that has already moved returns to its profile at its next launch.
172172* **Allow only your organization**: set [`forceLoginOrgUUID`](/docs/cowork/hipaa-setup#what-each-claude-desktop-key-does) to your organization ID, and set the SSH keys you rely on in the console too. The key also limits standard Claude Desktop sign-in on the device to your organization.
173173
174Before you add either key to a profile that sets only [app-behavior keys](/docs/third-party/claude-desktop/mdm#update-keys-and-managed-precedence), such as `disableAutoUpdates`, read the warning under [Keep a device on its managed profile](/docs/third-party/claude-desktop/admin-console#keep-a-device-on-its-managed-profile).
174Before you add either key to a profile that sets only [app-behavior keys](/docs/third-party/claude-desktop/mdm.md#update-keys-and-managed-precedence), such as `disableAutoUpdates`, read the warning under [Keep a device on its managed profile](/docs/third-party/claude-desktop/admin-console.md#keep-a-device-on-its-managed-profile).
175175
176176## Inference credentials on the remote host
177177
from line 183
183183
184184| Provider | Works on a remote host | Refused at session start |
185185| - | - | - |
186| [LLM gateway](/docs/third-party/claude-desktop/gateway) | Static API key, single sign-on, credential helper | |
187| [Claude API](/docs/third-party/claude-desktop/claude-api) | Static API key, Sign in with Claude Console, credential helper | |
188| [Microsoft Foundry](/docs/third-party/claude-desktop/foundry) | API key, in-app Entra ID sign-in, credential helper | |
189| [Amazon Bedrock](/docs/third-party/claude-desktop/bedrock) | Bearer token, identity provider sign-in, credential helper | In-app AWS sign-in (IAM Identity Center), named profile |
190| [Amazon Bedrock Mantle](/docs/third-party/claude-desktop/mantle) | Bearer token, credential helper | |
191| [Google Cloud's Agent Platform](/docs/third-party/claude-desktop/vertex) | In-app Workforce Identity sign-in, credential helper | In-app Google sign-in, service-account key or credentials file, application default credentials on the device |
186| [LLM gateway](/docs/third-party/claude-desktop/gateway.md) | Static API key, single sign-on, credential helper | |
187| [Claude API](/docs/third-party/claude-desktop/claude-api.md) | Static API key, Sign in with Claude Console, credential helper | |
188| [Microsoft Foundry](/docs/third-party/claude-desktop/foundry.md) | API key, in-app Entra ID sign-in, credential helper | |
189| [Amazon Bedrock](/docs/third-party/claude-desktop/bedrock.md) | Bearer token, identity provider sign-in, credential helper | In-app AWS sign-in (IAM Identity Center), named profile |
190| [Amazon Bedrock Mantle](/docs/third-party/claude-desktop/mantle.md) | Bearer token, credential helper | |
191| [Google Cloud's Agent Platform](/docs/third-party/claude-desktop/vertex.md) | In-app Workforce Identity sign-in, credential helper | In-app Google sign-in, service-account key or credentials file, application default credentials on the device |
192192
193193When the configured credential is a refused kind, the session fails at session start, with the card [SSH sessions can't use your model provider settings](#ssh-sessions-can%E2%80%99t-use-your-model-provider-settings).
194194
195When the remote engine's credential expires during a turn, Claude Desktop obtains a new one on the device, by re-running a [credential helper](/docs/third-party/claude-desktop/credential-helper) or using a sign-in's refresh token, and sends it over the SSH connection. When the user signs out of the inference provider in the app, Claude Desktop ends the remote engine.
195When the remote engine's credential expires during a turn, Claude Desktop obtains a new one on the device, by re-running a [credential helper](/docs/third-party/claude-desktop/credential-helper.md) or using a sign-in's refresh token, and sends it over the SSH connection. When the user signs out of the inference provider in the app, Claude Desktop ends the remote engine.
196196
197197The host needs its own network route to the inference endpoint and must trust the endpoint's certificate. Claude Desktop passes the endpoint address to the remote engine but not the device's proxy settings, CA certificates, or the user's shell variables such as `AWS_*` or `GOOGLE_*`. A gateway at `localhost` on the device is refused for remote sessions, because the host cannot reach it.
198198
199199## Managed configuration on the remote host
200200
201Most of the policy that Claude Desktop applies to a local Code session applies on the remote host too. The [Code page](/docs/third-party/claude-desktop/code#how-configuration-propagates) describes how each key reaches Claude Code.
201Most of the policy that Claude Desktop applies to a local Code session applies on the remote host too. The [Code page](/docs/third-party/claude-desktop/code.md#how-configuration-propagates) describes how each key reaches Claude Code.
202202
203203* `disableEssentialTelemetry` and `disableNonessentialTelemetry`.
204204* `otlpEndpoint`, `otlpProtocol`, `otlpHeaders`, `otlpResourceAttributes`, and `otlpContentCapture`. Remote sessions appear in your collector under the same `service.name` as local Code sessions. A collector at `localhost` on the device is not forwarded. An `otlpHeadersHelper` runs on the device at session start, and the remote session keeps those headers for its lifetime.
from line 207
207207* [`blockReadsOutsideWorkingDirectories`](/docs/third-party/claude-desktop/configuration#blockreadsoutsideworkingdirectories), evaluated on the host, so the working directories and the home directory it hides from shell commands are the SSH user's there. Hiding files from shell commands needs the host's sandbox dependencies (next item); on a host without them, or a Windows host, shell reads outside the working directories ask for approval instead, and the file-tool restriction applies regardless. Files a user attaches to a remote session stay readable, except on a Windows host, where the session's plugin files and attachments stay outside the file tools' reach under this key.
208208* `coworkEgressAllowedHosts`, as Claude Code managed settings. The network and filesystem sandbox it produces with `allowedWorkspaceFolders` depends on the host having Claude Code's sandbox dependencies installed (see [Claude Code sandboxing](https://code.claude.com/docs/en/sandboxing)). Without them, commands run unsandboxed. See [Sandbox status on the remote host](#sandbox-status-on-the-remote-host) for the message the session shows.
209209* `managedMcpServers`, as the Claude Code managed setting that keeps the session from loading MCP servers that users define in Claude Code's own configuration on the host. The managed servers themselves are reached from the device (see [Where MCP servers run in a remote session](#where-mcp-servers-run-in-a-remote-session)).
210* Plugins from your [allowed marketplaces](/docs/third-party/claude-desktop/extensions), copied to the host. A plugin's `hooks` directory is not copied, so its hooks do not run in a remote session, and a plugin whose manifest declares hooks elsewhere is not copied at all.
210* Plugins from your [allowed marketplaces](/docs/third-party/claude-desktop/extensions.md), copied to the host. A plugin's `hooks` directory is not copied, so its hooks do not run in a remote session, and a plugin whose manifest declares hooks elsewhere is not copied at all.
211211
212If the host has its own Claude Code managed settings, those take precedence over the policy Claude Desktop supplies, as described under [Interaction with Claude Code's own managed settings](/docs/third-party/claude-desktop/code#interaction-with-claude-code%E2%80%99s-own-managed-settings) for local sessions.
212If the host has its own Claude Code managed settings, those take precedence over the policy Claude Desktop supplies, as described under [Interaction with Claude Code's own managed settings](/docs/third-party/claude-desktop/code.md#interaction-with-claude-code%E2%80%99s-own-managed-settings) for local sessions.
213213
214214### Read-only folders on the remote host
215215
from line 218
218218A remote session doesn't enforce `mode` in these cases:
219219
220220* **Windows hosts.**
221* **Hosts with their own Claude Code managed settings**: Claude Code ignores the rules, and the sandbox settings that Claude Desktop supplies with them, unless those settings set `parentSettingsBehavior` to `"merge"`. Under `"merge"` the host's own values still win where the two differ, so `sandbox.enabled` set to `false` there leaves shell commands unsandboxed (see [Interaction with Claude Code's own managed settings](/docs/third-party/claude-desktop/code#interaction-with-claude-code%E2%80%99s-own-managed-settings)).
221* **Hosts with their own Claude Code managed settings**: Claude Code ignores the rules, and the sandbox settings that Claude Desktop supplies with them, unless those settings set `parentSettingsBehavior` to `"merge"`. Under `"merge"` the host's own values still win where the two differ, so `sandbox.enabled` set to `false` there leaves shell commands unsandboxed (see [Interaction with Claude Code's own managed settings](/docs/third-party/claude-desktop/code.md#interaction-with-claude-code%E2%80%99s-own-managed-settings)).
222222* **An entry that is or contains the SSH user's `~/.claude` folder, such as `~`**: Claude Code keeps its own files there. List narrower folders.
223223
224224Where the rules apply, they cover the following:
from line 230
230230
231231### Sandbox status on the remote host
232232
233Claude Desktop asks Claude Code on the host whether the [sandbox](/docs/third-party/claude-desktop/code#applied-as-managed-policy) from your Claude Desktop policy is turned on and running there. The answer is Claude Code's own report, and it doesn't compare each allowed host or folder. Your policy includes the sandbox, and Claude Desktop asks, unless `coworkEgressAllowedHosts` contains `*` and `allowedWorkspaceFolders` is unset. Requires Claude Desktop 2.26454.0 or later.
233Claude Desktop asks Claude Code on the host whether the [sandbox](/docs/third-party/claude-desktop/code.md#applied-as-managed-policy) from your Claude Desktop policy is turned on and running there. The answer is Claude Code's own report, and it doesn't compare each allowed host or folder. Your policy includes the sandbox, and Claude Desktop asks, unless `coworkEgressAllowedHosts` contains `*` and `allowedWorkspaceFolders` is unset. Requires Claude Desktop 2.26454.0 or later.
234234
235235When the sandbox isn't confirmed, the session continues and shell commands can run outside the sandbox. To keep Claude Code from starting on a host whose operating system has no sandbox or that lacks a dependency, set [`sandbox.failIfUnavailable`](https://code.claude.com/docs/en/sandboxing#enforce-sandboxing-with-managed-settings) to `true` and [`parentSettingsBehavior`](/docs/third-party/claude-desktop/code#interaction-with-claude-code%E2%80%99s-own-managed-settings) to `"merge"` in the host's Claude Code managed settings. With `"merge"`, that setting applies together with your policy.
236236
from line 260
260260* **`session_id`**: Claude Desktop's ID for the session
261261* **`backend_kind`**: `ssh`
262262
263The event doesn't name the host. To find the host, ask the user that the [user attribution](/docs/third-party/claude-desktop/telemetry#user-attribution) attributes identify.
263The event doesn't name the host. To find the host, ask the user that the [user attribution](/docs/third-party/claude-desktop/telemetry.md#user-attribution) attributes identify.
264264
265265## Host requirements
266266
from line 292
292292| `~/.claude/remote/run/<id>/` | The server's socket, token, and log |
293293| `~/.claude/remote/plugins/<id>/` | Plugins synced from the device, in one folder for each Claude Desktop installation that connects |
294294| `~/.claude/uploads/<session-id>/` | Files the user attached to a message. Not removed when the session ends |
295| `~/.claude/` and `~/.claude.json` | Claude Code's own data, including session transcripts. See [Data storage](/docs/third-party/claude-desktop/data-storage) |
295| `~/.claude/` and `~/.claude.json` | Claude Code's own data, including session transcripts. See [Data storage](/docs/third-party/claude-desktop/data-storage.md) |
296296
297297Each side of a remote session needs its own network access.
298298
299* Devices installed with the regular installer must reach `downloads.claude.ai`: Claude Desktop downloads the remote server there and uploads it to the host over SFTP. Devices installed with the [offline installer](/docs/third-party/claude-desktop/installation#offline-installation) don't: it bundles the remote server and the Claude Code engine for Linux x64 and arm64 hosts, and Claude Desktop uploads both over SFTP. Hosts on other platforms still need the download, so an offline-installed device that cannot reach `downloads.claude.ai` fails the session with a message saying the installer doesn't include remote components for that platform.
300* The host must reach your inference endpoint and, if configured, your OTLP collector, plus whatever the user's own work needs. With the regular installer, it downloads the Claude Code engine from `downloads.claude.ai` when it can; when that fails, Claude Desktop downloads the engine on the device and uploads it over SFTP. Unless you disabled telemetry, the engine on the host also reports to the same Anthropic hosts as a local Code session (see [Telemetry and egress](/docs/third-party/claude-desktop/telemetry)). Blocking them does not affect the session.
299* Devices installed with the regular installer must reach `downloads.claude.ai`: Claude Desktop downloads the remote server there and uploads it to the host over SFTP. Devices installed with the [offline installer](/docs/third-party/claude-desktop/installation.md#offline-installation) don't: it bundles the remote server and the Claude Code engine for Linux x64 and arm64 hosts, and Claude Desktop uploads both over SFTP. Hosts on other platforms still need the download, so an offline-installed device that cannot reach `downloads.claude.ai` fails the session with a message saying the installer doesn't include remote components for that platform.
300* The host must reach your inference endpoint and, if configured, your OTLP collector, plus whatever the user's own work needs. With the regular installer, it downloads the Claude Code engine from `downloads.claude.ai` when it can; when that fails, Claude Desktop downloads the engine on the device and uploads it over SFTP. Unless you disabled telemetry, the engine on the host also reports to the same Anthropic hosts as a local Code session (see [Telemetry and egress](/docs/third-party/claude-desktop/telemetry.md)). Blocking them does not affect the session.
301301
302302### SSH configuration on the device
303303
from line 398
398398>
399399> * **An `allowedWorkspaceFolders` entry with `mode` set to `ro`**: see [Read-only folders on the remote host](#read-only-folders-on-the-remote-host)
400400> * **A message with `unable to unlink old`**: see [A git command fails with `unable to unlink old`](https://code.claude.com/docs/en/sandboxing#a-git-command-fails-with-unable-to-unlink-old)
401> * **The other places that the sandbox lets these commands write to**: see [Filesystem isolation](https://code.claude.com/docs/en/sandboxing#filesystem-isolation) and the `allowedWorkspaceFolders` row under [Applied as managed policy](/docs/third-party/claude-desktop/code#applied-as-managed-policy)
401> * **The other places that the sandbox lets these commands write to**: see [Filesystem isolation](https://code.claude.com/docs/en/sandboxing#filesystem-isolation) and the `allowedWorkspaceFolders` row under [Applied as managed policy](/docs/third-party/claude-desktop/code.md#applied-as-managed-policy)
402402
403403## Related
404404
405* [Code in Claude Desktop on 3P](/docs/third-party/claude-desktop/code)
405* [Code in Claude Desktop on 3P](/docs/third-party/claude-desktop/code.md)
406406* [`sshHostAllowlist` in the configuration reference](/docs/third-party/claude-desktop/configuration#sshhostallowlist)
407* [Desktop and filesystem access](/docs/third-party/claude-desktop/local-access)
407* [Desktop and filesystem access](/docs/third-party/claude-desktop/local-access.md)
408408
third-party/claude-desktop/telemetry Changed · +41 / -41 lines
from line 2
22
33> What Claude Desktop on 3P sends to Anthropic, how to disable it, and the network paths your firewall needs to allow
44
5When Claude Desktop on third-party (3P) is configured with Google Cloud's Agent Platform, Amazon Bedrock, or Microsoft Foundry, the app sends conversation content only to your configured inference endpoint. The app does, by default, send a small amount of operational telemetry (crash reports and product analytics) that helps Anthropic diagnose issues and improve the product. It also checks for updates and fetches the published model catalog, and in [Code](/docs/third-party/claude-desktop/code) sessions Claude Code checks each fetched domain with Anthropic. Each of these connections can be disabled independently via managed configuration, and [Disabling all Anthropic-bound connections](#disabling-all-anthropic-bound-connections) lists them with the key that turns each one off.
5When Claude Desktop on third-party (3P) is configured with Google Cloud's Agent Platform, Amazon Bedrock, or Microsoft Foundry, the app sends conversation content only to your configured inference endpoint. The app does, by default, send a small amount of operational telemetry (crash reports and product analytics) that helps Anthropic diagnose issues and improve the product. It also checks for updates and fetches the published model catalog, and in [Code](/docs/third-party/claude-desktop/code.md) sessions Claude Code checks each fetched domain with Anthropic. Each of these connections can be disabled independently via managed configuration, and [Disabling all Anthropic-bound connections](#disabling-all-anthropic-bound-connections) lists them with the key that turns each one off.
66
7Data handling at the inference endpoint depends on the provider. For Google Cloud's Agent Platform and Amazon Bedrock, data handling is governed by the cloud provider. For Microsoft Foundry, Anthropic operates the Claude models and handles conversation data as an independent processor for Microsoft. See [Data handling by provider](/docs/third-party/claude-desktop/overview#data-handling-by-provider) on the Overview page for each provider's data path.
7Data handling at the inference endpoint depends on the provider. For Google Cloud's Agent Platform and Amazon Bedrock, data handling is governed by the cloud provider. For Microsoft Foundry, Anthropic operates the Claude models and handles conversation data as an independent processor for Microsoft. See [Data handling by provider](/docs/third-party/claude-desktop/overview.md#data-handling-by-provider) on the Overview page for each provider's data path.
88
99This page covers what each telemetry category contains, how to turn it off, and the complete set of outbound hostnames the app uses so you can configure your perimeter firewall.
1010
1111## Telemetry categories
1212
13To find out whether a managed profile's keys apply on a device that uses the [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console), see [Which settings apply on a device with a managed profile](/docs/third-party/claude-desktop/admin-console#which-settings-apply-on-a-device-with-a-managed-profile).
13To find out whether a managed profile's keys apply on a device that uses the [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console.md), see [Which settings apply on a device with a managed profile](/docs/third-party/claude-desktop/admin-console.md#which-settings-apply-on-a-device-with-a-managed-profile).
1414
1515### Essential telemetry
1616
from line 20
2020| - | - | - |
2121| `disableEssentialTelemetry` | `false` | No crash or error data leaves the device. |
2222
23On Claude Desktop 2.7032.0 and later, the [**Keep only your organization ID and restrictions on disk**](/docs/third-party/claude-desktop/admin-console#configuration-kept-on-devices) switch in the [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console) also stops the app's crash reports, even while `disableEssentialTelemetry` is `false`. Error stack traces and performance timings still leave the device while `disableEssentialTelemetry` is `false`.
23On Claude Desktop 2.7032.0 and later, the [**Keep only your organization ID and restrictions on disk**](/docs/third-party/claude-desktop/admin-console.md#configuration-kept-on-devices) switch in the [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console.md) also stops the app's crash reports, even while `disableEssentialTelemetry` is `false`. Error stack traces and performance timings still leave the device while `disableEssentialTelemetry` is `false`.
2424
2525> [!WARNING]
2626>
from line 38
3838
3939### Non-essential services
4040
41Cosmetic third-party fetches: favicons for connectors shown in the UI, the sandboxed iframe that renders interactive artifact previews, and the sandboxed iframes that render [MCP Apps](/docs/connectors/building/mcp-apps/getting-started), the interactive widgets connectors can display. Disabling these degrades the UI (generic icons, static artifact previews, and connector tool results shown as text instead of widgets) but doesn't affect functionality. On Linux, `disableNonessentialServices` also applies to the spellcheck dictionary, which the built-in spellchecker downloads from the hosts listed under [Required egress paths](#required-egress-paths). Without the dictionary, misspelled words aren't underlined.
41Cosmetic third-party fetches: favicons for connectors shown in the UI, the sandboxed iframe that renders interactive artifact previews, and the sandboxed iframes that render [MCP Apps](/docs/connectors/building/mcp-apps/getting-started.md), the interactive widgets connectors can display. Disabling these degrades the UI (generic icons, static artifact previews, and connector tool results shown as text instead of widgets) but doesn't affect functionality. On Linux, `disableNonessentialServices` also applies to the spellcheck dictionary, which the built-in spellchecker downloads from the hosts listed under [Required egress paths](#required-egress-paths). Without the dictionary, misspelled words aren't underlined.
4242
4343| Setting | Default | Effect when `true` |
4444| - | - | - |
from line 58
5858
5959Independently of what's sent to Anthropic, you can export session activity to your own OpenTelemetry collector by setting `otlpEndpoint`. This is the recommended way to retain an audit trail in environments that disable Anthropic-bound telemetry.
6060
61For third-party deployments, the export includes session metadata (event names, durations, token counts, result counts, errors) by default, but not message content. It also identifies the signed-in user; see [User attribution](#user-attribution). See [Monitoring](/docs/cowork/monitoring) for the event schema and the [`otlp*` keys](/docs/third-party/claude-desktop/configuration#otlpendpoint) in the configuration reference.
61For third-party deployments, the export includes session metadata (event names, durations, token counts, result counts, errors) by default, but not message content. It also identifies the signed-in user; see [User attribution](#user-attribution). See [Monitoring](/docs/cowork/monitoring.md) for the event schema and the [`otlp*` keys](/docs/third-party/claude-desktop/configuration#otlpendpoint) in the configuration reference.
6262
63The export carries logs and metrics. Cowork sessions, Code sessions, and the desktop application's own events arrive under the `service.name` values `cowork`, `claude-code-desktop`, and `claude-desktop` respectively. With [Unified Claude](/docs/third-party/claude-desktop/unified-claude) on, a Cowork session started from the home screen also arrives under `cowork`. The export isn't checked against the [agent egress allowlist](#required-egress-paths), so `otlpEndpoint` doesn't need an entry in `coworkEgressAllowedHosts`; your perimeter firewall still needs to allow the host.
63The export carries logs and metrics. Cowork sessions, Code sessions, and the desktop application's own events arrive under the `service.name` values `cowork`, `claude-code-desktop`, and `claude-desktop` respectively. With [Unified Claude](/docs/third-party/claude-desktop/unified-claude.md) on, a Cowork session started from the home screen also arrives under `cowork`. The export isn't checked against the [agent egress allowlist](#required-egress-paths), so `otlpEndpoint` doesn't need an entry in `coworkEgressAllowedHosts`; your perimeter firewall still needs to allow the host.
6464
65For collector authentication headers, extra resource attributes, and the log level of the desktop application's own event stream, see [`otlpHeaders`, `otlpResourceAttributes`, and `otlpDesktopLogLevel`](/docs/third-party/claude-desktop/configuration#otlpheaders) in the configuration reference. Events on the `claude-desktop` stream include `desktop_ssh_sandbox_check_failed`, described under [Sandbox status on the remote host](/docs/third-party/claude-desktop/ssh-remote-sessions#sandbox-status-on-the-remote-host).
65For collector authentication headers, extra resource attributes, and the log level of the desktop application's own event stream, see [`otlpHeaders`, `otlpResourceAttributes`, and `otlpDesktopLogLevel`](/docs/third-party/claude-desktop/configuration#otlpheaders) in the configuration reference. Events on the `claude-desktop` stream include `desktop_ssh_sandbox_check_failed`, described under [Sandbox status on the remote host](/docs/third-party/claude-desktop/ssh-remote-sessions.md#sandbox-status-on-the-remote-host).
6666
6767### Collector endpoint and headers
6868
from line 72
7272>
7373> With `otlpEndpoint` set, all signals go to this one address. Claude Desktop sets Claude Code's per-signal endpoint variables (`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`, `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`, and `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`) itself. Chat, Cowork, and Code sessions ignore the same variables in Claude Code's own settings on the device, including managed settings. To send signals to different places, route them in your collector.
7474
75The receiver must implement the OpenTelemetry protocol (OTLP) over HTTP in both its protobuf and JSON encodings, as an OpenTelemetry Collector does by default. If your logging or SIEM platform accepts only its own HTTP ingestion format, run an OpenTelemetry Collector that receives OTLP and forwards to that platform, and set `otlpEndpoint` to the collector's address. Each device opens its own connection to the collector, so the collector must present a TLS certificate the operating system trusts. See [TLS-intercepting proxies](/docs/third-party/claude-desktop/network-proxy#tls-intercepting-proxies) if a TLS-intercepting proxy sits in between.
75The receiver must implement the OpenTelemetry protocol (OTLP) over HTTP in both its protobuf and JSON encodings, as an OpenTelemetry Collector does by default. If your logging or SIEM platform accepts only its own HTTP ingestion format, run an OpenTelemetry Collector that receives OTLP and forwards to that platform, and set `otlpEndpoint` to the collector's address. Each device opens its own connection to the collector, so the collector must present a TLS certificate the operating system trusts. See [TLS-intercepting proxies](/docs/third-party/claude-desktop/network-proxy.md#tls-intercepting-proxies) if a TLS-intercepting proxy sits in between.
7676
77[`otlpHeaders`](/docs/third-party/claude-desktop/configuration#otlpheaders) is a JSON object that maps each header name to its value, for example `{"Authorization":"Bearer <token>","X-Tenant":"agency"}`. As with the other object-typed keys described under [Value types](/docs/third-party/claude-desktop/configuration#value-types), write it as a JSON string.
77[`otlpHeaders`](/docs/third-party/claude-desktop/configuration#otlpheaders) is a JSON object that maps each header name to its value, for example `{"Authorization":"Bearer <token>","X-Tenant":"agency"}`. As with the other object-typed keys described under [Value types](/docs/third-party/claude-desktop/configuration.md#value-types), write it as a JSON string.
7878
7979The app reads both keys at launch, so users must restart it after a change. If the collector refuses requests or cannot be reached, the app keeps working, shows no error, and drops the affected telemetry batches. Check the collector's own request logs to confirm data is arriving.
8080
from line 95
9595
9696The `otlpProtocol` key selects the transport for the telemetry export to your collector: `http/protobuf` (the default), `http/json`, or `grpc`. The protocol applies per session type:
9797
98* [Code](/docs/third-party/claude-desktop/code) sessions export over the protocol as configured, including `grpc`.
99* Cowork and [Chat](/docs/third-party/claude-desktop/chat) sessions export over the protocol as configured, except that when `otlpProtocol` is `grpc` they export over `http/protobuf` instead on Windows, and on other platforms whenever the Claude Code engine is given an HTTP proxy (from the operating system's proxy settings, a [pinned proxy](/docs/third-party/claude-desktop/network-proxy#pin-a-proxy-from-managed-configuration), or `HTTPS_PROXY`/`HTTP_PROXY` in a Claude Code settings file).
98* [Code](/docs/third-party/claude-desktop/code.md) sessions export over the protocol as configured, including `grpc`.
99* Cowork and [Chat](/docs/third-party/claude-desktop/chat.md) sessions export over the protocol as configured, except that when `otlpProtocol` is `grpc` they export over `http/protobuf` instead on Windows, and on other platforms whenever the Claude Code engine is given an HTTP proxy (from the operating system's proxy settings, a [pinned proxy](/docs/third-party/claude-desktop/network-proxy.md#pin-a-proxy-from-managed-configuration), or `HTTPS_PROXY`/`HTTP_PROXY` in a Claude Code settings file).
100100* The desktop application's own event stream (`claude-desktop`) always exports over `http/json`, whatever `otlpProtocol` is set to.
101101
102102These substitutions change the protocol only, not the endpoint. A stream that exports over HTTP while `otlpProtocol` is `grpc` still goes to the same `otlpEndpoint`; if that address is your collector's OTLP/gRPC receiver (conventionally port 4317), that telemetry never reaches the collector. To receive all three streams with one collector, set `otlpProtocol` to `http/protobuf` and point `otlpEndpoint` at the collector's OTLP/HTTP receiver (conventionally port 4318).
from line 154
154154Claude Desktop on 3P has **two** independent network boundaries:
155155
1561561. **Perimeter firewall:** your corporate network controls what the device can reach. The hostnames below are what you allowlist here.
1572. **Agent egress allowlist:** the [`coworkEgressAllowedHosts`](/docs/third-party/claude-desktop/configuration#coworkegressallowedhosts) key controls what the agent's web-fetch and shell tools can reach. This is independent of the perimeter. See [Web Fetch](/docs/third-party/claude-desktop/web-tools#web-fetch) for where the key applies.
1572. **Agent egress allowlist:** the [`coworkEgressAllowedHosts`](/docs/third-party/claude-desktop/configuration#coworkegressallowedhosts) key controls what the agent's web-fetch and shell tools can reach. This is independent of the perimeter. See [Web Fetch](/docs/third-party/claude-desktop/web-tools.md#web-fetch) for where the key applies.
158158
159159> [!NOTE]
160160>
from line 169
169169| `downloads.claude.ai` | VM workspace bundle and Claude CLI binary, fetched in the background or at session start |
170170| `downloads.claude.ai` | Claude Code model catalog (signed picker metadata), polled every 5–15 minutes |
171171
172Without this host reachable, Chat conversations, Cowork tasks, and Code sessions cannot start on a device that has not yet downloaded these components. App updates often change one or both of these components, and the app then downloads the new versions from the same host. Devices installed with the [offline installer variant](/docs/third-party/claude-desktop/installation#offline-installation), which includes both components in the installer package, are not affected. The model catalog fetch is not needed to run the app: set [`modelCatalogEnabled`](/docs/third-party/claude-desktop/configuration#modelcatalogenabled) to `false` to turn it off, or [`modelCatalogUrl`](/docs/third-party/claude-desktop/configuration#modelcatalogurl) to fetch the catalog from a mirror inside your network. While the catalog is unreachable, sessions still start and the model picker keeps the names and effort options the app last fetched or shipped with.
172Without this host reachable, Chat conversations, Cowork tasks, and Code sessions cannot start on a device that has not yet downloaded these components. App updates often change one or both of these components, and the app then downloads the new versions from the same host. Devices installed with the [offline installer variant](/docs/third-party/claude-desktop/installation.md#offline-installation), which includes both components in the installer package, are not affected. The model catalog fetch is not needed to run the app: set [`modelCatalogEnabled`](/docs/third-party/claude-desktop/configuration#modelcatalogenabled) to `false` to turn it off, or [`modelCatalogUrl`](/docs/third-party/claude-desktop/configuration#modelcatalogurl) to fetch the catalog from a mirror inside your network. While the catalog is unreachable, sessions still start and the model picker keeps the names and effort options the app last fetched or shipped with.
173173
174174### Inference provider
175175
from line 192
192192| `bedrock-runtime.<region>.amazonaws.com` | Model inference. Replaced by the host of `inferenceBedrockBaseUrl` if set. |
193193| `bedrock.<region>.amazonaws.com` | Control plane (model discovery) |
194194| `sts.amazonaws.com`, `sts.<region>.amazonaws.com` | STS token exchange (profile auth only) |
195| `portal.sso.<sso-region>.amazonaws.com`, `oidc.<sso-region>.amazonaws.com` | IAM Identity Center sign-in and token refresh, for [in-app AWS sign-in](/docs/third-party/claude-desktop/bedrock#in-app-aws-sign-in) and for named profiles that use IAM Identity Center. `<sso-region>` is `inferenceBedrockSsoRegion` (or the profile's `sso_region`) and can differ from the inference region. |
195| `portal.sso.<sso-region>.amazonaws.com`, `oidc.<sso-region>.amazonaws.com` | IAM Identity Center sign-in and token refresh, for [in-app AWS sign-in](/docs/third-party/claude-desktop/bedrock.md#in-app-aws-sign-in) and for named profiles that use IAM Identity Center. `<sso-region>` is `inferenceBedrockSsoRegion` (or the profile's `sso_region`) and can differ from the inference region. |
196196
197197With `inferenceBedrockBearerToken` set, the runtime and control-plane hosts are required.
198198
from line 274
274274| `redirector.gvt1.com` | Spellcheck dictionary download (Linux) |
275275| `*.gvt1.com` | Redirect targets of the spellcheck dictionary download (Linux) |
276276
277`*.claudemcpcontent.com` serves [MCP Apps](/docs/connectors/building/mcp-apps/getting-started), the interactive widgets connectors can render. Each widget loads in a sandboxed iframe on its own generated subdomain, so allowlist the wildcard.
277`*.claudemcpcontent.com` serves [MCP Apps](/docs/connectors/building/mcp-apps/getting-started.md), the interactive widgets connectors can render. Each widget loads in a sandboxed iframe on its own generated subdomain, so allowlist the wildcard.
278278
279279### Optional features
280280
from line 283
283283| Host of `otlpEndpoint` | OpenTelemetry export is configured |
284284| `github.com`, `objects.githubusercontent.com`, `pypi.org`, `files.pythonhosted.org` | Python-based desktop extensions are enabled |
285285| Hosts of each entry in `managedMcpServers` (server URL, plus `oauth.authorizationServer` and `login.microsoftonline.com` if configured) | Managed MCP servers are configured |
286| Search provider host of a built-in `websearch` server (`api.search.brave.com`, `api.tavily.com`, `api.exa.ai`, or the host of your `customUrl`) | [Built-in web search](/docs/third-party/claude-desktop/web-tools#built-in-web-search) is configured |
286| Search provider host of a built-in `websearch` server (`api.search.brave.com`, `api.tavily.com`, `api.exa.ai`, or the host of your `customUrl`) | [Built-in web search](/docs/third-party/claude-desktop/web-tools.md#built-in-web-search) is configured |
287287| Hosts in `coworkEgressAllowedHosts` | Sandbox web access is configured |
288| `api.anthropic.com` | [Code](/docs/third-party/claude-desktop/code) sessions can use Web Fetch and [`skipWebFetchPreflight`](/docs/third-party/claude-desktop/configuration#skipwebfetchpreflight) is not `true` (Claude Code's Web Fetch [domain check](/docs/third-party/claude-desktop/web-tools#web-fetch)) |
289| `hcaptcha.com`, `*.hcaptcha.com` | Users sign in with **Sign in with Claude Console** (the [Claude API](/docs/third-party/claude-desktop/claude-api) with no static key or credential helper). The Claude Console sign-in and approval pages open in the user's default browser and run a browser check from these hosts. Allow them even when the in-app Egress list doesn't show them. If they're blocked, signing in or approving can fail with a message that the browser couldn't be verified |
290| `claude.ai`, `hcaptcha.com`, `*.hcaptcha.com`, `api.anthropic.com`, `storage.googleapis.com` | [Import from claude.ai](/docs/third-party/claude-desktop/import) is enabled (`claudeAiImport` with `enabled` set to `true`). Used only while a user signs in to claude.ai and fetches an export in the import wizard; importing a downloaded export file needs none of them. The two `hcaptcha.com` entries serve the browser check on the claude.ai sign-in and approval pages |
291| `releases.claude.com` | The [built-in browser](/docs/third-party/claude-desktop/browser) is turned on (`builtinBrowserEnabled` set to `true`), for its [site safety check](/docs/third-party/claude-desktop/browser#site-safety-check) |
292| `downloads.claude.ai` | [SSH remote sessions](/docs/third-party/claude-desktop/ssh-remote-sessions) are enabled (`sshHostAllowlist` set). With the offline installer, needed only for connections to hosts other than Linux x64 and arm64, because that installer bundles the remote components for those hosts (see [Host requirements](/docs/third-party/claude-desktop/ssh-remote-sessions#host-requirements)) |
288| `api.anthropic.com` | [Code](/docs/third-party/claude-desktop/code.md) sessions can use Web Fetch and [`skipWebFetchPreflight`](/docs/third-party/claude-desktop/configuration#skipwebfetchpreflight) is not `true` (Claude Code's Web Fetch [domain check](/docs/third-party/claude-desktop/web-tools.md#web-fetch)) |
289| `hcaptcha.com`, `*.hcaptcha.com` | Users sign in with **Sign in with Claude Console** (the [Claude API](/docs/third-party/claude-desktop/claude-api.md) with no static key or credential helper). The Claude Console sign-in and approval pages open in the user's default browser and run a browser check from these hosts. Allow them even when the in-app Egress list doesn't show them. If they're blocked, signing in or approving can fail with a message that the browser couldn't be verified |
290| `claude.ai`, `hcaptcha.com`, `*.hcaptcha.com`, `api.anthropic.com`, `storage.googleapis.com` | [Import from claude.ai](/docs/third-party/claude-desktop/import.md) is enabled (`claudeAiImport` with `enabled` set to `true`). Used only while a user signs in to claude.ai and fetches an export in the import wizard; importing a downloaded export file needs none of them. The two `hcaptcha.com` entries serve the browser check on the claude.ai sign-in and approval pages |
291| `releases.claude.com` | The [built-in browser](/docs/third-party/claude-desktop/browser.md) is turned on (`builtinBrowserEnabled` set to `true`), for its [site safety check](/docs/third-party/claude-desktop/browser.md#site-safety-check) |
292| `downloads.claude.ai` | [SSH remote sessions](/docs/third-party/claude-desktop/ssh-remote-sessions.md) are enabled (`sshHostAllowlist` set). With the offline installer, needed only for connections to hosts other than Linux x64 and arm64, because that installer bundles the remote components for those hosts (see [Host requirements](/docs/third-party/claude-desktop/ssh-remote-sessions.md#host-requirements)) |
293293
294294## Disabling all Anthropic-bound connections
295295
from line 302
302302| Connector favicons, artifact previews, and MCP App widgets | Icon fetches, and the sandboxed iframe pages that render previews and widgets. Some of these requests go to third-party hosts rather than to Anthropic, such as the icon fetches to `www.google.com` and `*.gstatic.com`. See [Non-essential services](#non-essential-services) and, for each host, [Required egress paths](#required-egress-paths). | [`disableNonessentialServices`](/docs/third-party/claude-desktop/configuration#disablenonessentialservices) set to `true` |
303303| Auto-updates | Requests to Anthropic's update feed, and downloads of new builds. On Linux, `apt` downloads new versions from `downloads.claude.ai`. See [Auto-updates](#auto-updates). | [`disableAutoUpdates`](/docs/third-party/claude-desktop/configuration#disableautoupdates) set to `true`. On Linux, also keep Anthropic's apt repository off the device, as described under [Auto-updates](#auto-updates). |
304304| Model catalog | The signed model catalog that labels the model picker, fetched from `downloads.claude.ai` at launch and then every 5 to 15 minutes, including on devices installed with the offline installer. A blocked catalog request affects nothing else. | [`modelCatalogEnabled`](/docs/third-party/claude-desktop/configuration#modelcatalogenabled) set to `false`, or [`modelCatalogUrl`](/docs/third-party/claude-desktop/configuration#modelcatalogurl) set to a mirror inside your network |
305| Web Fetch domain check in [Code](/docs/third-party/claude-desktop/code) sessions | The hostname of each page Claude Code fetches, sent to `api.anthropic.com` before the fetch. See [Web Fetch](/docs/third-party/claude-desktop/web-tools#web-fetch). | [`skipWebFetchPreflight`](/docs/third-party/claude-desktop/configuration#skipwebfetchpreflight) set to `true`, or `WebFetch` added to [`disabledBuiltinTools`](/docs/third-party/claude-desktop/configuration#disabledbuiltintools) |
305| Web Fetch domain check in [Code](/docs/third-party/claude-desktop/code.md) sessions | The hostname of each page Claude Code fetches, sent to `api.anthropic.com` before the fetch. See [Web Fetch](/docs/third-party/claude-desktop/web-tools.md#web-fetch). | [`skipWebFetchPreflight`](/docs/third-party/claude-desktop/configuration#skipwebfetchpreflight) set to `true`, or `WebFetch` added to [`disabledBuiltinTools`](/docs/third-party/claude-desktop/configuration#disabledbuiltintools) |
306306
307With all six connections turned off, the only remaining Anthropic-operated egress is `downloads.claude.ai`, for the VM workspace bundle and Claude CLI binary at session start. The only other required egress is your inference provider. With the [offline installer variant](/docs/third-party/claude-desktop/installation#offline-installation), `downloads.claude.ai` is not needed either, and your inference provider is the only required egress.
307With all six connections turned off, the only remaining Anthropic-operated egress is `downloads.claude.ai`, for the VM workspace bundle and Claude CLI binary at session start. The only other required egress is your inference provider. With the [offline installer variant](/docs/third-party/claude-desktop/installation.md#offline-installation), `downloads.claude.ai` is not needed either, and your inference provider is the only required egress.
308308
309309These optional features add hosts back when you turn them on:
310310
311* [SSH remote sessions](/docs/third-party/claude-desktop/ssh-remote-sessions) download the remote-session components from `downloads.claude.ai`. The offline installer bundles those components for Linux x64 and arm64 hosts, so devices installed with it download them only when connecting to hosts on other platforms.
312* **Sign in with Claude Console** (the [Claude API](/docs/third-party/claude-desktop/claude-api) with no static key or credential helper) loads a browser check from `hcaptcha.com` and `*.hcaptcha.com` on the Claude Console sign-in and approval pages.
313* [Import from claude.ai](/docs/third-party/claude-desktop/import) reaches `claude.ai`, `api.anthropic.com`, and `storage.googleapis.com` (for the export download) only while a user signs in to claude.ai and fetches an export in the import wizard. The claude.ai sign-in and approval pages also load a browser check from `hcaptcha.com` and `*.hcaptcha.com`.
314* The [built-in browser](/docs/third-party/claude-desktop/browser) contacts `releases.claude.com` for its [site safety check](/docs/third-party/claude-desktop/browser#site-safety-check).
315* With the [remote Microsoft 365 connector](/docs/third-party/claude-desktop/connectors-m365#remote-connector), the app connects to the connector service that Anthropic hosts, at the host in the entry's `url` (`microsoft365.mcp.claude.com` in the setup steps).
311* [SSH remote sessions](/docs/third-party/claude-desktop/ssh-remote-sessions.md) download the remote-session components from `downloads.claude.ai`. The offline installer bundles those components for Linux x64 and arm64 hosts, so devices installed with it download them only when connecting to hosts on other platforms.
312* **Sign in with Claude Console** (the [Claude API](/docs/third-party/claude-desktop/claude-api.md) with no static key or credential helper) loads a browser check from `hcaptcha.com` and `*.hcaptcha.com` on the Claude Console sign-in and approval pages.
313* [Import from claude.ai](/docs/third-party/claude-desktop/import.md) reaches `claude.ai`, `api.anthropic.com`, and `storage.googleapis.com` (for the export download) only while a user signs in to claude.ai and fetches an export in the import wizard. The claude.ai sign-in and approval pages also load a browser check from `hcaptcha.com` and `*.hcaptcha.com`.
314* The [built-in browser](/docs/third-party/claude-desktop/browser.md) contacts `releases.claude.com` for its [site safety check](/docs/third-party/claude-desktop/browser.md#site-safety-check).
315* With the [remote Microsoft 365 connector](/docs/third-party/claude-desktop/connectors-m365.md#remote-connector), the app connects to the connector service that Anthropic hosts, at the host in the entry's `url` (`microsoft365.mcp.claude.com` in the setup steps).
316316
317An app that receives its configuration from the [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console) still connects to Anthropic with all of these keys set. It never fetches the model catalog (its model names and options come from the console's settings), and it contacts `api.anthropic.com` at every launch and at each configuration check (every 10 minutes by default) to download its configuration. The app contacts `claude.ai` when the user signs in, and the `claude.ai` sign-in and approval pages load a browser check from `hcaptcha.com` and `*.hcaptcha.com`, whichever sign-in method your organization uses. While the organization's **Report desktop usage to this organization** switch is on, the app also sends [usage analytics](/docs/third-party/claude-desktop/admin-console#usage-analytics) counts to `api.anthropic.com` every few minutes during use. You turn the telemetry categories for these apps on and off on the console's **Telemetry & updates** page.
317An app that receives its configuration from the [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console.md) still connects to Anthropic with all of these keys set. It never fetches the model catalog (its model names and options come from the console's settings), and it contacts `api.anthropic.com` at every launch and at each configuration check (every 10 minutes by default) to download its configuration. The app contacts `claude.ai` when the user signs in, and the `claude.ai` sign-in and approval pages load a browser check from `hcaptcha.com` and `*.hcaptcha.com`, whichever sign-in method your organization uses. While the organization's **Report desktop usage to this organization** switch is on, the app also sends [usage analytics](/docs/third-party/claude-desktop/admin-console.md#usage-analytics) counts to `api.anthropic.com` every few minutes during use. You turn the telemetry categories for these apps on and off on the console's **Telemetry & updates** page.
318318
319These settings control only the application's telemetry, update, and non-essential service connections. They do not change how your inference provider handles conversation content at the endpoint. On Microsoft Foundry, the Claude models behind your inference endpoint run in an Anthropic-operated service, so conversation content reaches Anthropic-operated infrastructure regardless of these settings. See [Data handling by provider](/docs/third-party/claude-desktop/overview#data-handling-by-provider) on the Overview page.
319These settings control only the application's telemetry, update, and non-essential service connections. They do not change how your inference provider handles conversation content at the endpoint. On Microsoft Foundry, the Claude models behind your inference endpoint run in an Anthropic-operated service, so conversation content reaches Anthropic-operated infrastructure regardless of these settings. See [Data handling by provider](/docs/third-party/claude-desktop/overview.md#data-handling-by-provider) on the Overview page.
320320
321See the [Locked down profile](/docs/third-party/claude-desktop/configuration#recommended-security-profiles) for a complete configuration.
321See the [Locked down profile](/docs/third-party/claude-desktop/configuration.md#recommended-security-profiles) for a complete configuration.
322322
323323## Proxy support
324324
325Claude Desktop and the Claude Code engine it runs follow the operating system's proxy settings by default, including PAC files, and on macOS and Windows so does the Cowork sandbox. You can also pin a specific proxy for all three from managed configuration. See [Network proxy](/docs/third-party/claude-desktop/network-proxy) for the default behavior, the pinned-proxy keys, the traffic that bypasses the proxy, and [TLS-intercepting proxies](/docs/third-party/claude-desktop/network-proxy#tls-intercepting-proxies).
325Claude Desktop and the Claude Code engine it runs follow the operating system's proxy settings by default, including PAC files, and on macOS and Windows so does the Cowork sandbox. You can also pin a specific proxy for all three from managed configuration. See [Network proxy](/docs/third-party/claude-desktop/network-proxy.md) for the default behavior, the pinned-proxy keys, the traffic that bypasses the proxy, and [TLS-intercepting proxies](/docs/third-party/claude-desktop/network-proxy.md#tls-intercepting-proxies).
326326
third-party/claude-desktop/unified-claude Changed · +3 / -3 lines
from line 4
44
55> [!NOTE]
66>
7> Unified Claude is in beta. It is opt-in until November 10, when it becomes enforced for all Desktop 3P deployments. New [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console) organizations start with Unified Claude on.
7> Unified Claude is in beta. It is opt-in until November 10, when it becomes enforced for all Desktop 3P deployments. New [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console.md) organizations start with Unified Claude on.
88
9Unified Claude combines Chat and Cowork into one experience in Claude Desktop 3P. Users get a single Claude interface for both quick chats and longer agentic tasks. [Code](/docs/third-party/claude-desktop/code) stays separate.
9Unified Claude combines Chat and Cowork into one experience in Claude Desktop 3P. Users get a single Claude interface for both quick chats and longer agentic tasks. [Code](/docs/third-party/claude-desktop/code.md) stays separate.
1010
1111Unified Claude contains the same capabilities as Cowork on Desktop 3P today, including bash execution, subagents, and scheduled tasks. The Chat experience is going away, but you can restrict specific Cowork capabilities in Unified Claude through your other settings options and tool policies.
1212
from line 25
2525Unified Claude is opt-in today. To enable it, follow the instructions below:
2626
2727* **Enterprise Admin Console**: Go to Capabilities and toggle on "Opt into the new Chat and Cowork unified view."
28* **MDM or a bootstrap server**: For MDM and bootstrap deployments, the [`desktopHome`](/docs/third-party/claude-desktop/configuration#desktophome) key controls Unified Claude. Create and set `desktopHome` to `standard` in your [MDM profile](/docs/third-party/claude-desktop/mdm) or [bootstrap response](/docs/third-party/claude-desktop/bootstrap). Claude Desktop reads a value it doesn't recognize as `off`. Remove the key to disable the Unified Claude experience.
28* **MDM or a bootstrap server**: For MDM and bootstrap deployments, the [`desktopHome`](/docs/third-party/claude-desktop/configuration#desktophome) key controls Unified Claude. Create and set `desktopHome` to `standard` in your [MDM profile](/docs/third-party/claude-desktop/mdm.md) or [bootstrap response](/docs/third-party/claude-desktop/bootstrap.md). Claude Desktop reads a value it doesn't recognize as `off`. Remove the key to disable the Unified Claude experience.
2929
3030## How Unified Claude interacts with Chat and Cowork settings
3131
third-party/claude-desktop/vertex Changed · +8 / -8 lines
from line 13
1313| Proof of concept, single team | [Service-account key](#credentials-file) (`inferenceVertexCredentialsFile`) | The key file on each device | No (shared service account) | A long-lived secret distributed to every device. Simplest to start; not recommended for broad rollout. |
1414| Users have Google Workspace or Cloud Identity accounts | [In-app Google sign-in](#in-app-google-sign-in) (`inferenceVertexOAuth*`) | None | Yes | Users sign in with their Google account inside the app. See the session-control warning below. |
1515| Users authenticate with a third-party IdP (Entra ID, Okta, Ping, …) and you don't want to provision Google identities | [In-app Workforce Identity sign-in](#in-app-workforce-identity-sign-in) (`inferenceVertexWorkforce*`) | None | Yes (workforce-pool principal) | Users sign in with their corporate identity inside the app. The app runs PKCE against your IdP and exchanges the ID token at Google STS. |
16| Your organization already has tooling that obtains a bearer token accepted by Google Cloud's Agent Platform | [Credential helper](/docs/third-party/claude-desktop/configuration#inferencecredentialhelper) (`inferenceCredentialHelper`) | The helper executable on each device | Depends on what the helper obtains | The app sends the token the helper prints as the bearer on each inference request. |
17| You already operate an LLM proxy | [Gateway provider](/docs/third-party/claude-desktop/gateway) instead of Google Cloud's Agent Platform | None | At your gateway | The proxy holds the Google Cloud credentials; the app authenticates only to the proxy. |
16| Your organization already has tooling that obtains a bearer token accepted by Google Cloud's Agent Platform | [Credential helper](/docs/third-party/claude-desktop/configuration.md#inferencecredentialhelper) (`inferenceCredentialHelper`) | The helper executable on each device | Depends on what the helper obtains | The app sends the token the helper prints as the bearer on each inference request. |
17| You already operate an LLM proxy | [Gateway provider](/docs/third-party/claude-desktop/gateway.md) instead of Google Cloud's Agent Platform | None | At your gateway | The proxy holds the Google Cloud credentials; the app authenticates only to the proxy. |
1818
1919> [!WARNING]
2020>
from line 227
227227
228228The app always requests the `offline_access` scope so that the IdP returns a refresh token for silent renewal. If your IdP rejects `offline_access` on this client (for example, a PingFederate public client without the Refresh Token grant type enabled), set the `omitOfflineAccess` field of `inferenceVertexWorkforceOidc` to `true`. Without a refresh token the app cannot refresh silently, so users will be prompted to sign in again each time the IdP's ID token expires, typically about once an hour.
229229
230When your IdP is Microsoft Entra ID, you can run this sign-in through the [OS identity broker](/docs/third-party/claude-desktop/entra-broker) on Windows and macOS instead of the system browser by setting `inferenceVertexWorkforceAuthFlow` to `broker`. The `issuer` in `inferenceVertexWorkforceOidc` must then be `https://login.microsoftonline.com/TENANT_ID/v2.0`, and no loopback redirect URI is needed. The token exchange at `sts.googleapis.com` is unchanged.
230When your IdP is Microsoft Entra ID, you can run this sign-in through the [OS identity broker](/docs/third-party/claude-desktop/entra-broker.md) on Windows and macOS instead of the system browser by setting `inferenceVertexWorkforceAuthFlow` to `broker`. The `issuer` in `inferenceVertexWorkforceOidc` must then be `https://login.microsoftonline.com/TENANT_ID/v2.0`, and no loopback redirect URI is needed. The token exchange at `sts.googleapis.com` is unchanged.
231231
232232## Configure the app
233233
234With Google Cloud set up and devices prepared, open the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration#open-the-configuration-window) (**Developer → Configure Third-Party Inference…**) on an evaluation device. In the **Connection** section, set **Inference provider** to **Vertex AI** and fill in the **Vertex AI credentials** card with the values for whichever authentication approach you chose:
234With Google Cloud set up and devices prepared, open the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration.md#open-the-configuration-window) (**Developer → Configure Third-Party Inference…**) on an evaluation device. In the **Connection** section, set **Inference provider** to **Vertex AI** and fill in the **Vertex AI credentials** card with the values for whichever authentication approach you chose:
235235
236236| Field | Service-account key | In-app Google sign-in |
237237| - | - | - |
from line 245
245245
246246Under **Models**, add at least one **Model list** entry using the publisher model ID, for example `claude-sonnet-5`.
247247
248Then click **Export** to produce a `.mobileconfig` (macOS) or `.reg` (Windows) file for your MDM. See [Deploy with MDM](/docs/third-party/claude-desktop/mdm) for the export and deployment workflow.
248Then click **Export** to produce a `.mobileconfig` (macOS) or `.reg` (Windows) file for your MDM. See [Deploy with MDM](/docs/third-party/claude-desktop/mdm.md) for the export and deployment workflow.
249249
250250### Configuration keys
251251
252252The full set of `inferenceVertex*` keys is below. Set `inferenceProvider` to `vertex`, supply a project and region, and provide exactly one credential source.
253253
254The region can be a single region such as `us-east5`, the `eu` or `us` multi-region, or `global`. The app routes inference to a different endpoint host for multi-regions and `global`; if you allowlist egress by hostname, see the [inference provider egress hosts](/docs/third-party/claude-desktop/telemetry#inference-provider).
254The region can be a single region such as `us-east5`, the `eu` or `us` multi-region, or `global`. The app routes inference to a different endpoint host for multi-regions and `global`; if you allowlist egress by hostname, see the [inference provider egress hosts](/docs/third-party/claude-desktop/telemetry.md#inference-provider).
255255
256256| Setting | Type | Availability | Default | Description |
257257| - | - | - | - | - |
from line 291
291291
292292If none of `inferenceVertexCredentialsFile`, the OAuth client keys, the Workforce Identity keys, or `inferenceCredentialHelper` is set, the Google client library falls back to the standard Application Default Credentials search path on the device (`~/.config/gcloud/application_default_credentials.json`, then the environment's metadata server).
293293
294You must also set `inferenceModels` to a list of publisher model IDs, for example `claude-sonnet-5`. See the [Configuration reference](/docs/third-party/claude-desktop/configuration#inferencemodels).
294You must also set `inferenceModels` to a list of publisher model IDs, for example `claude-sonnet-5`. See the [Configuration reference](/docs/third-party/claude-desktop/configuration.md#inferencemodels).
295295
296296## What users experience
297297
from line 306
306306
307307## Troubleshoot
308308
309To confirm which keys the app read and whether the provider settings validated, use **Help → Troubleshooting → Generate Diagnostic Report**, export the report, and check `managed-config.txt` and `provider-status.txt`; see [Verifying the deployment](/docs/third-party/claude-desktop/installation#verifying-the-deployment) for that workflow and the common causes when the app does not enter 3P mode. Application log locations are listed in [User identity and local data](/docs/third-party/claude-desktop/data-storage#where-data-lives).
309To confirm which keys the app read and whether the provider settings validated, use **Help → Troubleshooting → Generate Diagnostic Report**, export the report, and check `managed-config.txt` and `provider-status.txt`; see [Verifying the deployment](/docs/third-party/claude-desktop/installation.md#verifying-the-deployment) for that workflow and the common causes when the app does not enter 3P mode. Application log locations are listed in [User identity and local data](/docs/third-party/claude-desktop/data-storage.md#where-data-lives).
310310
third-party/claude-desktop/web-tools Changed · +11 / -9 lines
from line 50
5050
5151Add the bundled `websearch` server to [`managedMcpServers`](/docs/third-party/claude-desktop/configuration#managedmcpservers). Search runs in the desktop app itself, so it works on every inference provider, including Amazon Bedrock.
5252
53You can add it from the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration): under **Connectors**, add a **Web search** server, choose the search provider, and supply the vendor key as a header or through a headers helper script.
53You can add it from the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration.md): under **Connectors**, add a **Web search** server, choose the search provider, and supply the vendor key as a header or through a headers helper script.
5454
5555
5656
57The Web search server in the Connectors section of the in-app configuration window, with the search provider menu open.
58
5759In the exported configuration, set `provider` to a hosted search vendor (`brave`, `tavily`, or `exa`) for the lowest setup, or to `custom` with `customUrl` to point at a search server you run.
5860
5961Hosted vendor:
from line 122
120122
121123#### Data handling
122124
123Search queries go to whichever backend you configure. In every option, the query is also visible to your inference provider as part of the conversation, because the model emits the search call. For Google Cloud's Agent Platform and Amazon Bedrock, Anthropic does not receive search queries in any of these options. For Microsoft Foundry, the Anthropic API, or a gateway, the query is part of the conversation content covered under [Data handling by provider](/docs/third-party/claude-desktop/overview#data-handling-by-provider). To keep the search backend itself inside your network, use `provider: "custom"` (or a self-hosted MCP) pointed at a search index that runs inside your boundary.
125Search queries go to whichever backend you configure. In every option, the query is also visible to your inference provider as part of the conversation, because the model emits the search call. For Google Cloud's Agent Platform and Amazon Bedrock, Anthropic does not receive search queries in any of these options. For Microsoft Foundry, the Anthropic API, or a gateway, the query is part of the conversation content covered under [Data handling by provider](/docs/third-party/claude-desktop/overview.md#data-handling-by-provider). To keep the search backend itself inside your network, use `provider: "custom"` (or a self-hosted MCP) pointed at a search index that runs inside your boundary.
124126
125For audit, each search the model runs is recorded in the Cowork or Code session telemetry sent to your [OTLP collector](/docs/third-party/claude-desktop/telemetry#sending-telemetry-to-your-own-collector) as a `tool_result` event, whichever option you choose (a `WebSearch` event for provider-side or gateway-side search, an MCP tool event for the built-in or a remote search server). Add `toolDetails` to [`otlpContentCapture`](/docs/third-party/claude-desktop/telemetry#content-capture) to include the tool input, which carries the query text (long values are truncated). The built-in `websearch` server also emits a `builtin_websearch_call` event on the desktop application's own stream with the search provider, query length, result count, duration, and status, never the query text. The app exports that event only when [`otlpDesktopLogLevel`](/docs/third-party/claude-desktop/configuration#otlpdesktoploglevel) is `info` or `debug`, not at the default `error` level.
127For audit, each search the model runs is recorded in the Cowork or Code session telemetry sent to your [OTLP collector](/docs/third-party/claude-desktop/telemetry.md#sending-telemetry-to-your-own-collector) as a `tool_result` event, whichever option you choose (a `WebSearch` event for provider-side or gateway-side search, an MCP tool event for the built-in or a remote search server). Add `toolDetails` to [`otlpContentCapture`](/docs/third-party/claude-desktop/telemetry#content-capture) to include the tool input, which carries the query text (long values are truncated). The built-in `websearch` server also emits a `builtin_websearch_call` event on the desktop application's own stream with the search provider, query length, result count, duration, and status, never the query text. The app exports that event only when [`otlpDesktopLogLevel`](/docs/third-party/claude-desktop/configuration#otlpdesktoploglevel) is `info` or `debug`, not at the default `error` level.
126128
127129> [!NOTE]
128130>
from line 146
144146
145147> [!NOTE]
146148>
147> Your perimeter firewall is a separate, outer layer from `coworkEgressAllowedHosts`, so a host allowed by this key still won't be reachable if your corporate network blocks it. See [Telemetry and egress](/docs/third-party/claude-desktop/telemetry#required-egress-paths) for the distinction.
149> Your perimeter firewall is a separate, outer layer from `coworkEgressAllowedHosts`, so a host allowed by this key still won't be reachable if your corporate network blocks it. See [Telemetry and egress](/docs/third-party/claude-desktop/telemetry.md#required-egress-paths) for the distinction.
148150
149The same allowlist governs other in-sandbox network activity (for example, `curl` or `pip install` from the agent's shell), not just the Web Fetch tool. A command-line tool that a [plugin](/docs/third-party/claude-desktop/extensions#controlling-user-extensions) adds to the Cowork sandbox can also reach the hosts its plugin declares, whatever the list holds. Claude Desktop's own connections for inference, sign-in, model discovery, telemetry export, and MCP servers aren't checked against it and need no entry.
151The same allowlist governs other in-sandbox network activity (for example, `curl` or `pip install` from the agent's shell), not just the Web Fetch tool. A command-line tool that a [plugin](/docs/third-party/claude-desktop/extensions.md#controlling-user-extensions) adds to the Cowork sandbox can also reach the hosts its plugin declares, whatever the list holds. Claude Desktop's own connections for inference, sign-in, model discovery, telemetry export, and MCP servers aren't checked against it and need no entry.
150152
151153If a shell command or a Claude Code [HTTP hook](https://code.claude.com/docs/en/hooks#http-hook-fields) calls your gateway, inference provider, OTLP collector, or `api.anthropic.com`, add that host. Earlier versions of Claude Desktop added some of these hosts automatically, so when you update, add the ones the agent calls.
152154
153In [Code](/docs/third-party/claude-desktop/code) sessions, Claude Code's Web Fetch tool also asks `api.anthropic.com` whether each domain is on Anthropic's blocklist before fetching, and refuses the fetch if that lookup cannot complete. If your devices cannot reach `api.anthropic.com`, or you do not want fetched hostnames sent there, set [`skipWebFetchPreflight`](/docs/third-party/claude-desktop/configuration#skipwebfetchpreflight) to `true`. The key requires Claude Desktop 1.37937.0 or later. Cowork sessions do not perform this lookup.
155In [Code](/docs/third-party/claude-desktop/code.md) sessions, Claude Code's Web Fetch tool also asks `api.anthropic.com` whether each domain is on Anthropic's blocklist before fetching, and refuses the fetch if that lookup cannot complete. If your devices cannot reach `api.anthropic.com`, or you do not want fetched hostnames sent there, set [`skipWebFetchPreflight`](/docs/third-party/claude-desktop/configuration#skipwebfetchpreflight) to `true`. The key requires Claude Desktop 1.37937.0 or later. Cowork sessions do not perform this lookup.
154156
155157### How the egress allowlist applies in Code sessions
156158
157In [Code](/docs/third-party/claude-desktop/code) sessions, the key reaches Claude Code's own Web Fetch tool and shell sandbox as managed settings, unless [Claude Code managed settings that you deploy separately](/docs/third-party/claude-desktop/code#interaction-with-claude-code%E2%80%99s-own-managed-settings) take precedence:
159In [Code](/docs/third-party/claude-desktop/code.md) sessions, the key reaches Claude Code's own Web Fetch tool and shell sandbox as managed settings, unless [Claude Code managed settings that you deploy separately](/docs/third-party/claude-desktop/code.md#interaction-with-claude-code%E2%80%99s-own-managed-settings) take precedence:
158160
159161* **Web Fetch**: each host you list becomes a Claude Code `WebFetch` allow rule. The key doesn't block a fetch to another host. In Auto mode, which new Code sessions start in by default, and in bypass permissions mode, Claude Code doesn't ask the user before that fetch. For the other modes, see [WebFetch tool behavior](https://code.claude.com/docs/en/tools-reference#webfetch-tool-behavior).
160162* **Web Fetch controls**: to have the user approve every fetch, set `WebFetch` to `"ask"` in [`builtinToolPolicy`](/docs/third-party/claude-desktop/configuration#builtintoolpolicy), which also applies in Cowork and Chat. To remove the tool, see [Disabling web tools](#disabling-web-tools).
161* **Shell commands**: commands that run in [Claude Code's sandbox](/docs/third-party/claude-desktop/code#applied-as-managed-policy) reach only the hosts you list. On Windows, and on Linux without Claude Code's sandbox dependencies, shell commands run unsandboxed and can reach any host your network allows. To keep Code off such devices, see [Disabling Code](/docs/third-party/claude-desktop/code#disabling-code). For SSH hosts, see [Sandbox status on the remote host](/docs/third-party/claude-desktop/ssh-remote-sessions#sandbox-status-on-the-remote-host).
163* **Shell commands**: commands that run in [Claude Code's sandbox](/docs/third-party/claude-desktop/code.md#applied-as-managed-policy) reach only the hosts you list. On Windows, and on Linux without Claude Code's sandbox dependencies, shell commands run unsandboxed and can reach any host your network allows. To keep Code off such devices, see [Disabling Code](/docs/third-party/claude-desktop/code.md#disabling-code). For SSH hosts, see [Sandbox status on the remote host](/docs/third-party/claude-desktop/ssh-remote-sessions.md#sandbox-status-on-the-remote-host).
162164
163165## Disabling web tools
164166
from line 172
170172
171173With the web tools removed and `coworkEgressAllowedHosts` empty, commands in the agent's sandboxed shell reach no host other than those a [plugin declares for its command-line tool](#web-fetch). In Code sessions where [Claude Code's sandbox doesn't run](#how-the-egress-allowlist-applies-in-code-sessions), shell commands can reach any host your network allows.
172174
173The agent can still read and write local files, run code against them, and call any MCP servers you've provisioned. See the [Locked down profile](/docs/third-party/claude-desktop/configuration#recommended-security-profiles).
175The agent can still read and write local files, run code against them, and call any MCP servers you've provisioned. See the [Locked down profile](/docs/third-party/claude-desktop/configuration.md#recommended-security-profiles).
174176
claude-science/artifacts Changed · +1 / -1 lines
from line 30
3030* **Code**: a reproducible script, downloadable as a script or notebook.
3131* **Execution Log**: every command that ran.
3232* **Environment**: the environment name, language version, and every installed package with its version.
33* **Review**: findings from [the reviewer](/docs/claude-science/the-reviewer).
33* **Review**: findings from [the reviewer](/docs/claude-science/the-reviewer.md).
3434
3535The **Execution Log** is the authoritative record of what ran. If the **Code** tab and the log disagree, trust the log.
3636
claude-science/comments Changed · +1 / -1 lines
from line 6
66
77> [!NOTE]
88>
9> This page covers comments on [artifacts in the Claude Science app](/docs/claude-science/artifacts). For artifacts in a claude.ai chat, see [What are artifacts and how do I use them?](https://support.claude.com/en/articles/17153992-what-are-artifacts-and-how-do-i-use-them) in the help center.
9> This page covers comments on [artifacts in the Claude Science app](/docs/claude-science/artifacts.md). For artifacts in a claude.ai chat, see [What are artifacts and how do I use them?](https://support.claude.com/en/articles/17153992-what-are-artifacts-and-how-do-i-use-them) in the help center.
1010
1111## Leaving a comment
1212
claude-science/custom-connectors Changed · +1 / -1 lines
from line 6
66
77Remote servers that need login take you through the provider's sign-in page.
88
9On Team and Enterprise plans, you can add and use custom connectors only if your organization allows them. When it doesn't, the **Remote** and **Local command** options under **Add connector** are grayed with a note that custom connectors are disabled by your admin. Custom connectors you added earlier stay listed and grayed, Claude can't use them, and they work again if your organization turns custom connectors back on. See [Custom connectors](/docs/claude-science/admin-controls#custom-connectors) in the admin controls.
9On Team and Enterprise plans, you can add and use custom connectors only if your organization allows them. When it doesn't, the **Remote** and **Local command** options under **Add connector** are grayed with a note that custom connectors are disabled by your admin. Custom connectors you added earlier stay listed and grayed, Claude can't use them, and they work again if your organization turns custom connectors back on. See [Custom connectors](/docs/claude-science/admin-controls.md#custom-connectors) in the admin controls.
1010
1111Every tool from a custom connector starts as **Not set**, and Claude asks before using it. On the connector's page, set individual tools to **Always allow**, **Ask each time**, or **Block** under **Tools**, or turn on Skip approvals for the whole connector.
1212
claude-science/example-gallery/bio-drift Changed · +1 / -1 lines
from line 8
88
99## Prompt
1010
11Copy the prompt and paste it into a new session in [Claude Science](/docs/claude-science/overview). By default, Claude asks with a [permission card](/docs/claude-science/core-concepts#permission-cards) before it runs code or installs packages.
11Copy the prompt and paste it into a new session in [Claude Science](/docs/claude-science/overview.md). By default, Claude asks with a [permission card](/docs/claude-science/core-concepts.md#permission-cards) before it runs code or installs packages.
1212
1313```text Prompt wrap theme={null}
1414In a 1956 paper, Peter Buri described keeping 107 bottles of fruit flies for 19 generations, restarting each bottle every generation with 8 males and 8 females picked at random. Every founder carried one copy each of two neutral eye-color alleles, bw and bw75, so bw75 started at a frequency of 0.5 in every bottle.
claude-science/example-gallery/chem-titration Changed · +1 / -1 lines
from line 8
88
99## Prompt
1010
11Copy the prompt and paste it into a new session in [Claude Science](/docs/claude-science/overview). By default, Claude asks with a [permission card](/docs/claude-science/core-concepts#permission-cards) before it runs code or installs packages.
11Copy the prompt and paste it into a new session in [Claude Science](/docs/claude-science/overview.md). By default, Claude asks with a [permission card](/docs/claude-science/core-concepts.md#permission-cards) before it runs code or installs packages.
1212
1313```text Prompt wrap theme={null}
1414I'm titrating 25.0 mL of 0.100 M acetic acid (pKa 4.76) with 0.100 M NaOH. Compute the pH after each addition of base, from 0 to 50 mL, by solving the full equilibrium (mass balance, charge balance, Kw = 1.0 × 10⁻¹⁴) without the usual shortcuts (no Henderson–Hasselbalch, no 'x is small'), using concentrations, at 25 °C. Plot the titration curve and mark the starting point, the half-equivalence point and the equivalence point. Show that the acid alone sets the start, pH = pKa half-way, and acetate acting as a weak base sets the equivalence point.
claude-science/example-gallery/clin-km Changed · +1 / -1 lines
from line 8
88
99## Prompt
1010
11Copy the prompt and paste it into a new session in [Claude Science](/docs/claude-science/overview). By default, Claude asks with a [permission card](/docs/claude-science/core-concepts#permission-cards) before it runs code or installs packages.
11Copy the prompt and paste it into a new session in [Claude Science](/docs/claude-science/overview.md). By default, Claude asks with a [permission card](/docs/claude-science/core-concepts.md#permission-cards) before it runs code or installs packages.
1212
1313```text Prompt wrap theme={null}
1414In 1963 Freireich and colleagues published an early randomized, placebo-controlled trial of a chemotherapy drug: 42 patients under 20 with acute leukemia in remission got either 6-mercaptopurine (6-MP) or a placebo, and were followed until they relapsed or the trial was stopped, which happened early, once 6-MP was clearly ahead. These are the weeks each patient stayed in remission. A + means the patient was still in remission when the trial was stopped.
claude-science/example-gallery/cs-pagerank-tiny Changed · +1 / -1 lines
from line 8
88
99## Prompt
1010
11Copy the prompt and paste it into a new session in [Claude Science](/docs/claude-science/overview). By default, Claude asks with a [permission card](/docs/claude-science/core-concepts#permission-cards) before it runs code or installs packages.
11Copy the prompt and paste it into a new session in [Claude Science](/docs/claude-science/overview.md). By default, Claude asks with a [permission card](/docs/claude-science/core-concepts.md#permission-cards) before it runs code or installs packages.
1212
1313```text Prompt wrap theme={null}
1414PageRank is the idea that launched Google (Brin & Page, 1998): a page matters if pages that matter link to it. Here is a tiny web of 11 pages, A to K, where B→C means that page B links to page C:
claude-science/example-gallery/eng-beam Changed · +1 / -1 lines
from line 8
88
99## Prompt
1010
11Copy the prompt and paste it into a new session in [Claude Science](/docs/claude-science/overview). By default, Claude asks with a [permission card](/docs/claude-science/core-concepts#permission-cards) before it runs code or installs packages.
11Copy the prompt and paste it into a new session in [Claude Science](/docs/claude-science/overview.md). By default, Claude asks with a [permission card](/docs/claude-science/core-concepts.md#permission-cards) before it runs code or installs packages.
1212
1313```text Prompt wrap theme={null}
1414I'm learning the finite-element method. Model a steel ruler clamped at one end: length 300 mm, width 25 mm, thickness 3 mm, E = 200 GPa, density 7850 kg/m³. Split it into 4 standard 2-node beam elements (cubic shape functions, consistent mass matrix) and write the matrices yourself with numpy. First hang 1 N (about 100 g) on the free end: beam theory says the tip drops PL³/(3EI) = 0.800 mm. Check that you get it, and draw the bent ruler over the theory curve. Then let the ruler vibrate: plot its first 3 mode shapes, each labeled with its frequency. Theory gives 27.18, 170.33 and 476.93 Hz; finite-element frequencies land slightly above and get closer with more elements, so show that in a small table for 2, 4, 8 and 16 elements. Give each frequency to 2 decimals, and its error in % worked out from the unrounded frequencies. Explain each step as you would to an undergraduate.
claude-science/example-gallery/mat-xrd Changed · +1 / -1 lines
from line 8
88
99## Prompt
1010
11Copy the prompt and paste it into a new session in [Claude Science](/docs/claude-science/overview). By default, Claude asks with a [permission card](/docs/claude-science/core-concepts#permission-cards) before it runs code or installs packages.
11Copy the prompt and paste it into a new session in [Claude Science](/docs/claude-science/overview.md). By default, Claude asks with a [permission card](/docs/claude-science/core-concepts.md#permission-cards) before it runs code or installs packages.
1212
1313```text Prompt wrap theme={null}
1414X-ray diffraction is how we know where the atoms sit in a crystal. Simulate the powder diffraction patterns of silicon (diamond structure, a = 5.4311 Å) and rock salt (NaCl, a = 5.6402 Å) with pymatgen, for copper Kα₁ X-rays (wavelength="CuKa1", λ = 1.54056 Å) and angles 2θ up to 90°. Nothing needs downloading. Label every peak with its Miller indices hkl, and check each angle by hand with Bragg's law, λ = 2d sin θ, where d = a/√(h²+k²+l²). Both crystals share a face-centered cubic lattice, which allows 9 reflections in this range, yet silicon shows only 6: show that its 2-atom basis cancels 200, 222 and 420. In salt the all-odd peaks (111, 311, 331) are weak because Na and Cl scatter out of phase: show that too. Leave out other salts and what-ifs such as Na and Cl scattering equally, and round every number once, from its full-precision value. Put both patterns in 1 figure. Explain each step as you would to an undergraduate.
claude-science/example-gallery/math-ulam Changed · +1 / -1 lines
from line 8
88
99## Prompt
1010
11Copy the prompt and paste it into a new session in [Claude Science](/docs/claude-science/overview). By default, Claude asks with a [permission card](/docs/claude-science/core-concepts#permission-cards) before it runs code or installs packages.
11Copy the prompt and paste it into a new session in [Claude Science](/docs/claude-science/overview.md). By default, Claude asks with a [permission card](/docs/claude-science/core-concepts.md#permission-cards) before it runs code or installs packages.
1212
1313```text Prompt wrap theme={null}
1414In 1963 the mathematician Stanisław Ulam, doodling during a long and boring talk, wrote the whole numbers in a square spiral and circled the primes. Recreate his picture. Find all primes up to 40,401 (= 201 × 201) with a sieve of Eratosthenes, and check that 1,229 of them are below 10,000. Write 1, 2, 3, … in a square spiral starting from the center, and mark the primes.
claude-science/example-gallery/phys-doubleslit Changed · +1 / -1 lines
from line 8
88
99## Prompt
1010
11Copy the prompt and paste it into a new session in [Claude Science](/docs/claude-science/overview). By default, Claude asks with a [permission card](/docs/claude-science/core-concepts#permission-cards) before it runs code or installs packages.
11Copy the prompt and paste it into a new session in [Claude Science](/docs/claude-science/overview.md). By default, Claude asks with a [permission card](/docs/claude-science/core-concepts.md#permission-cards) before it runs code or installs packages.
1212
1313```text Prompt wrap theme={null}
1414In 1989 Akira Tonomura's team at Hitachi sent electrons one at a time past an electron biprism, the electron version of a double slit, and filmed an interference pattern building up dot by dot. Recreate that with an ideal double slit. Say nothing else about the 1989 experiment.