Capture
One read of Claude Documentation
9 pages moved out of 217 read.
cowork/changelog Changed · +46 / -0 lines
from line 2
> Release notes for Claude Desktop +<Update label="v1.40609.0" description="2026-08-27"> + **General** + + * Fixed Claude sometimes being unable to read or search a page in the built-in browser just after opening it or while it was still loading, and browser screenshots and interactions timing out or stalling on Windows and Linux while the browser pane was closed or another page was selected. + * Fixed the app failing to launch when one of its settings files had become corrupted, and settings files sometimes being left corrupt after an unexpected shutdown or power loss on Windows. + * Fixed the Share dialog: "Keep private" now takes effect immediately, and sharing a chat while offline shows an error instead of waiting indefinitely. + * Fixed typing with an IME (Japanese, Chinese, or Korean): confirming or cancelling a conversion with Enter, Escape, or a digit key no longer sends half-composed text, discards typed drafts, denies tool approvals, rejects plans, or stops Claude's response in Code sessions, and no longer commits or discards text in the browser pane's address field. + * Fixed scheduled tasks that run on this computer occasionally being marked as skipped without running; a run the app fails to pick up is now retried a few minutes later. + + **Code** + + * Added side-task suggestions in cloud sessions: Claude can suggest follow-up tasks that you start on your machine, in the cloud, or in the same session with one click. + * Added `/resume`: search the Claude Code sessions started from your terminal on this computer and continue one in the app on the same transcript. + * Added a view of the session's MCP servers: type `/mcp` in a local session to see the servers from `.mcp.json`, `~/.claude.json`, plugins, and your claude.ai connectors, with live status and Connect, Reconnect, and Re-authenticate actions. + * Fixed "Import Claude Code CLI sessions" (Help > Troubleshooting): it again finds Code sessions whose sidebar entries were lost after a reinstall or repair, no longer rewrites a session file that a running Claude Code process is still using, and saves a backup of the original transcript when importing removes its thinking blocks. + * Fixed inline plan comments being silently lost when left after a plan was approved; the Plan pane now accepts comments in Plan mode or while Claude is asking you to approve the plan, and says when commenting opens otherwise. + * Fixed SSH sessions losing messages that were waiting to be sent when the remote host became unreachable or the app was quit, updated, or restarted; they are now kept and delivered automatically at the next connection, and Claude Code is restarted on the host when needed. + * Improved SSH session reconnects: high-latency links no longer drop their own connection, a network change mid-stream is noticed within seconds, an unreachable host is no longer re-dialed every few seconds in the background, and the session shows the specific connection error with a Try again button instead of a generic message or an indefinite "Reconnecting…". + + **Cowork** + + * Fixed files dropped onto the composer together with a folder being discarded; they now attach alongside the folder. + * Fixed shell commands that use plugin or skill file paths failing with "No such file or directory". + * Fixed the app running out of memory after many scheduled task runs. + * Fixed the Cowork readiness check appearing to hang for minutes when a network-redirected profile folder is unreachable, and reporting a computer as unsupported because of an encrypted leftover folder from an uninstalled Claude version. + * Fixed organization plugins failing to install or update on some Windows Store installs. + * Fixed a message that starts with a typed, pasted, or app-filled slash command for one of your enabled skills failing with "Unknown skill" in an existing task; it now sends. + + **3P** + + * Added `relaunchEnforcementHours` (served configuration only): when a served configuration change needs a restart, it sets how many hours (0 to 336) users may keep running on the previous configuration; at the deadline Claude shows a restart dialog and restarts on its own after 2 minutes of inactivity. Unset means 1 hour. + * Added `sshHostAllowlist` (beta): admins can turn on SSH remote sessions in the Code tab by listing the hosts users may connect to (`["*"]` allows any host). Unset keeps SSH sessions off unless a Claude Code managed-settings file on the device already allows hosts; an explicit `[]` keeps them off even then when the configuration is admin-delivered (device management or trusted remote delivery), while on a self-configured install the device allowlist still applies. Works with a gateway, Claude API key, or Foundry, and with Bedrock and Vertex when they use token-based credentials; file-based credential kinds are refused at session start with a message naming the kind. + * Added an estimated-cost view to the Usage page chart: when the organization has turned on cost estimates, the chart can switch between tokens and estimated cost per day (per week at 90 days), and days with turns that have no estimate show as gaps rather than \$0. + * Added an in-app warning when the organization's configuration uses a deprecated field: each user sees a dismissible notice from September 10, 2026 and once more in the 24 hours before the field stops being accepted, with a Details dialog naming each field, its replacement, the cut-off date and what changes then, plus a Copy report button that puts a plain-text summary for administrators on the clipboard. The new `disableConfigDeprecationWarnings` key hides the first showing; the final 24-hour reminder still appears. The warning also appears on standard deployments whose device-management profile uses one of these fields. + * Added Anthropic's Cowork and Claude Code plugin marketplaces as prefilled entries in the Setup window's `allowedPluginMarketplaces` Add menu. + * (breaking) Deprecated a set of older managed-configuration spellings, each accepted until October 7, 2026, 12:00 PM Pacific Time, with an in-app warning from September 10, 2026: `inferenceGatewayHeaders` (use `inferenceCustomHeaders`), `trustBootstrapLocalExec` (use `trustBootstrapDelivery`), `enduserAttribution` (use `endUserAttribution`), `inferenceGatewayAuthScheme` values `sso` (use `inferenceCredentialKind: "interactive"`) and `auto` (remove the key; `bearer` is the default), `isDxtEnabled` (use `isDesktopExtensionEnabled`) and `isDxtSignatureRequired` (use `isDesktopExtensionSignatureRequired`), header maps written as strings or lists in `inferenceCustomHeaders`, `otlpHeaders`, `otlpResourceAttributes` and `bootstrapHeaders` (use a JSON object), the `orgPluginSettings` record form (use the array form), the `ask-session` tool-permission value in `builtinToolPolicy`, `managedMcpServers[].toolPolicy` and `orgPluginSettings[].tools[].permission` (use `ask`), and in `managedMcpServers` entries the `scopes` list (use `scope`), `transport: "builtin"` (remove it), `authorityHost` (use `azureCloud: "us-gov-high"` for a GCC High tenant), `source` (remove it), `oauth` written as a number or string (use `true` or an `oauth` object), `oauth.scopes` or a list-valued `oauth.scope` (use `oauth.scope` as one space-separated string), and entries other than a built-in server with no `transport` (add `transport: "http"`, `"sse"` or `"stdio"`; a built-in Microsoft 365 or GitHub entry takes no `transport`). After the cut-off a renamed key's old name falls back to its fail-closed value or default, and an invalid `managedMcpServers` or `orgPluginSettings` entry makes that connector or tool policy unavailable until it is rewritten. + * Changed `inferenceVertexProjectId` and `inferenceVertexWorkforceUserProject`: a value delivered by a bootstrap URL the user configured themselves (in Settings or a local configuration file) now asks that user to approve it before it takes effect, and declining quits the app. Because the project ID is required, each such Vertex install prompts once after updating. Values delivered through device management, or by a bootstrap URL that device management set or that `trustBootstrapDelivery: true` covers, are unchanged and never prompt. Both keys must now match the Google Cloud project format. + * Changed `toolSearchEnabled` on gateway deployments to enable tool search alone; other experimental Claude Code betas stay suppressed. + * Changed how a managed-configuration value the app cannot read is handled: it now engages the restriction it belongs to instead of being ignored. Restriction keys such as `disabledBuiltinTools`, `builtinToolPolicy`, `coworkTabEnabled` and `disableBundledSkills` fall back to their restrictive value, an unreadable `managedMcpServers` keeps Code sessions restricted to managed MCP servers, an unreadable `isDesktopExtensionEnabled` or `isDesktopExtensionSignatureRequired` disables extensions or requires signed extensions, and a tool-permission value the app does not recognize is applied as the most restrictive setting (`ask` for a built-in tool, `blocked` for a plugin-delivered tool) and reported as a configuration error. `allowedPluginMarketplaces`, the built-in GitHub MCP preset and `otlpTracesEnabled` are no longer marked Beta. + * Changed the Setup window's configuration exports and the published bootstrap JSON schema to write `orgPluginSettings` in its array form; the app still accepts the older record form until October 7, 2026. Desktop versions before 1.15200.0 read only the record form and do not enforce plugin tool locks given the array, so update the fleet past 1.15200.0 before deploying an exported configuration that uses it. + * Changed the Vertex AI credential kind for Google sign-in to `inferenceCredentialKind: "interactive"`, matching other providers; `oauth` keeps working until October 7, 2026 (12:00 PM Pacific Time). If you deliver configuration as nested JSON (a self-hosted bootstrap server or a Setup JSON export), keep `oauth` until the whole fleet is on this release or later, because an older desktop drops the Google client ID from a nested `interactive` credential and Vertex sign-in stops working; flat MDM keys, .mobileconfig and .reg files are unaffected. Until October 7, 2026 a Vertex configuration that sets `interactive` together with `inferenceVertexWorkforceAudience` and no `inferenceVertexOAuthClientId` is still read as Workforce Identity; after that it means Google sign-in, so set `workforce` explicitly if that is the intent. + * Improved Cowork reliability when the workspace is slow to start or has been idle, and made switching back to a recently opened Code tab session faster. + * Fixed importing sessions from a previous Claude Desktop install: imported Cowork sessions keep their Project and its `~/Claude/Projects/<Name>` folder instead of getting a new empty one, an interrupted import now appears in Import history and its sessions are no longer imported twice on the next run, and the import wizard no longer re-creates a Project you had deleted (an imported Project that duplicates an existing name gets a "(1)" suffix). + * Fixed the Code tab's plugin directory and Customize > Plugins not listing plugins from marketplaces configured with `allowedPluginMarketplaces`; an admin-configured marketplace is now managed as the organization's in both tabs. +</Update> + <Update label="v1.37937.3" description="2026-08-26"> **General**
third-party/claude-desktop/bootstrap Changed · +8 / -8 lines
from line 358
## MDM configuration keys -| Setting | Type | Availability | Default | Description | -| ---------------------------------------------------------------------------------------------------- | --------- | ------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| <span id="bootstrapenabled" />Use bootstrap config<br />`bootstrapEnabled` | `boolean` | MDM only | `true` | Fetch and apply the URL above at launch. Turn off to keep the URL saved but skip the fetch. Defaults to `true`. | -| <span id="bootstrapurl" />Bootstrap config URL<br />`bootstrapUrl` | `string` | MDM only | — | HTTPS endpoint that returns a per-user JSON config overlay. Values from the response override local settings and become read-only. | -| <span id="bootstrapoidc" />Bootstrap OIDC parameters<br />`bootstrapOidc` | `object` | MDM only | — | When set, the bootstrap request sends a Bearer token from a browser sign-in (authorization-code-with-PKCE). | -| <span id="bootstrapheaders" />Bootstrap request headers<br />`bootstrapHeaders` | `object` | MDM only | — | HTTP headers sent on every bootstrap config fetch. Use this instead of embedding user:pass@ in the URL. | -| <span id="bootstrapheadershelper" />Bootstrap headers helper script<br />`bootstrapHeadersHelper` | `string` | MDM only | — | Absolute path to an executable that prints a JSON object of bootstrap request headers. Merged over the static headers; the helper wins. | -| <span id="trustbootstrapdelivery" />Trust bootstrap-delivered settings<br />`trustBootstrapDelivery` | `boolean` | MDM only | `false` | Skip the per-user consent prompt for sign-in targets, inference endpoints, helper scripts, and connectors the bootstrap server delivers. Defaults to `false`. Previously named `trustBootstrapLocalExec`. | +| Setting | Type | Availability | Default | Description | +| ---------------------------------------------------------------------------------------------------- | --------- | ------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| <span id="bootstrapenabled" />Use bootstrap config<br />`bootstrapEnabled` | `boolean` | MDM only | `true` | Fetch and apply the URL above at launch. Turn off to keep the URL saved but skip the fetch. Defaults to `true`. | +| <span id="bootstrapurl" />Bootstrap config URL<br />`bootstrapUrl` | `string` | MDM only | — | HTTPS endpoint that returns a per-user JSON config overlay. Values from the response override local settings and become read-only. | +| <span id="bootstrapoidc" />Bootstrap OIDC parameters<br />`bootstrapOidc` | `object` | MDM only | — | When set, the bootstrap request sends a Bearer token from a browser sign-in (authorization-code-with-PKCE). | +| <span id="bootstrapheaders" />Bootstrap request headers<br />`bootstrapHeaders` | `object` | MDM only | — | HTTP headers sent on every bootstrap config fetch. Use this instead of embedding user:pass@ in the URL. Deprecated: `bootstrapHeaders as a "Name=value,…" string or a ["Name: value", …] list` (accepted until October 7, 2026); use a JSON object such as \{"Name": "value"}. If it is still present after that, a string or list value will be rejected as malformed and no bootstrap request headers will be sent (the fetch may then fail to authenticate). | +| <span id="bootstrapheadershelper" />Bootstrap headers helper script<br />`bootstrapHeadersHelper` | `string` | MDM only | — | Absolute path to an executable that prints a JSON object of bootstrap request headers. Merged over the static headers; the helper wins. | +| <span id="trustbootstrapdelivery" />Trust bootstrap-delivered settings<br />`trustBootstrapDelivery` | `boolean` | MDM only | `false` | Skip the per-user consent prompt for sign-in targets, inference endpoints, helper scripts, and connectors the bootstrap server delivers. Defaults to `false`. Previously named `trustBootstrapLocalExec` (the old name is accepted until October 7, 2026). If it is still present after that, the key will read as false (its fail-closed value): each user will be asked to consent to bootstrap-delivered sign-in targets, endpoints, helper scripts and connectors, even when the bootstrap URL came from a device-managed profile. | <AccordionGroup> <Accordion title="bootstrapOidc details">
third-party/claude-desktop/code Changed · +4 / -0 lines
## Remote sessions over SSH
from line 55
In a third-party deployment there is no Anthropic authentication, so Claude Code's server-managed settings tier is never present. If you have not separately deployed a Claude Code `managed-settings.json` or OS profile, Claude Desktop's policy applies automatically and you do not need to set `parentSettingsBehavior`. </Note> +## Remote sessions over SSH + +A Code session can run its Claude Code engine on a remote host over SSH while the Code tab stays on the user's device. In a 3P deployment this is off until you set [`sshHostAllowlist`](/docs/third-party/claude-desktop/configuration#sshhostallowlist), because the app forwards the session's inference credential to the host. [SSH remote sessions](/docs/third-party/claude-desktop/ssh-remote-sessions) lists the credential kinds that work on a remote host and which of the keys above apply there. + ## Further reading * [Claude Code settings reference](https://code.claude.com/docs/en/settings-reference)
third-party/claude-desktop/configuration Changed · +142 / -104 lines
### Configuration updates
from line 73
## Connection -| Setting | Type | Availability | Default | Description | -| ------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | --------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| <span id="inferencecustomheaders" />Custom inference headers<br />`inferenceCustomHeaders` | `object` | MDM + Bootstrap | — | Extra headers on every inference request — routing and tenant headers only (org IDs, Bedrock Guardrails). No credentials; use the credential helper for tokens. Previously named `inferenceGatewayHeaders`. | -| <span id="inferencesessionlifetimesec" />Sign-in session lifetime<br />`inferenceSessionLifetimeSec` | `integer` | MDM + Bootstrap | — | How long a sign-in stays valid under your IdP’s session policy. Shows a re-authenticate banner before it expires. | -| <span id="inferencecredentialhelper" />Helper script<br />`inferenceCredentialHelper` | `string` | MDM + Bootstrap | — | Absolute path to an executable that prints the credential, optionally with per-request headers. | -| <span id="inferencecredentialhelperttlsec" />Helper script TTL<br />`inferenceCredentialHelperTtlSec` | `integer` | MDM + Bootstrap | `3600` | Helper output is cached for this many seconds; once it expires the helper re-runs without a relaunch (before the next turn when set above 120). Defaults to `3600`. | -| <span id="inferencecredentialhelpertimeoutsec" />Credential helper timeout<br />`inferenceCredentialHelperTimeoutSec` | `integer` | MDM + Bootstrap | `60` | Maximum wait for the helper executable to finish. Raise this if the helper opens a browser for interactive sign-in. Defaults to `60`. Range: 1–600. | -| <span id="inferencecredentialhelpersilentrefreshenabled" />Re-run helper for silent refresh<br />`inferenceCredentialHelperSilentRefreshEnabled` | `boolean` | MDM + Bootstrap | `true` | On credential expiry, re-run the helper (CLAUDE\_HELPER\_CONTEXT=mid-session-refresh) to recover silently. Turn off if the helper can’t run non-interactively. Defaults to `true`. | -| <span id="usercontentrendererurl" />Artifact preview iframe origin<br />`userContentRendererUrl` | `string` | MDM + Bootstrap | — | HTTPS origin of the user-content-renderer deployment used for artifact and file previews. Defaults to the commercial host when unset. | -| <span id="inferenceprovider" />Inference provider<br />`inferenceProvider` | `enum` | MDM + Bootstrap | — | Selects the inference backend. Setting this key activates third-party mode. One of: `gateway`, `anthropic`, `bedrock`, `mantle`, `vertex`, `foundry`. | -| <span id="inferencecredentialkind" />Credential kind<br />`inferenceCredentialKind` | `enum` | MDM + Bootstrap | — | Selects the credential source. When set, only that source is used (no fallback). One of: `static`, `helper-script`, `interactive`, `vendor-profile`, `oauth`, `workforce`. | +| Setting | Type | Availability | Default | Description | +| ------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | --------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| <span id="inferencecustomheaders" />Custom inference headers<br />`inferenceCustomHeaders` | `object` | MDM + Bootstrap | — | Extra headers on every inference request — routing and tenant headers only (org IDs, Bedrock Guardrails). No credentials; use the credential helper for tokens. Previously named `inferenceGatewayHeaders` (the old name is accepted until October 7, 2026). If it is still present after that, no custom inference headers will be sent. Deprecated: `inferenceCustomHeaders as a "Name=value,…" string or a ["Name: value", …] list` (accepted until October 7, 2026); use a JSON object such as \{"Name": "value"}. If it is still present after that, a string or list value will be rejected as malformed and no custom inference headers will be sent. | +| <span id="inferencesessionlifetimesec" />Sign-in session lifetime<br />`inferenceSessionLifetimeSec` | `integer` | MDM + Bootstrap | — | How long a sign-in stays valid under your IdP’s session policy. Shows a re-authenticate banner before it expires. | +| <span id="inferencecredentialhelper" />Helper script<br />`inferenceCredentialHelper` | `string` | MDM + Bootstrap | — | Absolute path to an executable that prints the credential, optionally with per-request headers. | +| <span id="inferencecredentialhelperttlsec" />Helper script TTL<br />`inferenceCredentialHelperTtlSec` | `integer` | MDM + Bootstrap | `3600` | Helper output is cached for this many seconds; once it expires the helper re-runs without a relaunch (before the next turn when set above 120). Defaults to `3600`. | +| <span id="inferencecredentialhelpertimeoutsec" />Credential helper timeout<br />`inferenceCredentialHelperTimeoutSec` | `integer` | MDM + Bootstrap | `60` | Maximum wait for the helper executable to finish. Raise this if the helper opens a browser for interactive sign-in. Defaults to `60`. Range: 1–600. | +| <span id="inferencecredentialhelpersilentrefreshenabled" />Re-run helper for silent refresh<br />`inferenceCredentialHelperSilentRefreshEnabled` | `boolean` | MDM + Bootstrap | `true` | On credential expiry, re-run the helper (CLAUDE\_HELPER\_CONTEXT=mid-session-refresh) to recover silently. Turn off if the helper can’t run non-interactively. Defaults to `true`. | +| <span id="usercontentrendererurl" />Artifact preview iframe origin<br />`userContentRendererUrl` | `string` | MDM + Bootstrap | — | HTTPS origin of the user-content-renderer deployment used for artifact and file previews. Defaults to the commercial host when unset. | +| <span id="inferenceprovider" />Inference provider<br />`inferenceProvider` | `enum` | MDM + Bootstrap | — | Selects the inference backend. Setting this key activates third-party mode. One of: `gateway`, `anthropic`, `bedrock`, `mantle`, `vertex`, `foundry`. | +| <span id="inferencecredentialkind" />Credential kind<br />`inferenceCredentialKind` | `enum` | MDM + Bootstrap | — | Selects the credential source. When set, only that source is used (no fallback). One of: `static`, `helper-script`, `interactive`, `vendor-profile`, `workforce`. Deprecated: `inferenceCredentialKind: "oauth" (Vertex AI)` (accepted until October 7, 2026); use "interactive" — the same Google sign-in under its new name (in hosted or nested documents, switch once every desktop is on a release that knows the Vertex "interactive" kind). If it is still present after that, "oauth" will no longer be a Vertex AI credential kind: the value will be reported as invalid and ignored — the device will then derive the kind from the credential fields present (Google sign-in when an OAuth client id is set), and the hosted editor will refuse to save the configuration until the kind is changed. Deprecated: `inferenceCredentialKind: "interactive" together with inferenceVertexWorkforceAudience (Vertex AI)` (accepted until October 7, 2026); use "workforce" — or remove inferenceVertexWorkforceAudience if Google sign-in ("interactive") is what is meant. If it is still present after that, the audience will no longer imply Workforce Identity: the kind will stay "interactive" (Google sign-in), which needs inferenceVertexOAuthClientId — without it the configuration will be reported as incomplete and inference will not start. | <AccordionGroup> <Accordion title="inferenceCustomHeaders details">
from line 168
### Gateway -| Setting | Type | Availability | Default | Description | -| -------------------------------------------------------------------------------------------------- | -------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -| <span id="inferencegatewaybaseurl" />Gateway base URL<br />`inferenceGatewayBaseUrl` | `string` | MDM + Bootstrap | — | Full URL of the inference gateway endpoint. | -| <span id="inferencegatewayapikey" />Gateway API key<br />`inferenceGatewayApiKey` | `string` | MDM + Bootstrap | — | API key for the configured inference gateway. | -| <span id="inferencegatewayauthscheme" />Gateway auth scheme<br />`inferenceGatewayAuthScheme` | `enum` | MDM + Bootstrap | `bearer` | How the gateway credential is sent on the wire (Authorization: Bearer vs x-api-key header). One of: `bearer`, `x-api-key`. Defaults to `bearer`. | -| <span id="inferencegatewayoidcauthflow" />Gateway sign-in flow<br />`inferenceGatewayOidcAuthFlow` | `enum` | MDM + Bootstrap | — | How the IdP sign-in runs: system browser (default) or the OS Microsoft Entra broker. One of: `browser`, `broker`. | -| <span id="inferencegatewayoidc" />Gateway SSO IdP (OIDC)<br />`inferenceGatewayOidc` | `object` | MDM + Bootstrap | — | External IdP for gateway sign-in. The user’s token from this issuer is sent to the gateway as the Bearer credential. | +| Setting | Type | Availability | Default | Description | +| -------------------------------------------------------------------------------------------------- | -------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| <span id="inferencegatewaybaseurl" />Gateway base URL<br />`inferenceGatewayBaseUrl` | `string` | MDM + Bootstrap | — | Full URL of the inference gateway endpoint. | +| <span id="inferencegatewayapikey" />Gateway API key<br />`inferenceGatewayApiKey` | `string` | MDM + Bootstrap | — | API key for the configured inference gateway. | +| <span id="inferencegatewayauthscheme" />Gateway auth scheme<br />`inferenceGatewayAuthScheme` | `enum` | MDM + Bootstrap | `bearer` | How the gateway credential is sent on the wire (Authorization: Bearer vs x-api-key header). One of: `bearer`, `x-api-key`. Defaults to `bearer`. Deprecated: `inferenceGatewayAuthScheme: "sso"` (accepted until October 7, 2026); use inferenceCredentialKind: "interactive". If it is still present after that, browser sign-in will no longer be inferred from it — the key will be reported as invalid and, unless inferenceCredentialKind or another credential field (an API key, inferenceGatewayOidc) says how to sign in, the gateway connection will have no credential and inference will not start. Deprecated: `inferenceGatewayAuthScheme: "auto"` (accepted until October 7, 2026); use "bearer" (or remove the key — bearer is the default). If it is still present after that, the value will be reported as invalid and ignored like any unrecognised scheme; the key will then take its default, "bearer", so the credential will still be sent as an Authorization: Bearer header. | +| <span id="inferencegatewayoidcauthflow" />Gateway sign-in flow<br />`inferenceGatewayOidcAuthFlow` | `enum` | MDM + Bootstrap | — | How the IdP sign-in runs: system browser (default) or the OS Microsoft Entra broker. One of: `browser`, `broker`. | +| <span id="inferencegatewayoidc" />Gateway SSO IdP (OIDC)<br />`inferenceGatewayOidc` | `object` | MDM + Bootstrap | — | External IdP for gateway sign-in. The user’s token from this issuer is sent to the gateway as the Bearer credential. | <AccordionGroup> <Accordion title="inferenceGatewayOidcAuthFlow details">
from line 222
### Models -| Setting | Type | Availability | Default | Description | -| ---------------------------------------------------------------------------------------------------- | ---------- | --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| <span id="modeldiscoveryenabled" />Model discovery<br />`modelDiscoveryEnabled` | `boolean` | MDM + Bootstrap | — | Auto-populate the model picker from the provider at launch. | -| <span id="modelprefer1mcontext" />Default to 1M context<br />`modelPrefer1mContext` | `boolean` | MDM + Bootstrap | — | When a user has no saved selection, start the picker on the 1M-context variant of the default model if it offers one. | -| <span id="inferencemodels" />Model list<br />`inferenceModels` | `object[]` | MDM + Bootstrap | — | Override the auto-discovered model list. First entry is the default. | -| <span id="inferencemodelpricingenabled" />Show estimated cost<br />`inferenceModelPricingEnabled` | `boolean` | MDM + Bootstrap | — | Show an estimated cost on the Usage page, at Anthropic list price for any model without a rate below. | -| <span id="inferencemodelpricingmultiplier" />Price multiplier<br />`inferenceModelPricingMultiplier` | `number` | MDM + Bootstrap | — | Scales every estimated cost (0.85 = 85% of the price); between 0 and 1. Takes effect in a future release; until then turns are estimated at list price. Range: 0–1. | -| <span id="inferencemodelpricing" />Model pricing<br />`inferenceModelPricing` | `object[]` | MDM + Bootstrap | — | Per-model rates replacing Anthropic list price in the Usage page’s estimate. Takes effect in a future release; until then turns are estimated at list price. | +| Setting | Type | Availability | Default | Description | +| ---------------------------------------------------------------------------------------------------- | ---------- | --------------- | ------- | --------------------------------------------------------------------------------------------------------------------- | +| <span id="modeldiscoveryenabled" />Model discovery<br />`modelDiscoveryEnabled` | `boolean` | MDM + Bootstrap | — | Auto-populate the model picker from the provider at launch. | +| <span id="modelprefer1mcontext" />Default to 1M context<br />`modelPrefer1mContext` | `boolean` | MDM + Bootstrap | — | When a user has no saved selection, start the picker on the 1M-context variant of the default model if it offers one. | +| <span id="inferencemodels" />Model list<br />`inferenceModels` | `object[]` | MDM + Bootstrap | — | Override the auto-discovered model list. First entry is the default. | +| <span id="inferencemodelpricingenabled" />Show estimated cost<br />`inferenceModelPricingEnabled` | `boolean` | MDM + Bootstrap | — | Show an estimated cost on the Usage page, at Anthropic list price for any model without a rate below. | +| <span id="inferencemodelpricingmultiplier" />Price multiplier<br />`inferenceModelPricingMultiplier` | `number` | MDM + Bootstrap | — | Scales every estimated cost (0.85 = 85% of the price); between 0 and 1. Range: 0–1. | +| <span id="inferencemodelpricing" />Model pricing<br />`inferenceModelPricing` | `object[]` | MDM + Bootstrap | — | Per-model rates replacing Anthropic list price in the Usage page’s estimate. | <AccordionGroup> <Accordion title="modelDiscoveryEnabled details">
from line 286
</Accordion> <Accordion title="inferenceModelPricingMultiplier details"> - Mirrors Claude Code's managed `modelPricing.multiplier`: a number in (0, 1] applied to every computed cost, whether the model was priced at Anthropic list price or by an `inferenceModelPricing` row — use it for a flat contracted discount. Setting it also turns the Usage page's estimate on. Takes effect in a future release, once Desktop bundles a Claude Code version that reads it; until then turns are estimated at Anthropic list price. Ignored when a machine-level Claude Code managed `modelPricing` is present. + Mirrors Claude Code's managed `modelPricing.multiplier`: a number in (0, 1] applied to every computed cost, whether the model was priced at Anthropic list price or by an `inferenceModelPricing` row — use it for a flat contracted discount. Setting it also turns the Usage page's estimate on. Ignored when a machine-level Claude Code managed `modelPricing` is present. </Accordion> <Accordion title="inferenceModelPricing details"> - Each row replaces Anthropic list price for one model in the Usage page's estimate, in USD per million tokens (`inputPerMtok`, `outputPerMtok`, `cacheReadPerMtok`, `cacheWritePerMtok` — all four required; `cacheWritePerMtok` prices both 5-minute and 1-hour cache writes); any row also turns the estimate on. Mirrors Claude Code's managed `modelPricing.overrides`, and `name` is matched the same way: a built-in Claude model ID (e.g. `claude-sonnet-4-6`, or its Bedrock, Vertex, or Foundry ID) covers every dated and provider spelling of that model; any other value — a gateway alias, an inference-profile ARN — matches that exact ID only (case-insensitive) and wins over a built-in row. An ID Claude Code cannot map to a Claude model at all gets no estimate until a row here prices it. `inferenceModelPricingMultiplier` still applies on top of a row. These rates take effect in a future release, once Desktop bundles a Claude Code version that reads them; until then turns are estimated at Anthropic list price. + Each row replaces Anthropic list price for one model in the Usage page's estimate, in USD per million tokens (`inputPerMtok`, `outputPerMtok`, `cacheReadPerMtok`, `cacheWritePerMtok` — all four required; `cacheWritePerMtok` prices both 5-minute and 1-hour cache writes); any row also turns the estimate on. Mirrors Claude Code's managed `modelPricing.overrides`, and `name` is matched the same way: a built-in Claude model ID (e.g. `claude-sonnet-4-6`, or its Bedrock, Vertex, or Foundry ID) covers every dated and provider spelling of that model; any other value — a gateway alias, an inference-profile ARN — matches that exact ID only (case-insensitive) and wins over a built-in row. An ID Claude Code cannot map to a Claude model at all gets no estimate until a row here prices it. `inferenceModelPricingMultiplier` still applies on top of a row. ```json theme={null} {"inferenceModelPricingEnabled": true, "inferenceModelPricingMultiplier": 0.9, "inferenceModelPricing": [{"name": "claude-sonnet-4-6", "inputPerMtok": 2.4, "outputPerMtok": 12, "cacheReadPerMtok": 0.24, "cacheWritePerMtok": 3}]}
from line 371
### Code surface -| Setting | Type | Availability | Default | Description | -| ------------------------------------------------------------------------------------------ | --------- | --------------- | ------- | ------------------------------------------------------------- | -| <span id="isclaudecodefordesktopenabled" />Allow Code<br />`isClaudeCodeForDesktopEnabled` | `boolean` | MDM + Bootstrap | `true` | Enable Code. Claude writes and runs code. Defaults to `true`. | +| Setting | Type | Availability | Default | Description | +| ------------------------------------------------------------------------------------------ | ---------- | ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| <span id="isclaudecodefordesktopenabled" />Allow Code<br />`isClaudeCodeForDesktopEnabled` | `boolean` | MDM + Bootstrap | `true` | Enable Code. Claude writes and runs code. Defaults to `true`. | +| <span id="sshhostallowlist" />SSH host allowlist<br />`sshHostAllowlist` | `string[]` | MDM + Bootstrap · Beta | — | SSH hosts users may connect to for Code sessions. Empty or unset: off unless the device’s Claude Code managed-settings allowlist applies. \* allows any host. | +<AccordionGroup> + <Accordion title="sshHostAllowlist details"> + Controls whether the Code tab offers SSH remote sessions, and to which hosts. When this key is `[]` or unset and no Claude Code managed-settings allowlist applies on the device (see below), SSH remote sessions are off: the option is hidden and any connection attempt is refused. Set it to a list of host patterns to turn the feature on for those hosts, or to `["*"]` to allow any host. + + Entries are exact hostnames (`build01.corp.example.com`) or `*.` wildcards (`*.corp.example.com` matches the apex and subdomains at any depth); matching is case-insensitive and ignores a `user@` prefix. Each connection is checked twice: against the host the user entered, and again against the `HostName` their `~/.ssh/config` resolves it to, so an alias cannot reach a host outside the list. `ProxyCommand`/`ProxyJump` are permitted when the resolved host matches — this key governs which hosts the app offers, not network egress. + + This is opt-in because a remote session runs Claude Code on the SSH host and the app forwards the session's inference credentials (the API key or gateway token it would hand a local session) to that process — and, when `otlpEndpoint` is configured, the organization's OTLP collector endpoint and its auth headers so the remote session exports telemetry like a local one. List only hosts you trust with those credentials. Remote sessions work with the Gateway, Anthropic API, and Foundry providers, and with Bedrock, Bedrock Mantle, and Vertex when the connection uses a token-based credential the app can forward (API key / bearer token, credential helper script, Vertex workforce identity federation). File-based kinds — Bedrock IAM Identity Center sign-in and AWS profile, Vertex Google sign-in and an ADC / service-account credentials file — are refused at session start with a message naming the credential kind, because those credentials live in local files the app does not copy to the remote host. + + If this key is unset, an `sshHostAllowlist` deployed through Claude Code's own managed-settings file on the device still applies; when both are set, this key wins where the app's configuration is admin-managed (an MDM-owned configuration, or one served by the admin console / a device-managed bootstrap URL) — on a self-configured install it applies only while that managed-settings file sets none. Like any key outside the app-behavior group, delivering it by MDM makes the MDM tier the app's whole configuration; to restrict SSH on self-configured installs without taking ownership, deploy `sshHostAllowlist` in Claude Code's managed-settings file instead. `allowedWorkspaceFolders` continues to apply on the remote host (see that key). + </Accordion> +</AccordionGroup> + ### Cowork surface | Setting | Type | Availability | Default | Description |
from line 396
### Workspace -| Setting | Type | Availability | Default | Description | -| -------------------------------------------------------------------------------------------------------------------- | ---------- | ---------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| <span id="userpluginmarketplacesenabled" />Allow user-added plugin marketplaces<br />`userPluginMarketplacesEnabled` | `boolean` | MDM + Bootstrap | — | Allow users to add plugin marketplaces themselves. When off, the add-marketplace surfaces are hidden and in-app adds are refused. | -| <span id="userpluginuploadsenabled" />Allow user-added plugins<br />`userPluginUploadsEnabled` | `boolean` | MDM + Bootstrap | — | Allow users to add their own plugins. When off, every in-app option for adding one is hidden and uploads that still reach the app are refused. | -| <span id="disabledbuiltintools" />Disabled built-in tools<br />`disabledBuiltinTools` | `string[]` | MDM + Bootstrap | — | Built-in tools, or argument-scoped permission rules such as Read(\*\*/.env), denied in Cowork and Code. | -| <span id="disablebundledskills" />Disable bundled skills and workflows<br />`disableBundledSkills` | `boolean` | MDM + Bootstrap | — | Disables Claude Code’s bundled skills and workflows (deep-research and similar). Use where WebFetch/WebSearch aren’t available. | -| <span id="skillcreationenabled" />Allow user-created skills<br />`skillCreationEnabled` | `boolean` | MDM + Bootstrap | — | Allow users to create and upload their own skills. When off, the creation and upload surfaces are hidden and the agent’s skill-creation tools are disabled. | -| <span id="builtintoolpolicy" />Built-in tool policy<br />`builtinToolPolicy` | `object` | MDM + Bootstrap | — | Approval policy per built-in tool or argument-scoped rule such as Bash(curl \*). “ask” requires user approval before each matching call; “allow” is the default. | -| <span id="automodeenabled" />Allow Auto mode<br />`autoModeEnabled` | `boolean` | MDM + Bootstrap | `false` | Offer Auto mode in the Cowork and Code permission selectors. Claude decides which actions need approval. Defaults to `false`. | -| <span id="toolsearchenabled" />Enable tool search<br />`toolSearchEnabled` | `boolean` | MDM + Bootstrap | `false` | Load MCP tool schemas on demand (tool search) instead of inlining every schema into context. Defaults to `false`. | -| <span id="skipwebfetchpreflight" />Skip WebFetch domain check<br />`skipWebFetchPreflight` | `boolean` | MDM + Bootstrap | — | Skip Claude Code’s WebFetch domain lookup against api.anthropic.com in Code sessions. Off by default; turn on when that host is blocked. | -| <span id="allowedworkspacefolders" />Allowed workspace folders<br />`allowedWorkspaceFolders` | `object[]` | MDM + Bootstrap | — | Folders where Claude may work. Applies to both Cowork and Code sessions. Leave unset for unrestricted access. | -| <span id="coworkegressallowedhosts" />Allowed egress hosts<br />`coworkEgressAllowedHosts` | `string[]` | MDM + Bootstrap | — | Hostnames the agent’s tools may reach from Cowork and Code sessions. Also surfaced under Egress Requirements. | -| <span id="requirecoworkfullvmsandbox" />Require full VM sandbox<br />`requireCoworkFullVmSandbox` | `boolean` | MDM + Bootstrap · Deprecated | `false` | Runs tools inside an isolated VM instead of the host. Stronger isolation; slower file access and no host-process tools. Defaults to `false`. | -| <span id="organizationinstructions" />Organization instructions<br />`organizationInstructions` | `string` | MDM + Bootstrap | — | Appended to Claude’s system prompt in Chat, Cowork, and Code. Guidance the model follows, not an enforced control. Up to 3,000 characters. | +| Setting | Type | Availability | Default | Description | +| -------------------------------------------------------------------------------------------------------------------- | ---------- | ---------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| <span id="userpluginmarketplacesenabled" />Allow user-added plugin marketplaces<br />`userPluginMarketplacesEnabled` | `boolean` | MDM + Bootstrap | — | Allow users to add plugin marketplaces themselves. When off, the add-marketplace surfaces are hidden and in-app adds are refused. | +| <span id="userpluginuploadsenabled" />Allow user-added plugins<br />`userPluginUploadsEnabled` | `boolean` | MDM + Bootstrap | — | Allow users to add their own plugins. When off, every in-app option for adding one is hidden and uploads that still reach the app are refused. | +| <span id="disabledbuiltintools" />Disabled built-in tools<br />`disabledBuiltinTools` | `string[]` | MDM + Bootstrap | — | Built-in tools, or argument-scoped permission rules such as Read(\*\*/.env), denied in Cowork and Code. | +| <span id="disablebundledskills" />Disable bundled skills and workflows<br />`disableBundledSkills` | `boolean` | MDM + Bootstrap | — | Disables Claude Code’s bundled skills and workflows (deep-research and similar). Use where WebFetch/WebSearch aren’t available. | +| <span id="skillcreationenabled" />Allow user-created skills<br />`skillCreationEnabled` | `boolean` | MDM + Bootstrap | — | Allow users to create and upload their own skills. When off, the creation and upload surfaces are hidden and the agent’s skill-creation tools are disabled. | +| <span id="builtintoolpolicy" />Built-in tool policy<br />`builtinToolPolicy` | `object` | MDM + Bootstrap | — | Approval policy per built-in tool or argument-scoped rule such as Bash(curl \*). “ask” requires user approval before each matching call; “allow” is the default. Deprecated: `builtinToolPolicy: "ask-session"` (accepted until October 7, 2026); use "ask". If it is still present after that, the entry will be read as "ask" (approval on every call), like any unrecognized value. | +| <span id="automodeenabled" />Allow Auto mode<br />`autoModeEnabled` | `boolean` | MDM + Bootstrap | `false` | Offer Auto mode in the Cowork and Code permission selectors. Claude decides which actions need approval. Defaults to `false`. | +| <span id="toolsearchenabled" />Enable tool search<br />`toolSearchEnabled` | `boolean` | MDM + Bootstrap | `false` | Load MCP tool schemas on demand (tool search) instead of inlining every schema into context. Defaults to `false`. | +| <span id="skipwebfetchpreflight" />Skip WebFetch domain check<br />`skipWebFetchPreflight` | `boolean` | MDM + Bootstrap | — | Skip Claude Code’s WebFetch domain lookup against api.anthropic.com in Code sessions. Off by default; turn on when that host is blocked. | +| <span id="allowedworkspacefolders" />Allowed workspace folders<br />`allowedWorkspaceFolders` | `object[]` | MDM + Bootstrap | — | Folders where Claude may work. Applies to both Cowork and Code sessions. Leave unset for unrestricted access. | +| <span id="coworkegressallowedhosts" />Allowed egress hosts<br />`coworkEgressAllowedHosts` | `string[]` | MDM + Bootstrap | — | Hostnames the agent’s tools may reach from Cowork and Code sessions. Also surfaced under Egress Requirements. | +| <span id="requirecoworkfullvmsandbox" />Require full VM sandbox<br />`requireCoworkFullVmSandbox` | `boolean` | MDM + Bootstrap · Deprecated | `false` | Runs tools inside an isolated VM instead of the host. Stronger isolation; slower file access and no host-process tools. Defaults to `false`. | +| <span id="organizationinstructions" />Organization instructions<br />`organizationInstructions` | `string` | MDM + Bootstrap | — | Appended to Claude’s system prompt in Chat, Cowork, and Code. Guidance the model follows, not an enforced control. Up to 3,000 characters. | <AccordionGroup> <Accordion title="userPluginMarketplacesEnabled details">
from line 452
The argument-scoped syntax requires the Claude Desktop release it first shipped in or newer — hold off deploying argument-scoped entries until your whole fleet is on that build (note `disableAutoUpdates` pins builds): an older build passes an argument-scoped **deny** entry through to Claude Code unchanged, but drops an argument-scoped **ask** entry as an unknown key — recorded there as a managed-configuration error (which, until that client updates, also blocks WSL sessions on Windows) — and the tool runs at its default (no prompt). - An entry that is not a usable rule at all (a lowercase tool name, an unbalanced parenthesis, a scoped `WebFetch(…)` or `WebSearch(…)`) is dropped and recorded as a configuration error, like any other unreadable managed value. `ask-session` is accepted for compatibility and treated as `ask`. To remove a tool or deny a rule entirely, use **Disabled built-in tools** instead. + An entry that is not a usable rule at all (a lowercase tool name, an unbalanced parenthesis, a scoped `WebFetch(…)` or `WebSearch(…)`) is dropped and recorded as a configuration error, like any other unreadable managed value; an entry for a known tool whose value is not `allow` or `ask` is treated as `ask` and reported. To remove a tool or deny a rule entirely, use **Disabled built-in tools** instead. </Accordion> <Accordion title="autoModeEnabled details">
from line 464
</Accordion> <Accordion title="toolSearchEnabled details"> - When enabled, Cowork, Code, and Chat sessions load MCP tool schemas on demand ("tool search"): only tool names are placed in context up front, and Claude fetches a tool's full schema the first time it needs it. Use this when many MCP tools are configured and their inlined schemas crowd out the context window (sessions that compact every turn or two). Equivalent to running terminal Claude Code with `ENABLE_TOOL_SEARCH=true` against the same endpoint. + When enabled, Cowork, Code, and Chat sessions load MCP tool schemas on demand ("tool search"): only tool names are placed in context up front, and Claude fetches a tool's full schema the first time it needs it. Use this when many MCP tools are configured and their inlined schemas crowd out the context window (sessions that compact every turn or two). - **Enabling this key causes sessions to send experimental `anthropic-beta` request headers, and the beta request fields that ride with them, to your inference endpoint** — tool search (`advanced-tool-use`, with `tool_reference` content blocks and deferred tool loading) and context management (a `context_management` request field on supported models) among them. Enable it only if your gateway forwards and accepts these; when it does not, requests fail with HTTP 400 on the beta header or fields. A practical preflight: run terminal Claude Code through the same gateway with `ENABLE_TOOL_SEARCH=true` — Claude Desktop then sends the same request surface, so if the terminal works, Desktop will too. **Do not enable this on Vertex-provider deployments** — Vertex rejects the tool-search beta header, and this key overrides the protection Claude Code applies to Vertex by default, turning working (inlined) MCP tools into failing requests. + What the key adds to requests depends on the provider and on the Claude Code version the app bundles: - Claude Desktop otherwise suppresses **all** of Claude Code's experimental beta features on 3P deployments (it pins `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` into session environments, because strict gateways reject unrecognized beta headers and fields). Enabling this key lifts that suppression, so other experimental betas — for example, on gateway- and Foundry-backed deployments, `context_management` request fields on models that support them — are re-enabled as well. This matches the request surface terminal Claude Code presents through the same gateway by default. Leave unset to keep the conservative default. + * **App versions that bundle Claude Code 2.1.247 or later, with `inferenceProvider: "gateway"`**: adds only the tool-search request shape: the `tool-search-tool-2025-10-19` value in the `anthropic-beta` header, deferred tool loading, and `tool_reference` content blocks. Every other experimental Claude Code beta stays suppressed (the app keeps `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` pinned in session environments, because strict gateways reject unrecognized beta headers and fields). If a machine also has OS-level Claude Code managed settings that set that kill switch or turn `ENABLE_TOOL_SEARCH` off, those win; set `ENABLE_TOOL_SEARCH` to `force` there instead (with `parentSettingsBehavior: "merge"` so the app's own restrictions keep applying). A user whose environment puts Claude Code in its own gateway mode (`CLAUDE_CODE_USE_GATEWAY`) is unaffected by the above: Claude Code then chooses its gateway-safe request shape itself, with tool search on. + * **Earlier app versions, and every provider other than gateway on any version**: lifts the experimental-beta suppression for the session, so requests carry the tool-search shape (`advanced-tool-use-2025-11-20` where Claude Code treats the endpoint as first-party) together with Claude Code's other experimental betas for that provider, for example `context_management` request fields. On app versions that bundle Claude Code older than 2.1.221 with the Vertex provider, leave this unset if any model older than Claude 4.5 is in use: those engines send the tool-search header without checking the model generation, and Vertex's pre-4.5 serving stacks reject it (newer engines skip tool search on those models themselves). + + Enable it only if your endpoint forwards and accepts the shape it will receive; when it does not, requests fail with HTTP 400. Leave unset to keep the conservative default. </Accordion> <Accordion title="skipWebFetchPreflight details">
from line 517
## Connectors -| Setting | Type | Availability | Default | Description | -| ----------------------------------------------------------------------- | -------- | --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| <span id="claudeaiimport" />Claude.ai data import<br />`claudeAiImport` | `object` | MDM + Bootstrap | — | Lets users import Claude.ai chats and projects, plus earlier Claude sessions on this computer, into this deployment when `enabled` is true. | +| Setting | Type | Availability | Default | Description | +| ----------------------------------------------------------------------- | -------- | --------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| <span id="claudeaiimport" />Claude.ai data import<br />`claudeAiImport` | `object` | MDM + Bootstrap | — | Lets users import Claude.ai chats and projects, plus earlier Claude sessions on this computer, when `enabled` is true. `automatic3pImport` is a separate switch. | <AccordionGroup> <Accordion title="claudeAiImport details"> - | Field | Type | Default | Description | - | ---------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | `enabled` | `boolean` | `false` | Lets users import a Claude.ai data export and earlier Claude sessions on this computer from Settings → Import. Doesn’t affect a provisioned sign-in import. | - | `exportEnabled` | `boolean` | `false` | Lets users export this computer’s chats, Cowork tasks, and Code sessions as a zip another install can import. No effect unless `enabled` is true. | - | `bannerBehavior` | `enum` | — | Prompt to import at the top of a new chat or task. `detect`: only when earlier Claude sessions are found on this computer. `show`: always. Hidden when unset. One of: `off`, `detect`, `show`. | + | Field | Type | Default | Description | + | ------------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | `enabled` | `boolean` | `false` | Lets users import a Claude.ai data export and earlier Claude sessions on this computer from Settings → Import. Doesn’t affect a provisioned sign-in import. | + | `automatic3pImport` | `boolean` | `false` | Beta. Copy this computer’s earlier third-party sessions into the app once, in the background. Independent of `enabled`. | + | `exportEnabled` | `boolean` | `false` | Lets users export this computer’s chats, Cowork tasks, and Code sessions as a zip another install can import. No effect unless `enabled` is true. | + | `bannerBehavior` | `enum` | — | Prompt to import at the top of a new chat or task. `detect`: only when earlier Claude sessions are found on this computer. `show`: always. Hidden when unset. One of: `off`, `detect`, `show`. | </Accordion> </AccordionGroup>
from line 540
### Extensions -| Setting | Type | Availability | Default | Description | -| --------------------------------------------------------------------------------------------------------------------- | --------- | --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| <span id="isdesktopextensionenabled" />Allow desktop extensions<br />`isDesktopExtensionEnabled` | `boolean` | MDM + Bootstrap | `false` | .dxt and .mcpb installs. Defaults to `false`. Previously named `isDxtEnabled`. | -| <span id="isdesktopextensionsignaturerequired" />Require signed extensions<br />`isDesktopExtensionSignatureRequired` | `boolean` | MDM + Bootstrap | `false` | Reject desktop extensions that are not signed by a trusted publisher. Defaults to `false`. Previously named `isDxtSignatureRequired`. | +| Setting | Type | Availability | Default | Description | +| --------------------------------------------------------------------------------------------------------------------- | --------- | --------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| <span id="isdesktopextensionenabled" />Allow desktop extensions<br />`isDesktopExtensionEnabled` | `boolean` | MDM + Bootstrap | `false` | .dxt and .mcpb installs. Defaults to `false`. Previously named `isDxtEnabled` (the old name is accepted until October 7, 2026). If it is still present after that, the old name will be reported as unreadable and the key will read as false: desktop extensions will be disabled until the name is updated. | +| <span id="isdesktopextensionsignaturerequired" />Require signed extensions<br />`isDesktopExtensionSignatureRequired` | `boolean` | MDM + Bootstrap | `false` | Reject desktop extensions that are not signed by a trusted publisher. Defaults to `false`. Previously named `isDxtSignatureRequired` (the old name is accepted until October 7, 2026). If it is still present after that, the old name will be reported as unreadable and the key will read as true: only signed extensions will load until the name is updated. | <AccordionGroup> <Accordion title="isDesktopExtensionEnabled details">
from line 553
### MCP -| Setting | Type | Availability | Default | Description | -| ------------------------------------------------------------------------------------------------------------------- | ---------- | --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -| <span id="managedmcpservers" />Managed MCP servers<br />`managedMcpServers` | `object[]` | MDM + Bootstrap | — | Org-pushed MCP servers: remote (HTTP/SSE) or local (stdio command). May embed bearer tokens. | -| <span id="mcppersistentalwaysallowenabled" />Allow persistent tool approvals<br />`mcpPersistentAlwaysAllowEnabled` | `boolean` | MDM + Bootstrap | `true` | Offer the persistent “Always allow” approval options for MCP tools. Disable to keep tool approvals per-call or session-scoped only. Defaults to `true`. | -| <span id="islocaldevmcpenabled" />Allow user-added MCP servers<br />`isLocalDevMcpEnabled` | `boolean` | MDM + Bootstrap | `true` | Local stdio servers added via the Developer settings. Remote servers come from the managed list above or organization plugins. Defaults to `true`. | -| <span id="mcptooltimeoutsec" />MCP tool call timeout<br />`mcpToolTimeoutSec` | `integer` | MDM + Bootstrap | — | Per-call timeout for MCP tool calls, in seconds. Default 180 (3 minutes). Range: 60–3600. | +| Setting | Type | Availability | Default | Description | +| ------------------------------------------------------------------------------------------------------------------- | ---------- | --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| <span id="managedmcpservers" />Managed MCP servers<br />`managedMcpServers` | `object[]` | MDM + Bootstrap | — | Org-pushed MCP servers: remote (HTTP/SSE) or local (stdio command). May embed bearer tokens. Deprecated: `managedMcpServers[].scopes` (accepted until October 7, 2026); use scope (one space-separated string, for example "Mail.Read Calendars.Read"). If it is still present after that, the entry will be rejected as invalid and that connector will be unavailable until the entry is rewritten. Deprecated: `managedMcpServers[].toolPolicy: "ask-session"` (accepted until October 7, 2026); use "ask". If it is still present after that, the entry will be rejected as invalid and that connector will be unavailable until the entry is rewritten. Deprecated: `managedMcpServers[].transport: "builtin"` (accepted until October 7, 2026); no longer needed — safe to remove. If it is still present after that, the entry will be rejected as invalid and that connector will be unavailable until the entry is rewritten. Deprecated: `managedMcpServers[].authorityHost` (accepted until October 7, 2026); use azureCloud: "us-gov-high" for a GCC High tenant; otherwise nothing. If it is still present after that, the entry will be rejected as invalid and that connector will be unavailable until the entry is rewritten — the Microsoft 365 connector will disappear rather than guess a cloud. Deprecated: `managedMcpServers[].source` (accepted until October 7, 2026); no longer needed — safe to remove. If it is still present after that, it will be treated as any unrecognised entry member — ignored by the desktop (the connector still loads; the app assigns each connector's provenance itself) and refused by a customer-run Apps Gateway serving the configuration. Deprecated: `managedMcpServers[].oauth as a number or string` (accepted until October 7, 2026); use true (automatic registration) or an oauth object. If it is still present after that, it will be treated as any wrong-typed member: the entry will be rejected as invalid and that connector will be unavailable until the entry is rewritten. Deprecated: `managedMcpServers[].oauth.scopes (or oauth.scope as a list)` (accepted until October 7, 2026); use oauth.scope as one space-separated string, for example "read write". If it is still present after that, it will be treated as any wrong-typed member: the entry will be rejected as invalid and that connector will be unavailable until the entry is rewritten. Deprecated: `managedMcpServers[] entry without transport` (accepted until October 7, 2026); use transport: "http" (or "sse" / "stdio") on every entry that is not a built-in server. If it is still present after that, the entry will be rejected as invalid and that connector will be unavailable until the entry is rewritten. | +| <span id="mcppersistentalwaysallowenabled" />Allow persistent tool approvals<br />`mcpPersistentAlwaysAllowEnabled` | `boolean` | MDM + Bootstrap | `true` | Offer the persistent “Always allow” approval options for MCP tools. Disable to keep tool approvals per-call or session-scoped only. Defaults to `true`. | +| <span id="islocaldevmcpenabled" />Allow user-added MCP servers<br />`isLocalDevMcpEnabled` | `boolean` | MDM + Bootstrap | `true` | Local stdio servers added via the Developer settings. Remote servers come from the managed list above or organization plugins. Defaults to `true`. | +| <span id="mcptooltimeoutsec" />MCP tool call timeout<br />`mcpToolTimeoutSec` | `integer` | MDM + Bootstrap | — | Per-call timeout for MCP tool calls, in seconds. Default 180 (3 minutes). Range: 60–3600. | <AccordionGroup> <Accordion title="managedMcpServers details"> For OAuth-authenticated entries, the app builds the redirect URI as `http://<callbackHost>:<callbackPort>/callback`; register that exact value with the OAuth provider. Tokens refresh automatically during a session, so users aren't interrupted when the initial access token expires. - `toolPolicy` locks the per-tool approval state, keyed by tool name. Keys may contain `*` wildcards (`"read_*"` matches every tool whose name starts with `read_`; matching is anchored and `*` is the only wildcard, identical to Claude Code permission-rule globs). An exact-name key wins over matching wildcard keys, with two exceptions in the stricter direction: in Code sessions, a forwarded `ask` wildcard rule, or a `blocked` wildcard other than the bare `"*"`, takes precedence over a less strict exact key (the deny-by-default form, `"*": "blocked"` plus exact `"allow"` entries, is honored in Code sessions too), and in chat approval flows and always-allow persistence a wildcard `ask` key keeps every matching tool behind a per-call prompt (no persistent always-allow), even when a more permissive exact-name key matches — for direct (imperative) tool invocations such as artifact or widget tool calls, the exact-name key still decides. When several wildcard keys match a tool, the strictest applies (blocked > ask > allow). `"blocked"` removes the tool from the session and labels it admin-blocked. `"ask"` requires approval on every call (Allow once / Deny only; no persistent always-allow). `"ask-session"` is accepted for compatibility and behaves exactly as `"ask"`. `"allow"` pre-approves. Tools **not listed** follow the user's choice: the prompt offers a persistent Always allow, except for tools that can modify data, which instead show a session-scoped **Allow for this task** alongside **Allow for all tasks** with a malicious-instruction warning. In Code sessions, `blocked` and `ask` (including `ask-session`) are forwarded as Claude Code permission rules; `allow` is not. + `toolPolicy` locks the per-tool approval state, keyed by tool name. Keys may contain `*` wildcards (`"read_*"` matches every tool whose name starts with `read_`; matching is anchored and `*` is the only wildcard, identical to Claude Code permission-rule globs). An exact-name key wins over matching wildcard keys, with two exceptions in the stricter direction: in Code sessions, a forwarded `ask` wildcard rule, or a `blocked` wildcard other than the bare `"*"`, takes precedence over a less strict exact key (the deny-by-default form, `"*": "blocked"` plus exact `"allow"` entries, is honored in Code sessions too), and in chat approval flows and always-allow persistence a wildcard `ask` key keeps every matching tool behind a per-call prompt (no persistent always-allow), even when a more permissive exact-name key matches — for direct (imperative) tool invocations such as artifact or widget tool calls, the exact-name key still decides. When several wildcard keys match a tool, the strictest applies (blocked > ask > allow). `"blocked"` removes the tool from the session and labels it admin-blocked. `"ask"` requires approval on every call (Allow once / Deny only; no persistent always-allow). `"allow"` pre-approves. Tools **not listed** follow the user's choice: the prompt offers a persistent Always allow, except for tools that can modify data, which instead show a session-scoped **Allow for this task** alongside **Allow for all tasks** with a malicious-instruction warning. In Code sessions, `blocked` and `ask` are forwarded as Claude Code permission rules; `allow` is not. For the bundled Microsoft 365 connector, the send tools (`outlook_send_mail`, `outlook_send_draft`, `outlook_forward_mail`, `outlook_create_event`, `outlook_update_event`, `teams_send_chat_message`, `teams_send_channel_message`, `teams_reply_channel_message`) cannot be loosened below `ask` — an `allow` setting resolves to `ask`.
from line 615
When disabled, the persistent options are hidden from approval prompts and from the Connector settings picker, previously stored persistent grants stop being honored, and scheduled-task runs no longer record or replay cross-run tool approvals. Session-scoped approvals are unchanged: users can still approve each call, and tools that can modify data keep the session-scoped **Allow for this task** option. - A per-tool `toolPolicy` entry on `managedMcpServers` always takes precedence over this key: `blocked`, `ask`, `ask-session`, and `allow` behave exactly as documented there whether this key is enabled or not. + A per-tool `toolPolicy` entry on `managedMcpServers` always takes precedence over this key: `blocked`, `ask`, and `allow` behave exactly as documented there whether this key is enabled or not. This key governs the chat and Cowork surfaces. Code sessions use a separate permission path this key does not cover — govern Code tool approvals with per-tool `toolPolicy` entries, whose `blocked` and `ask` values are forwarded there. </Accordion>
from line 686
</Accordion> </AccordionGroup> +### Configuration updates + +| Setting | Type | Availability | Default | Description | +| --------------------------------------------------------------------------------------------------- | --------- | -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| <span id="relaunchenforcementhours" />Configuration relaunch window<br />`relaunchEnforcementHours` | `integer` | Bootstrap only | `1` | Hours a user may keep working on the old configuration after a served configuration change. 0 = restart required at once. Blank = 1 hour. Defaults to `1`. Range: 0–336. | + +<AccordionGroup> + <Accordion title="relaunchEnforcementHours details"> + Served by your configuration endpoint (remote bootstrap configuration); not read from MDM (plist, registry, or file). When the running app observes a served change it cannot apply without restarting, it shows the sidebar relaunch card and starts this window. When the window ends the app blocks with a restart dialog and restarts on its own after 2 minutes with no activity (no running Claude task and no keyboard or pointer input); the user can also restart right away. Defaults to 1 hour. Set a larger value (up to 336 = 14 days) to give users longer; `0` shows the dialog at the first observation. + + Read from the newest served configuration, so tightening or loosening the window takes effect at the next poll without a restart, and a change to this key alone never asks for one. Changes delivered only through MDM are read at launch and are not detected while the app runs, which is why an MDM value for this key is ignored with a warning rather than honored. + </Accordion> +</AccordionGroup> + ### OTLP -| Setting | Type | Availability | Default | Description | -| --------------------------------------------------------------------------------------------------- | --------- | --------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| <span id="otlpendpoint" />OpenTelemetry collector endpoint<br />`otlpEndpoint` | `string` | MDM + Bootstrap | — | Where Cowork sends OpenTelemetry logs and metrics. Leave blank to disable. | -| <span id="otlpprotocol" />OpenTelemetry exporter protocol<br />`otlpProtocol` | `enum` | MDM + Bootstrap | `http/protobuf` | grpc or http/protobuf. One of: `http/protobuf`, `http/json`, `grpc`. Defaults to `http/protobuf`. | -| <span id="otlpheaders" />OpenTelemetry exporter headers<br />`otlpHeaders` | `object` | MDM + Bootstrap | — | Static collector headers — routing and tenant headers only. No credentials here; use Collector authentication or the headers helper script for tokens. | -| <span id="otlpauthmode" />Collector authentication<br />`otlpAuthMode` | `enum` | MDM + Bootstrap | — | inference-credential sends the user’s inference bearer token to the collector as Authorization: Bearer. One of: `none`, `inference-credential`. | -| <span id="otlpheadershelper" />OpenTelemetry headers helper script<br />`otlpHeadersHelper` | `string` | MDM + Bootstrap | — | Absolute path to an executable that prints a JSON object of collector headers. Merged over the static headers and Collector authentication; the helper wins. | -| <span id="otlpresourceattributes" />OpenTelemetry resource attributes<br />`otlpResourceAttributes` | `object` | MDM + Bootstrap | — | Extra resource attributes to attach to every span/metric. A static enduser.id set here always wins over the runtime identity. | -| <span id="otlpdesktoploglevel" />Desktop telemetry export level<br />`otlpDesktopLogLevel` | `enum` | MDM + Bootstrap | `error` | Controls the Claude Desktop application’s events, separate from Cowork and Code sessions. Defaults to error. One of: `off`, `error`, `warn`, `info`, `debug`. Defaults to `error`. | -| <span id="otlpcontentcapture" />Content capture categories<br />`otlpContentCapture` | `enum[]` | MDM + Bootstrap | — | Content categories the desktop exporter sends unredacted to your collector. Leave empty to redact all content (default). One of: `userPrompts`, `assistantResponses`, `toolDetails`, `toolContent`, `rawApiBodies`. | -| <span id="otlptracesenabled" />Export traces (beta)<br />`otlpTracesEnabled` | `boolean` | MDM + Bootstrap | — | Also export OpenTelemetry traces from Cowork tasks and Code sessions. Uses Claude Code’s session-tracing beta. | +| Setting | Type | Availability | Default | Description | +| --------------------------------------------------------------------------------------------------- | --------- | --------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| <span id="otlpendpoint" />OpenTelemetry collector endpoint<br />`otlpEndpoint` | `string` | MDM + Bootstrap | — | Where Cowork sends OpenTelemetry logs and metrics. Leave blank to disable. | +| <span id="otlpprotocol" />OpenTelemetry exporter protocol<br />`otlpProtocol` | `enum` | MDM + Bootstrap | `http/protobuf` | grpc or http/protobuf. One of: `http/protobuf`, `http/json`, `grpc`. Defaults to `http/protobuf`. | +| <span id="otlpheaders" />OpenTelemetry exporter headers<br />`otlpHeaders` | `object` | MDM + Bootstrap | — | Static collector headers — routing and tenant headers only. No credentials here; use Collector authentication or the headers helper script for tokens. Deprecated: `otlpHeaders as a "Name=value,…" string or a ["Name: value", …] list` (accepted until October 7, 2026); use a JSON object such as \{"Name": "value"}. If it is still present after that, a string or list value will be rejected as malformed and no exporter headers will be sent. | +| <span id="otlpauthmode" />Collector authentication<br />`otlpAuthMode` | `enum` | MDM + Bootstrap | — | inference-credential sends the user’s inference bearer token to the collector as Authorization: Bearer. One of: `none`, `inference-credential`. | +| <span id="otlpheadershelper" />OpenTelemetry headers helper script<br />`otlpHeadersHelper` | `string` | MDM + Bootstrap | — | Absolute path to an executable that prints a JSON object of collector headers. Merged over the static headers and Collector authentication; the helper wins. | +| <span id="otlpresourceattributes" />OpenTelemetry resource attributes<br />`otlpResourceAttributes` | `object` | MDM + Bootstrap | — | Extra resource attributes to attach to every span/metric. A static enduser.id set here always wins over the runtime identity. Deprecated: `otlpResourceAttributes as a "Name=value,…" string or a ["Name: value", …] list` (accepted until October 7, 2026); use a JSON object such as \{"Name": "value"}. If it is still present after that, a string or list value will be rejected as malformed and no custom resource attributes will be attached. | +| <span id="otlpdesktoploglevel" />Desktop telemetry export level<br />`otlpDesktopLogLevel` | `enum` | MDM + Bootstrap | `error` | Controls the Claude Desktop application’s events, separate from Cowork and Code sessions. Defaults to error. One of: `off`, `error`, `warn`, `info`, `debug`. Defaults to `error`. | +| <span id="otlpcontentcapture" />Content capture categories<br />`otlpContentCapture` | `enum[]` | MDM + Bootstrap | — | Content categories the desktop exporter sends unredacted to your collector. Leave empty to redact all content (default). One of: `userPrompts`, `assistantResponses`, `toolDetails`, `toolContent`, `rawApiBodies`. | +| <span id="otlptracesenabled" />Export traces<br />`otlpTracesEnabled` | `boolean` | MDM + Bootstrap | — | Also export OpenTelemetry traces from Cowork tasks and Code sessions. Uses Claude Code’s session tracing. | <AccordionGroup> <Accordion title="otlpAuthMode details">
from line 740
</Accordion> <Accordion title="otlpTracesEnabled details"> - Enables Claude Code's session-tracing beta (`CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` + `OTEL_TRACES_EXPORTER=otlp`) in spawned Cowork tasks and Code sessions. Each user interaction exports a trace whose spans and events carry `trace_id`/`span_id`, enabling end-to-end correlation in your observability backend (metrics do not carry trace context; correlate those via `session.id`). Traces go to the collector endpoint and protocol configured above. While the Claude Code feature is in beta the span structure may evolve; see the [Claude Code monitoring docs](https://code.claude.com/docs/en/monitoring-usage). + Enables Claude Code's session tracing (`CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` + `OTEL_TRACES_EXPORTER=otlp`) in spawned Cowork tasks and Code sessions. Each user interaction exports a trace whose spans and events carry `trace_id`/`span_id`, enabling end-to-end correlation in your observability backend (metrics do not carry trace context; correlate those via `session.id`). Traces go to the collector endpoint and protocol configured above. The span structure may evolve between Claude Code releases; see the [Claude Code monitoring docs](https://code.claude.com/docs/en/monitoring-usage). </Accordion> </AccordionGroup>
from line 765
## Appearance -| Setting | Type | Availability | Default | Description | -| --------------------------------------------------------------------------------------------------- | --------- | --------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| <span id="enduserattribution" />End-user attribution<br />`endUserAttribution` | `boolean` | MDM + Bootstrap | — | Show the signed-in user’s identity-provider identity in the sidebar and account menu, and emit it as the OpenTelemetry enduser.id resource attribute. Previously named `enduserAttribution`. | -| <span id="deploymentdisplayname" />Deployment display name<br />`deploymentDisplayName` | `string` | MDM + Bootstrap | — | Overrides the provider label shown in the sidebar footer, user-menu header, and connection-error banner. | -| <span id="deploymentdisplaysubtitle" />Deployment display subtitle<br />`deploymentDisplaySubtitle` | `string` | MDM + Bootstrap | — | Optional detail shown after the deployment display name in the account-menu header. | -| <span id="banner" />Organization banner<br />`banner` | `object` | MDM + Bootstrap | — | A persistent banner across the top of the app window after sign-in. | +| Setting | Type | Availability | Default | Description | +| ----------------------------------------------------------------------------------------------------------------------------- | --------- | --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| <span id="enduserattribution" />End-user attribution<br />`endUserAttribution` | `boolean` | MDM + Bootstrap | — | Show the signed-in user’s identity-provider identity in the sidebar and account menu, and emit it as the OpenTelemetry enduser.id resource attribute. Previously named `enduserAttribution` (the old name is accepted until October 7, 2026). If it is still present after that, the key will read as false (its fail-closed value): end-user attribution will stay off — no identity shown, no enduser.id emitted — whatever the old name said. | +| <span id="deploymentdisplayname" />Deployment display name<br />`deploymentDisplayName` | `string` | MDM + Bootstrap | — | Overrides the provider label shown in the sidebar footer, user-menu header, and connection-error banner. | +| <span id="deploymentdisplaysubtitle" />Deployment display subtitle<br />`deploymentDisplaySubtitle` | `string` | MDM + Bootstrap | — | Optional detail shown after the deployment display name in the account-menu header. | +| <span id="disableconfigdeprecationwarnings" />Hide configuration deprecation warnings<br />`disableConfigDeprecationWarnings` | `boolean` | MDM + Bootstrap | — | Don’t show users the in-app warning that this configuration uses a deprecated field. The final reminder in the 24 hours before the cut-off still appears. | +| <span id="banner" />Organization banner<br />`banner` | `object` | MDM + Bootstrap | — | A persistent banner across the top of the app window after sign-in. | <AccordionGroup> <Accordion title="endUserAttribution details">
from line 786
Optional detail shown after the deployment display name in the account-menu header (for example, "Claude for Veterans Affairs · Claude for Government"). Shown only when the display name is also set. Maximum 60 characters. </Accordion> + <Accordion title="disableConfigDeprecationWarnings details"> + When the organization's configuration uses a field that is deprecated — a renamed key, or a legacy value or entry form — the app shows every user a dismissable warning naming the field, what to use instead, and the date support ends (each field's cut-off is listed in the configuration changelog and takes effect at 12:00 PM Pacific Time on that date). The warning shows from the field's announced warning date until dismissed, and once more in the 24 hours before the cut-off. Set this to `true` to suppress the first showing for your users while you migrate; the final 24-hour reminder is always shown, and the deprecation stays listed in the diagnostic report (Help → Troubleshooting) and the hosted configuration editor regardless. + </Accordion> + <Accordion title="banner details"> Use this for compliance notices, an internal-support link, or to identify the deployment. The banner is shown on every page after sign-in and cannot be dismissed by the user. Colors are six-digit hex (`#RRGGBB`); when `linkUrl` is set the banner text becomes an HTTPS link.
from line 819
## Plugins -| Setting | Type | Availability | Default | Description | -| ------------------------------------------------------------------------------------------- | ---------- | ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| <span id="orgpluginsettings" />Organization plugin settings<br />`orgPluginSettings` | `object[]` | MDM + Bootstrap | — | Admin policy applied to plugin-delivered MCP servers. | -| <span id="allowedpluginmarketplaces" />Plugin marketplaces<br />`allowedPluginMarketplaces` | `object[]` | MDM + Bootstrap · Beta | — | Git repositories or hosted marketplace.json URLs to surface as plugin marketplaces in the Directory’s Organization tab. The app re-fetches each periodically. | +| Setting | Type | Availability | Default | Description | +| ------------------------------------------------------------------------------------------- | ---------- | --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| <span id="orgpluginsettings" />Organization plugin settings<br />`orgPluginSettings` | `object[]` | MDM + Bootstrap | — | Admin policy applied to plugin-delivered MCP servers. Deprecated: `orgPluginSettings as a {"mcpServers": {…}} record` (accepted until October 7, 2026); use the array form \[\{"serverName": "…", "tools": \[\{"toolName": "…", "permission": "…"}]}] (read by desktop 1.15200.0 and later; older desktops ignore the array and enforce no tool blocks). If it is still present after that, the record will be rejected as malformed and the key will fail closed: every plugin-delivered MCP tool will be blocked until the value is rewritten. Deprecated: `orgPluginSettings[].tools[].permission: "ask-session"` (accepted until October 7, 2026); use "ask". If it is still present after that, that tool will be treated as "blocked", like any unrecognized permission. | +| <span id="allowedpluginmarketplaces" />Plugin marketplaces<br />`allowedPluginMarketplaces` | `object[]` | MDM + Bootstrap | — | Git repositories or hosted marketplace.json URLs to surface as plugin marketplaces in the Directory’s Organization tab. The app re-fetches each periodically. | <AccordionGroup> <Accordion title="orgPluginSettings details"> - Applies `toolPolicy` locks to MCP servers that arrive via the org-plugins directory, keyed by server name. Either shape is accepted; when hand-authoring a profile, use the legacy record shape until your fleet floor parses the canonical array form: + Locks per-tool permissions on MCP servers that arrive via the org-plugins directory — one entry per server name: ```json theme={null} - {"mcpServers": {"internal-search": {"toolPolicy": {"delete_document": "blocked"}}}} + [{"serverName": "internal-search", "tools": [{"toolName": "delete_document", "permission": "blocked"}]}] ``` + The older record form (`{"mcpServers": {"internal-search": {"toolPolicy": {"delete_document": "blocked"}}}}`) is deprecated and accepted only until October 7, 2026. Desktop versions before 1.15200.0 parse only the record form: on those builds an array value is ignored and plugin tool locks are **not enforced**, so update the fleet past 1.15200.0 before deploying the array form. + If a Managed MCP servers entry and an org-plugin server share a name, the Managed MCP servers entry wins and its `toolPolicy` (if any) applies; the entry here for that name is ignored. | Field | Type | Default | Description |
from line 864
### Bootstrap -| Setting | Type | Availability | Default | Description | -| ---------------------------------------------------------------------------------------------------- | --------- | ------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| <span id="bootstrapenabled" />Use bootstrap config<br />`bootstrapEnabled` | `boolean` | MDM only | `true` | Fetch and apply the URL above at launch. Turn off to keep the URL saved but skip the fetch. Defaults to `true`. | -| <span id="bootstrapurl" />Bootstrap config URL<br />`bootstrapUrl` | `string` | MDM only | — | HTTPS endpoint that returns a per-user JSON config overlay. Values from the response override local settings and become read-only. | -| <span id="bootstrapoidc" />Bootstrap OIDC parameters<br />`bootstrapOidc` | `object` | MDM only | — | When set, the bootstrap request sends a Bearer token from a browser sign-in (authorization-code-with-PKCE). | -| <span id="bootstrapheaders" />Bootstrap request headers<br />`bootstrapHeaders` | `object` | MDM only | — | HTTP headers sent on every bootstrap config fetch. Use this instead of embedding user:pass@ in the URL. | -| <span id="bootstrapheadershelper" />Bootstrap headers helper script<br />`bootstrapHeadersHelper` | `string` | MDM only | — | Absolute path to an executable that prints a JSON object of bootstrap request headers. Merged over the static headers; the helper wins. | -| <span id="trustbootstrapdelivery" />Trust bootstrap-delivered settings<br />`trustBootstrapDelivery` | `boolean` | MDM only | `false` | Skip the per-user consent prompt for sign-in targets, inference endpoints, helper scripts, and connectors the bootstrap server delivers. Defaults to `false`. Previously named `trustBootstrapLocalExec`. | +| Setting | Type | Availability | Default | Description | +| ---------------------------------------------------------------------------------------------------- | --------- | ------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| <span id="bootstrapenabled" />Use bootstrap config<br />`bootstrapEnabled` | `boolean` | MDM only | `true` | Fetch and apply the URL above at launch. Turn off to keep the URL saved but skip the fetch. Defaults to `true`. | +| <span id="bootstrapurl" />Bootstrap config URL<br />`bootstrapUrl` | `string` | MDM only | — | HTTPS endpoint that returns a per-user JSON config overlay. Values from the response override local settings and become read-only. | +| <span id="bootstrapoidc" />Bootstrap OIDC parameters<br />`bootstrapOidc` | `object` | MDM only | — | When set, the bootstrap request sends a Bearer token from a browser sign-in (authorization-code-with-PKCE). | +| <span id="bootstrapheaders" />Bootstrap request headers<br />`bootstrapHeaders` | `object` | MDM only | — | HTTP headers sent on every bootstrap config fetch. Use this instead of embedding user:pass@ in the URL. Deprecated: `bootstrapHeaders as a "Name=value,…" string or a ["Name: value", …] list` (accepted until October 7, 2026); use a JSON object such as \{"Name": "value"}. If it is still present after that, a string or list value will be rejected as malformed and no bootstrap request headers will be sent (the fetch may then fail to authenticate). | +| <span id="bootstrapheadershelper" />Bootstrap headers helper script<br />`bootstrapHeadersHelper` | `string` | MDM only | — | Absolute path to an executable that prints a JSON object of bootstrap request headers. Merged over the static headers; the helper wins. | +| <span id="trustbootstrapdelivery" />Trust bootstrap-delivered settings<br />`trustBootstrapDelivery` | `boolean` | MDM only | `false` | Skip the per-user consent prompt for sign-in targets, inference endpoints, helper scripts, and connectors the bootstrap server delivers. Defaults to `false`. Previously named `trustBootstrapLocalExec` (the old name is accepted until October 7, 2026). If it is still present after that, the key will read as false (its fail-closed value): each user will be asked to consent to bootstrap-delivered sign-in targets, endpoints, helper scripts and connectors, even when the bootstrap URL came from a device-managed profile. | <AccordionGroup> <Accordion title="bootstrapOidc details">
third-party/claude-desktop/configuration-changelog Changed · +50 / -0 lines
from line 4
Configuration keys by Claude Desktop release. Each section lists keys added in that release, with the MDM key name (for plist/registry deployment) and the equivalent JSON shape (for local-file or bootstrap remote configuration). +<Update label="v1.40609.0" description="2026-08-27"> + <div className="cfg-keys"> + | MDM key | Type | Description | + | ---------------------------------------------------------------------------------------------------------------- | ---------- | --------------------------------------- | + | [`sshHostAllowlist`](/docs/third-party/claude-desktop/configuration#sshhostallowlist) · Beta | `string[]` | SSH host allowlist | + | [`disableConfigDeprecationWarnings`](/docs/third-party/claude-desktop/configuration#disableconfigdeprecationwarnings) | `boolean` | Hide configuration deprecation warnings | + </div> + + **JSON (e.g. for non-MDM users or Bootstrap):** + + ```json theme={null} + { + "codeSurface": { + "sshHostAllowlist": ["<string>"] + }, + "bootstrap": { + "relaunchEnforcementHours": "<integer>" + }, + "appearance": { + "disableConfigDeprecationWarnings": "<boolean>" + } + } + ``` + + `relaunchEnforcementHours` is read from served configuration only (a bootstrap URL); a value in a local configuration file or in device management is ignored with a warning. + + **Changed:** + + * `inferenceVertexProjectId` and `inferenceVertexWorkforceUserProject` now require the user's consent when delivered by a bootstrap URL the user configured themselves (`consentRequired`); a bootstrap URL set by device management, or covered by `trustBootstrapDelivery: true`, never prompts. Both keys must match the Google Cloud project format (`^[a-z0-9][a-z0-9.:-]*$`). + * `inferenceCredentialKind` accepts `interactive` for Vertex AI (Google sign-in); the Vertex `oauth` value is deprecated (below). + * `orgPluginSettings` is published as an array of `{ "serverName", "tools": [{ "toolName", "permission" }] }` entries; the `{ "mcpServers": {…} }` record form is deprecated (below). + * The published bootstrap JSON schema now rejects `authorityHost` on the Microsoft 365 entry, so a configuration that still uses it fails schema validation in tools that check against the schema; the app itself keeps mapping it to `azureCloud` until October 7, 2026. + * `allowedPluginMarketplaces` is no longer marked Beta. + + **Deprecated** (each accepted until October 7, 2026, 12:00 PM Pacific Time; users see an in-app warning from September 10, 2026, which `disableConfigDeprecationWarnings` hides, and a final reminder in the 24 hours before the cut-off, which it does not): + + * `inferenceGatewayHeaders`: use `inferenceCustomHeaders` instead. After the cut-off no custom inference headers are sent. + * `inferenceCustomHeaders`, `otlpHeaders`, `otlpResourceAttributes` and `bootstrapHeaders` written as a `"Name=value,…"` string or a `["Name: value", …]` list: use a JSON object such as `{"Name": "value"}` instead. After the cut-off a string or list value is rejected as malformed and no headers (or resource attributes) are sent. + * `inferenceGatewayAuthScheme: "sso"`: use `inferenceCredentialKind: "interactive"` instead. After the cut-off the value is reported as invalid and, unless another credential field says how to sign in, the gateway connection has no credential and inference does not start. + * `inferenceGatewayAuthScheme: "auto"`: use `"bearer"` instead, or remove the key (`bearer` is the default). After the cut-off the value is reported as invalid and the default applies. + * `inferenceCredentialKind: "oauth"` (Vertex AI): use `"interactive"` instead. After the cut-off `oauth` is reported as invalid and the kind is derived from the credential fields present. + * `inferenceCredentialKind: "interactive"` together with `inferenceVertexWorkforceAudience` (Vertex AI): use `"workforce"` instead, or remove the audience if Google sign-in is meant. After the cut-off the audience no longer implies Workforce Identity; `interactive` then needs `inferenceVertexOAuthClientId` or inference does not start. + * `isDxtEnabled` and `isDxtSignatureRequired`: use `isDesktopExtensionEnabled` and `isDesktopExtensionSignatureRequired` instead. After the cut-off the old names are unreadable: extensions are disabled, or only signed extensions load, until the name is updated. + * `trustBootstrapLocalExec`: use `trustBootstrapDelivery` instead. After the cut-off the key reads `false` and each user is asked to consent to bootstrap-delivered values. + * `enduserAttribution`: use `endUserAttribution` instead. After the cut-off the key reads `false` and end-user attribution stays off. + * `orgPluginSettings` as a `{ "mcpServers": {…} }` record: use the array form instead (read by desktop 1.15200.0 and later; older desktops ignore the array and enforce no tool locks). After the cut-off the record is rejected and every plugin-delivered MCP tool is blocked until the value is rewritten. + * `ask-session` in `builtinToolPolicy`, `orgPluginSettings[].tools[].permission` and `managedMcpServers[].toolPolicy`: use `ask` instead. After the cut-off it is treated as an unrecognized value: `ask` for a built-in tool, `blocked` for a plugin-delivered tool, and an invalid entry for a managed server. + * In `managedMcpServers` entries: replace `scopes` with `scope` (one space-separated string); remove `transport: "builtin"` and `source`; replace `authorityHost` with `azureCloud: "us-gov-high"` for a GCC High tenant; write `oauth` as `true` or an oauth object rather than a number or string; replace `oauth.scopes` (or `oauth.scope` as a list) with `oauth.scope` as one string; add `transport: "http"` (or `"sse"` / `"stdio"`) to an entry with no `transport` that is not a built-in server (a built-in Microsoft 365 or GitHub entry takes no `transport`). After the cut-off such an entry is rejected and that connector is unavailable until it is rewritten (`source` is ignored by the desktop but refused by a customer-run Apps Gateway). +</Update> + <Update label="v1.37937.3" description="2026-08-26"> No configuration changes in this release. </Update>
third-party/claude-desktop/gateway Changed · +7 / -7 lines
from line 164
### Configuration keys -| Setting | Type | Availability | Default | Description | -| -------------------------------------------------------------------------------------------------- | -------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -| <span id="inferencegatewaybaseurl" />Gateway base URL<br />`inferenceGatewayBaseUrl` | `string` | MDM + Bootstrap | — | Full URL of the inference gateway endpoint. | -| <span id="inferencegatewayapikey" />Gateway API key<br />`inferenceGatewayApiKey` | `string` | MDM + Bootstrap | — | API key for the configured inference gateway. | -| <span id="inferencegatewayauthscheme" />Gateway auth scheme<br />`inferenceGatewayAuthScheme` | `enum` | MDM + Bootstrap | `bearer` | How the gateway credential is sent on the wire (Authorization: Bearer vs x-api-key header). One of: `bearer`, `x-api-key`. Defaults to `bearer`. | -| <span id="inferencegatewayoidcauthflow" />Gateway sign-in flow<br />`inferenceGatewayOidcAuthFlow` | `enum` | MDM + Bootstrap | — | How the IdP sign-in runs: system browser (default) or the OS Microsoft Entra broker. One of: `browser`, `broker`. | -| <span id="inferencegatewayoidc" />Gateway SSO IdP (OIDC)<br />`inferenceGatewayOidc` | `object` | MDM + Bootstrap | — | External IdP for gateway sign-in. The user’s token from this issuer is sent to the gateway as the Bearer credential. | +| Setting | Type | Availability | Default | Description | +| -------------------------------------------------------------------------------------------------- | -------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| <span id="inferencegatewaybaseurl" />Gateway base URL<br />`inferenceGatewayBaseUrl` | `string` | MDM + Bootstrap | — | Full URL of the inference gateway endpoint. | +| <span id="inferencegatewayapikey" />Gateway API key<br />`inferenceGatewayApiKey` | `string` | MDM + Bootstrap | — | API key for the configured inference gateway. | +| <span id="inferencegatewayauthscheme" />Gateway auth scheme<br />`inferenceGatewayAuthScheme` | `enum` | MDM + Bootstrap | `bearer` | How the gateway credential is sent on the wire (Authorization: Bearer vs x-api-key header). One of: `bearer`, `x-api-key`. Defaults to `bearer`. Deprecated: `inferenceGatewayAuthScheme: "sso"` (accepted until October 7, 2026); use inferenceCredentialKind: "interactive". If it is still present after that, browser sign-in will no longer be inferred from it — the key will be reported as invalid and, unless inferenceCredentialKind or another credential field (an API key, inferenceGatewayOidc) says how to sign in, the gateway connection will have no credential and inference will not start. Deprecated: `inferenceGatewayAuthScheme: "auto"` (accepted until October 7, 2026); use "bearer" (or remove the key — bearer is the default). If it is still present after that, the value will be reported as invalid and ignored like any unrecognised scheme; the key will then take its default, "bearer", so the credential will still be sent as an Authorization: Bearer header. | +| <span id="inferencegatewayoidcauthflow" />Gateway sign-in flow<br />`inferenceGatewayOidcAuthFlow` | `enum` | MDM + Bootstrap | — | How the IdP sign-in runs: system browser (default) or the OS Microsoft Entra broker. One of: `browser`, `broker`. | +| <span id="inferencegatewayoidc" />Gateway SSO IdP (OIDC)<br />`inferenceGatewayOidc` | `object` | MDM + Bootstrap | — | External IdP for gateway sign-in. The user’s token from this issuer is sent to the gateway as the Bearer credential. | <AccordionGroup> <Accordion title="inferenceGatewayOidcAuthFlow details">
third-party/claude-desktop/local-access Changed · +5 / -5 lines
from line 20
Each entry is either a plain path string or an object with these fields: -| Field | Description | -| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `path` | The folder path (required). Subfolders are included. | -| `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, read-only applies to Claude's file tools only; shell commands and SSH sessions do not enforce it. | -| `isDefaultSelected` | When `true`, the folder appears already selected on the new-task page and skips the trust prompt. Users can remove it. | +| Field | Description | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `path` | The folder path (required). Subfolders are included. | +| `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, read-only applies to Claude's file tools only; shell commands and [SSH remote sessions](/docs/third-party/claude-desktop/ssh-remote-sessions) do not enforce it. | +| `isDefaultSelected` | When `true`, the folder appears already selected on the new-task page and skips the trust prompt. Users can remove it. | For 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.
third-party/claude-desktop/ssh-remote-sessions New page · 163 lines, new page
# SSH remote sessions in Claude Desktop on 3P ## How a remote session works ## Enable SSH remote sessions ### Interaction with Claude Code managed settings on the device ## Inference credentials on the remote host ## Managed configuration on the remote host ## Host requirements ### SSH configuration on the device ## Troubleshoot ### SSH isn't allowed by your organization ### SSH to this machine isn't available ### Remote sessions aren't available with this inference setup ### SSH host key verification failed ## Related
A whole new page. There's nothing to diff it against, so here is what it says.
# SSH remote sessions in Claude Desktop on 3P
> 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
An SSH remote session is a [Code](/docs/third-party/claude-desktop/code) session whose Claude Code engine runs on another machine that the user reaches over SSH, while the session's interface stays in Claude Desktop on the user's device. Claude Desktop connects to the host, places the engine there, and starts the session with the inference credential and policy from your managed configuration. Users can work on code that lives on a development server, a build box, or a cloud workstation without copying it to their device. In Claude Desktop on third-party (3P), SSH remote sessions are off until you set the [`sshHostAllowlist`](/docs/third-party/claude-desktop/configuration#sshhostallowlist) key, because enabling them sends your inference credential to the hosts users connect to.
<Note>
SSH remote sessions are in beta in Claude Desktop on 3P and require Claude Desktop 1.40609.0 or later. The in-app configuration window marks `sshHostAllowlist` with a **Beta** pill.
</Note>
## How a remote session works
1. **Connect.** The user picks an SSH host from the environment picker in the Code tab, or adds one by entering its address, port, and an identity file. Claude Desktop connects with its built-in SSH client, 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.
2. **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.
3. **Run.** The remote server starts the engine on the host with the inference credential and policy from your managed configuration. Every file read, edit, shell command, and git operation runs on the host, in the working directory the user chose there. Claude Desktop connects to [managed MCP servers](/docs/third-party/claude-desktop/extensions#managed-mcp-servers-admin) from the device and exposes them to the engine as tools.
4. **Stream.** Claude's responses and tool output stream back to Claude Desktop. Permission prompts appear in the Code tab, and the engine waits on the host until the user answers.
The 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. Reopening starts a fresh engine from the transcript stored on the host, so a turn that finished while the app was closed is shown in full; a turn still running at that moment is cut short and not continued automatically. 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.
An idle engine stays on the host, with the credential in its environment, until the user reopens, archives, or deletes the session, the host restarts, or a Claude Desktop update replaces the remote server on the host (deferred while a session on that host was active in the last 24 hours, for up to 7 days).
## Enable SSH remote sessions
Set [`sshHostAllowlist`](/docs/third-party/claude-desktop/configuration#sshhostallowlist) in your managed configuration. It appears in the **Code surface** section of the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration) while Code is enabled.
| Value | Behavior |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Unset | Off, unless a Claude Code managed-settings `sshHostAllowlist` on the device allows hosts (see [Interaction with Claude Code managed settings](#interaction-with-claude-code-managed-settings-on-the-device)) |
| `[]` | Off. Delivered by an administrator, `[]` also overrides a Claude Code managed-settings allowlist on the device |
| `["*"]` | Users can connect to any host |
| `["build01.corp.example.com", "*.dev.example.com"]` | Users can connect only to hosts that match an entry |
While SSH remote sessions are off, the environment picker shows local sessions only, and any attempt to connect to a saved host is refused.
Each entry is an exact hostname, an IP address, or a `*.` wildcard.
* `*.dev.example.com` matches `dev.example.com` and any subdomain of it at any depth.
* Matching is case-insensitive and ignores a `user@` prefix.
* An IP address entry matches only that address.
* Entries do not restrict the port.
* A value that is not an array of strings counts as `[]`.
Both the host the user entered and the `HostName` that the device's `~/.ssh/config` resolves it to must match an entry, so an alias that resolves to a host outside the list is refused. A `ProxyCommand` is permitted when the resolved hostname matches; the app does not inspect where the command itself connects. The allowlist limits which hosts Claude Desktop connects to. It does not limit what the device can reach over SSH from a terminal. Use network controls for that.
For example, this Linux managed-settings file turns the feature on for one domain:
```json /etc/claude-desktop/managed-settings.json theme={null}
{
"sshHostAllowlist": ["*.dev.example.com"]
}
```
In a `.mobileconfig` or registry policy, write the array as a JSON string as described under [Value types](/docs/third-party/claude-desktop/configuration#value-types). In a [bootstrap](/docs/third-party/claude-desktop/bootstrap) response, the key sits inside the `codeSurface` object.
### Interaction with Claude Code managed settings on the device
Claude 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:
1. `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), or by a bootstrap server the app trusts (a `bootstrapUrl` set through device management or covered by `trustBootstrapDelivery`; see [Keys that require user consent](/docs/third-party/claude-desktop/bootstrap#keys-that-require-user-consent)). User-scope registry policy (`HKCU`) counts as applied locally.
2. `sshHostAllowlist` from Claude Code's managed settings on the device.
3. `sshHostAllowlist` from a Claude Desktop configuration the user applied locally in the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration#apply-locally-or-export-for-a-fleet).
4. Off.
On devices where users applied the configuration locally, deploy `sshHostAllowlist` in Claude Code's managed settings. That restricts SSH without an MDM profile taking ownership of the whole configuration (see [Update keys and managed precedence](/docs/third-party/claude-desktop/mdm#update-keys-and-managed-precedence)).
## Inference credentials on the remote host
<Warning>
A remote session runs Claude Code on the SSH host with your organization's inference credential in its process environment, for as long as that process runs, including while Claude Desktop is closed. Anyone who can read that process's environment on the host, such as the same user account or a root user, can read the credential. List only hosts you trust with it, and prefer a credential that expires (single sign-on, or a credential helper that issues short-lived tokens) over a long-lived key.
</Warning>
The remote engine uses only the credential Claude Desktop passes in its environment. It ignores credentials already on the host, such as an AWS profile or application default credentials, and Claude Desktop copies no credential files there. Credential kinds that live in a file on the device are refused at session start.
| Provider | Works on a remote host | Refused at session start |
| ------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| [LLM gateway](/docs/third-party/claude-desktop/gateway) | Static API key, single sign-on, credential helper | |
| [Claude API](/docs/third-party/claude-desktop/claude-api) | Static API key, Sign in with Claude Console, credential helper | |
| [Microsoft Foundry](/docs/third-party/claude-desktop/foundry) | API key, in-app Entra ID sign-in, credential helper | |
| [Amazon Bedrock](/docs/third-party/claude-desktop/bedrock) | Bearer token, credential helper | In-app AWS sign-in (IAM Identity Center), named profile |
| [Amazon Bedrock Mantle](/docs/third-party/claude-desktop/mantle) | Bearer token, credential helper | |
| [Google Cloud's Agent Platform](/docs/third-party/claude-desktop/vertex) | In-app Workforce Identity sign-in, credential helper | In-app Google sign-in, service-account key or credentials file, application default credentials on the device |
When the configured credential is a refused kind, the session fails before anything is deployed to the host, with the card [Remote sessions aren't available with this inference setup](#remote-sessions-aren%E2%80%99t-available-with-this-inference-setup).
When the remote engine's credential expires during a turn, Claude Desktop obtains a new one on the device, by re-running a [credential helper](/docs/third-party/claude-desktop/credential-helper) or using a sign-in's refresh token, and sends it over the SSH connection. When the user signs out of the inference provider in the app, Claude Desktop ends the remote engine.
The 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.
## Managed configuration on the remote host
Most of the policy that Claude Desktop applies to a local Code session applies on the remote host too. The [Code page](/docs/third-party/claude-desktop/code#how-configuration-propagates) describes how each key reaches Claude Code.
* `disableEssentialTelemetry` and `disableNonessentialTelemetry`.
* `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.
* `disabledBuiltinTools`, `builtinToolPolicy`, and `autoModeEnabled`.
* [`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 a fleet value such as `~/Documents/Claude` confines remote sessions to that path under the SSH user's home. A folder with `mode` set to `ro` is allowed on the host but not read-only there.
* `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 and Claude Code shows a warning in the session.
* `managedMcpServers`, as the Claude Code managed setting that keeps users from adding their own MCP servers. The managed servers themselves are reached from the device.
* Plugins from your [allowed marketplaces](/docs/third-party/claude-desktop/extensions), copied to the host. A plugin's `hooks` directory is not copied, so its hooks do not run in a remote session, and a plugin whose manifest declares hooks elsewhere is not copied at all.
If the host has its own Claude Code managed settings, those take precedence over the policy Claude Desktop supplies, as described under [Interaction with Claude Code's own managed settings](/docs/third-party/claude-desktop/code#interaction-with-claude-code%E2%80%99s-own-managed-settings) for local sessions.
## Host requirements
The host needs the following.
* Linux or macOS on x86\_64 or arm64, or Windows on x64 or arm64.
* An SSH server with the SFTP subsystem. On Windows, Microsoft's OpenSSH Server; with other SSH servers, the engine does not survive a dropped connection.
* A POSIX shell, or PowerShell on Windows.
* `git` on the path, for git features.
* Up to about 700 MB of disk space in the SSH user's home directory, for the three Claude Code versions the app keeps.
The Claude Code engine is a standalone executable with no runtime dependencies. The device needs the OpenSSH client (`ssh` and `ssh-keygen`).
Claude Desktop writes the following into the SSH user's home directory on the host. Each user who connects gets their own copy.
| Path on the host | Contents |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| `~/.claude/remote/srv/<version>/` | The remote server that Claude Desktop talks to |
| `~/.claude/remote/ccd-cli/<version>` | The Claude Code engine, one file per version (the three most recent versions are kept) |
| `~/.claude/remote/run/<id>/` | The server's socket, token, and log |
| `~/.claude/remote/plugins/<hash>/` | Plugins synced from the device |
| `~/.claude/uploads/<session-id>/` | Files the user attached to a message. Not removed when the session ends |
| `~/.claude/` and `~/.claude.json` | Claude Code's own data, including session transcripts. See [Data storage](/docs/third-party/claude-desktop/data-storage) |
Each side of a remote session needs its own network access.
* The device must reach `downloads.claude.ai`, including devices installed with the [offline installer](/docs/third-party/claude-desktop/installation#offline-installation). Claude Desktop downloads the remote server there and uploads it to the host over SFTP.
* The host must reach your inference endpoint and, if configured, your OTLP collector, plus whatever the user's own work needs. It downloads the Claude Code engine from `downloads.claude.ai` when it can; when that fails, Claude Desktop downloads the engine on the device and uploads it over SFTP. Unless you disabled telemetry, the engine on the host also reports to the same Anthropic hosts as a local Code session (see [Telemetry and egress](/docs/third-party/claude-desktop/telemetry)). Blocking them does not affect the session.
### SSH configuration on the device
Claude Desktop applies the host's entry in the user's `~/.ssh/config`: hostname, port, user, identity file, SSH agent, and `ProxyCommand`.
* For hosts behind a bastion, configure a `ProxyCommand`. `ProxyJump` is not supported.
* The host's key must already be in the device's `~/.ssh/known_hosts` as a plain entry; the app does not prompt to accept a new key and does not evaluate `@cert-authority` entries. Have users connect once from a terminal before adding the host in the app.
* An identity file protected by a passphrase is skipped, not prompted for. Load it into the SSH agent, or use an unencrypted key.
* For a host reached through a `ProxyCommand`, the app skips host key verification and relies on the command to authenticate the host.
* The connection times out after 30 seconds. A larger `ConnectTimeout` in the host entry extends it.
## Troubleshoot
### SSH isn't allowed by your organization
The `sshHostAllowlist` in effect on this device is unset, empty, or has no entry that matches the host; the card's details say which. Both the host as the user entered it and the `HostName` from the device's `~/.ssh/config` must match. Which configuration source supplies the key on a device follows [Interaction with Claude Code managed settings on the device](#interaction-with-claude-code-managed-settings-on-the-device). The connection test reports the same denial as "Your organization's settings do not allow this connection."
### SSH to this machine isn't available
The host resolves to the device itself (`localhost`, `127.0.0.1`, or a tunnel or port forward that ends on the device) while `allowedWorkspaceFolders` restricts workspace folders. A session over SSH to the device reaches the same disk the policy restricts, so it is refused. Connect to a different host, or use a local session.
### Remote sessions aren't available with this inference setup
The configured inference credential is one of the kinds listed as refused under [Inference credentials on the remote host](#inference-credentials-on-the-remote-host), or the inference endpoint is on the device itself. The card's details say which. Switch the deployment to a credential kind that works on a remote host, or point the app at an endpoint the host can reach.
### SSH host key verification failed
The host's key is not in the device's `~/.ssh/known_hosts`, or it has changed. Connect to the host from a terminal on the device to record the current key, then retry.
## Related
* [Code in Claude Desktop on 3P](/docs/third-party/claude-desktop/code)
* [`sshHostAllowlist` in the configuration reference](/docs/third-party/claude-desktop/configuration#sshhostallowlist)
* [Desktop and filesystem access](/docs/third-party/claude-desktop/local-access)
third-party/claude-desktop/telemetry Changed · +9 / -8 lines
from line 249
### Optional features -| Host | Required when | -| ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | -| Host of `otlpEndpoint` | OpenTelemetry export is configured | -| `github.com`, `objects.githubusercontent.com`, `pypi.org`, `files.pythonhosted.org` | Python-based desktop extensions are enabled | -| Hosts of each entry in `managedMcpServers` (server URL, plus `oauth.authorizationServer` and `login.microsoftonline.com` if configured) | Managed MCP servers are configured | -| Search provider host of a built-in `websearch` server (`api.search.brave.com`, `api.tavily.com`, `api.exa.ai`, or the host of your `customUrl`) | [Built-in web search](/docs/third-party/claude-desktop/web-tools#built-in-web-search) is configured | -| Hosts in `coworkEgressAllowedHosts` | Sandbox web access is configured | +| Host | Required when | +| ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Host of `otlpEndpoint` | OpenTelemetry export is configured | +| `github.com`, `objects.githubusercontent.com`, `pypi.org`, `files.pythonhosted.org` | Python-based desktop extensions are enabled | +| Hosts of each entry in `managedMcpServers` (server URL, plus `oauth.authorizationServer` and `login.microsoftonline.com` if configured) | Managed MCP servers are configured | +| Search provider host of a built-in `websearch` server (`api.search.brave.com`, `api.tavily.com`, `api.exa.ai`, or the host of your `customUrl`) | [Built-in web search](/docs/third-party/claude-desktop/web-tools#built-in-web-search) is configured | +| Hosts in `coworkEgressAllowedHosts` | Sandbox web access is configured | +| `downloads.claude.ai` | [SSH remote sessions](/docs/third-party/claude-desktop/ssh-remote-sessions) are enabled (`sshHostAllowlist` set), including on devices installed with the offline installer | ## Disabling all Anthropic-bound connections -With `disableEssentialTelemetry`, `disableNonessentialTelemetry`, `disableNonessentialServices`, and `disableAutoUpdates` all set to `true`, the desktop application makes **no outbound connections to Anthropic-operated hosts at runtime**. The only required egress is `downloads.claude.ai` (for the VM bundle at session start) and your inference provider. With the [offline installer variant](/docs/third-party/claude-desktop/installation#offline-installation), `downloads.claude.ai` is not needed either, and your inference provider is the only required egress. +With `disableEssentialTelemetry`, `disableNonessentialTelemetry`, `disableNonessentialServices`, and `disableAutoUpdates` all set to `true`, the desktop application makes **no outbound connections to Anthropic-operated hosts at runtime**. The only required egress is `downloads.claude.ai` (for the VM bundle at session start) and your inference provider. With the [offline installer variant](/docs/third-party/claude-desktop/installation#offline-installation), `downloads.claude.ai` is not needed either, and your inference provider is the only required egress. Enabling [SSH remote sessions](/docs/third-party/claude-desktop/ssh-remote-sessions) adds `downloads.claude.ai` back for every device, because the offline installer does not include the remote-session components. These settings control only the application's telemetry, update, and non-essential service connections. They do not change how your inference provider handles conversation content at the endpoint. On Microsoft Foundry, the Claude models behind your inference endpoint run in an Anthropic-operated service, so conversation content reaches Anthropic-operated infrastructure regardless of these settings. See [Data handling by provider](/docs/third-party/claude-desktop/overview#data-handling-by-provider) on the Overview page.