One read of Claude Documentationclaude-docs-20261023T180724Z
267 pages moved out of 280 read.
Pages moved
267
significant first
Pages read
280
in this capture
Captured
18:07 UTC
Corpus hash
307a31a7094a
corpus-hash
What this read moved
226-250 of 267, page 10 of 11This capture is too large to show at once. Changes 226-250 of 267 are below, significant first; the rest are on the following screens.
third-party/claude-desktop/installation Changed · +26 / -26 lines
from line 19
1919Check these on Windows devices before rollout:
2020
2121* **Log on as a service**: Cowork's virtual machine runs under an account in the built-in `NT VIRTUAL MACHINE\Virtual Machines` group, and that group needs the **Log on as a service** user right. If your organization assigns that right through Group Policy or MDM, see [Windows security policy blocks the Cowork workspace](#windows-security-policy-blocks-the-cowork-workspace).
22* **Hooks**: a [hook](https://code.claude.com/docs/en/hooks) command written for Bash needs Git for Windows on the device. If your Windows devices have hooks in plugins or in Claude Code managed settings, see [Hooks on Windows devices without Git for Windows](/docs/third-party/claude-desktop/extensions.md#hooks-on-windows-devices-without-git-for-windows).
22* **Hooks**: a [hook](https://code.claude.com/docs/en/hooks) command written for Bash needs Git for Windows on the device. If your Windows devices have hooks in plugins or in Claude Code managed settings, see [Hooks on Windows devices without Git for Windows](https://claude.com/docs/third-party/claude-desktop/extensions.md#hooks-on-windows-devices-without-git-for-windows).
2323
24With [Unified Claude](/docs/third-party/claude-desktop/unified-claude.md) on, a message sent from the home screen starts a Cowork session on a device that can run Cowork, and a Chat conversation on a device that can't.
24With [Unified Claude](https://claude.com/docs/third-party/claude-desktop/unified-claude.md) on, a message sent from the home screen starts a Cowork session on a device that can run Cowork, and a Chat conversation on a device that can't.
2525
2626## Check device readiness
2727
from line 63
6363
6464Choose an MDM profile when one configuration, or a few group-scoped profiles, covers your fleet and no device should depend on a sign-in to Anthropic. Most MDMs support role-based distribution, so per-group configuration doesn't require a bootstrap server.
6565
66Building the configuration in the app is optional. The [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration.md) can also export schema-only templates (an ADMX template for Windows, a Profile Manifest `.plist` for macOS) from its **Export** menu, so you can enter values directly in your management console instead. See [Export the profile](/docs/third-party/claude-desktop/mdm.md#2-export-the-profile) for all formats.
66Building the configuration in the app is optional. The [in-app configuration window](https://claude.com/docs/third-party/claude-desktop/in-app-configuration.md) can also export schema-only templates (an ADMX template for Windows, a Profile Manifest `.plist` for macOS) from its **Export** menu, so you can enter values directly in your management console instead. See [Export the profile](https://claude.com/docs/third-party/claude-desktop/mdm.md#2-export-the-profile) for all formats.
6767
6868Choose a bootstrap server when your organization doesn't use MDM, or when per-user credentials or frequently changing settings would make per-group profiles unwieldy. The tradeoff is that you operate the endpoint.
6969
70A device whose MDM profile or registry policy sets any key other than the [app-behavior keys](/docs/third-party/claude-desktop/mdm.md#update-keys-and-managed-precedence) uses that configuration, except as described under [Devices with a managed profile](/docs/third-party/claude-desktop/admin-console.md#devices-with-a-managed-profile). When a bootstrap response is in effect, it replaces MDM-delivered values wholesale, and a few device-level keys are only available via MDM (the keys labeled **MDM only** in the [configuration reference](/docs/third-party/claude-desktop/configuration.md)).
70A device whose MDM profile or registry policy sets any key other than the [app-behavior keys](https://claude.com/docs/third-party/claude-desktop/mdm.md#update-keys-and-managed-precedence) uses that configuration, except as described under [Devices with a managed profile](https://claude.com/docs/third-party/claude-desktop/admin-console.md#devices-with-a-managed-profile). When a bootstrap response is in effect, it replaces MDM-delivered values wholesale, and a few device-level keys are only available via MDM (the keys labeled **MDM only** in the [configuration reference](https://claude.com/docs/third-party/claude-desktop/configuration.md)).
7171
7272Pick your path:
7373
74* [Deploy with Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console.md) covers provisioning, configuring the app in the console, and onboarding users.
75* [Deploy with MDM](/docs/third-party/claude-desktop/mdm.md) covers authoring the configuration in the app, exporting the profile, and deploying it to your fleet.
76* [Deploy with a bootstrap server](/docs/third-party/claude-desktop/bootstrap.md) covers getting the bootstrap keys onto devices and running the server.
74* [Deploy with Enterprise Admin Console](https://claude.com/docs/third-party/claude-desktop/admin-console.md) covers provisioning, configuring the app in the console, and onboarding users.
75* [Deploy with MDM](https://claude.com/docs/third-party/claude-desktop/mdm.md) covers authoring the configuration in the app, exporting the profile, and deploying it to your fleet.
76* [Deploy with a bootstrap server](https://claude.com/docs/third-party/claude-desktop/bootstrap.md) covers getting the bootstrap keys onto devices and running the server.
7777
7878On the MDM and bootstrap paths, deploy the configuration before the app so users open Claude for the first time and land directly in the third-party deployment. With the Enterprise Admin Console, save a configuration in the console first, and users then install the app and sign in.
7979
from line 82
8282For evaluating before a fleet rollout, for pilots, or for organizations that don't use MDM, a single machine can be configured directly in the app.
8383
84841. Install Claude Desktop from [claude.com/download](https://claude.com/download).
852. Launch the app. **Do not sign in or create an Anthropic account.** 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 [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration.md).
852. Launch the app. **Do not sign in or create an Anthropic account.** 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 [in-app configuration window](https://claude.com/docs/third-party/claude-desktop/in-app-configuration.md).
86863. Enter the provider, endpoint, and credential values supplied by your administrator.
87874. Click **Apply Changes**, then click **Save & Restart**. The app relaunches and the sign-in screen now offers the option to start in Claude Desktop on 3P using the configuration you entered.
8888
8989The configuration is written to the application's local config file and applies only to that device and user account. It can be edited from the same window at any time. To return to standard Claude Desktop, choose the Anthropic sign-in option on the sign-in screen instead.
9090
91If your organization runs a [bootstrap server](/docs/third-party/claude-desktop/bootstrap.md) but doesn't use MDM, your administrator can instead supply a small configuration file containing only the bootstrap keys. Load it with **Import configuration** in the same window; the bootstrap server supplies everything else after you sign in.
91If your organization runs a [bootstrap server](https://claude.com/docs/third-party/claude-desktop/bootstrap.md) but doesn't use MDM, your administrator can instead supply a small configuration file containing only the bootstrap keys. Load it with **Import configuration** in the same window; the bootstrap server supplies everything else after you sign in.
9292
9393When the configuration works on a single machine, roll it out to the fleet with the [delivery model you chose](#choose-a-configuration-delivery-model); on the MDM path, you can export the tested configuration as the profile you deploy.
9494
from line 96
9696
9797On any configured device, open Claude Desktop, go to **Help → Troubleshooting → Generate Diagnostic Report**, and click **Export to file**. In the saved `.zip` file, `managed-config.txt` shows where the configuration was read from and each key's configured or default value, with secret values redacted and anything it could not parse listed under `Parse errors`. `provider-status.txt` shows whether the provider settings are complete and valid, and `deployment-mode.txt` shows whether the app is running in third-party mode.
9898
99Also confirm that the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration.md) (**Developer → Configure Third-Party Inference…**) opens read-only on a managed device. The app reads managed keys from the profile by name and silently ignores a misspelled key rather than reporting an error. On macOS, a window that is still editable means no recognized key reached the app, even if your MDM shows the profile as delivered. On Windows, even a misspelled value under `HKLM\SOFTWARE\Policies\Claude` counts as machine policy and locks the window, so compare each key's value in `managed-config.txt` with the value you set. If your profile deliberately sets [only app-behavior keys](/docs/third-party/claude-desktop/mdm.md#update-keys-and-managed-precedence) (the update, relaunch window, configuration re-check, or network proxy keys), an editable window is expected.
99Also confirm that the [in-app configuration window](https://claude.com/docs/third-party/claude-desktop/in-app-configuration.md) (**Developer → Configure Third-Party Inference…**) opens read-only on a managed device. The app reads managed keys from the profile by name and silently ignores a misspelled key rather than reporting an error. On macOS, a window that is still editable means no recognized key reached the app, even if your MDM shows the profile as delivered. On Windows, even a misspelled value under `HKLM\SOFTWARE\Policies\Claude` counts as machine policy and locks the window, so compare each key's value in `managed-config.txt` with the value you set. If your profile deliberately sets [only app-behavior keys](https://claude.com/docs/third-party/claude-desktop/mdm.md#update-keys-and-managed-precedence) (the update, relaunch window, configuration re-check, or network proxy keys), an editable window is expected.
100100
101101If the app shows the standard claude.ai sign-in screen instead of Cowork, the configuration was not read. Common causes:
102102
from line 105
105105* The configuration was written to the local config file but you're checking the managed location (or vice versa)
106106* On Windows (v1.19367.0 and later), the configuration is in `HKCU\SOFTWARE\Policies\Claude` but machine policy is also present: any `REG_SZ`, `REG_EXPAND_SZ`, or `REG_DWORD` value directly under `HKLM\SOFTWARE\Policies\Claude` causes the app to ignore user policy entirely. In the diagnostic report (**Help → Troubleshooting → Generate Diagnostic Report**, then **Export to file**), `managed-config.txt` shows each key's configured or default value and lists under `Parse errors` any machine-policy values it could not use. A `REG_EXPAND_SZ` value shows as present in `reg query` output while the app reports the managed configuration as invalid or absent, because the app counts the value as machine policy but cannot read its contents
107107
108If the app shows a configuration error instead, it read the configuration but can't use it. For example, a required key for the chosen provider is missing or invalid, or a macOS configuration profile, Windows policy under `HKLM`, or the root-owned policy file on Linux sets [`inferenceProvider`](/docs/third-party/claude-desktop/configuration#inferenceprovider) to a value the app doesn't recognize. Check **Help → Troubleshooting** or the application log at `~/Library/Logs/Claude-3p/main.log` (macOS) / `%LOCALAPPDATA%\Claude-3p\Logs\main.log` (Windows).
108If the app shows a configuration error instead, it read the configuration but can't use it. For example, a required key for the chosen provider is missing or invalid, or a macOS configuration profile, Windows policy under `HKLM`, or the root-owned policy file on Linux sets [`inferenceProvider`](https://claude.com/docs/third-party/claude-desktop/configuration#inferenceprovider) to a value the app doesn't recognize. Check **Help → Troubleshooting** or the application log at `~/Library/Logs/Claude-3p/main.log` (macOS) / `%LOCALAPPDATA%\Claude-3p\Logs\main.log` (Windows).
109109
110110## Troubleshooting
111111
from line 119
119119
120120Restarting the app tries the download again, which is enough when an earlier attempt was only interrupted. When the same message returns on every attempt, the usual cause is a proxy, secure web gateway, or web filter between the device and `downloads.claude.ai`. Such equipment can block the app's requests, cut off the transfer partway (the workspace bundle is more than 1 GB), or return its own page in place of the file. Less often, security software on the device locks or quarantines the downloaded files.
121121
122* Allow Claude Desktop itself, not only browsers, to reach `downloads.claude.ai`, as listed under [Required egress paths](/docs/third-party/claude-desktop/telemetry.md#required-egress-paths). The download follows the app's proxy settings, described under [Network proxy](/docs/third-party/claude-desktop/network-proxy.md).
122* Allow Claude Desktop itself, not only browsers, to reach `downloads.claude.ai`, as listed under [Required egress paths](https://claude.com/docs/third-party/claude-desktop/telemetry.md#required-egress-paths). The download follows the app's proxy settings, described under [Network proxy](https://claude.com/docs/third-party/claude-desktop/network-proxy.md).
123123* If a proxy or secure web gateway inspects this traffic, make sure files from `downloads.claude.ai` reach the device complete and unchanged.
124124* On a network that cannot allow these downloads, deploy the [offline installer](#offline-installation), which includes both components.
125125
from line 127
127127
128128### Windows security policy blocks the Cowork workspace
129129
130On Windows, the app shows **A Windows security policy is blocking Claude's workspace** when a user-rights policy stops the virtual machine that Cowork runs in from starting. Cowork tasks don't start on that device, and [advanced file analysis](/docs/third-party/claude-desktop/chat.md#advanced-file-analysis) in Chat, which uses the same virtual machine, fails too. The banner's **Copy details** button copies a description of the error that includes the code `0x80070569`. Standard (non-3P) installs show this banner too.
130On Windows, the app shows **A Windows security policy is blocking Claude's workspace** when a user-rights policy stops the virtual machine that Cowork runs in from starting. Cowork tasks don't start on that device, and [advanced file analysis](https://claude.com/docs/third-party/claude-desktop/chat.md#advanced-file-analysis) in Chat, which uses the same virtual machine, fails too. The banner's **Copy details** button copies a description of the error that includes the code `0x80070569`. Standard (non-3P) installs show this banner too.
131131
132132The virtual machine runs under an account in the built-in `NT VIRTUAL MACHINE\Virtual Machines` group (SID `S-1-5-83-0`), and that group needs the **Log on as a service** user right. Microsoft's [Starting or live migrating Hyper-V VMs fails](https://learn.microsoft.com/en-us/troubleshoot/windows-server/virtualization/starting-or-live-migrating-hyper-v-vms-fails) describes the same error for Hyper-V virtual machines when the group is missing that right. A Group Policy that defines **Log on as a service** replaces the list of accounts on each device instead of adding to it. When the policy's list leaves this group out, or a policy lists the group under **Deny log on as a service**, the virtual machine can't start.
133133
from line 200
200200
201201Download the installer from a connected machine and bring it across your boundary with your usual software-distribution process.
202202
203Pair the offline installer with [`disableAutoUpdates`](/docs/third-party/claude-desktop/configuration#disableautoupdates). The app cannot reach the update feed from an air-gapped network, and you update the fleet by distributing each new offline installer through your MDM. Also set [`modelCatalogEnabled`](/docs/third-party/claude-desktop/configuration#modelcatalogenabled) to `false`, or point [`modelCatalogUrl`](/docs/third-party/claude-desktop/configuration#modelcatalogurl) at a mirror inside your network. Otherwise the app tries to fetch the signed model catalog from `downloads.claude.ai` at launch and every 5 to 15 minutes after that, and while those requests fail the model picker keeps the names and effort options that ship with the app. With updates and the catalog fetch handled this way, the only egress an air-gapped deployment needs is your inference provider; see [Telemetry and egress](/docs/third-party/claude-desktop/telemetry.md#required-egress-paths).
203Pair the offline installer with [`disableAutoUpdates`](https://claude.com/docs/third-party/claude-desktop/configuration#disableautoupdates). The app cannot reach the update feed from an air-gapped network, and you update the fleet by distributing each new offline installer through your MDM. Also set [`modelCatalogEnabled`](https://claude.com/docs/third-party/claude-desktop/configuration#modelcatalogenabled) to `false`, or point [`modelCatalogUrl`](https://claude.com/docs/third-party/claude-desktop/configuration#modelcatalogurl) at a mirror inside your network. Otherwise the app tries to fetch the signed model catalog from `downloads.claude.ai` at launch and every 5 to 15 minutes after that, and while those requests fail the model picker keeps the names and effort options that ship with the app. With updates and the catalog fetch handled this way, the only egress an air-gapped deployment needs is your inference provider; see [Telemetry and egress](https://claude.com/docs/third-party/claude-desktop/telemetry.md#required-egress-paths).
204204
205205## Updates
206206
from line 209
209209In 3P deployments you can:
210210
211211* **Leave auto-update enabled** (recommended) so fixes reach users without IT intervention. Set `autoUpdaterEnforcementHours` to shorten the enforcement window (1 to 72 hours; values above 72 are rejected). Setting the key also makes the window strict: the restart fires as soon as the window elapses, without waiting for a pause in user activity.
212* **Switch to a slower release channel** by setting [`releaseChannel`](/docs/third-party/claude-desktop/configuration#releasechannel) to `staggered`. Devices on the default release channel, `stable`, take each release as it rolls out. Devices on `staggered` typically trail `stable` by 7-14 days. Usually once a week, Anthropic marks a tested release from `stable` as the new `staggered` release. Urgent fixes may be released sooner. Features and fixes, including security fixes, reach `staggered` devices later.
212* **Switch to a slower release channel** by setting [`releaseChannel`](https://claude.com/docs/third-party/claude-desktop/configuration#releasechannel) to `staggered`. Devices on the default release channel, `stable`, take each release as it rolls out. Devices on `staggered` typically trail `stable` by 7-14 days. Usually once a week, Anthropic marks a tested release from `stable` as the new `staggered` release. Urgent fixes may be released sooner. Features and fixes, including security fixes, reach `staggered` devices later.
213213* **Disable auto-update** (`disableAutoUpdates`) and redistribute new builds through your MDM on your own cadence. This is required for [air-gapped environments](#offline-installation) but means your IT team owns the update pipeline. To move open apps to each version you install, see [Restart open apps after you install a new version](#restart-open-apps-after-you-install-a-new-version).
214214
215215> [!WARNING]
from line 218
218218
219219Set `releaseChannel` in:
220220
221* **An MDM profile that sets only [app-behavior keys](/docs/third-party/claude-desktop/mdm.md#update-keys-and-managed-precedence)**: put the key in that profile, even if the device also has a bootstrap server or the admin console
222* **A [bootstrap server](/docs/third-party/claude-desktop/bootstrap.md)**: return the key from the server
223* **The [admin console](/docs/third-party/claude-desktop/admin-console.md)**: open **Organization settings**, go to the **Telemetry & updates** page, and set the **Release channel**
221* **An MDM profile that sets only [app-behavior keys](https://claude.com/docs/third-party/claude-desktop/mdm.md#update-keys-and-managed-precedence)**: put the key in that profile, even if the device also has a bootstrap server or the admin console
222* **A [bootstrap server](https://claude.com/docs/third-party/claude-desktop/bootstrap.md)**: return the key from the server
223* **The [admin console](https://claude.com/docs/third-party/claude-desktop/admin-console.md)**: open **Organization settings**, go to the **Telemetry & updates** page, and set the **Release channel**
224224* **Any other configuration, with no bootstrap server and no admin console**, such as an MDM profile that sets the inference provider: put the key with the rest of that configuration
225225
226`releaseChannel` has no effect on Linux, which [updates through apt](/docs/third-party/claude-desktop/telemetry.md#auto-updates), or on installs from the Microsoft Store.
226`releaseChannel` has no effect on Linux, which [updates through apt](https://claude.com/docs/third-party/claude-desktop/telemetry.md#auto-updates), or on installs from the Microsoft Store.
227227
228228App versions from before `releaseChannel` existed may reject a Windows or Linux machine policy that names it, and then turn off local settings.
229229
230See [Telemetry and egress](/docs/third-party/claude-desktop/telemetry.md) for the network paths the updater uses.
230See [Telemetry and egress](https://claude.com/docs/third-party/claude-desktop/telemetry.md) for the network paths the updater uses.
231231
232232### Restart open apps after you install a new version
233233
234When you set [`disableAutoUpdates`](/docs/third-party/claude-desktop/configuration#disableautoupdates) and install new versions with your own tools, an install can land while Claude Desktop is open. The open app finds the newer version on the device and shows **Relaunch to update** in the sidebar. Clicking **Relaunch to update** moves the person to the newer version.
234When you set [`disableAutoUpdates`](https://claude.com/docs/third-party/claude-desktop/configuration#disableautoupdates) and install new versions with your own tools, an install can land while Claude Desktop is open. The open app finds the newer version on the device and shows **Relaunch to update** in the sidebar. Clicking **Relaunch to update** moves the person to the newer version.
235235
236236On Windows, the app shows **Relaunch to update** for installs from the `.msix` package. Clicking it closes Claude Desktop, and Windows may then open the newer version. If Claude Desktop stays closed, open it again to get the newer version. Quitting and reopening Claude Desktop without the click can start the earlier version again, while signing out of Windows and back in moves the person to the newer version.
237237
238238You can also have Claude Desktop restart itself when nobody clicks. Two keys control the restart:
239239
240* [`installedUpdateEnforcementEnabled`](/docs/third-party/claude-desktop/configuration#installedupdateenforcementenabled): set it to `true` to turn on the restart, which is off by default
241* [`installedUpdateEnforcementHours`](/docs/third-party/claude-desktop/configuration#installedupdateenforcementhours): how long the app waits after it finds the newer version. With a number from 1 to 72, the app restarts when those hours end, even while someone is using the computer. With the key unset, the app waits 72 hours and then until the computer has been idle for 10 minutes.
240* [`installedUpdateEnforcementEnabled`](https://claude.com/docs/third-party/claude-desktop/configuration#installedupdateenforcementenabled): set it to `true` to turn on the restart, which is off by default
241* [`installedUpdateEnforcementHours`](https://claude.com/docs/third-party/claude-desktop/configuration#installedupdateenforcementhours): how long the app waits after it finds the newer version. With a number from 1 to 72, the app restarts when those hours end, even while someone is using the computer. With the key unset, the app waits 72 hours and then until the computer has been idle for 10 minutes.
242242
243243The hours count only while the app is open and the computer is awake, and they start again from zero each time the app starts. The restart also waits while Claude is working on a task, except a task on an SSH host that the app expects to pick up again afterward.
244244
from line 248
248248* **Windows can refuse the switch**: Claude Desktop comes back on the version it had and shows **Relaunch to update** again. It doesn't try again by itself until Claude Desktop next starts, such as after someone quits and reopens it, or until you install a newer version.
249249* **Other people use the same computer**: the switch can end the Cowork tasks of anyone else signed in to it, and the newest version on the device can be one that was installed for someone else.
250250
251Set the restart keys in the same place as `disableAutoUpdates`, such as the same MDM profile or configuration file. If an MDM profile sets only the restart keys, devices ignore a `disableAutoUpdates` value from any other source, such as a configuration file or a bootstrap server. See [Update keys and managed precedence](/docs/third-party/claude-desktop/mdm.md#update-keys-and-managed-precedence).
251Set the restart keys in the same place as `disableAutoUpdates`, such as the same MDM profile or configuration file. If an MDM profile sets only the restart keys, devices ignore a `disableAutoUpdates` value from any other source, such as a configuration file or a bootstrap server. See [Update keys and managed precedence](https://claude.com/docs/third-party/claude-desktop/mdm.md#update-keys-and-managed-precedence).
252252
253253> [!NOTE]
254254>
255> Add the restart keys after your devices have a version that supports them. An earlier version can show people a configuration warning at every launch, or reject the managed configuration that holds the keys and ignore the device's own configuration too. For what each platform does with a key it doesn't know, see [`installedUpdateEnforcementEnabled`](/docs/third-party/claude-desktop/configuration#installedupdateenforcementenabled).
255> Add the restart keys after your devices have a version that supports them. An earlier version can show people a configuration warning at every launch, or reject the managed configuration that holds the keys and ignore the device's own configuration too. For what each platform does with a key it doesn't know, see [`installedUpdateEnforcementEnabled`](https://claude.com/docs/third-party/claude-desktop/configuration#installedupdateenforcementenabled).
256256
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.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.
17If your organization manages Claude Desktop on 3P from the [Enterprise Admin Console for Desktop 3P](https://claude.com/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.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.
29See the [Overview](https://claude.com/docs/third-party/claude-desktop/overview.md) for the architecture and [Data handling by provider](https://claude.com/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.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.
33For HIPAA, see [HIPAA](https://claude.com/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.md). See [Telemetry and egress](/docs/third-party/claude-desktop/telemetry.md) 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](https://claude.com/docs/third-party/claude-desktop/admin-console.md). See [Telemetry and egress](https://claude.com/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.md#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](https://claude.com/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.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.
5Like [Cowork](https://claude.com/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.md) covers where the managed configuration lives on each platform and how to deploy it.
11Set [`allowedWorkspaceFolders`](https://claude.com/docs/third-party/claude-desktop/configuration#allowedworkspacefolders) in the managed configuration to restrict which paths users may attach as workspace folders. The [Configuration reference](https://claude.com/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.md#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](https://claude.com/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.md#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](https://claude.com/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.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`.
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](https://claude.com/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`](https://claude.com/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.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.
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](https://claude.com/docs/third-party/claude-desktop/installation.md#check-device-readiness) verifies. Install the macOS or Windows package (see [System requirements](https://claude.com/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 · +9 / -9 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.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.
5Amazon Bedrock Mantle is Amazon Bedrock's Anthropic-native API surface. Unlike the standard [Amazon Bedrock provider](https://claude.com/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.md) 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](https://claude.com/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.md#inferencecredentialhelper) (`inferenceCredentialHelper`) | An executable that prints the bearer token to stdout at runtime. |
14| Token must not be stored statically | [Credential helper](https://claude.com/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.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.
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](https://claude.com/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.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:
30Open the [in-app configuration window](https://claude.com/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.md) 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](https://claude.com/docs/third-party/claude-desktop/mdm.md) for the export and deployment workflow.
4343
4444### Configuration keys
4545
4646Mantle reuses the `inferenceBedrock*` key names. Only `inferenceBedrockRegion`, `inferenceBedrockBearerToken`, and `inferenceBedrockBaseUrl` apply; the other keys below (`inferenceBedrockProfile`, `inferenceBedrockSso*`, `inferenceBedrockAwsDir`, `inferenceBedrockAwsCliPath`, `inferenceBedrockServiceTier`) are ignored for this provider.
4747
48[Entry labels](/docs/third-party/claude-desktop/configuration.md#entry-labels) says what each label means.
48[Entry labels](https://claude.com/docs/third-party/claude-desktop/configuration.md#entry-labels) says what each label means.
4949
5050#### `inferenceBedrockRegion`
5151
from line 175
175175
176176***
177177
178You 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).
178You must also set `inferenceModels`. As with the standard Amazon Bedrock provider, server-side Web Search is not supported. See the [Configuration reference](https://claude.com/docs/third-party/claude-desktop/configuration.md#inferencemodels).
179179
180180## What users experience
181181
from line 183
183183
184184## Troubleshoot
185185
186To 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).
186To 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](https://claude.com/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](https://claude.com/docs/third-party/claude-desktop/data-storage.md#where-data-lives).
187187
third-party/claude-desktop/mcp-sign-in Changed · +7 / -7 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.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.
5For a remote [managed MCP server](https://claude.com/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.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).
7This page is for administrators who add servers on the **Connectors** page of the [Enterprise Admin Console](https://claude.com/docs/third-party/claude-desktop/admin-console.md). The [in-app configuration window](https://claude.com/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`](https://claude.com/docs/third-party/claude-desktop/configuration#managedmcpservers) entry. For the redirect URI, discovery, and token handling in detail, see [OAuth sign-in](https://claude.com/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.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`.
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](https://claude.com/docs/third-party/claude-desktop/admin-console.md#when-a-helper-script-is-the-right-choice), and see [Connect to Box](https://claude.com/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
3333## OAuth fields
3434
35These fields appear when **OAuth** is set to **Bring your own client**. The [`managedMcpServers` reference](/docs/third-party/claude-desktop/configuration#managedmcpservers) lists every `oauth` key and its minimum Claude Desktop version.
35These fields appear when **OAuth** is set to **Bring your own client**. The [`managedMcpServers` reference](https://claude.com/docs/third-party/claude-desktop/configuration#managedmcpservers) lists every `oauth` key and its minimum Claude Desktop version.
3636
3737| Field | When to set | What to enter |
3838| - | - | - |
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.md) | **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](https://claude.com/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.md#where-data-lives) on the user's device.
62These messages appear in Claude Desktop, or in `main.log` in the [logs directory](https://claude.com/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.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).
72[Connect to Google Cloud](https://claude.com/docs/third-party/claude-desktop/connectors-google-cloud.md) and [Connect to Box](https://claude.com/docs/third-party/claude-desktop/connectors-box.md) walk through two servers that need a client you register and its secret. [Connect to GitHub](https://claude.com/docs/third-party/claude-desktop/connectors-github.md) and [Connect to Microsoft 365](https://claude.com/docs/third-party/claude-desktop/connectors-m365.md) cover those connectors end to end, including the [built-in servers](https://claude.com/docs/third-party/claude-desktop/built-in-connectors.md) that run inside the app. [Connect to Salesforce](https://claude.com/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](https://claude.com/docs/third-party/claude-desktop/admin-console.md#plugin-marketplaces).
7373
third-party/claude-desktop/mdm Changed · +16 / -16 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.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.
7Before you start, install Claude Desktop on an admin workstation; see [Installation and setup](https://claude.com/docs/third-party/claude-desktop/installation.md). If you deliver configuration from a [bootstrap server](https://claude.com/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.md) on their own device.
15An admin builds and tests a working configuration in the [in-app configuration window](https://claude.com/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.md), 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](https://claude.com/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 The enforcement window for downloaded updates, or the restart for versions you install yourself 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.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 |
43| **Plugins** | [Plugin marketplaces](https://claude.com/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.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 |
45| **Source** | The bootstrap keys, if you are using the [bootstrap server](https://claude.com/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.md#enabling-unified-claude), set `desktopHome` to `standard` in your MDM profile.
47To turn on [Unified Claude](https://claude.com/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.md).
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](https://claude.com/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.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.
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](https://claude.com/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`](https://claude.com/docs/third-party/claude-desktop/configuration#modelcatalogenabled) is `false` or [`modelCatalogUrl`](https://claude.com/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.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.
96Open these hosts on your perimeter firewall before rolling out to devices. See [Telemetry and egress](https://claude.com/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.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).
132A user who signs in to any organization that uses the [Enterprise Admin Console](https://claude.com/docs/third-party/claude-desktop/admin-console.md) can move the device to that organization's configuration. To prevent that, set [`disableDeploymentModeChooser`](https://claude.com/docs/third-party/claude-desktop/configuration#disabledeploymentmodechooser) to `true`, as described under [Keep a device on its managed profile](https://claude.com/docs/third-party/claude-desktop/admin-console.md#keep-a-device-on-its-managed-profile).
133133
134134### Update keys and managed precedence
135135
136136A small group of **app-behavior keys** is treated specially, so you can set an update policy, a restart window, or a network proxy from MDM without managing the whole configuration:
137137
138* The update keys `disableAutoUpdates`, `autoUpdaterEnforcementHours`, `installedUpdateEnforcementEnabled`, `installedUpdateEnforcementHours`, `updateViaUpdatesHost`, and [`releaseChannel`](/docs/third-party/claude-desktop/configuration#releasechannel).
139* 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.md#pin-a-proxy-from-managed-configuration).
138* The update keys `disableAutoUpdates`, `autoUpdaterEnforcementHours`, `installedUpdateEnforcementEnabled`, `installedUpdateEnforcementHours`, `updateViaUpdatesHost`, and [`releaseChannel`](https://claude.com/docs/third-party/claude-desktop/configuration#releasechannel).
139* The configuration lifecycle keys [`relaunchEnforcementHours`](https://claude.com/docs/third-party/claude-desktop/configuration#relaunchenforcementhours) and [`configRecheckIntervalMinutes`](https://claude.com/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](https://claude.com/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
144If the managed profile sets any other recognized key, the normal rule above applies and the whole configuration is managed. For a profile that also sets `bootstrapUrl`, see [Which configuration source applies on a device](/docs/third-party/claude-desktop/configuration-format.md#which-configuration-source-applies-on-a-device).
144If the managed profile sets any other recognized key, the normal rule above applies and the whole configuration is managed. For a profile that also sets `bootstrapUrl`, see [Which configuration source applies on a device](https://claude.com/docs/third-party/claude-desktop/configuration-format.md#which-configuration-source-applies-on-a-device).
145145
146146## 5. Distribute the app
147147
from line 149
149149
150150## 6. Deploy organization plugins (optional)
151151
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.
152If you're distributing [organization plugins](https://claude.com/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.md#verifying-the-deployment).
156After deployment, confirm devices picked up the configuration with the checks in [Verifying the deployment](https://claude.com/docs/third-party/claude-desktop/installation.md#verifying-the-deployment).
157157
third-party/claude-desktop/models Changed · +12 / -12 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.md). The [configuration reference](/docs/third-party/claude-desktop/configuration.md#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](https://claude.com/docs/third-party/claude-desktop/in-app-configuration.md). The [configuration reference](https://claude.com/docs/third-party/claude-desktop/configuration.md#models) lists every field.
66
77## Model list and default model
88
9[`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).
9[`inferenceModels`](https://claude.com/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.md#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](https://claude.com/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.md#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`](https://claude.com/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](https://claude.com/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.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.
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](https://claude.com/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 29
2929
3030### Per-model effort cap
3131
32[`maxEffort`](/docs/third-party/claude-desktop/configuration#inferencemodels) on an `inferenceModels` entry sets the highest effort level Claude Desktop offers for that model in Chat, Cowork, and Code. Set it to `low`, `medium`, `high`, `xhigh`, or `max`. The picker shows `xhigh` as **Extra**. The **Effort** control doesn't offer levels above the cap.
32[`maxEffort`](https://claude.com/docs/third-party/claude-desktop/configuration#inferencemodels) on an `inferenceModels` entry sets the highest effort level Claude Desktop offers for that model in Chat, Cowork, and Code. Set it to `low`, `medium`, `high`, `xhigh`, or `max`. The picker shows `xhigh` as **Extra**. The **Effort** control doesn't offer levels above the cap.
3333
3434In Code sessions, the cap also limits Claude Code's own effort settings, such as a `CLAUDE_CODE_EFFORT_LEVEL` environment variable or the `/effort` command. If a model's recommended level is above its cap, the model starts at the cap. If Claude Desktop doesn't recognize the `maxEffort` value, it caps the model at low.
3535
3636### Starting effort level for the default model
3737
38[`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.
38[`defaultModelEffort`](https://claude.com/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.md#modeldiscoveryenabled) fills the picker instead of an `inferenceModels` list.
40`defaultModelEffort` also applies when [model discovery](https://claude.com/docs/third-party/claude-desktop/configuration.md#modeldiscoveryenabled) fills the picker instead of an `inferenceModels` list.
4141
4242### Models without an Effort control
4343
44Some model IDs, such as a gateway routing alias, don't name a specific Claude model. For such a model, the picker shows no **Effort** control, so users can't change its effort level. Its conversations and sessions never run above the `maxEffort` on its entry. When such a model is the default model, its conversations and sessions run at [`defaultModelEffort`](/docs/third-party/claude-desktop/configuration#defaultmodeleffort), up to that cap. With only `maxEffort` set, they run at that cap.
44Some model IDs, such as a gateway routing alias, don't name a specific Claude model. For such a model, the picker shows no **Effort** control, so users can't change its effort level. Its conversations and sessions never run above the `maxEffort` on its entry. When such a model is the default model, its conversations and sessions run at [`defaultModelEffort`](https://claude.com/docs/third-party/claude-desktop/configuration#defaultmodeleffort), up to that cap. With only `maxEffort` set, they run at that cap.
4545
4646## Start every conversation on the default model
4747
48Set [`alwaysStartWithDefaultModel`](/docs/third-party/claude-desktop/configuration#alwaysstartwithdefaultmodel) to `true` to start every new Chat conversation, Cowork session, and Code session on the [default model](#model-list-and-default-model) at its [starting effort level](#effort-levels), not on the user's last choice. When the user picks a model or effort level, it applies only for that conversation or session.
48Set [`alwaysStartWithDefaultModel`](https://claude.com/docs/third-party/claude-desktop/configuration#alwaysstartwithdefaultmodel) to `true` to start every new Chat conversation, Cowork session, and Code session on the [default model](#model-list-and-default-model) at its [starting effort level](#effort-levels), not on the user's last choice. When the user picks a model or effort level, it applies only for that conversation or session.
4949
5050If you leave `alwaysStartWithDefaultModel` unset, the default model and its starting effort level apply until a user picks a different model or effort level. Claude Desktop remembers that choice and starts the user's new conversations and sessions from it.
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.md#modeldiscoveryenabled) fills the picker instead of an `inferenceModels` list.
54`alwaysStartWithDefaultModel` also applies when [model discovery](https://claude.com/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.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-format.md#value-types) section describes.
75The example is plain JSON, which is the form a [bootstrap server](https://claude.com/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](https://claude.com/docs/third-party/claude-desktop/configuration-format.md#value-types) section describes.
7676
third-party/claude-desktop/move-to-claude-enterprise Changed · +7 / -7 lines
from line 43
4343
4444Special cases:
4545
46* If Cowork runs only in its VM sandbox in your organization (for example, because [`requireCoworkFullVmSandbox`](/docs/third-party/claude-desktop/configuration#requirecoworkfullvmsandbox) is enforced), nothing is migrated. Ask your Anthropic account team.
46* If Cowork runs only in its VM sandbox in your organization (for example, because [`requireCoworkFullVmSandbox`](https://claude.com/docs/third-party/claude-desktop/configuration#requirecoworkfullvmsandbox) is enforced), nothing is migrated. Ask your Anthropic account team.
4747* If your organization needs HIPAA, make it HIPAA-ready before users first sign in. A HIPAA-ready organization migrates no skills, local MCP servers, extensions, plugins, plugin marketplaces, or instructions.
4848* With the MSIX install on Windows 10 Enterprise LTSC 2021, or Windows 10 older than 21H1, update Claude in place. Uninstalling or resetting it deletes the Claude (third-party) data.
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.md) 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](https://claude.com/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.md#managedmcpservers): add them as connectors. The Microsoft 365 connector keeps working.
56* Remote [managed MCP servers](https://claude.com/docs/third-party/claude-desktop/configuration.md#managedmcpservers): add them as connectors. The Microsoft 365 connector keeps working.
5757
58Telemetry 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.
58Telemetry 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`](https://claude.com/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.md) 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](https://claude.com/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.md), 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`](https://claude.com/docs/third-party/claude-desktop/configuration#disabledeploymentmodechooser) and [`deploymentOrganizationUuid`](https://claude.com/docs/third-party/claude-desktop/configuration#deploymentorganizationuuid). Leave other keys in place. If your settings come from a [bootstrap server](https://claude.com/docs/third-party/claude-desktop/bootstrap.md), copy the keys you want to keep into the policy or profile itself.
6767
68The desktop extensions feature is on after the change unless [`isDesktopExtensionEnabled`](/docs/third-party/claude-desktop/configuration#isdesktopextensionenabled) is set to `false`.
68The desktop extensions feature is on after the change unless [`isDesktopExtensionEnabled`](https://claude.com/docs/third-party/claude-desktop/configuration#isdesktopextensionenabled) is set to `false`.
6969
7070**2. Set your organization ID**
7171
third-party/claude-desktop/network-proxy Changed · +17 / -17 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.md) on, a Cowork session started from the home screen runs its commands in Cowork's sandboxed shell.
13With [Unified Claude](https://claude.com/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.md#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](https://claude.com/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. On Windows it is a `REG_SZ` value named `egressProxyUrl` under `HKLM\SOFTWARE\Policies\Claude`, or under `HKCU\SOFTWARE\Policies\Claude` if the rest of your registry policy is there. The app [ignores `HKCU` policy when machine policy is present](/docs/third-party/claude-desktop/mdm#4-deploy-the-configuration). See [Value types](/docs/third-party/claude-desktop/configuration-format.md#value-types) and [Deploy with MDM](/docs/third-party/claude-desktop/mdm.md) 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. On Windows it is a `REG_SZ` value named `egressProxyUrl` under `HKLM\SOFTWARE\Policies\Claude`, or under `HKCU\SOFTWARE\Policies\Claude` if the rest of your registry policy is there. The app [ignores `HKCU` policy when machine policy is present](https://claude.com/docs/third-party/claude-desktop/mdm#4-deploy-the-configuration). See [Value types](https://claude.com/docs/third-party/claude-desktop/configuration-format.md#value-types) and [Deploy with MDM](https://claude.com/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.md) | None from the device; the remote host's own network route applies |
89| The agent in an [SSH remote Code session](https://claude.com/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 96
9696
9797Some traffic never uses the pinned key or the proxy the app resolved, and it is worth being explicit about each case and what you can do about it.
9898
99* **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.
100* **Commands in Cowork's sandboxed shell.** No proxy settings reach the Cowork sandbox on Linux, so `curl`, `pip`, `npm`, `git`, and anything else the agent runs there connect directly. On macOS and Windows those commands follow the pinned key, or the OS proxy settings when no key is set. When the key or the OS settings name a PAC script, the commands follow it only while the sandbox has [its copy of the script](#pac-script-for-the-sandboxed-shell). If the download of a pinned PAC script fails when the sandbox starts, the commands connect directly until the sandbox next starts. On every platform, [`coworkEgressAllowedHosts`](/docs/third-party/claude-desktop/web-tools) still applies inside the sandbox and sits in front of any proxy.
99* **App updates.** Checking for and downloading Claude Desktop updates is handled by the OS-native updater on macOS and Windows, which follows the OS proxy settings only. This is the one app-controlled path with no admin-side option other than the OS proxy: neither the pinned key nor Claude Code managed settings reach it. If updates must not traverse a direct path, configure the OS proxy on the device or distribute updates yourself with [`disableAutoUpdates`](https://claude.com/docs/third-party/claude-desktop/configuration) and your software-distribution tool. On Linux, updates come from your package manager, which has its own proxy configuration.
100* **Commands in Cowork's sandboxed shell.** No proxy settings reach the Cowork sandbox on Linux, so `curl`, `pip`, `npm`, `git`, and anything else the agent runs there connect directly. On macOS and Windows those commands follow the pinned key, or the OS proxy settings when no key is set. When the key or the OS settings name a PAC script, the commands follow it only while the sandbox has [its copy of the script](#pac-script-for-the-sandboxed-shell). If the download of a pinned PAC script fails when the sandbox starts, the commands connect directly until the sandbox next starts. On every platform, [`coworkEgressAllowedHosts`](https://claude.com/docs/third-party/claude-desktop/web-tools) still applies inside the sandbox and sits in front of any proxy.
101101* **SOCKS proxies in Cowork's sandboxed shell.** On macOS and Windows, the sandboxed shell skips SOCKS proxies. Its commands connect directly to a host for which a PAC script returns only SOCKS proxies, and to every host when the OS proxy settings name only a SOCKS proxy. Have the script return a `PROXY` or `HTTPS` entry for each host that must go through a proxy, or [pin a proxy from managed configuration](#pin-a-proxy-from-managed-configuration).
102* **Cowork's sandboxed shell when every host is allowed.** With a list of hosts in [`coworkEgressAllowedHosts`](/docs/third-party/claude-desktop/web-tools), the shell's commands reach the network only through a filter inside the sandbox, and a program that ignores proxy variables has no route around it. When the list contains `*`, that filter is off and commands make their own connections. On macOS and Windows they get the proxy setting only as `HTTPS_PROXY`, `HTTP_PROXY`, and `NO_PROXY`, so a program that ignores those variables connects directly.
103* **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).
102* **Cowork's sandboxed shell when every host is allowed.** With a list of hosts in [`coworkEgressAllowedHosts`](https://claude.com/docs/third-party/claude-desktop/web-tools), the shell's commands reach the network only through a filter inside the sandbox, and a program that ignores proxy variables has no route around it. When the list contains `*`, that filter is off and commands make their own connections. On macOS and Windows they get the proxy setting only as `HTTPS_PROXY`, `HTTP_PROXY`, and `NO_PROXY`, so a program that ignores those variables connects directly.
103* **SSH remote Code sessions.** When a user runs a Code session on another machine through [`sshHostAllowlist`](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions), the agent runs on that host and connects to the inference endpoint from there. Claude Desktop passes the endpoint address to the remote agent but not the pinned key, the device's OS proxy settings, or proxy variables from Claude Code managed settings on the device. The host's own network route and any Claude Code managed settings installed on the host apply instead. See [Inference credentials on the remote host](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions.md#inference-credentials-on-the-remote-host).
104104* **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.
105* **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.
105* **Brokered Microsoft Entra sign-in.** When [brokered authentication](https://claude.com/docs/third-party/claude-desktop/entra-broker.md) is in use, the token request is made by Company Portal (macOS) or Web Account Manager (Windows), not by the app. Those components follow the OS proxy settings; configure them through the same MDM that manages the device.
106106* **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.
107107* **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.
108108
from line 139
139139}
140140```
141141
142Set `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.
142Set `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](https://claude.com/docs/third-party/claude-desktop/code.md#interaction-with-claude-code%E2%80%99s-own-managed-settings) explains the merge behavior.
143143
144144`NO_PROXY` matching in the agent follows these rules:
145145
from line 172
172172
173173## Troubleshoot
174174
175**"Can't reach" banner.** The app could not get a response from the inference host the banner names. Behind a proxy this usually means the proxy resolved for that host is unreachable, requires a sign-in the app cannot perform, or does not allow the host. Use **Copy report for IT** on the banner to capture the details, confirm the device's OS proxy settings (or the pinned key) point at a reachable HTTP proxy, and confirm the proxy allows the inference host listed in [Required egress paths](/docs/third-party/claude-desktop/telemetry.md#required-egress-paths).
175**"Can't reach" banner.** The app could not get a response from the inference host the banner names. Behind a proxy this usually means the proxy resolved for that host is unreachable, requires a sign-in the app cannot perform, or does not allow the host. Use **Copy report for IT** on the banner to capture the details, confirm the device's OS proxy settings (or the pinned key) point at a reachable HTTP proxy, and confirm the proxy allows the inference host listed in [Required egress paths](https://claude.com/docs/third-party/claude-desktop/telemetry.md#required-egress-paths).
176176
177**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.
177**Confirm which proxy is in effect.** Open `main.log` in the app's [logs directory](https://claude.com/docs/third-party/claude-desktop/data-storage.md). When a key is pinned, startup logs `[egress-proxy] pinned to fixed proxy at proxy.example.com:8080; OS proxy settings ignored` (or `pinned to PAC script at …`). The log records the proxy handed to the agent the first time and whenever it changes, for example `Resolved system proxy for Code sessions: http://proxy.example.com:8080`, a `Keeping system proxy` line when the app reuses the last proxy because the OS answer was direct, SOCKS, or missing, and a `Skipping SOCKS proxy entry` line if the OS answer was SOCKS. If Claude Code managed settings supplied any proxy variable, a line names the variables it set or replaced and the settings file they came from. For Cowork's sandboxed shell, `cowork_vm_node.log` in the same directory records `[VM:start] guest egress pinned to fixed proxy at …` (or `PAC script at …`) when the sandbox starts with a key pinned, and `[VM:start] PAC fetch from … failed (…); guest connects directly` if the sandbox's copy of the script could not be downloaded.
178178
179179**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`.
180180
181181**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.
182182
183**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).
183**Cowork's sandboxed shell has no proxy on macOS while the app is proxied.** Check the PAC address in the OS proxy settings. The sandboxed shell uses its own copy of the PAC script. macOS refuses the download of that copy from a plain `http://` address unless the host is a name with no dot in it, a `.local` name, a loopback address, or a private-network IPv4 address such as `10.0.0.5`. The app's logs then record `PAC fetch from … refused: macOS requires https for this address (App Transport Security)`, which you can search for in the [logs directory](https://claude.com/docs/third-party/claude-desktop/data-storage.md). Serve the script over `https://`. See [PAC script for the sandboxed shell](#pac-script-for-the-sandboxed-shell).
184184
185185**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).
186186
from line 188
188188
189189## Related
190190
191* [Configuration reference](/docs/third-party/claude-desktop/configuration.md) for `egressProxyUrl`, `egressProxyPacUrl`, and `coworkEgressAllowedHosts`
192* [Telemetry and egress](/docs/third-party/claude-desktop/telemetry.md#required-egress-paths) for the hosts your proxy must allow
193* [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
194* [Web tools](/docs/third-party/claude-desktop/web-tools.md) for `coworkEgressAllowedHosts`
191* [Configuration reference](https://claude.com/docs/third-party/claude-desktop/configuration.md) for `egressProxyUrl`, `egressProxyPacUrl`, and `coworkEgressAllowedHosts`
192* [Telemetry and egress](https://claude.com/docs/third-party/claude-desktop/telemetry.md#required-egress-paths) for the hosts your proxy must allow
193* [Claude Code in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/code.md) for how Claude Code managed settings combine with Claude Desktop policy
194* [Web tools](https://claude.com/docs/third-party/claude-desktop/web-tools.md) for `coworkEgressAllowedHosts`
195195
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.md).
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](https://claude.com/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.md), 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](https://claude.com/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.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.
18If your organization can use Anthropic's first-party products directly, standard Claude Desktop with [Cowork](https://claude.com/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.md) |
29| Conversation storage | Anthropic backend | Local disk on the user's machine, and the remote host for [SSH remote sessions](https://claude.com/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.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).
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](https://claude.com/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](https://claude.com/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.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).
40* **Centrally managed.** Configuration is delivered through your existing MDM (Jamf, Intune, Workspace ONE, Group Policy), a [bootstrap server](https://claude.com/docs/third-party/claude-desktop/bootstrap.md), or the [admin console](https://claude.com/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`](https://claude.com/docs/third-party/claude-desktop/configuration#disabledeploymentmodechooser) to `true` in the MDM profile, as described under [Keep a device on its managed profile](https://claude.com/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.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.
54For the Anthropic API, Anthropic processes conversation data under your Anthropic agreement, as described on the [Claude API](https://claude.com/docs/third-party/claude-desktop/claude-api.md) page. For an [LLM gateway](https://claude.com/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.md) host, which sends that session's inference requests and stores its conversation
623. The physical location of any [SSH remote session](https://claude.com/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.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.
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](https://claude.com/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.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.
74With Anthropic-bound telemetry, non-essential services, updates, and the [model catalog fetch](https://claude.com/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](https://claude.com/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`](https://claude.com/docs/third-party/claude-desktop/configuration#skipwebfetchpreflight) to `true` (or add `WebFetch` to `disabledBuiltinTools`), because Claude Code in [Code](https://claude.com/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](https://claude.com/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.md)**
84> **[Installation and setup](https://claude.com/docs/third-party/claude-desktop/installation.md)**
8585>
8686> Roll out Claude Desktop on 3P to your organization, or configure a single machine for evaluation.
8787
88> **[Configuration reference](/docs/third-party/claude-desktop/configuration.md)**
88> **[Configuration reference](https://claude.com/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.md)**
92> **[Extensions](https://claude.com/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.md)**
96> **[Telemetry and egress](https://claude.com/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 · +58 / -58 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.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.
5An SSH remote session is a [Code](https://claude.com/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`](https://claude.com/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.md#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](https://claude.com/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 39
3939
4040Some tool calls wait for an answer from Claude Desktop, and fail while it is disconnected:
4141
42* **File tools under a folder restriction**: if you set [`allowedWorkspaceFolders`](/docs/third-party/claude-desktop/configuration#allowedworkspacefolders), Claude Desktop checks each file read, search, and edit before it happens. While Claude Desktop is disconnected, each of these calls waits up to 10 minutes and then fails.
43* **Tools that your policy sets to ask**: if [`builtinToolPolicy`](/docs/third-party/claude-desktop/configuration#builtintoolpolicy) sets a bare tool name, such as `Bash`, to `ask`, Claude Desktop is consulted before each call to that tool. While Claude Desktop is disconnected, each call waits up to 10 minutes and then fails.
42* **File tools under a folder restriction**: if you set [`allowedWorkspaceFolders`](https://claude.com/docs/third-party/claude-desktop/configuration#allowedworkspacefolders), Claude Desktop checks each file read, search, and edit before it happens. While Claude Desktop is disconnected, each of these calls waits up to 10 minutes and then fails.
43* **Tools that your policy sets to ask**: if [`builtinToolPolicy`](https://claude.com/docs/third-party/claude-desktop/configuration#builtintoolpolicy) sets a bare tool name, such as `Bash`, to `ask`, Claude Desktop is consulted before each call to that tool. While Claude Desktop is disconnected, each call waits up to 10 minutes and then fails.
4444* **Tools from MCP servers that run on the device**: these include your managed MCP servers (see [Where MCP servers run in a remote session](#where-mcp-servers-run-in-a-remote-session)). While Claude Desktop is disconnected, each call to one of their tools fails after about 30 seconds. The 30-second limit requires Claude Desktop 2.2553.0 or later.
4545
4646For a task that uses these tools, have the user keep the device awake and connected. For other limits, see [Limits while Desktop is disconnected](https://code.claude.com/docs/en/desktop#limits-while-desktop-is-disconnected).
from line 84
8484
8585The `Notification` hook doesn't run for a tool call that is waiting for Claude Desktop's own check. That check comes before any permission prompt for the call. Calls that wait for that check include these:
8686
87* Each file read, search, and edit, if you set [`allowedWorkspaceFolders`](/docs/third-party/claude-desktop/configuration#allowedworkspacefolders)
88* Each call to a tool that [`builtinToolPolicy`](/docs/third-party/claude-desktop/configuration#builtintoolpolicy) sets to `ask` by its bare name, such as `Bash`
87* Each file read, search, and edit, if you set [`allowedWorkspaceFolders`](https://claude.com/docs/third-party/claude-desktop/configuration#allowedworkspacefolders)
88* Each call to a tool that [`builtinToolPolicy`](https://claude.com/docs/third-party/claude-desktop/configuration#builtintoolpolicy) sets to `ask` by its bare name, such as `Bash`
8989* Each call to a tool from an MCP server that runs on the device
9090
9191While Claude Desktop is disconnected, each of these calls waits and then fails, after up to 10 minutes for file tools and tools set to `ask` (for each limit, see [How a remote session works](#how-a-remote-session-works)). Claude receives the failure as the call's result, and a further call of the same kind waits again, which delays the `Stop` hook. For a task that makes these calls, have the user keep the device awake and connected.
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.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.
103* **[Managed MCP servers](https://claude.com/docs/third-party/claude-desktop/extensions.md#managed-mcp-servers-admin), and servers from plugins in the [`org-plugins` directory](https://claude.com/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.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)).
108[`isLocalDevMcpEnabled`](https://claude.com/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](https://claude.com/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.md) while Code is enabled.
112Set [`sshHostAllowlist`](https://claude.com/docs/third-party/claude-desktop/configuration#sshhostallowlist) in your managed configuration. It appears in the **Code surface** section of the [in-app configuration window](https://claude.com/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-format.md#value-types). In a [bootstrap](/docs/third-party/claude-desktop/bootstrap.md) 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](https://claude.com/docs/third-party/claude-desktop/configuration-format.md#value-types). In a [bootstrap](https://claude.com/docs/third-party/claude-desktop/bootstrap.md) response, the key sits inside the `codeSurface` object.
144144
145145### Jump hosts and the allowlist
146146
147Add each jump host, or bastion, that Claude Desktop checks to `sshHostAllowlist`, by the `HostName` that the device's `~/.ssh/config` gives for it. Add the jump hosts before devices update to Claude Desktop 3.1623.0 or later, or users can't connect through them. To hold updates until devices have the new allowlist, see [Auto-updates](/docs/third-party/claude-desktop/telemetry.md#auto-updates).
147Add each jump host, or bastion, that Claude Desktop checks to `sshHostAllowlist`, by the `HostName` that the device's `~/.ssh/config` gives for it. Add the jump hosts before devices update to Claude Desktop 3.1623.0 or later, or users can't connect through them. To hold updates until devices have the new allowlist, see [Auto-updates](https://claude.com/docs/third-party/claude-desktop/telemetry.md#auto-updates).
148148
149149> [!WARNING]
150150>
from line 156
156156
1571571. Run `ssh -G` with a host that users connect to, for example `ssh -G build01`. Look for a `proxyjump` line, or a `proxycommand` line written as `ssh -W %h:%p <host>`. The command still counts with any of `-l`, `-p`, `-J`, `-q`, `-v`, `-N`, `-T`, `-x`, or `-a`, and the hosts after `-J` are jump hosts too. If a `proxycommand` line runs a program other than `ssh`, add nothing for it.
1581582. Run `ssh -G` with each jump host on that line, without any `:port`, and note the `hostname` that it prints. If the output for the first jump host on that line has a line of either kind, repeat this step with it. Ignore such a line in a later jump host's output.
1593. Add each hostname, or a wildcard that covers it, to the `sshHostAllowlist` that applies on the device. To tell which one applies, see [Interaction with Claude Code managed settings on the device](#interaction-with-claude-code-managed-settings-on-the-device). Then have users quit and reopen Claude Desktop, because an open app keeps the list from a [bootstrap server](/docs/third-party/claude-desktop/bootstrap.md#availability) or the [admin console](/docs/third-party/claude-desktop/admin-console.md#configuration-updates) until it restarts.
1593. Add each hostname, or a wildcard that covers it, to the `sshHostAllowlist` that applies on the device. To tell which one applies, see [Interaction with Claude Code managed settings on the device](#interaction-with-claude-code-managed-settings-on-the-device). Then have users quit and reopen Claude Desktop, because an open app keeps the list from a [bootstrap server](https://claude.com/docs/third-party/claude-desktop/bootstrap.md#availability) or the [admin console](https://claude.com/docs/third-party/claude-desktop/admin-console.md#configuration-updates) until it restarts.
160160
161161### Interaction with Claude Code managed settings on the device
162162
163163Claude 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:
164164
1651. `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.
1651. `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](https://claude.com/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](https://claude.com/docs/third-party/claude-desktop/bootstrap.md#keys-that-require-user-consent)). User-scope registry policy (`HKCU`) counts as applied locally.
1661662. `sshHostAllowlist` from Claude Code's managed settings on the device.
1673. `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).
1673. `sshHostAllowlist` from a Claude Desktop configuration the user applied locally in the [in-app configuration window](https://claude.com/docs/third-party/claude-desktop/in-app-configuration.md#apply-locally-or-export-for-a-fleet).
1681684. Off.
169169
170On 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)).
170On 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](https://claude.com/docs/third-party/claude-desktop/mdm.md#update-keys-and-managed-precedence)).
171171
172To 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).
172To 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](https://claude.com/docs/third-party/claude-desktop/code.md#interaction-with-claude-code%E2%80%99s-own-managed-settings) on the Code page).
173173
174174Before 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.
175175
176176### Devices that move to an admin console organization
177177
178A 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.
178A 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](https://claude.com/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.
179179
180After 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).
180After 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](https://claude.com/docs/third-party/claude-desktop/admin-console.md#which-settings-apply-on-a-device-with-a-managed-profile).
181181
182182* **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.
183183* **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 184
184184
185185To prevent or limit the move, set one of these keys in the profile itself:
186186
187* **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.
188* **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.
187* **Keep the device on its profile**: set [`disableDeploymentModeChooser`](https://claude.com/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.
188* **Allow only your organization**: set [`forceLoginOrgUUID`](https://claude.com/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.
189189
190Before 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).
190Before you add either key to a profile that sets only [app-behavior keys](https://claude.com/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](https://claude.com/docs/third-party/claude-desktop/admin-console.md#keep-a-device-on-its-managed-profile).
191191
192192## Inference credentials on the remote host
193193
from line 199
199199
200200| Provider | Works on a remote host | Refused at session start |
201201| - | - | - |
202| [LLM gateway](/docs/third-party/claude-desktop/gateway.md) | Static API key, single sign-on, credential helper | |
203| [Claude API](/docs/third-party/claude-desktop/claude-api.md) | Static API key, Sign in with Claude Console, credential helper | |
204| [Microsoft Foundry](/docs/third-party/claude-desktop/foundry.md) | API key, in-app Entra ID sign-in, credential helper | |
205| [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 |
206| [Amazon Bedrock Mantle](/docs/third-party/claude-desktop/mantle.md) | Bearer token, credential helper | |
207| [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 |
202| [LLM gateway](https://claude.com/docs/third-party/claude-desktop/gateway.md) | Static API key, single sign-on, credential helper | |
203| [Claude API](https://claude.com/docs/third-party/claude-desktop/claude-api.md) | Static API key, Sign in with Claude Console, credential helper | |
204| [Microsoft Foundry](https://claude.com/docs/third-party/claude-desktop/foundry.md) | API key, in-app Entra ID sign-in, credential helper | |
205| [Amazon Bedrock](https://claude.com/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 |
206| [Amazon Bedrock Mantle](https://claude.com/docs/third-party/claude-desktop/mantle.md) | Bearer token, credential helper | |
207| [Google Cloud's Agent Platform](https://claude.com/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 |
208208
209209When 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).
210210
211When 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.
211When the remote engine's credential expires during a turn, Claude Desktop obtains a new one on the device, by re-running a [credential helper](https://claude.com/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.
212212
213213The 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.
214214
215215## Managed configuration on the remote host
216216
217Most 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.
217Most of the policy that Claude Desktop applies to a local Code session applies on the remote host too. The [Code page](https://claude.com/docs/third-party/claude-desktop/code.md#how-configuration-propagates) describes how each key reaches Claude Code.
218218
219219* `disableEssentialTelemetry` and `disableNonessentialTelemetry`.
220220* `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.
221221* `disabledBuiltinTools`, `builtinToolPolicy`, `autoModeEnabled`, and `disableBypassPermissionsMode`.
222* [`allowedWorkspaceFolders`](/docs/third-party/claude-desktop/configuration#allowedworkspacefolders), evaluated against the host's filesystem. `~` is the SSH user's home on the host, `%VAR%` entries are ignored, and Claude Desktop refuses to start a session in a directory outside every entry, so with a fleet value such as `~/Documents/Claude`, remote sessions start only under that path in the SSH user's home. For an entry with `mode` set to `ro`, see [Read-only folders on the remote host](#read-only-folders-on-the-remote-host).
223* [`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.
222* [`allowedWorkspaceFolders`](https://claude.com/docs/third-party/claude-desktop/configuration#allowedworkspacefolders), evaluated against the host's filesystem. `~` is the SSH user's home on the host, `%VAR%` entries are ignored, and Claude Desktop refuses to start a session in a directory outside every entry, so with a fleet value such as `~/Documents/Claude`, remote sessions start only under that path in the SSH user's home. For an entry with `mode` set to `ro`, see [Read-only folders on the remote host](#read-only-folders-on-the-remote-host).
223* [`blockReadsOutsideWorkingDirectories`](https://claude.com/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.
224224* `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.
225225* `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)).
226* 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.
226* Plugins from your [allowed marketplaces](https://claude.com/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.
227227
228If 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.
228If 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](https://claude.com/docs/third-party/claude-desktop/code.md#interaction-with-claude-code%E2%80%99s-own-managed-settings) for local sessions.
229229
230230### Read-only folders on the remote host
231231
232On a Linux or macOS host, Claude Desktop applies `mode` set to `ro` on an [`allowedWorkspaceFolders`](/docs/third-party/claude-desktop/configuration#allowedworkspacefolders) entry by supplying Claude Code with permission rules that deny edits under the entry's path. The rules are Claude Code's own checks on what Claude does, not file permissions on the host. Where a folder must not change, use the host's file permissions to keep the SSH user from writing to it. Before Claude Desktop 2.31226.0, a folder with `mode` set to `ro` was allowed on the host but not read-only there.
232On a Linux or macOS host, Claude Desktop applies `mode` set to `ro` on an [`allowedWorkspaceFolders`](https://claude.com/docs/third-party/claude-desktop/configuration#allowedworkspacefolders) entry by supplying Claude Code with permission rules that deny edits under the entry's path. The rules are Claude Code's own checks on what Claude does, not file permissions on the host. Where a folder must not change, use the host's file permissions to keep the SSH user from writing to it. Before Claude Desktop 2.31226.0, a folder with `mode` set to `ro` was allowed on the host but not read-only there.
233233
234234A remote session doesn't enforce `mode` in these cases:
235235
236236* **Windows hosts.**
237* **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)).
237* **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](https://claude.com/docs/third-party/claude-desktop/code.md#interaction-with-claude-code%E2%80%99s-own-managed-settings)).
238238* **An entry that is or contains the SSH user's `~/.claude` folder, such as `~`**: Claude Code keeps its own files there. List narrower folders.
239239
240240Where the rules apply, they cover the following:
from line 246
246246
247247### Sandbox status on the remote host
248248
249Claude 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.
249Claude Desktop asks Claude Code on the host whether the [sandbox](https://claude.com/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.
250250
251When 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.
251When 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`](https://claude.com/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.
252252
253253Find the message, or the `reason` your collector received, for the cause and the fix.
254254
from line 269
269269
270270If the card has no **Sandbox** row, have the user send a message, and enter `/status` again after Claude's reply.
271271
272With [`otlpEndpoint`](/docs/third-party/claude-desktop/configuration#otlpendpoint) set, your collector receives a `desktop_ssh_sandbox_check_failed` event under the `service.name` value `claude-desktop`, unless [`otlpDesktopLogLevel`](/docs/third-party/claude-desktop/configuration#otlpdesktoploglevel) is `off`. A session can send the event more than once, for example when the reason changes or after Claude Desktop restarts, so count distinct `session_id` values rather than events. The event carries these attributes:
272With [`otlpEndpoint`](https://claude.com/docs/third-party/claude-desktop/configuration#otlpendpoint) set, your collector receives a `desktop_ssh_sandbox_check_failed` event under the `service.name` value `claude-desktop`, unless [`otlpDesktopLogLevel`](https://claude.com/docs/third-party/claude-desktop/configuration#otlpdesktoploglevel) is `off`. A session can send the event more than once, for example when the reason changes or after Claude Desktop restarts, so count distinct `session_id` values rather than events. The event carries these attributes:
273273
274274* **`reason`**: `cannot_start`, `unsupported`, `overridden`, or `unknown`
275275* **`sandbox_on`**: `false` when Claude Code reports no sandbox running, `true` when it reports one that Claude Desktop can't match to your policy, and absent when Claude Code doesn't say
from line 276
276276* **`session_id`**: Claude Desktop's ID for the session
277277* **`backend_kind`**: `ssh`
278278
279The 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.
279The event doesn't name the host. To find the host, ask the user that the [user attribution](https://claude.com/docs/third-party/claude-desktop/telemetry.md#user-attribution) attributes identify.
280280
281281## Host requirements
282282
from line 290
290290* `git` on the path, for git features.
291291* A home directory that the SSH user can write to and run programs from, with about 1 GB of disk space for the three Claude Code versions the app keeps and a fourth while an update installs. A home directory mounted `noexec` doesn't work.
292292
293The device needs the OpenSSH client (`ssh` and `ssh-keygen`). Claude Desktop runs the first `ssh` on the user's `PATH`; to pin a specific OpenSSH installation instead, set [`sshClientPath`](/docs/third-party/claude-desktop/configuration#sshclientpath) (beta, Claude Desktop 1.46388.1 or later) to the program's absolute path, and `ssh-keygen` is then taken from the same directory when present. If the pinned program is missing or cannot be run, SSH connections fail with an error that shows the configured path, rather than falling back to another `ssh`. For the `ssh` that carries the connection on a Windows device, see [Prepare Windows devices for the OpenSSH client](#prepare-windows-devices-for-the-openssh-client).
293The device needs the OpenSSH client (`ssh` and `ssh-keygen`). Claude Desktop runs the first `ssh` on the user's `PATH`; to pin a specific OpenSSH installation instead, set [`sshClientPath`](https://claude.com/docs/third-party/claude-desktop/configuration#sshclientpath) (beta, Claude Desktop 1.46388.1 or later) to the program's absolute path, and `ssh-keygen` is then taken from the same directory when present. If the pinned program is missing or cannot be run, SSH connections fail with an error that shows the configured path, rather than falling back to another `ssh`. For the `ssh` that carries the connection on a Windows device, see [Prepare Windows devices for the OpenSSH client](#prepare-windows-devices-for-the-openssh-client).
294294
295On macOS and Linux, Claude Desktop makes the SSH connection by running the device's OpenSSH client, so your own OpenSSH build's Kerberos (GSSAPI), certificate, and `ssh_config` support handles authentication. The program is the one `sshClientPath` names, or else the first `ssh` on the user's `PATH`, and it must be OpenSSH 7.6 or newer. On Windows, the app's built-in SSH client makes the connection by default, and the app runs the device's OpenSSH tools to evaluate the user's SSH configuration, look up host keys, and run the session's terminal. To have the device's OpenSSH client carry the connection on Windows too, set [`sshTransport`](/docs/third-party/claude-desktop/configuration#sshtransport) (beta) to `system-openssh`; a client that the app finds itself must be Win32-OpenSSH 9.4 or newer. On a Windows device with no usable OpenSSH client and no `sshClientPath`, the built-in client is used regardless. For what to check first, see [Prepare Windows devices for the OpenSSH client](#prepare-windows-devices-for-the-openssh-client). Set `sshTransport` to `builtin` to use the built-in client on every platform. A change applies to new connections, and sessions that are already connected keep their client.
295On macOS and Linux, Claude Desktop makes the SSH connection by running the device's OpenSSH client, so your own OpenSSH build's Kerberos (GSSAPI), certificate, and `ssh_config` support handles authentication. The program is the one `sshClientPath` names, or else the first `ssh` on the user's `PATH`, and it must be OpenSSH 7.6 or newer. On Windows, the app's built-in SSH client makes the connection by default, and the app runs the device's OpenSSH tools to evaluate the user's SSH configuration, look up host keys, and run the session's terminal. To have the device's OpenSSH client carry the connection on Windows too, set [`sshTransport`](https://claude.com/docs/third-party/claude-desktop/configuration#sshtransport) (beta) to `system-openssh`; a client that the app finds itself must be Win32-OpenSSH 9.4 or newer. On a Windows device with no usable OpenSSH client and no `sshClientPath`, the built-in client is used regardless. For what to check first, see [Prepare Windows devices for the OpenSSH client](#prepare-windows-devices-for-the-openssh-client). Set `sshTransport` to `builtin` to use the built-in client on every platform. A change applies to new connections, and sessions that are already connected keep their client.
296296
297297The built-in client also makes the connection in these cases:
298298
from line 308
308308| `~/.claude/remote/run/<id>/` | The server's socket, token, and log |
309309| `~/.claude/remote/plugins/<id>/` | Plugins synced from the device, in one folder for each Claude Desktop installation that connects |
310310| `~/.claude/uploads/<session-id>/` | Files the user attached to a message. Not removed when the session ends |
311| `~/.claude/` and `~/.claude.json` | Claude Code's own data, including session transcripts. See [Data storage](/docs/third-party/claude-desktop/data-storage.md) |
311| `~/.claude/` and `~/.claude.json` | Claude Code's own data, including session transcripts. See [Data storage](https://claude.com/docs/third-party/claude-desktop/data-storage.md) |
312312
313313Each side of a remote session needs its own network access.
314314
315* 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.
316* 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.
315* 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](https://claude.com/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.
316* 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](https://claude.com/docs/third-party/claude-desktop/telemetry.md)). Blocking them does not affect the session.
317317
318318### Prepare Windows devices for the OpenSSH client
319319
320On Windows devices, the app's built-in SSH client makes the SSH connection by default. The device's OpenSSH client makes it when you set [`sshTransport`](/docs/third-party/claude-desktop/configuration#sshtransport) (beta) to `system-openssh`.
320On Windows devices, the app's built-in SSH client makes the SSH connection by default. The device's OpenSSH client makes it when you set [`sshTransport`](https://claude.com/docs/third-party/claude-desktop/configuration#sshtransport) (beta) to `system-openssh`.
321321
322322With the device's OpenSSH client on a Windows device:
323323
from line 328
328328Before you set `sshTransport`, check what the device's OpenSSH client needs on Windows:
329329
330330* **One value for all platforms**: `sshTransport` has no per-platform form. A Windows registry policy reaches Windows devices only. A value from a bootstrap server or the Enterprise Admin Console reaches the macOS and Linux devices that it serves too, where the device's OpenSSH client already makes the connection by default.
331* **Devices with a bootstrap server**: an available [bootstrap response](/docs/third-party/claude-desktop/bootstrap.md) replaces the registry's value of `sshTransport`, even if the response leaves the key out, so return the key in the response too. If you set `sshClientPath`, return it too, but only in a response that goes to Windows devices alone. It has no per-platform form either, and SSH connections fail on a macOS or Linux device that gets a Windows path.
332* **Client version**: with no [`sshClientPath`](/docs/third-party/claude-desktop/configuration#sshclientpath), a usable client prints a version that starts with `OpenSSH_for_Windows_` and is 9.4 or later. Run `ssh -V` in a Command Prompt window on a device, signed in as the user. If that output is anything else, run `ssh.exe -V` in `%SystemRoot%\System32\OpenSSH` and in `%ProgramFiles%\OpenSSH`: Claude Desktop uses the first usable client that it finds, on the `PATH`, then in those two folders in that order. If you set `sshClientPath`, run that program with `-V` instead. In Claude Desktop 3.1623 and earlier, it has to pass the same test.
331* **Devices with a bootstrap server**: an available [bootstrap response](https://claude.com/docs/third-party/claude-desktop/bootstrap.md) replaces the registry's value of `sshTransport`, even if the response leaves the key out, so return the key in the response too. If you set `sshClientPath`, return it too, but only in a response that goes to Windows devices alone. It has no per-platform form either, and SSH connections fail on a macOS or Linux device that gets a Windows path.
332* **Client version**: with no [`sshClientPath`](https://claude.com/docs/third-party/claude-desktop/configuration#sshclientpath), a usable client prints a version that starts with `OpenSSH_for_Windows_` and is 9.4 or later. Run `ssh -V` in a Command Prompt window on a device, signed in as the user. If that output is anything else, run `ssh.exe -V` in `%SystemRoot%\System32\OpenSSH` and in `%ProgramFiles%\OpenSSH`: Claude Desktop uses the first usable client that it finds, on the `PATH`, then in those two folders in that order. If you set `sshClientPath`, run that program with `-V` instead. In Claude Desktop 3.1623 and earlier, it has to pass the same test.
333333* **Devices without a usable client**: on a Windows device with no usable OpenSSH client and no `sshClientPath`, the built-in client is used regardless. Add the **OpenSSH Client** optional feature in Windows and install pending Windows updates, or install [Microsoft's newer build](https://learn.microsoft.com/en-us/troubleshoot/windows-server/system-management-components/upgrade-in-box-openssh-to-latest-openssh-release). Run the version check again, then have users quit and reopen Claude Desktop.
334334* **Application control**: `ssh` shows its prompts through three helper programs that ship with Claude Desktop, `claude-ssh-askpass.exe`, `claude-ssh-broker.exe`, and `claude-ssh-proxy.exe`. Allow them in your application control policy by their publisher, Anthropic, PBC. Their folder changes with each update, and the files carry no product name or version. Allow the `ssh.exe` that the version check found too. If Windows refuses to start the helpers, sign-ins that need a password, a one-time code, or a key passphrase fail, and `ssh` refuses a host whose key isn't on record. See [This computer won't start Claude's SSH sign-in helper](#this-computer-won%E2%80%99t-start-claude%E2%80%99s-ssh-sign-in-helper).
335335* **Key files**: `ssh` doesn't read a PuTTY `.ppk` key file. Export the key in OpenSSH format, and have the user select the exported file as the connection's identity file.
from line 390
390390
391391The built-in client made the connection, and the host needs the device's OpenSSH client. Where the app can name a step, the card's title gives it, and the card's text gives the cause, either "Claude's built-in SSH library can't connect through a jump host (ProxyJump)." or "Claude's built-in SSH library can't check host keys against a certificate authority or another known\_hosts file."
392392
393* **"Ask your IT administrator to set sshTransport to system-openssh"**: the built-in client is the device's default, and the device has a usable OpenSSH client. Set [`sshTransport`](/docs/third-party/claude-desktop/configuration#sshtransport) to `system-openssh`.
393* **"Ask your IT administrator to set sshTransport to system-openssh"**: the built-in client is the device's default, and the device has a usable OpenSSH client. Set [`sshTransport`](https://claude.com/docs/third-party/claude-desktop/configuration#sshtransport) to `system-openssh`.
394394* **"Ask your IT administrator to change sshTransport from builtin to system-openssh"**: your configuration sets `sshTransport` to `builtin`. Change it to `system-openssh`.
395395* **"Ask your admin to correct the sshTransport setting"**: the app can't read the value that your configuration gives `sshTransport`, for example a misspelling, so the built-in client makes the connection. Correct the value. Requires Claude Desktop 2.37337.0 or later.
396396* **"Ask your IT administrator to install Microsoft OpenSSH 9.4 or newer and set sshTransport to system-openssh, then quit and reopen Claude"**: the built-in client is the device's default, and the app found no usable OpenSSH client on the device. Install the client, and set the key.
from line 444
444444>
445445> * **An `allowedWorkspaceFolders` entry with `mode` set to `ro`**: see [Read-only folders on the remote host](#read-only-folders-on-the-remote-host)
446446> * **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)
447> * **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)
447> * **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](https://claude.com/docs/third-party/claude-desktop/code.md#applied-as-managed-policy)
448448
449449## Related
450450
451* [Code in Claude Desktop on 3P](/docs/third-party/claude-desktop/code.md)
452* [`sshHostAllowlist` in the configuration reference](/docs/third-party/claude-desktop/configuration#sshhostallowlist)
453* [Desktop and filesystem access](/docs/third-party/claude-desktop/local-access.md)
451* [Code in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/code.md)
452* [`sshHostAllowlist` in the configuration reference](https://claude.com/docs/third-party/claude-desktop/configuration#sshhostallowlist)
453* [Desktop and filesystem access](https://claude.com/docs/third-party/claude-desktop/local-access.md)
454454
third-party/claude-desktop/telemetry Changed · +53 / -53 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.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.
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](https://claude.com/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.md#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](https://claude.com/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.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).
13To find out whether a managed profile's keys apply on a device that uses the [Enterprise Admin Console](https://claude.com/docs/third-party/claude-desktop/admin-console.md), see [Which settings apply on a device with a managed profile](https://claude.com/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.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`.
23On Claude Desktop 2.7032.0 and later, the [**Keep only your organization ID and restrictions on disk**](https://claude.com/docs/third-party/claude-desktop/admin-console.md#configuration-kept-on-devices) switch in the [Enterprise Admin Console](https://claude.com/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.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.
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](https://claude.com/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.md) 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](https://claude.com/docs/cowork/monitoring.md) for the event schema and the [`otlp*` keys](https://claude.com/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.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.
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](https://claude.com/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.md#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`](https://claude.com/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](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions.md#sandbox-status-on-the-remote-host).
6666
6767### Collector endpoint and headers
6868
69Set [`otlpEndpoint`](/docs/third-party/claude-desktop/configuration#otlpendpoint) to the base address of your collector's OTLP/HTTP receiver, for example `https://otel-collector.example.com:4318`. The app appends the OpenTelemetry request paths itself (`/v1/logs`, `/v1/metrics`, and `/v1/traces` when [traces](#traces-beta) are enabled), so enter the address without those suffixes. A path prefix in front of them, such as `https://observability.example.com/otlp`, is kept.
69Set [`otlpEndpoint`](https://claude.com/docs/third-party/claude-desktop/configuration#otlpendpoint) to the base address of your collector's OTLP/HTTP receiver, for example `https://otel-collector.example.com:4318`. The app appends the OpenTelemetry request paths itself (`/v1/logs`, `/v1/metrics`, and `/v1/traces` when [traces](#traces-beta) are enabled), so enter the address without those suffixes. A path prefix in front of them, such as `https://observability.example.com/otlp`, is kept.
7070
7171> [!NOTE]
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.md#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](https://claude.com/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-format.md#value-types), write it as a JSON string.
77[`otlpHeaders`](https://claude.com/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](https://claude.com/docs/third-party/claude-desktop/configuration-format.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
81For a collector credential that cannot be a static header, [`otlpHeadersHelper`](/docs/third-party/claude-desktop/configuration#otlpheadershelper) names a script on the device that prints the headers, and [`otlpAuthMode`](/docs/third-party/claude-desktop/configuration#otlpauthmode) set to `inference-credential` sends the user's own inference bearer token, which suits only a collector you operate. The configuration reference describes both.
81For a collector credential that cannot be a static header, [`otlpHeadersHelper`](https://claude.com/docs/third-party/claude-desktop/configuration#otlpheadershelper) names a script on the device that prints the headers, and [`otlpAuthMode`](https://claude.com/docs/third-party/claude-desktop/configuration#otlpauthmode) set to `inference-credential` sends the user's own inference bearer token, which suits only a collector you operate. The configuration reference describes both.
8282
8383### User attribution
8484
8585Every record sent to your collector carries the user's identity as two resource attributes, on all three `service.name` streams:
8686
87* `enduser.id` — the signed-in user's identity. With a sign-in that carries identity claims (for example, Workforce Identity Federation or Google sign-in on Google Cloud's Agent Platform), this is the identity from the provider's claims, normally the user's email address. Some credential methods carry no identity claims, such as a static key, a credential helper, an application default credentials file, [in-app AWS sign-in](/docs/third-party/claude-desktop/bedrock.md#in-app-aws-sign-in), or a [named AWS profile](/docs/third-party/claude-desktop/bedrock.md#named-profile). With one of those, on a device managed from the [Enterprise Admin Console](/docs/third-party/claude-desktop/admin-console.md), it is the email address of the user's Claude account. On other devices, it is the operating-system login name.
87* `enduser.id` — the signed-in user's identity. With a sign-in that carries identity claims (for example, Workforce Identity Federation or Google sign-in on Google Cloud's Agent Platform), this is the identity from the provider's claims, normally the user's email address. Some credential methods carry no identity claims, such as a static key, a credential helper, an application default credentials file, [in-app AWS sign-in](https://claude.com/docs/third-party/claude-desktop/bedrock.md#in-app-aws-sign-in), or a [named AWS profile](https://claude.com/docs/third-party/claude-desktop/bedrock.md#named-profile). With one of those, on a device managed from the [Enterprise Admin Console](https://claude.com/docs/third-party/claude-desktop/admin-console.md), it is the email address of the user's Claude account. On other devices, it is the operating-system login name.
8888* `process.owner` — the operating-system login name.
8989
90`enduser.id` is the same identity the app shows in the sidebar and account menu, and is controlled by the [`endUserAttribution`](/docs/third-party/claude-desktop/configuration#enduserattribution) key: set it to `false` to remove the identity from both the app and the export. `process.owner` is not gated by that key — it is standard OpenTelemetry process metadata and is always present. A static value set under [`otlpResourceAttributes`](/docs/third-party/claude-desktop/configuration#otlpresourceattributes) overrides either attribute: a static `enduser.id` is always passed through — taking precedence over the signed-in identity, and surviving `endUserAttribution: false` — and a static `process.owner` replaces the login name.
90`enduser.id` is the same identity the app shows in the sidebar and account menu, and is controlled by the [`endUserAttribution`](https://claude.com/docs/third-party/claude-desktop/configuration#enduserattribution) key: set it to `false` to remove the identity from both the app and the export. `process.owner` is not gated by that key — it is standard OpenTelemetry process metadata and is always present. A static value set under [`otlpResourceAttributes`](https://claude.com/docs/third-party/claude-desktop/configuration#otlpresourceattributes) overrides either attribute: a static `enduser.id` is always passed through — taking precedence over the signed-in identity, and surviving `endUserAttribution: false` — and a static `process.owner` replaces the login name.
9191
9292These attributes are attached only to the OpenTelemetry export; the Anthropic-bound telemetry described earlier on this page does not carry them.
9393
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.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).
98* [Code](https://claude.com/docs/third-party/claude-desktop/code.md) sessions export over the protocol as configured, including `grpc`.
99* Cowork and [Chat](https://claude.com/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](https://claude.com/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 115
115115
116116On Claude Desktop version 1.17377 or later, enabling `userPrompts` also captures model responses, even if `assistantResponses` is not listed. On those versions, no `otlpContentCapture` configuration captures user prompts without model responses.
117117
118Conversation titles arrive on the desktop application's own stream (`claude-desktop`) as a `desktop_session_title_set` event that carries each Cowork and Code session's title and the Claude Code `session.id` to join on. The event is exported only when [`otlpDesktopLogLevel`](/docs/third-party/claude-desktop/configuration#otlpdesktoploglevel) is `info` or `debug`, and the title text is included only when `otlpContentCapture` includes `userPrompts`. Requires Claude Desktop 1.44121.1 or later.
118Conversation titles arrive on the desktop application's own stream (`claude-desktop`) as a `desktop_session_title_set` event that carries each Cowork and Code session's title and the Claude Code `session.id` to join on. The event is exported only when [`otlpDesktopLogLevel`](https://claude.com/docs/third-party/claude-desktop/configuration#otlpdesktoploglevel) is `info` or `debug`, and the title text is included only when `otlpContentCapture` includes `userPrompts`. Requires Claude Desktop 1.44121.1 or later.
119119
120120With `rawApiBodies`, Claude Code always redacts Claude's extended-thinking content. See [API request body event](https://code.claude.com/docs/en/monitoring-usage#api-request-body-event) in the Claude Code documentation.
121121
from line 125
125125
126126In Chat, Cowork, and Code sessions, the OpenTelemetry export by default cuts [captured](#content-capture) model responses, tool content, and request and response bodies at 61,440 characters each. User prompts are not cut. When a request or response body is cut, the [body event](https://code.claude.com/docs/en/monitoring-usage#api-request-body-event) carries `body_truncated` set to `"true"`, and `body_length` holds the full length in characters.
127127
128To change the limit, set [`otlpAttrMaxChars`](/docs/third-party/claude-desktop/configuration#otlpattrmaxchars) to a number of characters from 256 to 15,000,000. The key doesn't change the smaller limits of `tool_input`, an attribute of the `toolDetails` category. To capture whole bodies, find the largest `body_length` on the events where `body_truncated` is `"true"`, and set `otlpAttrMaxChars` slightly above it.
128To change the limit, set [`otlpAttrMaxChars`](https://claude.com/docs/third-party/claude-desktop/configuration#otlpattrmaxchars) to a number of characters from 256 to 15,000,000. The key doesn't change the smaller limits of `tool_input`, an attribute of the `toolDetails` category. To capture whole bodies, find the largest `body_length` on the events where `body_truncated` is `"true"`, and set `otlpAttrMaxChars` slightly above it.
129129
130130Before you raise the limit, make sure that both of these are true:
131131
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.md#web-fetch) for where the key applies.
1572. **Agent egress allowlist:** the [`coworkEgressAllowedHosts`](https://claude.com/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](https://claude.com/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.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.
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](https://claude.com/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`](https://claude.com/docs/third-party/claude-desktop/configuration#modelcatalogenabled) to `false` to turn it off, or [`modelCatalogUrl`](https://claude.com/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.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. |
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](https://claude.com/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 232
232232| `api.anthropic.com` | Update feed (releases.claude.com when updateViaUpdatesHost is set) |
233233| `downloads.claude.ai` | Update binaries |
234234
235With [`updateViaUpdatesHost`](/docs/third-party/claude-desktop/configuration#updateviaupdateshost) set to `true`, the app reads the update feed from `releases.claude.com` instead of `claude.ai` and `api.anthropic.com`, so those two hosts are no longer needed for updates. Update binaries still come from `downloads.claude.ai`.
235With [`updateViaUpdatesHost`](https://claude.com/docs/third-party/claude-desktop/configuration#updateviaupdateshost) set to `true`, the app reads the update feed from `releases.claude.com` instead of `claude.ai` and `api.anthropic.com`, so those two hosts are no longer needed for updates. Update binaries still come from `downloads.claude.ai`.
236236
237237### Essential telemetry (`disableEssentialTelemetry: false`)
238238
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.md), 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](https://claude.com/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.md#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](https://claude.com/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.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)) |
288| `api.anthropic.com` | [Code](https://claude.com/docs/third-party/claude-desktop/code.md) sessions can use Web Fetch and [`skipWebFetchPreflight`](https://claude.com/docs/third-party/claude-desktop/configuration#skipwebfetchpreflight) is not `true` (Claude Code's Web Fetch [domain check](https://claude.com/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](https://claude.com/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](https://claude.com/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](https://claude.com/docs/third-party/claude-desktop/browser.md) is turned on (`builtinBrowserEnabled` set to `true`), for its [site safety check](https://claude.com/docs/third-party/claude-desktop/browser.md#site-safety-check) |
292| `downloads.claude.ai` | [SSH remote sessions](https://claude.com/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](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions.md#host-requirements)) |
293293
294294## Disabling all Anthropic-bound connections
295295
from line 297
297297
298298| Connection | What it carries | Key that turns it off |
299299| - | - | - |
300| Crash, error, and performance reporting | Diagnostic metadata, never prompt or response content. See [Essential telemetry](#essential-telemetry). | [`disableEssentialTelemetry`](/docs/third-party/claude-desktop/configuration#disableessentialtelemetry) set to `true` |
301| Product analytics and diagnostic-report uploads | Feature adoption, session counts, and UI interactions, plus Claude Code usage telemetry. No prompt or response content. See [Non-essential telemetry](#non-essential-telemetry). | [`disableNonessentialTelemetry`](/docs/third-party/claude-desktop/configuration#disablenonessentialtelemetry) set to `true` |
302| 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` |
303| 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). |
304| 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.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) |
300| Crash, error, and performance reporting | Diagnostic metadata, never prompt or response content. See [Essential telemetry](#essential-telemetry). | [`disableEssentialTelemetry`](https://claude.com/docs/third-party/claude-desktop/configuration#disableessentialtelemetry) set to `true` |
301| Product analytics and diagnostic-report uploads | Feature adoption, session counts, and UI interactions, plus Claude Code usage telemetry. No prompt or response content. See [Non-essential telemetry](#non-essential-telemetry). | [`disableNonessentialTelemetry`](https://claude.com/docs/third-party/claude-desktop/configuration#disablenonessentialtelemetry) set to `true` |
302| 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`](https://claude.com/docs/third-party/claude-desktop/configuration#disablenonessentialservices) set to `true` |
303| 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`](https://claude.com/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). |
304| 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`](https://claude.com/docs/third-party/claude-desktop/configuration#modelcatalogenabled) set to `false`, or [`modelCatalogUrl`](https://claude.com/docs/third-party/claude-desktop/configuration#modelcatalogurl) set to a mirror inside your network |
305| Web Fetch domain check in [Code](https://claude.com/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](https://claude.com/docs/third-party/claude-desktop/web-tools.md#web-fetch). | [`skipWebFetchPreflight`](https://claude.com/docs/third-party/claude-desktop/configuration#skipwebfetchpreflight) set to `true`, or `WebFetch` added to [`disabledBuiltinTools`](https://claude.com/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.md#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](https://claude.com/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.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).
311* [SSH remote sessions](https://claude.com/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](https://claude.com/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](https://claude.com/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](https://claude.com/docs/third-party/claude-desktop/browser.md) contacts `releases.claude.com` for its [site safety check](https://claude.com/docs/third-party/claude-desktop/browser.md#site-safety-check).
315* With the [remote Microsoft 365 connector](https://claude.com/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.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.
317An app that receives its configuration from the [Enterprise Admin Console](https://claude.com/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](https://claude.com/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.md#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](https://claude.com/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.md#recommended-security-profiles) for a complete configuration.
321See the [Locked down profile](https://claude.com/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.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).
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](https://claude.com/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](https://claude.com/docs/third-party/claude-desktop/network-proxy.md#tls-intercepting-proxies).
326326
third-party/claude-desktop/unified-claude Changed · +5 / -5 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.md) 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](https://claude.com/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.md) 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](https://claude.com/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.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.
28* **MDM or a bootstrap server**: For MDM and bootstrap deployments, the [`desktopHome`](https://claude.com/docs/third-party/claude-desktop/configuration#desktophome) key controls Unified Claude. Create and set `desktopHome` to `standard` in your [MDM profile](https://claude.com/docs/third-party/claude-desktop/mdm.md) or [bootstrap response](https://claude.com/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
32When Unified Claude is enabled, Claude Desktop ignores [`chatTabEnabled`](/docs/third-party/claude-desktop/configuration#chattabenabled), [`chatAdvancedFileAnalysisEnabled`](/docs/third-party/claude-desktop/configuration#chatadvancedfileanalysisenabled), and [`coworkTabEnabled`](/docs/third-party/claude-desktop/configuration#coworktabenabled). New conversations follow the Cowork retention period. The Chat retention period still covers Chat conversations, such as earlier chats.
32When Unified Claude is enabled, Claude Desktop ignores [`chatTabEnabled`](https://claude.com/docs/third-party/claude-desktop/configuration#chattabenabled), [`chatAdvancedFileAnalysisEnabled`](https://claude.com/docs/third-party/claude-desktop/configuration#chatadvancedfileanalysisenabled), and [`coworkTabEnabled`](https://claude.com/docs/third-party/claude-desktop/configuration#coworktabenabled). New conversations follow the Cowork retention period. The Chat retention period still covers Chat conversations, such as earlier chats.
3333
34Your other settings still apply while `desktopHome` has a value, including [`isClaudeCodeForDesktopEnabled`](/docs/third-party/claude-desktop/configuration#isclaudecodefordesktopenabled), which controls Code.
34Your other settings still apply while `desktopHome` has a value, including [`isClaudeCodeForDesktopEnabled`](https://claude.com/docs/third-party/claude-desktop/configuration#isclaudecodefordesktopenabled), which controls Code.
3535
third-party/claude-desktop/vertex Changed · +11 / -11 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.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. |
16| Your organization already has tooling that obtains a bearer token accepted by Google Cloud's Agent Platform | [Credential helper](https://claude.com/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](https://claude.com/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 221
221221* If your IdP permits loopback redirect URIs on any port (the [RFC 8252](https://datatracker.ietf.org/doc/html/rfc8252#section-7.3) native-app pattern, supported by Microsoft Entra ID under the **Mobile and desktop applications** platform), register `http://127.0.0.1/callback` and leave `redirectPort` unset.
222222* If your IdP requires an exact registered redirect URI (such as Okta or PingFederate), set the `redirectPort` field of `inferenceVertexWorkforceOidc` to a fixed port and register the resulting URI exactly, for example `http://127.0.0.1:53180/callback`.
223223
224Register the redirect URI with `127.0.0.1` rather than `localhost`, because the app uses `127.0.0.1` by default and most IdPs do not treat the two as interchangeable. If your IdP accepts only `localhost` in a registered redirect URI, set the `redirectHost` field of [`inferenceVertexWorkforceOidc`](/docs/third-party/claude-desktop/configuration#inferencevertexworkforceoidc) to `localhost` and register `http://localhost/callback` instead, or `http://localhost:<port>/callback` when you set `redirectPort`.
224Register the redirect URI with `127.0.0.1` rather than `localhost`, because the app uses `127.0.0.1` by default and most IdPs do not treat the two as interchangeable. If your IdP accepts only `localhost` in a registered redirect URI, set the `redirectHost` field of [`inferenceVertexWorkforceOidc`](https://claude.com/docs/third-party/claude-desktop/configuration#inferencevertexworkforceoidc) to `localhost` and register `http://localhost/callback` instead, or `http://localhost:<port>/callback` when you set `redirectPort`.
225225
226226Distribute the workforce-pool provider audience and the IdP OIDC client in the managed configuration; the app shows a **Sign in** page on first launch, runs an authorization-code-with-PKCE flow against your IdP in the system browser, exchanges the returned ID token for a Google Cloud access token at `sts.googleapis.com`, and stores the IdP refresh token encrypted with the operating system's secure storage. No `gcloud` CLI, helper script, or Google identity is required.
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.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.
230When your IdP is Microsoft Entra ID, you can run this sign-in through the [OS identity broker](https://claude.com/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.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:
234With Google Cloud set up and devices prepared, open the [in-app configuration window](https://claude.com/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.md) 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](https://claude.com/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.md#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](https://claude.com/docs/third-party/claude-desktop/telemetry.md#inference-provider).
255255
256[Entry labels](/docs/third-party/claude-desktop/configuration.md#entry-labels) says what each label means.
256[Entry labels](https://claude.com/docs/third-party/claude-desktop/configuration.md#entry-labels) says what each label means.
257257
258258#### `inferenceVertexProjectId`
259259
from line 436
436436
437437If 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).
438438
439You 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).
439You must also set `inferenceModels` to a list of publisher model IDs, for example `claude-sonnet-5`. See the [Configuration reference](https://claude.com/docs/third-party/claude-desktop/configuration.md#inferencemodels).
440440
441441## What users experience
442442
from line 451
451451
452452## Troubleshoot
453453
454To 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).
454To 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](https://claude.com/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](https://claude.com/docs/third-party/claude-desktop/data-storage.md#where-data-lives).
455455
third-party/claude-desktop/web-tools Changed · +13 / -13 lines
from line 21
2121| Anthropic API | Available |
2222| Gateway | Available if your gateway implements Anthropic's `web_search` server tool, passes it through to a provider that does, or runs the search itself; see [Gateway-side search](#gateway-side-search) |
2323
24On Microsoft Foundry, Web Search works on both [hosting options](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options) with no additional configuration. Deployments hosted on Azure support only the basic web search tool version (`web_search_20250305`), which is the version Claude Desktop uses; see [features not supported when hosted on Azure](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#additional-features-not-supported-when-hosted-on-azure) in the Claude in Microsoft Foundry documentation for what else differs when hosted on Azure. On any provider you can configure the [built-in web search](#built-in-web-search) to choose the search backend yourself. Once it is configured, the app stops offering provider-side search and routes the model's search calls to the built-in server. If you want no web search at all, add `"WebSearch"` to [`disabledBuiltinTools`](/docs/third-party/claude-desktop/configuration#disabledbuiltintools) instead. That entry also blocks the built-in web search tool, so do not combine the two.
24On Microsoft Foundry, Web Search works on both [hosting options](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options) with no additional configuration. Deployments hosted on Azure support only the basic web search tool version (`web_search_20250305`), which is the version Claude Desktop uses; see [features not supported when hosted on Azure](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#additional-features-not-supported-when-hosted-on-azure) in the Claude in Microsoft Foundry documentation for what else differs when hosted on Azure. On any provider you can configure the [built-in web search](#built-in-web-search) to choose the search backend yourself. Once it is configured, the app stops offering provider-side search and routes the model's search calls to the built-in server. If you want no web search at all, add `"WebSearch"` to [`disabledBuiltinTools`](https://claude.com/docs/third-party/claude-desktop/configuration#disabledbuiltintools) instead. That entry also blocks the built-in web search tool, so do not combine the two.
2525
2626The [Claude apps gateway](https://code.claude.com/docs/en/claude-apps-gateway) passes the `web_search` tool through to its upstream provider, so Web Search works in Claude Desktop behind that gateway when the upstream is Google Cloud's Agent Platform, Microsoft Foundry, or the Anthropic API. Claude Desktop can't see which upstream the gateway routes to and offers the tool regardless, so if the gateway routes any model to Amazon Bedrock, configure the [built-in web search](#built-in-web-search), which replaces provider-side search on every route. To turn web search off instead, add `"WebSearch"` to `disabledBuiltinTools` in the gateway's [Claude Desktop overlay](https://code.claude.com/docs/en/claude-apps-gateway-config#claude-desktop-overlay). That entry also blocks the built-in web search tool if one is configured.
2727
from line 48
4848
4949#### Built-in web search
5050
51Add 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.
51Add the bundled `websearch` server to [`managedMcpServers`](https://claude.com/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.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.
53You can add it from the [in-app configuration window](https://claude.com/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
from line 95
9595}
9696```
9797
98Set the per-entry `toolPolicy` to `"allow"` so users aren't prompted to approve each search. `headersHelper` is an executable that prints the auth header as a JSON object to stdout; it follows the same execution model as [`inferenceCredentialHelper`](/docs/third-party/claude-desktop/credential-helper) (exit 0, stdout read as JSON), but the output here is a flat header map, not the `{token, headers}` shape `inferenceCredentialHelper` uses.
98Set the per-entry `toolPolicy` to `"allow"` so users aren't prompted to approve each search. `headersHelper` is an executable that prints the auth header as a JSON object to stdout; it follows the same execution model as [`inferenceCredentialHelper`](https://claude.com/docs/third-party/claude-desktop/credential-helper) (exit 0, stdout read as JSON), but the output here is a flat header map, not the `{token, headers}` shape `inferenceCredentialHelper` uses.
9999
100100| Provider | Header your script should output |
101101| - | - |
from line 122
122122
123123#### Data handling
124124
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.
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](https://claude.com/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.
126126
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.
127For audit, each search the model runs is recorded in the Cowork or Code session telemetry sent to your [OTLP collector](https://claude.com/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`](https://claude.com/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`](https://claude.com/docs/third-party/claude-desktop/configuration#otlpdesktoploglevel) is `info` or `debug`, not at the default `error` level.
128128
129129> [!NOTE]
130130>
from line 146
146146
147147> [!NOTE]
148148>
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.
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](https://claude.com/docs/third-party/claude-desktop/telemetry.md#required-egress-paths) for the distinction.
150150
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.
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](https://claude.com/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.
152152
153153If 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.
154154
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.
155In [Code](https://claude.com/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`](https://claude.com/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.
156156
157157### How the egress allowlist applies in Code sessions
158158
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:
159In [Code](https://claude.com/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](https://claude.com/docs/third-party/claude-desktop/code.md#interaction-with-claude-code%E2%80%99s-own-managed-settings) take precedence:
160160
161161* **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).
162* **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).
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).
162* **Web Fetch controls**: to have the user approve every fetch, set `WebFetch` to `"ask"` in [`builtinToolPolicy`](https://claude.com/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).
163* **Shell commands**: commands that run in [Claude Code's sandbox](https://claude.com/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](https://claude.com/docs/third-party/claude-desktop/code.md#disabling-code). For SSH hosts, see [Sandbox status on the remote host](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions.md#sandbox-status-on-the-remote-host).
164164
165165## Disabling web tools
166166
from line 172
172172
173173With 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.
174174
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).
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](https://claude.com/docs/third-party/claude-desktop/configuration.md#recommended-security-profiles).
176176
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.md).
33* **Review**: findings from [the reviewer](https://claude.com/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.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.
9> This page covers comments on [artifacts in the Claude Science app](https://claude.com/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.md#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](https://claude.com/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.md). By default, Claude asks with a [permission card](/docs/claude-science/core-concepts.md#permission-cards) before it runs code or installs packages.
11Copy the prompt and paste it into a new session in [Claude Science](https://claude.com/docs/claude-science/overview.md). By default, Claude asks with a [permission card](https://claude.com/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.md). By default, Claude asks with a [permission card](/docs/claude-science/core-concepts.md#permission-cards) before it runs code or installs packages.
11Copy the prompt and paste it into a new session in [Claude Science](https://claude.com/docs/claude-science/overview.md). By default, Claude asks with a [permission card](https://claude.com/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.md). By default, Claude asks with a [permission card](/docs/claude-science/core-concepts.md#permission-cards) before it runs code or installs packages.
11Copy the prompt and paste it into a new session in [Claude Science](https://claude.com/docs/claude-science/overview.md). By default, Claude asks with a [permission card](https://claude.com/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.md). By default, Claude asks with a [permission card](/docs/claude-science/core-concepts.md#permission-cards) before it runs code or installs packages.
11Copy the prompt and paste it into a new session in [Claude Science](https://claude.com/docs/claude-science/overview.md). By default, Claude asks with a [permission card](https://claude.com/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.md). By default, Claude asks with a [permission card](/docs/claude-science/core-concepts.md#permission-cards) before it runs code or installs packages.
11Copy the prompt and paste it into a new session in [Claude Science](https://claude.com/docs/claude-science/overview.md). By default, Claude asks with a [permission card](https://claude.com/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.md). By default, Claude asks with a [permission card](/docs/claude-science/core-concepts.md#permission-cards) before it runs code or installs packages.
11Copy the prompt and paste it into a new session in [Claude Science](https://claude.com/docs/claude-science/overview.md). By default, Claude asks with a [permission card](https://claude.com/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.md). By default, Claude asks with a [permission card](/docs/claude-science/core-concepts.md#permission-cards) before it runs code or installs packages.
11Copy the prompt and paste it into a new session in [Claude Science](https://claude.com/docs/claude-science/overview.md). By default, Claude asks with a [permission card](https://claude.com/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.