claude-docs-20261106T213705Z / documentation capture

third-party/claude-desktop/connectors-m365 Changed · +4 / -2 lines

from line 406

406406> ms-appx-web://Microsoft.AAD.BrokerPlugin/APPLICATION_CLIENT_ID

407407> ```

408408>

409> If a brokered attempt fails with an error the broker cannot recover from, the connector falls back to the system browser automatically and stays on the browser flow until Claude Desktop restarts. A user canceling the broker dialog does not trigger the fallback. On tenants that require a compliant device, tool calls then fail with `AADSTS53003`, unless the browser itself carries the device identity (see above); fix the broker requirement that caused the fallback and restart the app. A fallback is recorded in the connector's log file as a `local_auth_broker_fallback` event.

409> If a brokered attempt fails with an error the broker cannot recover from, the connector falls back to the system browser automatically.

410410>

411411> A missing broker redirect URI does not trigger the fallback on Windows. The broker shows Entra error `AADSTS50011` in its own sign-in dialog, and closing that dialog counts as canceling, so every sign-in attempt ends at the same error until you register the URI above. To have users sign in through the browser instead of the broker, set [`microsoftAuthBroker`](https://claude.com/docs/third-party/claude-desktop/configuration#microsoftauthbroker) to `disabled` in the managed configuration. Tokens from browser sign-in carry no device identity claim unless the browser itself provides one (see above), so device-based Conditional Access policies block them.

412412>

from line 427

427427>

428428> If the app registration also lists `msauth.com.anthropic.claudefordesktop.helper://auth`, remove that entry. Claude Desktop does not use it.

429429>

430> If the broker rejects the app's sign-in request, or a brokered attempt fails with an error the broker cannot recover from, the connector falls back to the system browser automatically and stays on the browser flow until Claude Desktop restarts. A user canceling the broker dialog does not trigger the fallback. On tenants that require a compliant device, tool calls then fail with `AADSTS53003`, unless the browser itself is signed in through the device's SSO integration; fix the broker requirement that caused the fallback (most often a missing broker redirect URI or SSO profile) and restart the app. A fallback is recorded in the connector's log file as a `local_auth_broker_fallback` event.

430> If the broker rejects the app's sign-in request, or a brokered attempt fails with an error the broker cannot recover from, the connector falls back to the system browser automatically. A fallback most often comes from a missing broker redirect URI or SSO profile.

431

432After a brokered attempt falls back to the system browser, the connector stays on the browser flow until Claude Desktop restarts. On tenants that require a compliant device, tool calls then fail with `AADSTS53003`, unless the browser itself carries the device identity. Fix the broker requirement that caused the fallback, then restart the app. A fallback is recorded in the connector's log file as a `local_auth_broker_fallback` event. A user canceling the broker dialog doesn't trigger the fallback.

431433

432434### Token storage and sign-out

433435

third-party/claude-desktop/extensions Changed · +4 / -4 lines

from line 87

8787

8888Tokens are stored on the device, encrypted with the operating system's secure storage (see [Credentials](https://claude.com/docs/third-party/claude-desktop/data-storage.md#credentials)), and refreshed in the background before they expire. When the authorization request carries a scope and the authorization server's metadata lists `offline_access`, Claude Desktop adds `offline_access` so that a refresh token is issued; see `oauth.scope` and `oauth.appendOfflineAccess` in the [configuration reference](https://claude.com/docs/third-party/claude-desktop/configuration.md#managedmcpservers) to change the requested scopes. If the authorization server rejects the refresh token or the client, for example with `invalid_grant` or `invalid_client`, the MCP server's row under **Customize → Connectors** shows a **Reconnect** button. The row also shows **Reconnect** when a sign-in through the system browser returned no refresh token and the access token expires. The user selects **Reconnect** to sign in again. For a refresh that the authorization server refuses with another error while the server is connected, see [Troubleshoot sign-in](https://claude.com/docs/third-party/claude-desktop/mcp-sign-in.md#troubleshoot-sign-in). A stored sign-in belongs to the server's `url`, so after you change the `url`, each user signs in again.

8989

90If sign-in fails (the callback does not arrive within 120 seconds, the authorization server rejects the registration or the redirect URI, or the identity provider completes sign-in from a host other than the authorization endpoint's), the user sees a connection error, the server keeps its **Connect** or **Reconnect** button, and `main.log` in the [logs directory](https://claude.com/docs/third-party/claude-desktop/data-storage.md#where-data-lives) records the reason. For an identity provider that completes sign-in from a different host than its authorization endpoint, list that host in `oauth.additionalRedirectReferrerHosts`. The log names the rejected host.

90If sign-in fails (the callback does not arrive within 120 seconds, the authorization server rejects the registration, or the identity provider completes sign-in from a host other than the authorization endpoint's), the user sees a connection error, the server keeps its **Connect** or **Reconnect** button, and `main.log` in the [logs directory](https://claude.com/docs/third-party/claude-desktop/data-storage.md#where-data-lives) records the reason. When the authorization server rejects the redirect URI at its authorization endpoint, `main.log` records the callback timeout. For an identity provider that completes sign-in from a different host than its authorization endpoint, list that host in `oauth.additionalRedirectReferrerHosts`. The log names the rejected host.

9191

9292For a server whose OAuth sign-in goes to Microsoft Entra ID, you can run that sign-in through the [OS identity broker](https://claude.com/docs/third-party/claude-desktop/entra-broker.md) instead of the system browser by setting `authFlow` to `broker` inside the entry's `oauth` object, alongside `tenantId`, `clientId`, and `scope`. On a device where the broker is unavailable, sign-in for that server falls back to the system browser, so keep the loopback redirect URI registered as well if any devices lack the broker.

9393

from line 140

140140

141141A **plugin marketplace** is a catalog file (`marketplace.json`) that lists one or more Claude plugins. You host it either as a git repository or as a plain file over HTTPS. Claude Desktop fetches it on each device, lists its plugins under **Customize → Plugins → Discover → Organization** in both **Cowork** and [**Code**](https://claude.com/docs/third-party/claude-desktop/code.md), and keeps them in sync with the revision you pin. You control which plugins are available, which install automatically, and which are required.

142142

143This is the recommended way to distribute organization plugins. Claude Desktop clones a git-hosted marketplace with the git already installed on each device, so include git in your device baseline: Git for Windows on Windows, and the Xcode Command Line Tools on macOS. Devices without git can use a [marketplace hosted over HTTPS](#host-the-marketplace-over-https-instead-of-git) instead. Use the [system-wide directory](#organization-plugins-admin) path when end-user devices cannot reach a git server or an HTTPS file host.

143This is the recommended way to distribute organization plugins. Claude Desktop clones a git-hosted marketplace with the git already installed on each device, so include git in your device baseline: Git for Windows on Windows, the Xcode Command Line Tools on macOS, and the `git` package on Linux. Devices without git can use a [marketplace hosted over HTTPS](#host-the-marketplace-over-https-instead-of-git) instead. On macOS and Windows, use the [system-wide directory](#organization-plugins-admin) path when end-user devices cannot reach a git server or an HTTPS file host.

144144

145145### Create the marketplace repository

146146

from line 325

325325| macOS | `/Library/Application Support/Claude/org-plugins/` |

326326| Windows | `C:\Program Files\Claude\org-plugins\` |

327327

328On Windows, the directory is under `Program Files` (not `ProgramData`) so that only administrators can create or modify it. Claude Desktop treats the presence of this directory as an admin-provisioned source.

328On Windows, the directory is under `Program Files` (not `ProgramData`) so that only administrators can create or modify it. Claude Desktop treats the presence of this directory as an admin-provisioned source. On Linux, Claude Desktop reads no organization plugins directory, so use a [plugin marketplace](#plugin-marketplaces-admin) there.

329329

330330### Plugin structure

331331

from line 572

572572

573573The app sends the text of the skill's files to a Claude model on your organization's own inference provider, using the same credential that the user's sessions use.

574574

575How well a scan detects a malicious skill depends on the model that runs it. A scan runs on one model from your organization's [model list](https://claude.com/docs/third-party/claude-desktop/models.md#model-list-and-default-model). Claude Desktop prefers an Opus model, then a Sonnet model, then a Haiku model, but only among the models it can recognize. It recognizes a model when the model ID contains "opus", "sonnet", or "haiku", or when you set `anthropicFamilyTier` on that model in [`inferenceModels`](https://claude.com/docs/third-party/claude-desktop/configuration#inferencemodels). If your model IDs are a gateway's route names, Claude Desktop may not recognize them, so set `anthropicFamilyTier` on each model. If Claude Desktop recognizes none of your models, it still runs the scan on another model from the list.

575How well a scan detects a malicious skill depends on the model that runs it. A scan runs on one model from your organization's [model list](https://claude.com/docs/third-party/claude-desktop/models.md#model-list-and-default-model). Claude Desktop prefers an Opus model, then a Sonnet model, then a Haiku model, but only among the models it can recognize. It recognizes a model when the model ID contains "opus", "sonnet", or "haiku", or when you set `anthropicFamilyTier` on that model in [`inferenceModels`](https://claude.com/docs/third-party/claude-desktop/configuration#inferencemodels). If your model IDs are a gateway's route names, Claude Desktop may not recognize them, so set `anthropicFamilyTier` on the model that should run scans. `anthropicFamilyTier` also makes that model [stand in for its tier](https://claude.com/docs/third-party/claude-desktop/configuration.md#inferencemodels) in Cowork and Code sessions. If Claude Desktop recognizes none of your models, it still runs the scan on another model from the list.

576576

577577Your organization pays its inference provider for scans. A scan's tokens count toward the user's [token limit](https://claude.com/docs/third-party/claude-desktop/configuration.md#inferencemaxtokensperwindow).

578578

third-party/claude-desktop/gateway Changed · +4 / -4 lines

from line 9

99* `POST /v1/messages` with [streaming](https://docs.claude.com/en/api/streaming) and [tool use](https://docs.claude.com/en/docs/tool-use) is required.

1010* `GET /v1/models` is optional. If the gateway implements it, Claude Desktop on 3P auto-discovers available models; if not, set `inferenceModels` explicitly.

1111

12The gateway should also preserve [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching). Cowork and Code sessions send `cache_control` breakpoints with each turn so that the provider can reuse the tool definitions, system prompt, and earlier turns of the conversation instead of reprocessing them. A gateway that forwards these fields, or translates them for its upstream provider, keeps that behavior. A gateway that strips `cache_control`, or that changes the system prompt or tool list from one request to the next, makes the provider reprocess the whole conversation on every turn at full input-token cost and higher latency. To verify, check the [usage fields](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#tracking-cache-performance) your gateway returns or logs for Claude Desktop traffic: after the first request of a session, `cache_read_input_tokens` should be well above zero on most requests. If it is zero on every request, review the gateway's request transformation and caching settings for the route that serves Claude models.

12The gateway should also preserve [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching). Chat, Cowork, and Code sessions send `cache_control` breakpoints with each turn so that the provider can reuse the tool definitions, system prompt, and earlier turns of the conversation instead of reprocessing them. A gateway that forwards these fields, or translates them for its upstream provider, keeps that behavior. A gateway that strips `cache_control`, or that changes the system prompt or tool list from one request to the next, makes the provider reprocess the whole conversation on every turn at full input-token cost and higher latency. To verify, check the [usage fields](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#tracking-cache-performance) your gateway returns or logs for Claude Desktop traffic: after the first request of a session, `cache_read_input_tokens` should be well above zero on most requests. If it is zero on every request, review the gateway's request transformation and caching settings for the route that serves Claude models.

1313

14In each response's `usage`, return the provider's `cache_creation` object with its `ephemeral_5m_input_tokens` and `ephemeral_1h_input_tokens` fields. Without that object, the [API request event](https://claude.com/docs/cowork/monitoring.md#api-request-event) in your OpenTelemetry export reports `0` for both `cache_creation_5m_tokens` and `cache_creation_1h_tokens`.

14In Chat and Cowork, the main conversation's breakpoints ask for a one-hour lifetime (`"ttl": "1h"`). In each response's `usage`, return the provider's `cache_creation` object with its `ephemeral_5m_input_tokens` and `ephemeral_1h_input_tokens` fields. Without that object, the [API request event](https://claude.com/docs/cowork/monitoring.md#api-request-event) in your OpenTelemetry export reports `0` for both `cache_creation_5m_tokens` and `cache_creation_1h_tokens`.

1515

1616## Choose an authentication approach

1717

from line 525

525525

526526If your gateway serves Claude models under routing aliases, list each alias in `inferenceModels` and set `behavesAs` on its entry to the ID of the Claude model it routes to, such as `claude-sonnet-5`. For an alias without a model version, users then get that model's **Effort** control, and sessions assume that model's context window. Requires Claude Desktop 4.29.0 or later. For an alias that contains a model version, see [Map an unrecognized model ID to a Claude model](https://claude.com/docs/third-party/claude-desktop/models.md#map-an-unrecognized-model-id-to-a-claude-model).

527527

528Your gateway can mark which Claude tier a model serves by returning an `anthropic_family_tier` field (a tier name such as `sonnet` or `opus`) on that model object in its `/v1/models` response, optionally with `is_family_default: true` when several models map to the same tier. The app uses the marked model when it needs that tier, for example to resolve a bare `sonnet` alias. The app also reads other optional fields on each model object. `display_name` sets the picker label when the app cannot derive one from the model ID. `description` adds a one-line description beneath the label (Claude Desktop 1.49585.0 or later). `supports_1m: true`, or a `max_input_tokens` value of 1,000,000 or more, marks a discovered model as supporting the 1M-token context window, as `supports1m` does on an `inferenceModels` entry.

528Your gateway can mark which Claude tier a model serves by returning an `anthropic_family_tier` field (a tier name such as `sonnet` or `opus`) on that model object in its `/v1/models` response, optionally with `is_family_default: true` when several models map to the same tier. The app and its sessions use the marked model when they need that tier, such as for a sub-agent that asks for `sonnet`, even if the user picked another model. The app also reads other optional fields on each model object. `display_name` sets the picker label when the app cannot derive one from the model ID. `description` adds a one-line description beneath the label (Claude Desktop 1.49585.0 or later). `supports_1m: true`, or a `max_input_tokens` value of 1,000,000 or more, marks a discovered model as supporting the 1M-token context window, as `supports1m` does on an `inferenceModels` entry.

529529

530530If your gateway doesn't implement `GET /v1/models`, give every `inferenceModels` entry the full model ID your gateway accepts. When every entry is a full model ID, the app skips the `/v1/models` call automatically. A bare tier alias such as `sonnet` can't be resolved without discovery, so a list that contains one keeps discovery on. On earlier app versions that don't skip the call automatically, also set [`modelDiscoveryEnabled`](https://claude.com/docs/third-party/claude-desktop/configuration#modeldiscoveryenabled) to `false`. If discovery stays on, a gateway that answers the call with an error makes the app fall back to the `inferenceModels` list immediately. A gateway that accepts the call and hangs delays the model list by up to 10 seconds at launch.

531531

third-party/claude-desktop/installation Changed · +4 / -3 lines

from line 18

1818

1919Check these on Windows devices before rollout:

2020

21* **Apps from outside the Microsoft Store**: make sure Windows policy allows trusted app packages to install from outside the Microsoft Store. If your security baseline configures **Allow all trusted apps to install** (the `ApplicationManagement/AllowAllTrustedApps` policy), set it to enabled. Windows Developer Mode isn't required. If provisioning the `.msix` package fails with error `0x80073CFF`, check this policy.

2122* **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).

2223* **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).

2324* **Virtual desktops**: on virtual desktop infrastructure, Windows itself runs in a virtual machine, so Cowork's virtual machine starts only where the hosting platform exposes nested virtualization to that virtual machine. Run the [readiness check](#check-device-readiness) on one desktop in each pool.

from line 245

244245

245246By default, Claude Desktop downloads updates from Anthropic's update server automatically. On macOS and Windows, it then restarts itself to install the update after 10 minutes with no Claude window in use and no task running. On macOS it reopens by itself; on Windows, it may stay closed until someone opens it.

246247

247If the update still isn't installed 72 hours after the download, the app restarts itself, waiting for 10 minutes of user inactivity before doing so. This enforcement is always on and offers no in-app prompt to defer the restart; the `autoUpdaterEnforcementHours` key tunes the 72-hour window rather than enabling it. With or without the key, the restart waits while Claude is working on a task or the update server gives no answer.

248If the update still isn't installed 72 hours after the download, the app restarts itself, waiting for 10 minutes of user inactivity before doing so. This enforcement is always on and offers no in-app prompt to defer the restart; the `autoUpdaterEnforcementHours` key tunes the 72-hour window rather than enabling it. The hours count only while the app is open and the computer is awake. With or without the key, the restart waits while Claude is working on a task or the update server gives no answer.

248249

249250In 3P deployments you can:

250251

from line 255

254255

255256> [!WARNING]

256257>

257> `stable` is the default. Moving a device from `staggered` to `stable` updates it to a newer release, and setting `staggered` again doesn't move it back to the older one. Removing `releaseChannel`, or setting it only where the device doesn't read it, does the same.

258> `stable` is the default. Moving a device from `staggered` to `stable` updates it to a newer release, and setting `staggered` again doesn't move it back to the older one. Removing `releaseChannel`, or setting it only where the device doesn't read it, does the same. A device on `staggered` that's ahead of the `staggered` release gets no updates until `staggered` passes its version.

258259

259260Set `releaseChannel` in:

260261

261262* **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

262* **A [bootstrap server](https://claude.com/docs/third-party/claude-desktop/bootstrap.md)**: return the key from the server

263* **A [bootstrap server](https://claude.com/docs/third-party/claude-desktop/bootstrap.md)**: return the key from the server, because [its response replaces the value in the profile that sets `bootstrapUrl`](https://claude.com/docs/third-party/claude-desktop/configuration-format#which-configuration-source-applies-on-a-device)

263264* **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**

264265* **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

265266

third-party/claude-desktop/admin-console Changed · +2 / -2 lines

from line 136

136136

137137#### When a helper script is the right choice

138138

139Choose **Helper script** for Bedrock Mantle, or when the credential for your gateway or provider can only come from tooling that runs on the device, such as an internal secret broker. The console stores the script's path, not the script, and the same path goes to every device in the organization. Install the script at that absolute path on every device through your software distribution, in a location that users can't modify, for example `/usr/local/bin/corp-cred-helper` on a macOS fleet or `C:\Program Files\Corp\cred-helper.cmd` on a Windows fleet. Claude Desktop runs the script under the user's operating-system account, so anything that differs per user, such as reading that user's home folder or keychain, belongs inside the script.

139Choose **Helper script** for Bedrock Mantle, or when the credential for your gateway or provider can only come from tooling that runs on the device, such as an internal secret broker. The console stores the script's path, not the script. Install the script at that absolute path on every device through your software distribution, in a location that users can't modify, for example `/usr/local/bin/corp-cred-helper` on a macOS fleet or `C:\Program Files\Corp\cred-helper.cmd` on a Windows fleet. For a fleet of macOS and Windows devices, put the Windows path in **Helper script (Windows)**. Windows devices run that script in place of the one in **Helper script**. Claude Desktop runs the script under the user's operating-system account, so anything that differs per user, such as reading that user's home folder or keychain, belongs inside the script.

140140

141141#### Managed MCP servers that need authentication

142142

from line 473

473473

474474On a device whose profile sets only [app-behavior keys](https://claude.com/docs/third-party/claude-desktop/mdm.md#update-keys-and-managed-precedence), the profile's values apply instead of the console's for all of those keys. Any of those keys that the profile leaves out runs its default, as described under [Update keys and managed precedence](https://claude.com/docs/third-party/claude-desktop/mdm.md#update-keys-and-managed-precedence).

475475

476While a device whose profile sets any other key is on the admin console's configuration, the app still takes these from the profile:

476While a device whose profile sets any other key, such as `forceLoginOrgUUID`, is on the admin console's configuration, the app still takes these from the profile:

477477

478478* The [network proxy keys](https://claude.com/docs/third-party/claude-desktop/network-proxy.md#pin-a-proxy-from-managed-configuration).

479479* [`isLocalDevMcpEnabled`](https://claude.com/docs/third-party/claude-desktop/configuration#islocaldevmcpenabled) set to `false`, for local (stdio) servers in the console's managed MCP servers only. The app starts such a server only if the profile's own [`managedMcpServers`](https://claude.com/docs/third-party/claude-desktop/configuration#managedmcpservers) lists a local (stdio) server of the same name, and it uses the profile's command, arguments, and environment. The profile's value doesn't block local MCP servers that users add. To keep blocking them, turn off **Allow local MCP servers** on the console's **Connectors** page.

third-party/claude-desktop/code Changed · +1 / -1 lines

from line 78

7878}

7979```

8080

81With `"merge"`, Claude Desktop's policy values are layered under your Claude Code policy. Your values win any conflict, deny and allow lists are unioned, and Claude Desktop's values are filtered so they can only tighten policy, never loosen it. See [`parentSettingsBehavior`](https://code.claude.com/docs/en/settings-reference#parentsettingsbehavior) in the Claude Code settings reference. Requires Claude Code v2.1.133 or later, which ships with Claude Desktop on 3P.

81With `"merge"`, Claude Desktop's policy values are layered under your Claude Code policy. For how Claude Code combines the two policies, see [Let an embedding host add policy](https://code.claude.com/docs/en/managed-settings#let-an-embedding-host-add-policy) in the Claude Code documentation. Requires Claude Code v2.1.133 or later, which ships with Claude Desktop on 3P.

8282

8383With `"merge"`, two Claude Code policy keys weaken `blockReadsOutsideWorkingDirectories`. `sandbox.filesystem.allowManagedReadPathsOnly` limits the block to Claude's file tools, so a shell command that reads outside the working directories asks for approval instead of failing, and `allowManagedPermissionRulesOnly` removes the session's read access to its plugin and attachment folders, so skills that read their own files stop working. Leave both out of your Claude Code policy if you rely on the block.

8484

third-party/claude-desktop/configuration Changed · +2 / -2 lines

from line 1139

11391139>

11401140> Each entry is a model ID string or an object:

11411141>

1142> ```json theme={null}

1142> ```json theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

11431143> [

11441144> {"name": "claude-sonnet-5",

11451145> "supports1m": true},

from line 3925

39253925

39263926### Recommended security profiles

39273927

3928The profiles below are illustrative examples rather than built-in presets, and the labels are descriptive only. Use them as starting points and adjust for your environment. Layer the inference-provider keys for your cloud on top of whichever profile you choose.

3928These profiles are examples, not built-in presets. Adjust them for your environment, and add the inference-provider keys for your cloud to the profile you choose.

39293929

39303930> [tab] Standard

39313931>

third-party/claude-desktop/configuration-format Changed · +1 / -1 lines

from line 60

6060

6161### Value types in a profile or registry policy

6262

63Write every value as a **string** in the OS preference store, even booleans and arrays. This rule applies to plist and registry sources. [The Linux file](#the-linux-configuration-file) and a [bootstrap response](https://claude.com/docs/third-party/claude-desktop/bootstrap.md#response-schema) take JSON values. Each key's entry in the [configuration reference](https://claude.com/docs/third-party/claude-desktop/configuration.md) gives the key's type and the values or fields it accepts.

63In a plist or registry source, every value can be a **string**, even booleans and arrays. The app also reads a native boolean or integer (`<true/>`, `<false/>`, or `<integer>` in a profile, `REG_DWORD` in the registry), which is what its own export writes. [The Linux file](#the-linux-configuration-file) and a [bootstrap response](https://claude.com/docs/third-party/claude-desktop/bootstrap.md#response-schema) take JSON values. Each key's entry in the [configuration reference](https://claude.com/docs/third-party/claude-desktop/configuration.md) gives the key's type and the values or fields it accepts.

6464

6565| Documented type | What to write | Example |

6666| - | - | - |

third-party/claude-desktop/credential-helper Changed · +1 / -1 lines

from line 17

1717Stdout must contain exactly one of the following, with no banners, prompts, or log lines mixed in:

1818

1919* **A single bare token.** The whole trimmed stdout becomes the bearer token.

20* **A JSON object**, when per-request headers are needed:

20* **A JSON object**, when the helper also supplies request headers:

2121

2222 ```json theme={null}

2323 { "token": "...", "headers": { "X-Org-Route": "prod" } }

third-party/claude-desktop/data-storage Changed · +2 / -2 lines

from line 318

318318 Also leave out `plugin-mcp-auth/` and `connectors/*/plugin-mcp/`, which on Windows and Linux hold the user's sign-ins to plugin servers. The user signs in to those servers again on the new device.

319319

320320 If you copied any of these files or folders, quit Claude Desktop on the new device, then delete them.

321 * `~/Claude/`, or `~/Documents/Claude/` on legacy installs

321 * The user's Cowork files folder: `~/Claude/`, or `~/Documents/Claude/` on legacy installs. If the user changed it, note the folder shown under **Cowork files** in **Settings > Cowork** on the old device before step 1, and copy that folder instead.

322322 * `~/.claude/` and `~/.claude.json`

323323 * The folders and repositories that the user's projects, scheduled tasks, and Code sessions use

3244. Make the user the owner of the copied files, with read and write access. Give no other user account access to the application-data directory, `~/Claude/` or `~/Documents/Claude/`, `~/.claude/`, or `~/.claude.json`.

3244. Make the user the owner of the copied files, with read and write access. Give no other user account access to the application-data directory, the user's Cowork files folder, `~/.claude/`, or `~/.claude.json`.

3253255. Have the user launch Claude Desktop, sign in if the app asks, and confirm that their chats, Cowork tasks, Code sessions, and projects appear. If any are missing, check that:

326326 * The user owns the copied files

327327 * The [`ant-did`](#identity) file in the application-data directory has the same contents as on the old device. If it doesn't, start again from step 1.

third-party/claude-desktop/models Changed · +2 / -0 lines

from line 39

3939

4040[`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.

4141

42In Code, the `CLAUDE_CODE_EFFORT_LEVEL` environment variable or `effortLevel` in Claude Code's settings takes priority.

43

4244`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.

4345

4446### Map an unrecognized model ID to a Claude model

third-party/claude-desktop/network-proxy Changed · +2 / -2 lines

from line 97

9797

9898## Traffic that bypasses the app proxy

9999

100Some traffic never uses the pinned key or the proxy the app resolved.

100Some traffic doesn't follow the pinned key or the proxy the app resolved, or follows them only in some cases.

101101

102102* **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.

103103* **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.

from line 160

160160

161161## TLS-intercepting proxies

162162

163If your proxy performs TLS interception, it presents its own certificate authority. The app trusts the operating system's certificate store. On macOS, the app also configures the agent to trust the System keychain in addition to the bundled CA roots, so a corporate CA installed there normally works without extra setup.

163If your proxy performs TLS interception, it presents its own certificate authority. The app trusts the operating system's certificate store. On macOS, the app also configures the agent to trust the System keychain in addition to the bundled CA roots, so a corporate CA installed there normally works without extra setup. To clone a [git plugin marketplace](https://claude.com/docs/third-party/claude-desktop/extensions.md#plugin-marketplaces-admin), the app runs the device's `git`, which reads git's system-level configuration, not the user's own.

164164

165165If inference or tool requests still fail certificate verification, the CA was likely added with policy-restricted trust: certificates installed via `security add-trusted-cert -p ssl …` are trusted by Safari and Chrome but are not picked up by the agent's keychain reader. Re-add the CA with full root trust (omit `-p`):

166166

third-party/claude-desktop/telemetry Changed · +1 / -1 lines

from line 42

4242

4343| Setting | Default | Effect when `true` |

4444| - | - | - |

45| `disableNonessentialServices` | `false` | Favicon, artifact-preview, and MCP App widget fetches are blocked. In place of an MCP App widget, the conversation shows "There was a problem displaying content from" and the connector's name. On Linux, the setting also applies to the spellcheck dictionary download. Without the dictionary, misspelled words aren't underlined. |

45| `disableNonessentialServices` | `false` | Favicon, artifact-preview, and MCP App widget fetches are blocked. In place of an MCP App widget, the conversation shows "There was a problem displaying content from" and the connector's name. On Linux, the setting also applies to the spellcheck dictionary download. Without the dictionary, misspelled words aren't underlined. In Code sessions, the app doesn't read the status of GitLab merge requests or Gerrit changes. GitHub pull requests aren't affected. |

4646

4747### Auto-updates

4848

One read of Claude Documentationclaude-docs-20261106T213705Z

What this read moved