Configuration reference - Claude.ai Documentation

Most settings on this page are easier to configure in the in-app configuration window. Use this reference when you’re scripting an MDM policy or bootstrap response by hand.

Claude Desktop on third-party (3P) is configured through OS-native managed preferences: a .mobileconfig profile on macOS, registry policy on Windows, or a root-owned JSON file on Linux (organizations in the admin console beta can instead deliver these settings from Organization settings on claude.ai). This page documents every supported key. For the desktop release each key first appeared in, see the configuration changelog. The easiest way to author a configuration is the in-app configuration window (Developer → Configure Third-Party Inference…), which validates values, shows per-provider requirements, and exports directly to .mobileconfig or .reg. Use this reference when you need to author policy by hand, audit an existing profile, or understand exactly what a key does.

How keys are read

Platform	Managed (MDM) location	Local (user) location
macOS	`/Library/Managed Preferences/<user>/com.anthropic.claudefordesktop.plist`	`~/Library/Application Support/Claude-3p/configLibrary/`
Windows	`HKLM\SOFTWARE\Policies\Claude` (machine), `HKCU\SOFTWARE\Policies\Claude` (user)	`%LOCALAPPDATA%\Claude-3p\configLibrary\`
Linux	`/etc/claude-desktop/managed-settings.json`	`~/.config/Claude-3p/configLibrary/`

The local location is a directory: _meta.json records which saved configuration is applied, and each configuration is a <id>.json file alongside it. The in-app configuration window writes here. When a managed source is present, it wins and locally written values are ignored. The exception is a managed source that sets only app-behavior keys (the update keys disableAutoUpdates, autoUpdaterEnforcementHours, and updateViaUpdatesHost, the lifecycle keys relaunchEnforcementHours and configRecheckIntervalMinutes, or the network proxy keys): those keys are enforced from the managed source, but the rest of the configuration stays local and user-editable. Configuration takes effect at launch, so fully quit and reopen the app after any change. From version 1.46388.1 a running app also notices a changed managed configuration at its next re-check (configRecheckIntervalMinutes, 10 minutes by default), prompts the user to restart, and requires the restart after relaunchEnforcementHours (24 hours by default). On Windows, the two policy hives are not merged: when machine policy is present under HKLM\SOFTWARE\Policies\Claude, the app ignores HKCU\SOFTWARE\Policies\Claude entirely; Deploy the configuration has the exact rule. See Deploy with MDM for the full precedence rules.

Claude Desktop on 3P reads the same managed-configuration sources as standard Claude Desktop but ignores keys scoped to standard deployments. Keys such as forceLoginOrgUUID have no effect in a 3P deployment.

Value types

Write every value as a string in the OS preference store, even booleans and arrays.

Documented type	What to write	Example
string	Plain string	`vertex`
boolean	`"true"` or `"false"` (or `1` / `0`)	`"true"`
integer	Decimal string	`"3600"`
string[] (JSON)	JSON array encoded as a string	`["claude-sonnet-5","claude-opus-5"]`
object (JSON)	JSON object mapping name to value, as a string	`{"X-Org-Id":"team1"}`
object[] (JSON)	JSON array of objects, as a string	see `managedMcpServers`

Array- and object-typed keys such as inferenceModels, inferenceGatewayOidc, managedMcpServers, coworkEgressAllowedHosts, and otlpHeaders are single keys whose value is a whole JSON document. The portable encoding is a JSON string, which works on every platform. In a .mobileconfig that is a single <string> element containing [...] or {...}, and on Windows a REG_SZ value. A macOS profile may instead carry the value as a native <array> or <dict>, which the app reads as the equivalent JSON. Separate keys with dotted names, such as inferenceGatewayOidc.clientId, are never read.

On Windows, write registry values as REG_SZ, directly under the policy key rather than nested in a subkey (the app never reads subkeys). REG_DWORD is also accepted for boolean and integer keys and is read as its decimal value. Avoid REG_EXPAND_SZ: the app counts it toward machine policy being present but cannot read its contents. The app cannot see REG_QWORD, REG_MULTI_SZ, or REG_BINARY values at all.

Linux

The managed source on Linux is a single JSON file, /etc/claude-desktop/managed-settings.json, with keys at the top level exactly as named in the reference — no wrapper object, no nesting:

{
  "inferenceProvider": "gateway",
  "inferenceGatewayBaseUrl": "https://gateway.example.com/v1",
  "inferenceGatewayApiKey": "sk-example",
  "inferenceCustomHeaders": { "X-Tenant-Id": "acme" }
}

Because the file is real JSON, array- and object-typed keys use native JSON values — the string-encoding rule above applies to plist and registry sources only. (String-encoded values are also accepted, so a profile generated for another platform can be reused.) The file is only honored when it can’t be edited by the user it configures:

managed-settings.json must be a regular file (not a symlink), owned by root, and not group- or world-writable.
/etc/claude-desktop itself must be a directory (not a symlink), owned by root, and not group- or world-writable.

A file that fails these checks is rejected: none of its settings are applied, the app treats the device as managed but unreadable, and local settings are also disabled until the file is fixed and the app is relaunched. The reason is logged to main.log in the app’s logs directory — ~/.config/Claude/logs/ (or ~/.config/Claude-3p/logs/ once the app is running in 3P mode); search for managed-settings.json. The same log names any key that fails schema validation. There is no per-user managed location on Linux; per-user configuration goes through the in-app configuration window, which writes to the local configLibrary directory above.

Reference

The reference below is generated from the configuration schema and grouped to match the sidebar of the in-app configuration window. The Availability column shows whether a key can be set in an MDM profile, returned from a bootstrap server, or both.

Connection

Setting	Type	Availability	Default	Description
Custom inference headers `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.
Sign-in session lifetime `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.
Helper script `inferenceCredentialHelper`	`string`	MDM + Bootstrap	—	Absolute path to an executable that prints the credential, optionally with per-request headers.
Helper script TTL `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`.
Credential helper timeout `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.
Re-run helper for silent refresh `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`.
Proxy server URL `egressProxyUrl`	`string`	MDM only	—	Send the app’s and the agent’s traffic through this HTTP proxy instead of the operating system’s proxy settings.
Proxy auto-config (PAC) URL `egressProxyPacUrl`	`string`	MDM only	—	URL of a PAC file that decides the proxy per request. Wins over the proxy server URL when both are set.
Enable IPv6 in the workspace VM `coworkVmIpv6Enabled`	`boolean`	MDM + Bootstrap	—	Give the Cowork workspace VM an IPv6 address and route so the agent’s tools can reach IPv6-only hosts through the device. macOS and Windows; off by default.
Artifact preview iframe origin `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.
Inference provider `inferenceProvider`	`enum`	MDM + Bootstrap	—	Selects the inference backend. Setting this key activates third-party mode. One of: `gateway`, `anthropic`, `bedrock`, `mantle`, `vertex`, `foundry`.
Credential kind `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.

inferenceCustomHeaders details

Sent on every inference and model-discovery request (joined into the CLI’s ANTHROPIC_CUSTOM_HEADERS).Use this for fleet-wide, non-secret constants. Do not put API keys, bearer tokens or other credentials here — this map is stored and distributed as plain configuration. For tokens, and for per-user or per-session values, have the credential helper script emit JSON with a headers field; those are merged over these static entries (helper wins on conflict).

inferenceCredentialHelper details

Claude runs the executable with no arguments and reads stdout (trimmed). Exit code must be 0; any output on stderr is logged but ignored. Stdout must contain only one of the formats below (no banners, prompts, or log lines).Output format is either:

a single bare token (the API key / bearer token), or
a JSON object {"token": "...", "headers": {"Name": "Value", ...}} when per-request headers are needed (merged over Custom inference headers, helper wins on conflict)

The helper receives CLAUDE_HELPER_CONTEXT in its environment (interactive, mid-session-refresh, background, scheduled-task, setup-test) so it can decide whether to prompt the user — see the credential-helper docs for the full contract.Result is cached for the TTL below. On TTL expiry the helper is re-invoked transparently (no user prompt, no relaunch).Expiry and refresh: the app checks the active credential’s expiry before each turn and refreshes silently when possible (re-runs the helper, or uses the stored refresh token for interactive sign-in kinds). If the provider returns HTTP 401 mid-turn, the same silent refresh is attempted before surfacing an error. When silent refresh fails, a prompt appears with a provider-specific action (re-sign-in for interactive kinds; admin-contact for static credentials). Applies to all providers, and to both Cowork and Code.Typical use: a shell script that pulls from Keychain, 1Password CLI, or an internal secret broker. Example:security find-generic-password -s anthropic-api -wIf this field is set, static credential fields (API key, bearer token) are ignored. The helper always wins.

egressProxyUrl details

Pins the app (sign-in, the connection test, model discovery, MCP servers, plugins), the Claude Code engine behind Chat, Cowork, and Code, and on macOS and Windows the Cowork workspace VM (the agent’s shell, package-install, git, and plugin commands, and the whole engine under requireCoworkFullVmSandbox) to one HTTP proxy. Use it when your gateway or the internet is reachable only through a corporate proxy and you cannot rely on the system proxy. It is a reachability setting, not an egress control.The value is an http:// or https:// URL, usually with a port. SOCKS proxies and embedded credentials (user:pass@) are rejected. Give a local forwarding proxy on the device as http://127.0.0.1:port; an https:// loopback address cannot be verified from inside the Cowork workspace VM. Requests to localhost, 127.0.0.1, [::1], and *.local names bypass the proxy so local MCP servers keep working; everything else goes through it, and if the proxy is unreachable requests fail rather than connect directly. The engine receives it as HTTPS_PROXY and HTTP_PROXY with a matching NO_PROXY; if Claude Code managed settings on the device set those variables, they win for the engine on the host. Traffic that never uses this proxy: the Cowork workspace VM on Linux, credential and header helper scripts, the update download, the Windows sign-in broker, and pages opened in the system browser.Read once at launch from device management (MDM) or the local configuration file only; a configuration server cannot deliver it, because the app may need the proxy to reach that server. A profile that sets only this key (or only the other app-behavior keys, such as disableAutoUpdates) does not take over a connection users set up in the app, but those keys are read from one source as a group, so put the proxy in the same profile as your update settings. Changes apply at the next app start. When egressProxyPacUrl is also set, the PAC file wins and this key is ignored.

egressProxyPacUrl details

At launch the app downloads the PAC script and asks it which proxy to use for each request, as a browser would, instead of following the operating system’s proxy settings. Same value rules, coverage, exclusions, and delivery as egressProxyUrl, except that bypassing is the script’s decision: localhost, 127.0.0.1, and [::1] still never use a proxy, but *.local names and everything else follow whatever it returns. If the PAC file cannot be downloaded, the app connects directly rather than failing.On macOS and Windows the Cowork workspace VM is handed a copy of the script when it starts and evaluates it for each request itself; there myIpAddress() returns the VM’s internal address rather than the device’s, so a script that chooses by client subnet gives the VM its off-network answer (if that download fails, the VM connects directly). The Claude Code engine behind Chat, Cowork, and Code cannot evaluate a PAC file, so the app hands it one proxy (whichever the script returns for your inference endpoint) plus a bypass for loopback and *.local names. If the script answers DIRECT or only SOCKS for that endpoint, the engine uses no proxy at all, so have it return an HTTP PROXY host:port entry there; if the engine needs different rules, set HTTPS_PROXY and NO_PROXY in Claude Code managed settings, which win for the engine on the host.

coworkVmIpv6Enabled details

When set to true, the Cowork workspace VM on macOS and Windows gets a static IPv6 address (a unique local fd… address) and an IPv6 default route on its virtual network next to its IPv4 address, and the VM’s gateway forwards that traffic over the device’s own IPv6 connectivity, as it already does for IPv4. Use it when the tools the agent runs in the VM (shell commands, package installs, git, plugin commands, and the whole engine under requireCoworkFullVmSandbox) must reach IPv6-only destinations. The VM’s resolver then also returns IPv6 (AAAA) answers. A connection the VM makes over IPv6 succeeds only where the device’s own IPv6 does; on a device without working IPv6, destinations that have both keep working over IPv4 and IPv6-only destinations stay unreachable. Because the VM’s address is unique-local, most tools in it keep preferring IPv4 for destinations that have both, so IPv6 mostly carries traffic to IPv6-only destinations.This is a reachability setting, not an egress control: coworkEgressAllowedHosts keeps deciding which hostnames the agent’s tools may reach, by name, over either protocol, and IPv6 literals are still not accepted there. Hosts your policies allow must also be reachable, and filtered the way you intend, over IPv6 on your network.Unset (default): the VM is IPv4-only and its resolver returns no IPv6 answers. A change takes effect the next time the workspace VM starts, typically at the next app launch. Does not apply to the Cowork workspace VM on Linux or to Code sessions, which use the device’s own network stack.

inferenceProvider details

The app activates 3P mode only when this is set and the required credential keys for the selected provider are present and valid; otherwise it launches in standard mode. Keys for providers other than the selected one are ignored. Each provider’s required keys are documented on its dedicated page under Inference providers.

Anthropic

Setting	Type	Availability	Default	Description
Claude API key `inferenceAnthropicApiKey`	`string`	MDM + Bootstrap	—	Leave blank to fetch a key via browser sign-in, or to supply the key via a credential helper.

Bedrock

Setting	Type	Availability	Default	Description
AWS region `inferenceBedrockRegion`	`string`	MDM + Bootstrap	—	AWS region for the Bedrock runtime endpoint.
Bedrock base URL `inferenceBedrockBaseUrl`	`string`	MDM + Bootstrap	—	For VPC endpoints or gateway proxies. Host origin only.
Bedrock service tier `inferenceBedrockServiceTier`	`enum`	MDM + Bootstrap	—	Sent as the X-Amzn-Bedrock-Service-Tier header. Leave unset for on-demand. One of: `flex`, `priority`.
AWS bearer token `inferenceBedrockBearerToken`	`string`	MDM + Bootstrap	—	Static bearer token for inference. For providers that support profile or helper-script credentials, prefer those.
AWS SSO start URL `inferenceBedrockSsoStartUrl`	`string`	MDM + Bootstrap	—	Enables in-app AWS sign-in (no AWS CLI needed). Set with the three SSO fields below.
AWS SSO region `inferenceBedrockSsoRegion`	`string`	MDM + Bootstrap	—	IAM Identity Center home region.
AWS SSO account ID `inferenceBedrockSsoAccountId`	`string`	MDM + Bootstrap	—	12-digit AWS account ID assigned to users in IAM Identity Center.
AWS SSO role name `inferenceBedrockSsoRoleName`	`string`	MDM + Bootstrap	—	IAM Identity Center permission-set name granting bedrock:InvokeModel* on the account above.
AWS profile name `inferenceBedrockProfile`	`string`	MDM + Bootstrap	—	AWS named profile to use for Bedrock inference credentials.
AWS config directory `inferenceBedrockAwsDir`	`string`	MDM + Bootstrap	—	Folder with AWS config/credentials. Defaults to ~/.aws when no bearer token is set.
AWS CLI path `inferenceBedrockAwsCliPath`	`string`	MDM + Bootstrap	—	Absolute path to the aws executable. Leave unset to find it on PATH.

inferenceBedrockServiceTier details

Tier availability varies by model and region. Reserved capacity uses a provisioned-throughput ARN as the model ID instead of this setting. Older bundled Claude Code CLI versions ignore this key.

Foundry

Setting	Type	Availability	Default	Description
Azure AI Foundry resource name `inferenceFoundryResource`	`string`	MDM + Bootstrap	—	Azure AI Foundry resource name used to construct the endpoint URL.
Azure AI Foundry API key `inferenceFoundryApiKey`	`string`	MDM + Bootstrap	—	API key for Azure AI Foundry inference.
Entra ID tenant ID `inferenceFoundryTenantId`	`string`	MDM + Bootstrap	—	Directory (tenant) ID of the Entra ID app registration that has the Cognitive Services scope.
Entra ID client ID `inferenceFoundryClientId`	`string`	MDM + Bootstrap	—	Application (client) ID of the Entra ID app registration. Device-code sign-in requires the app to allow public client flows.
Entra ID sign-in flow `inferenceFoundryAuthFlow`	`enum`	MDM + Bootstrap	—	How Entra sign-in runs: device code (default), system browser, or the OS identity broker. One of: `device-code`, `browser`, `broker`.

inferenceFoundryAuthFlow details

device-code (default) — shows a code to enter at microsoft.com/devicelogin. The app registration must have Allow public client flows enabled.
browser — opens the system browser for an authorization-code (PKCE) sign-in on a loopback redirect URI. The app registration must include http://127.0.0.1/callback under the Mobile and desktop applications platform (Entra ignores the loopback port, but not the path). Works with Allow public client flows disabled, and is unaffected by Conditional Access policies that block device-code authentication.
broker — signs in through the OS identity broker (Web Account Manager on Windows, Company Portal on macOS), so it can satisfy Conditional Access policies that require a compliant/managed device or token protection. The app registration must include the broker redirect URIs ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id} (Windows) and msauth.com.anthropic.claudefordesktop://auth (macOS) under the Mobile and desktop applications platform. Not supported on Linux.

App versions that predate this key always use device code; versions that predate the broker option treat broker as unset and use device code.

Gateway

Setting	Type	Availability	Default	Description
Gateway base URL `inferenceGatewayBaseUrl`	`string`	MDM + Bootstrap	—	Full URL of the inference gateway endpoint.
Stream idle timeout `inferenceStreamIdleTimeoutSec`	`integer`	MDM + Bootstrap	—	Extra seconds to wait for model output on a streaming response that is sending only keep-alive pings. Gateway provider only. Default 300. Range: 300–1800.
Gateway API key `inferenceGatewayApiKey`	`string`	MDM + Bootstrap	—	API key for the configured inference gateway.
Gateway auth scheme `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.
Gateway sign-in flow `inferenceGatewayOidcAuthFlow`	`enum`	MDM + Bootstrap	—	How the IdP sign-in runs: system browser (default) or the OS Microsoft Entra broker. One of: `browser`, `broker`.
Gateway SSO IdP (OIDC) `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.

inferenceStreamIdleTimeoutSec details

Raises how long Cowork, Chat and Code sessions wait for the next model event on an open streaming response (Claude Code’s CLAUDE_STREAM_IDLE_TIMEOUT_MS). It only helps when the gateway writes SSE keep-alive ping events (or : comment lines) into the response while the upstream model is silent — for example a LiteLLM proxy with keep-alive pings enabled in front of Amazon Bedrock. With pings arriving, Claude Code accepts at least about five minutes of keep-alives and then waits this many seconds more for real model output before abandoning the request. Gateway provider only; the other providers keep Claude Code’s defaults.A response on which nothing at all arrives — no pings — still fails after about 5 minutes regardless of this key, because at the device a silent connection cannot be told apart from a dead one. If long generations fail behind a gateway that does not send pings, configure the gateway to send them rather than raising this value. While this key is set, the app’s value takes precedence over CLAUDE_STREAM_IDLE_TIMEOUT_MS in Claude Code’s own managed settings for sessions the app starts; when it is unset, that setting still applies. Values outside 300–1800 are rejected at parse time (the error is listed in the diagnostics report) and the default applies.

inferenceGatewayOidcAuthFlow details

browser (default) — opens the system browser for an authorization-code (PKCE) sign-in on a loopback redirect URI. See the IdP setup notes on inferenceGatewayOidc for redirect-URI registration.
broker — signs in through the OS identity broker (Web Account Manager on Windows, Company Portal on macOS). Requires the IdP to be Microsoft Entra ID — the issuer on inferenceGatewayOidc must be https://login.microsoftonline.com/{tenant-id}/v2.0. The broker satisfies Conditional Access policies that require a compliant/managed device or token protection, and needs no 127.0.0.1/callback loopback redirect. The Entra app registration must include the broker redirect URIs ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id} (Windows) and msauth.com.anthropic.claudefordesktop://auth (macOS) under the Mobile and desktop applications platform. Not supported on Linux.

Broker mode mints a token in the customer’s own Entra tenant with the customer-configured scopes, and forwards it to the customer’s own gateway; both endpoints of that trust relationship are inside the customer’s control.

inferenceGatewayOidc details

External IdP mode. The app discovers <issuer>/.well-known/openid-configuration, runs an OIDC authorization-code-with-PKCE sign-in in the system browser with clientId, and sends the resulting token as Authorization: Bearer on every inference request. Leave this unset for a gateway that hosts its own RFC 8414 metadata at <baseUrl>/.well-known/oauth-authorization-server.Bearer token type. id_token (the default) sends the OIDC ID token; the gateway validates signature, iss, and aud (the clientId configured here). access_token sends the OAuth access token, for gateways that validate as a resource server (Portkey, Kong, Envoy JWT filter, AWS API Gateway authorizers); scopes must then name the gateway’s registered API scope. Either way the gateway must check aud, not just signature and issuer, or it accepts any token from your tenant.IdP setup. The app’s loopback callback is http://127.0.0.1:<port>/callback; register 127.0.0.1 (not localhost) and include /callback. Entra: a public-client app with a Mobile and desktop applications redirect URI of http://127.0.0.1/callback (any port; omitting the path fails with AADSTS50011); in access_token mode also grant the gateway API’s delegated permission, or sign-in fails with AADSTS65001. Okta: a Native app with the exact URI http://127.0.0.1:<port>/callback and that port in redirectPort.Refresh. With offline_access the app renews the token silently and prompts a browser sign-in only when refresh fails. Google never returns an id_token on refresh, so a Google Workspace-backed gateway in id_token mode re-prompts about hourly; access_token mode is unaffected.

Field	Type	Default	Description
`clientId`	`string`	—	OAuth client ID of the desktop app registration at your identity provider (public client, PKCE).
`issuer`	`string`	—	HTTPS issuer with OIDC discovery. Set this, or set the authorization and token URLs instead.
`authorizationUrl`	`string`	—	HTTPS authorization endpoint. Used with the token URL when no issuer is set.
`tokenUrl`	`string`	—	HTTPS token endpoint. Used with the authorization URL when no issuer is set.
`bearerTokenType`	`enum`	`id_token`	Which token to send as the gateway bearer. Use access token for gateways that validate as an OAuth resource server. One of: `id_token`, `access_token`.
`scopes`	`string`	—	Space-separated scopes. Required in access-token mode: set the gateway’s API scope. offline_access is appended automatically unless disabled below.
`appendOfflineAccess`	`boolean`	`true`	Automatically append offline_access to scopes so the IdP returns a refresh token for silent refresh.
`resource`	`string`	—	Absolute URL identifying the gateway as the access-token audience. Sent as the RFC 8707 resource parameter when set; leave unset for Microsoft Entra ID.
`redirectPort`	`integer`	—	Fixed loopback port for the sign-in redirect (http://127.0.0.1:PORT/callback). Leave unset to use a free port each time.
`additionalRedirectReferrerHosts`	`string`	—	Space-separated hostnames also accepted as the referrer of the sign-in callback. Only needed when the IdP completes sign-in from a different host.

Models

Setting	Type	Availability	Default	Description
Model discovery `modelDiscoveryEnabled`	`boolean`	MDM + Bootstrap	—	Auto-populate the model picker from the provider at launch.
Default to 1M context `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.
Model list `inferenceModels`	`object[]`	MDM + Bootstrap	—	Override the auto-discovered model list. First entry is the default.
Show estimated cost `inferenceModelPricingEnabled`	`boolean`	MDM + Bootstrap	—	Show an estimated cost on the Usage page at Anthropic list price; turn on to set a multiplier or per-model rates.
Price multiplier `inferenceModelPricingMultiplier`	`number`	MDM + Bootstrap	—	Scales every estimated cost (0.85 = 85% of the price); between 0 and 1. Range: 0–1.
Model pricing `inferenceModelPricing`	`object[]`	MDM + Bootstrap	—	Per-model rates replacing Anthropic list price in the Usage page’s estimate.

modelDiscoveryEnabled details

Auto-populate the model picker from the provider’s model-list endpoint at launch. For gateway and Anthropic providers, a config that doesn’t set this key skips discovery automatically when the model list below already makes it unnecessary; the toggle here only sets it explicitly on or off. Turn off if the endpoint isn’t reachable from your network, or to use a fixed list. When off, the model list below is required and must use full model IDs (aliases like sonnet/opus are resolved via discovery).

modelPrefer1mContext details

When a user has no saved selection, start the picker on the 1M-context variant of the default model (the first listed model, or the first model your endpoint returns under discovery) if it offers one. A saved selection is always kept; users who picked a model before this version need to pick the 1M row once, after which it persists. Equivalent to setting prefer1m on the default entry of inferenceModels, but also applies under dynamic discovery.

inferenceModels details

Use the provider’s exact model ID: Vertex publisher IDs (claude-sonnet-5), Bedrock inference-profile IDs (us.anthropic.claude-sonnet-5), or Foundry deployment names. Entries may be plain ID strings or objects.Gateway: the name must be the exact ID your gateway’s /v1/models endpoint returns. If you set supports1m on an alias (sonnet) but discovery returns the full ID, the variant won’t appear.Extended context (supports1m) is a capability assertion you make about your deployment; only set it for models you’ve confirmed support the 1M-token window:

[{"name": "claude-sonnet-5", "supports1m": true}, "claude-opus-4-8"]

"claude-sonnet-5[1m]" is shorthand for the same entry. When an ID is listed both bare and with [1m] (as a gateway lists it), the picker shows one model with a 1M variant; put labelOverride on the bare entry (a label on the [1m] spelling is ignored there); tier-tagged entries are not folded. prefer1m: true (no effect without supports1m) makes the 1M variant the default picker selection when this entry is the default model; users can still switch, and an explicit pick is kept. Under dynamic discovery (no explicit list), set modelPrefer1mContext instead.Display label (labelOverride) is for IDs the picker can’t derive a friendly name from (Bedrock ARNs, gateway routing aliases). Display-only; name is still what the app sends:

[{"name": "arn:aws:bedrock:us-east-1:123:application-inference-profile/abc", "labelOverride": "Claude Opus (Prod)"}]

Tier mapping (anthropicFamilyTier) tells the app which Claude tier (haiku/sonnet/opus/fable/mythos) an entry stands in for, so bare tier aliases (e.g. in Code sessions) resolve to your model. isFamilyDefault: true picks the winner when several entries share a tier:

[{"name": "us.anthropic.claude-opus-4-8", "anthropicFamilyTier": "opus"}]

Field	Type	Default	Description
`name`	`string`	—	Model ID exactly as the provider expects it. The first entry is the default model.
`labelOverride`	`string`	—	Shown in the model picker. Leave blank to auto-format from the ID.
`supports1m`	`boolean`	—	Adds a 1M-context variant of this model to the picker. Set only if the deployment accepts 1M-token context for it.
`prefer1m`	`boolean`	—	Make the 1M-context variant the default picker selection when this model is the default (first) entry. Users can still choose the standard variant.
`anthropicFamilyTier`	`enum`	—	Which Claude tier this model stands in for. Pins the bare alias (e.g. ‘opus’) and, for opus/fable, the refusal fallback. One of: `sonnet`, `opus`, `haiku`, `fable`, `mythos`.
`isFamilyDefault`	`boolean`	—	When several models share a tier alias, marks this one as the model the alias resolves to. Otherwise the first listed wins.

inferenceModelPricingEnabled details

Off unless set: the Usage page shows token counts only, since the app cannot know your negotiated provider rates. true turns on a USD estimate priced at Anthropic’s published list price and is the only switch that does: inferenceModelPricingMultiplier and inferenceModelPricing refine the estimate while this is on and are ignored otherwise; turning this off hides them in the config editors without clearing them. Claude Code performs the calculation, so the same figures appear in its own cost reporting for Code sessions. Model IDs Claude Code cannot map to a Claude model (an opaque gateway alias, an inference-profile ARN it cannot resolve) are left out of the estimate until inferenceModelPricing gives them a rate. A machine-level Claude Code managed modelPricing (MDM / managed-settings.json / server-managed) takes precedence over all three keys.

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. Applies only while inferenceModelPricingEnabled is true; on its own it does not turn the estimate on. Ignored when a machine-level Claude Code managed modelPricing is present.

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); rows apply only while inferenceModelPricingEnabled is true and do not turn the estimate on by themselves. 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.

{"inferenceModelPricingEnabled": true, "inferenceModelPricingMultiplier": 0.9, "inferenceModelPricing": [{"name": "claude-sonnet-4-6", "inputPerMtok": 2.4, "outputPerMtok": 12, "cacheReadPerMtok": 0.24, "cacheWritePerMtok": 3}]}

These are estimates for visibility, not an invoice; your provider bills at its own rates. A machine-level Claude Code managed modelPricing (MDM / managed-settings.json / server-managed) takes precedence over this table.

Field	Type	Default	Description
`name`	`string`	—	A model ID from the list above, or any other ID or alias your provider serves. A built-in Claude ID also covers its dated and provider forms.
`inputPerMtok`	`number`	—	USD per million input tokens.
`outputPerMtok`	`number`	—	USD per million output tokens.
`cacheReadPerMtok`	`number`	—	USD per million prompt-cache read tokens.
`cacheWritePerMtok`	`number`	—	USD per million prompt-cache write tokens (5-minute and 1-hour writes alike).

Vertex

Setting	Type	Availability	Default	Description
GCP project ID `inferenceVertexProjectId`	`string`	MDM + Bootstrap	—	Google Cloud project ID for Vertex AI inference.
GCP region `inferenceVertexRegion`	`string`	MDM + Bootstrap	—	GCP region where your Vertex AI Claude models are deployed.
Vertex AI base URL `inferenceVertexBaseUrl`	`string`	MDM + Bootstrap	—	PSC endpoint, if using one.
Vertex OAuth client ID `inferenceVertexOAuthClientId`	`string`	MDM + Bootstrap	—	Desktop-app OAuth client ID. Enables Sign in with Google instead of a credentials file.
Vertex OAuth client secret `inferenceVertexOAuthClientSecret`	`string`	MDM + Bootstrap	—	Secret for the Desktop-app OAuth client above. Google classifies installed-app client secrets as non-confidential, so this may be set from hosted config.
Vertex OAuth scopes `inferenceVertexOAuthScopes`	`string`	MDM + Bootstrap	—	Override the Google OAuth scopes (space-separated). Leave blank for the default.
Vertex OAuth login hint `inferenceVertexOAuthLoginHint`	`string`	MDM + Bootstrap	—	Pre-fill Google’s account chooser and forward to your federated IdP. {username} expands to the OS login name.
Workforce Identity audience `inferenceVertexWorkforceAudience`	`string`	MDM + Bootstrap	—	Workforce-pool provider audience. When set, sign-in uses your own IdP plus a GCP STS exchange instead of a Google identity.
Workforce Identity billing project `inferenceVertexWorkforceUserProject`	`string`	MDM + Bootstrap	—	GCP project for STS billing and quota. Defaults to the Vertex project ID above.
Workforce Identity sign-in flow `inferenceVertexWorkforceAuthFlow`	`enum`	MDM + Bootstrap	—	How the IdP sign-in runs: system browser (default) or the OS Microsoft Entra broker. One of: `browser`, `broker`.
Workforce Identity IdP (OIDC) `inferenceVertexWorkforceOidc`	`object`	MDM + Bootstrap	—	Your organization’s OIDC IdP. The app runs an authorization-code-with-PKCE flow against this issuer and exchanges the returned ID token at GCP STS.
GCP credentials file path `inferenceVertexCredentialsFile`	`string`	MDM + Bootstrap	—	Absolute path to service-account JSON. Leave blank to fall back to ADC.

inferenceVertexWorkforceAuthFlow details

browser (default) — opens the system browser for an authorization-code (PKCE) sign-in on a loopback redirect URI. See the IdP setup notes on inferenceGatewayOidc for redirect-URI registration; the same rules apply here.
broker — signs in through the OS identity broker (Web Account Manager on Windows, Company Portal on macOS). Requires the workforce-pool IdP to be Microsoft Entra ID — the issuer on inferenceVertexWorkforceOidc must be https://login.microsoftonline.com/{tenant-id}/v2.0. The broker satisfies Conditional Access policies that require a compliant/managed device or token protection, and needs no 127.0.0.1/callback loopback redirect. The Entra app registration must include the broker redirect URIs ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id} (Windows) and msauth.com.anthropic.claudefordesktop://auth (macOS) under the Mobile and desktop applications platform. Not supported on Linux.

The GCP STS token-exchange step is unchanged in either flow; only how the Entra id_token is acquired differs.

inferenceVertexWorkforceOidc details

Field	Type	Default	Description
`clientId`	`string`	—	OAuth client ID of the desktop app registration at your identity provider (public client, PKCE).
`issuer`	`string`	—	HTTPS issuer with OIDC discovery. Set this, or set the authorization and token URLs instead.
`authorizationUrl`	`string`	—	HTTPS authorization endpoint. Used with the token URL when no issuer is set.
`tokenUrl`	`string`	—	HTTPS token endpoint. Used with the authorization URL when no issuer is set.
`scopes`	`string`	—	Space-separated scopes. Defaults to openid profile email offline_access.
`redirectPort`	`integer`	—	Fixed loopback port for the sign-in redirect (http://127.0.0.1:PORT/callback). Leave unset to use a free port each time.
`omitOfflineAccess`	`boolean`	—	Only enable if your IdP rejects the offline_access scope on this client. Without it the app prompts for sign-in each time the token expires.
`additionalRedirectReferrerHosts`	`string`	—	Space-separated hostnames also accepted as the referrer of the sign-in callback. Only needed when the IdP completes sign-in from a different host.

Workspace

Authentication

Setting	Type	Availability	Default	Description
Disable Claude.ai sign-in `disableDeploymentModeChooser`	`boolean`	MDM + Bootstrap	`false`	Users see only this provider at the login screen. The option to sign in to Claude.ai is hidden. Defaults to `false`.
Disable claude:// deep-link handling `disableDeepLinkRegistration`	`boolean`	MDM + Bootstrap	`false`	Stop external apps and websites from opening Claude Desktop via claude:// links. Defaults to `false`.

Chat surface

Setting	Type	Availability	Default	Description
Allow Chat `chatTabEnabled`	`boolean`	MDM + Bootstrap	—	Enable Chat. Quick questions and drafting.
Advanced file analysis `chatAdvancedFileAnalysisEnabled`	`boolean`	MDM + Bootstrap	—	Allow Claude to run code in a local sandbox to analyze attached files it can’t read natively — like Excel and PowerPoint. Off by default.

chatAdvancedFileAnalysisEnabled details

Also enables inline data analysis. The sandbox can only read files attached to the conversation and has no network access.

Code surface

Setting	Type	Availability	Default	Description
Allow Code `isClaudeCodeForDesktopEnabled`	`boolean`	MDM + Bootstrap	`true`	Enable Code. Claude writes and runs code. Defaults to `true`.
SSH host allowlist `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.
SSH client program `sshClientPath`	`string`	MDM + Bootstrap · Beta	—	Absolute path to the OpenSSH ssh program the app runs for SSH sessions. Unset: the first ssh on the user’s PATH.
SSH connection engine `sshTransport`	`enum`	MDM + Bootstrap · Beta	—	Which SSH engine carries Code sessions: the OpenSSH ssh program on the device, or the app’s built-in SSH library. Unset or auto: the build’s default. One of: `auto`, `system-openssh`, `builtin`.

sshHostAllowlist details

When off, the SSH option is hidden and any connection attempt is refused.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. Both the host the user entered and the HostName their ~/.ssh/config resolves it to must match, so an alias cannot reach a host outside the list. ProxyCommand is permitted when the resolved host matches (this key governs which hosts the app offers, not network egress); ProxyJump is refused with a message suggesting ProxyCommand.This is opt-in because a remote session runs Claude Code on the SSH host and the app forwards the session’s inference credential to it, plus your OTLP collector endpoint and auth headers when otlpEndpoint is set. List only hosts you trust with those. Token-based credentials are forwarded; file-based kinds (Bedrock IAM Identity Center sign-in or AWS profile, Vertex Google sign-in or a credentials file) are refused at session start.If this key is unset, an sshHostAllowlist in 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 (MDM, the admin console, or a device-managed bootstrap URL) and otherwise applies only while that file sets none. allowedWorkspaceFolders still applies on the remote host.

sshClientPath details

Pins which OpenSSH client the app runs wherever it starts ssh: evaluating the user’s SSH configuration (ssh -G), making the SSH connection and its channels, and the Code tab’s terminal. ssh-keygen and ssh-add are taken from the same directory when they exist there, otherwise from PATH. The program must be OpenSSH 7.6 or newer (on Windows, Win32-OpenSSH 9.4 or newer to carry the connection); on macOS and Linux a wrapper script that ends in one is accepted, on Windows it must be a native .exe (not a .cmd, .bat or .ps1 script). When this key is set and the program is missing, cannot be run, or is too old, SSH sessions fail with an error telling the user to ask their IT administrator (the configured path is in its details) — the app never falls back to another ssh. The connection itself runs through this program on the system-OpenSSH engine, which the SSH connection engine setting’s system-openssh value selects on every platform, including Windows; when the app’s built-in SSH library makes the connection instead, this key still governs configuration evaluation (ssh -G), host-key lookups (ssh-keygen) and the terminal.

sshTransport details

system-openssh: the app makes every SSH connection by running an OpenSSH ssh program — the one sshClientPath names, otherwise the first ssh on the user’s PATH (on Windows, a Win32-OpenSSH ssh.exe: the PATH one, else the in-box or Microsoft-installed client) — so the organization’s own OpenSSH build, with its Kerberos/GSSAPI, certificate and ssh_config support, is what authenticates. The program must be OpenSSH 7.6 or newer (Windows: Win32-OpenSSH 9.4 or newer). When sshClientPath is set and that program cannot be used, sessions fail with an error telling the user to ask their IT administrator rather than falling back; when it is unset and Windows has no usable client, the built-in library is used.builtin: the app’s built-in SSH library makes the connection, whatever the build’s default.auto or unset: the build’s default engine.An explicit value applies to new connections (sessions already connected keep their engine) and overrides the build’s default in both directions, including any remote switch-off Anthropic ships for the OpenSSH engine — so with system-openssh set, switching back is done here, by setting builtin.

Cowork surface

Setting	Type	Availability	Default	Description
Allow Cowork `coworkTabEnabled`	`boolean`	MDM + Bootstrap	`true`	Enable Cowork. Claude works on longer tasks like research, analysis, and documents. Defaults to `true`.

Workspace

Setting	Type	Availability	Default	Description
Allow user-added plugin marketplaces `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.
Allow user-added plugins `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.
Disabled built-in tools `disabledBuiltinTools`	`string[]`	MDM + Bootstrap	—	Built-in tools, or argument-scoped permission rules such as Read(**/.env), denied in Cowork and Code.
Disable bundled skills and workflows `disableBundledSkills`	`boolean`	MDM + Bootstrap	—	Disables Claude Code’s bundled skills and workflows (deep-research and similar). Use where WebFetch/WebSearch aren’t available.
Allow user-created skills `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.
Built-in tool policy `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.
Allow Auto mode `autoModeEnabled`	`boolean`	MDM + Bootstrap	`false`	Offer Auto mode in the Cowork and Code permission selectors. Claude decides which actions need approval. Defaults to `false`.
Disable bypass permissions mode `disableBypassPermissionsMode`	`boolean`	MDM + Bootstrap	—	Remove the bypass permissions mode from Code sessions and Cowork tasks, so Claude always follows the permission policy. Off by default.
Enable tool search `toolSearchEnabled`	`boolean`	MDM + Bootstrap	`false`	Load MCP tool schemas on demand (tool search) instead of inlining every schema into context. Defaults to `false`.
Skip WebFetch domain check `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.
Allowed workspace folders `allowedWorkspaceFolders`	`object[]`	MDM + Bootstrap	—	Folders where Claude may work. Applies to both Cowork and Code sessions. Leave unset for unrestricted access.
Block reads outside working directories `blockReadsOutsideWorkingDirectories`	`boolean`	MDM + Bootstrap	—	Keep Claude from reading files outside a Code session’s working directories. File tools refuse such reads; sandboxed shell commands lose the home directory.
Allowed egress hosts `coworkEgressAllowedHosts`	`string[]`	MDM + Bootstrap	—	Hostnames the agent’s tools may reach from Cowork and Code sessions. Also surfaced under Egress Requirements.
Require full VM sandbox `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`.
Organization instructions `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.

userPluginMarketplacesEnabled details

When on (default), users can add plugin marketplaces from the plugin browser. Set to false to block user marketplace adds: the add-marketplace surfaces are hidden, and the app refuses adds that still reach it (deep links, stale UI).This is a feature-availability control enforced in the app, not a data boundary: marketplaces already registered on the user’s machine (or registered outside the app, for example by the Claude Code CLI or by editing Claude Code’s plugin files) are not removed or blocked by this key. Marketplaces provisioned by your organization (allowedPluginMarketplaces) are unaffected.This key applies only while the app runs in third-party mode. If users could otherwise sign in to Claude.ai on the device, also set disableDeploymentModeChooser so the app stays in third-party mode.

userPluginUploadsEnabled details

When on (default), users can upload plugin files and create plugins with Claude. Set to false to stop users adding plugins of their own: every in-app option for doing so is hidden, and the app refuses uploads that still reach it.This is a feature-availability control enforced in the app, not a data boundary: plugins already installed (or placed on disk outside the app) are not removed or blocked by this key. Plugins from organization-provisioned marketplaces and the organization plugins directory are unaffected.This key applies only while the app runs in third-party mode. If users could otherwise sign in to Claude.ai on the device, also set disableDeploymentModeChooser so the app stays in third-party mode.

disabledBuiltinTools details

Each entry is a Claude Code tool name (Bash, Read, Write, Edit, Glob, Grep, NotebookEdit, WebFetch, WebSearch, Task, TodoWrite, TaskCreate, TaskUpdate, TaskGet, TaskList, TaskStop, Skill, REPL, JavaScript, AskUserQuestion, ToolSearch, SendUserMessage) or an argument-scoped permission rule such as Bash(curl *) or Edit(**/*.env). A bare name covers every call; a scoped rule covers matching calls in every permission mode, including Auto and bypass. Scopes are matched for Bash(…) (a command pattern) and for file paths written as Read(…) (covers Read, Grep, Glob) or Edit(…) (covers Edit, Write, NotebookEdit); other tools take Tool(<field>:<pattern>). WebSearch and WebFetch are bare-name only: per-host web access is coworkEgressAllowedHosts.Scoped Bash(…) rules apply in Code sessions and in VM-sandboxed Cowork sessions (requireCoworkFullVmSandbox); Cowork’s own sandboxed shell honors bare names only. Anchor file patterns with **/ (Read(**/secrets/**)), because in the VM sandbox a host absolute path does not match. Scoped rules need a build that supports them across the whole fleet (disableAutoUpdates pins builds): an older build passes a scoped entry to Claude Code unchecked. An entry whose pattern contains ) followed by a space or comma is enforced only through Claude Code’s managed-settings channel, so another Claude Code managed-settings source replaces it unless that source sets parentSettingsBehavior to "merge"; every other entry is enforced either way.An unusable entry (a lowercase tool name, an unbalanced parenthesis, a scoped WebSearch(…) or WebFetch(…)) is kept, because the deny list is served exactly as written, and raises a configuration warning.

skillCreationEnabled details

When on (default), users can create new skills and upload skill files in the app. Set to false to block user skill creation: the skill-creation and upload surfaces are hidden (the skill_creation feature is served as blocked by the organization), and the agent’s skill-creation tools (saving skills from a conversation, skill proposals) are not offered in sessions — the same effect as turning off the User-created skills organization setting available to claude.ai enterprise admins.This is a feature-availability control enforced in the app’s UI, not a data boundary: skills are files on the user’s machine, and files already present there (or placed there outside the app) are not removed or blocked by this key. Skills themselves remain usable; organization-distributed plugins and bundled skills are unaffected (to disable bundled skills, use disableBundledSkills).

builtinToolPolicy details

Keys use the same tool names and argument-scoped rule syntax as Disabled built-in tools (disabledBuiltinTools), and scopes apply in the same sessions. Scoped ask rules reach sessions only through Claude Code’s managed-settings channel, so another Claude Code managed-settings source replaces them unless it sets parentSettingsBehavior to "merge" (bare names hold either way). They need the same fleet-wide build support, and an older build drops a scoped ask entry as a configuration error (which also blocks WSL sessions on Windows until that client updates), so the tool runs unprompted.An ask entry, bare or scoped, also turns off the app’s remembered “always allow” choices for that tool, so each prompted call is confirmed individually. In Code side chats, and in Cowork sessions that run tools on the host, ask on a file tool (Read, Write, Edit, Glob, Grep) blocks matching calls instead of prompting; Code sessions and VM-sandboxed Cowork sessions show the prompt. An unusable entry is dropped and recorded as a configuration error; a value other than allow or ask is treated as ask and reported. To remove a tool or deny a rule outright, use Disabled built-in tools instead.

autoModeEnabled details

When enabled, users can select Auto mode (Code) / Automatically approve (Cowork). Claude runs a safety classifier on each action and only prompts for approval on actions it judges risky, instead of following the static per-tool policy.Requires a model that supports the safety classifier — which models qualify depends on the deployment’s provider and the app version. Models without support show the option greyed out. builtinToolPolicy and this key may both be set; Auto mode is a user-selectable option alongside the default policy, not a replacement for it.In Code sessions, a separately deployed Claude Code managed-settings file that sets disableAutoMode to "disable" overrides this key and keeps Auto mode hidden.

disableBypassPermissionsMode details

When set to true, sessions cannot run in bypass permissions mode: the app stops offering the mode in Code and Cowork, and a session that requests it anyway is downgraded. This is the disableBypassPermissionsMode setting from the permissions section of Claude Code’s managed settings; a separately deployed Claude Code managed-settings file that sets it to "disable" also removes the mode, whichever source sets it.Unset (default): users the deployment otherwise allows can choose bypass permissions mode.

toolSearchEnabled details

When enabled, Cowork, Code, and Chat sessions place only tool names 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. If your endpoint does not accept the request shape it then receives, requests fail with HTTP 400.

Claude API, Vertex AI, Bedrock, or Bedrock Mantle with no custom base URL: not needed. The app leaves Claude Code’s experimental betas on there, as terminal Claude Code does, so tool search is on by default (on Vertex AI, for Claude 4.5 and newer models). To turn it off in Code, Cowork, and Chat, set ENABLE_TOOL_SEARCH to false in the env block of OS-level Claude Code managed settings (with parentSettingsBehavior: "merge"). Earlier app versions treat these like the last case.
Gateway provider, app versions bundling Claude Code 2.1.247 or later: requests add only the tool-search shape (the tool-search-tool-2025-10-19 anthropic-beta value, deferred tool loading, tool_reference content blocks); every other experimental Claude Code beta stays suppressed. OS-level Claude Code managed settings that keep that suppression or turn ENABLE_TOOL_SEARCH off still win; set ENABLE_TOOL_SEARCH to force there instead (with parentSettingsBehavior: "merge"). Sessions in Claude Code’s own gateway mode (CLAUDE_CODE_USE_GATEWAY) get its gateway-safe tool-search shape regardless.
Foundry, a custom base URL, and earlier app versions: the app suppresses Claude Code’s experimental betas for the session and the key lifts that, so requests carry the tool-search shape together with Claude Code’s other experimental betas for that provider. On Vertex with app versions bundling Claude Code older than 2.1.221, leave this unset while any model older than Claude 4.5 is in use; those engines send the header regardless of model and Vertex’s pre-4.5 stacks reject it.

skipWebFetchPreflight details

Before fetching a page, Claude Code’s WebFetch tool asks api.anthropic.com whether the domain is on Anthropic’s content blocklist, and refuses the fetch if that lookup cannot complete. Third-party deployments route inference elsewhere and often block api.anthropic.com at the firewall; with the lookup on, every WebFetch in Code sessions then fails with “Unable to verify if domain … is safe to fetch”, and where the host is reachable, every fetched hostname is sent to Anthropic. (Cowork sessions fetch through the app’s own allowlisted fetch and never run this lookup.)Off (default): the lookup runs as it does today, so api.anthropic.com must be reachable from users’ machines for Code-session WebFetch to work (listed under Egress Requirements). Set to true when users’ machines cannot reach api.anthropic.com (corporate firewall, government network) or you do not want fetched hostnames sent there: Code sessions then fetch without the lookup and never contact that host for it. This is the same skipWebFetchPreflight setting Claude Code reads from its own managed-settings file; the app passes it to every session it starts. To restrict which domains Claude may fetch, use coworkEgressAllowedHosts or builtinToolPolicy instead.

allowedWorkspaceFolders details

Paths can reference ~ and these environment variables, expanded per user: %OneDrive%, %OneDriveCommercial%, %OneDriveConsumer%, %APPDATA%, %LOCALAPPDATA%, %USERNAME%, %XDG_DOCUMENTS_DIR%. The set is fixed; an entry that references any other %VAR%, or one that is unset on the device, is ignored.Each folder is interpreted on the machine the session runs on. For a Code session on an SSH host, ~ means the remote user’s home, an entry that references a %VAR% is ignored there (environment variables belong to the machine that defines them), and the session’s working directory must fall inside one of the folders as they exist on that host. One list serves every machine: ["/Users", "~"] governs /Users on a managed Mac and the signed-in user’s home on a Linux host. A folder that names nothing real on a given machine simply allows nothing there.

Field	Type	Default	Description
`path`	`string`	—	Absolute folder path. May start with ~ or one of the listed %VAR% tokens, expanded per user. Subfolders are included.
`isDefaultSelected`	`boolean`	—	Shows as a folder chip on the new-task page and skips the trust prompt. Users can remove it.
`mode`	`enum`	—	Read-only folders can be viewed and searched but not modified in Cowork. In Code, applies to file tools only; Bash and SSH do not yet enforce read-only. One of: `rw`, `ro`.

blockReadsOutsideWorkingDirectories details

When set to true, Code sessions refuse reads outside their working directories (the session folder plus any allowedWorkspaceFolders). The file tools (Read, Grep, Glob) refuse them in every permission mode; where Claude Code’s sandbox runs (macOS, or Linux and SSH hosts with bubblewrap, once allowedWorkspaceFolders or an egress allowlist is also configured) shell commands cannot see the home directory and other user folders (/Users, /home, mounted volumes) and a read there is refused with no prompt; elsewhere (Windows, Linux without bubblewrap, or neither folders nor an egress allowlist configured) such shell reads prompt for approval. The app keeps the user’s git configuration files (which may themselves embed credentials such as URL tokens; a symlinked one stays hidden), its own Claude Code installation, and the session’s plugin and attachment folders readable (not on a Windows SSH host, where plugin files and attachments stay out of the file tools’ reach under the block). An allowed folder that is or contains the home directory leaves it readable.Users can re-open folders (even their whole home) in their own Claude Code settings with sandbox.filesystem.allowRead or permissions.additionalDirectories; settings files tracked in a git repository cannot. The key travels on Claude Code’s managed-settings channel: another Claude Code managed-settings source replaces it unless that source sets parentSettingsBehavior to "merge", and one that sets sandbox.filesystem.allowManagedReadPathsOnly reduces it to approval prompts. This is permissions.blockReadsOutsideWorkingDirectories in Claude Code’s managed settings.Unset (default): nothing changes.

coworkEgressAllowedHosts details

Applies to both Cowork and Code, and only to tool calls. In Cowork it governs the sandbox’s web fetch, shell commands, and package installs; in Code sessions it is translated into Claude Code’s network sandbox allowlist, where a separately deployed Claude Code managed-settings file takes precedence by default. It does not cover Web Search (which runs at your inference provider), inference, or MCP traffic. When unset, only the inference endpoint is reachable from the sandbox, so the agent’s package installs and web fetches fail with a 403.Entries are exact hostnames (api.github.com), wildcards (*.corp.com matches subdomains at any depth, not corp.com itself), or * to allow all. IP addresses match only when listed exactly. localhost and private-network addresses are always blocked for web fetch; shell commands and package installs run in a network sandbox that reaches only the listed hosts plus your inference provider. With *, that sandbox is disabled and web fetch still blocks private addresses.Any entry except bare * may carry a :port suffix (internal.corp.com:8443, *.corp.com:8443) restricting it to that port. IPv6 literals are not supported. An invalid entry is dropped (with a warning in the app log) and the rest keep working; an unreadable value counts as an empty list. Ports are enforced for the Cowork sandbox’s web fetch, shell, and package-install egress; plugin CLIs ignore port-scoped entries for now, and the Code translation treats them as the bare host. Deploy port-scoped entries only once your whole fleet is on a build that supports them (disableAutoUpdates pins builds): on an older build one such entry invalidates the sandbox’s whole shell and package-install allowlist for the session.Listed hosts also need to be open on your network firewall.

organizationInstructions details

Free-text instructions from your organization that Claude Desktop appends, in a clearly delimited block, after its own system prompt in Chat, Cowork, and Code (every chat, task, and Code session, including the sub-agents they spawn): for example house style, data-handling rules, or topics to decline. The model is told these instructions come from the organization’s administrator and take priority over a user’s personal preferences.This is guidance the model follows, not an enforced control: like any system-prompt text it steers the model’s behavior and is usually honored, but it does not guarantee an outcome and is not a substitute for the restriction keys (tool policy, egress allowlist, folder allowlist). The app’s own system prompt is never replaced or shortened by this key; in Code sessions it is added after Claude Code’s own prompt and any CLAUDE.md instructions still apply.Read from the app’s loaded configuration when a session starts; a changed value generally takes effect for sessions started after the next app launch. Leading and trailing whitespace is trimmed; an empty string is treated as unset. Maximum 3,000 characters; a longer value is rejected (the key is ignored with a configuration error) rather than truncated. Line breaks are preserved when the value is delivered as JSON, a bootstrap response, a .mobileconfig profile, or a .reg file; the Group Policy (ADMX) and Intune text box for this setting is single-line.

Connectors

Setting	Type	Availability	Default	Description
Claude.ai data import `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.

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.
`automatic3pImport` · Beta	`boolean`	`false`	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`.

Authentication

Setting	Type	Availability	Default	Description
Microsoft 365 native sign-in broker `microsoftAuthBroker`	`enum`	MDM + Bootstrap	`auto`	“disabled” forces browser-based Microsoft 365 sign-in; “required” fails sign-in when the OS broker is unavailable, so the refresh token stays broker-held. One of: `auto`, `disabled`, `required`. Defaults to `auto`.

microsoftAuthBroker details

auto (default): use the OS sign-in broker where available (WAM on Windows, the Company Portal SSO extension on macOS) and fall back to a browser sign-in otherwise. disabled: always use the browser sign-in. required: fail sign-in when the broker is unavailable rather than falling back to the browser, so the refresh token stays broker-held. Linux has no broker, so required is not supported there. Desktop builds older than the version that introduced required treat it as disabled (browser-only sign-in) — the opposite posture — so gate rollout on client version.

Extensions

Setting	Type	Availability	Default	Description
Allow desktop extensions `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.
Require signed extensions `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.

isDesktopExtensionEnabled details

1P builds default to enabled at runtime unless this is explicitly set. In 3P, enabling this allows loading extensions; local install additionally requires an org policy backend.

MCP

Setting	Type	Availability	Default	Description
Managed MCP servers `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.
Allow persistent tool approvals `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`.
Allow user-added MCP servers `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`.
MCP tool call timeout `mcpToolTimeoutSec`	`integer`	MDM + Bootstrap	—	Per-call timeout for MCP tool calls, in seconds. Default 180 (3 minutes). Range: 60–3600.

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.toolPolicy locks the per-tool approval state, keyed by tool name: "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 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.Keys may contain * wildcards ("read_*" matches every tool whose name starts with read_; anchored, and * is the only wildcard). When several wildcard keys match, the strictest applies (blocked > ask > allow). An exact-name key wins over matching wildcards, with two exceptions in the stricter direction: in Code sessions a wildcard ask, or a wildcard blocked other than the bare "*", beats a less strict exact key (so "*": "blocked" plus exact "allow" entries still works as deny-by-default there); and in chat approval prompts and always-allow persistence a wildcard ask keeps every matching tool behind a per-call prompt even when a more permissive exact key matches, while direct tool invocations such as artifact or widget calls follow the exact key.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.

Field	Type	Default	Description
`name`	`string`	—	Unique name for this server. Shown to users and used to key tool policy and sign-in state.
`server`	`string`	—	Which bundled connector this entry turns on. Set instead of a transport; each built-in server has its own fields. One of: `microsoft365`, `websearch`, `github`.
`tenantId`	`string`	—	Your organization’s Microsoft Entra directory (tenant) ID.
`clientId`	`string`	—	OAuth app client ID for this built-in server.
`azureCloud`	`enum`	—	Microsoft cloud for sign-in and Graph. Leave as global for commercial Microsoft 365; US Government clouds require your own app registration (Client ID). One of: `global`, `us-gov-high`, `us-gov-dod`.
`continuousAccessEvaluation`	`enum`	`enabled`	Request CAE-capable Microsoft Graph tokens: long-lived (up to about 28 hours) but revocable within minutes. Set “disabled” to keep standard one-hour tokens. One of: `enabled`, `disabled`.
`scope`	`string`	—	What the server may request at sign-in. If blank, Desktop’s default read set is used.
`toolPolicy`	`object`	—	Lock the approval state for specific tools. Unlisted tools stay user-controlled.
`headers`	`object`	—	Static headers sent on every request — routing and tenant headers only. No credentials here; use the headers helper script for tokens and rotating values.
`headersHelper`	`string`	—	Script that prints the auth header as a JSON object to stdout. Runs before each request (cached for the TTL below).
`headersHelperTtlSec`	`integer`	—	How long the helper’s headers are reused before it runs again, in seconds. Defaults to 300.
`headersHelperRefreshBufferSec`	`integer`	—	Seconds before the TTL expires at which the helper re-runs mid-session. Defaults to 60. Keep it larger than the helper’s typical runtime.
`provider`	`enum`	—	Runs search from the desktop, for inference providers without native web search. Supply the provider’s API key through the headers helper script below. One of: `brave`, `tavily`, `exa`, `custom`.
`customUrl`	`string`	—	POST endpoint accepting {q} JSON and returning a results[] array. Only used when provider is Custom.
`host`	`string`	—	Leave blank for github.com. For GitHub Enterprise Server, your instance’s base URL.
`toolsets`	`string`	—	Comma-separated github-mcp-server toolsets to enable. If blank, the bundled server’s default toolsets are used.
`readOnly`	`boolean`	—	Offer only read tools — the server registers no write tools at all.
`transport`	`enum`	—	How the app connects: Streamable HTTP or legacy SSE for remote servers, or a local command over stdio. One of: `http`, `sse`, `stdio`.
`url`	`string`	—	HTTPS endpoint of the remote MCP server.
`oauth`	`object`	—	OAuth for a remote server: true to auto-register a client, a pre-registered client ID with tenant and scope, or mode “hosted” for an Anthropic-signed identity.
`oauth.clientId`	`string`	—	OAuth client ID from your IdP app registration. Leave unset to auto-register (dynamic client registration) and only narrow scopes.
`oauth.clientSecret`	`string`	—	Only for IdPs whose token endpoint requires a client secret (e.g. Box). Leave blank for PKCE-only public clients.
`oauth.clientSecretHelper`	`string`	—	Executable that prints the client secret on stdout. Overrides the inline value.
`oauth.authorizationServer`	`string[]`	—	Issuer URLs the OAuth sign-in may use, as a JSON array. Pre-filled by presets; ask your IdP admin if unsure.
`oauth.authorizationUrl`	`string`	—	Only for IdPs that don’t serve a .well-known discovery document. Set together with Token URL; requires Client ID.
`oauth.tokenUrl`	`string`	—	Only for IdPs that don’t serve a .well-known discovery document. Set together with Authorization URL; requires Client ID.
`oauth.tenantId`	`string`	—	Required for single-tenant Entra apps. Leave blank for multi-tenant or non-Microsoft IdPs.
`oauth.authFlow`	`enum`	—	How Entra sign-in runs for this server: the system browser (default) or the OS identity broker. One of: `browser`, `broker`.
`oauth.scope`	`string`	—	Space-separated scopes sent on the authorize request. Leave unset to use the scopes the server advertises. Required when Tenant ID is set.
`oauth.appendOfflineAccess`	`boolean`	—	Adds offline_access to the authorize request so the IdP returns a refresh token for silent renewal.
`oauth.callbackHost`	`enum`	—	Use localhost only if your IdP’s registered redirect URI specifies it. One of: `127.0.0.1`, `localhost`.
`oauth.callbackPort`	`integer`	—	Only set if your IdP requires an exact-match redirect port. Entra accepts any.
`oauth.additionalRedirectReferrerHosts`	`string`	—	Space-separated hostnames also accepted as the referrer of the sign-in callback. Only needed when the IdP completes sign-in from a different host.
`command`	`string`	—	Absolute path to the server executable, run on the user’s machine.
`args`	`string[]`	—	Arguments passed to the command, one per entry.
`env`	`object`	—	Environment variables set for the command.
`envHelper`	`string`	—	Script that prints environment variables as a JSON object to stdout. Runs when the local server starts (cached for the TTL below).
`envHelperTtlSec`	`integer`	`300`	Maximum age of a cached helper result, in seconds (default 300). Applies when the server starts or restarts.
`startupTimeoutSec`	`integer`	`120`	Maximum wait in seconds for the server to start and list its tools.

mcpPersistentAlwaysAllowEnabled details

When enabled (the default), approval prompts for tools without a toolPolicy entry offer a persistent grant — Always allow, or Allow for all tasks for tools that can modify data — the Tool permissions picker in Connector settings lets users pre-approve tools, and those grants persist across sessions with no expiry.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, 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.

mcpToolTimeoutSec details

Sets the per-call timeout the agent applies to every MCP tool call; a call that runs longer fails with a timeout error the model can see. Cowork and chat sessions default to 180 seconds. Code sessions have no desktop-imposed MCP tool timeout today, so setting this key introduces one there as well. The desktop’s own request deadlines toward MCP servers — the managed servers above and, where isLocalDevMcpEnabled permits them, user-added local servers — follow this value so they never cut a call short first; while the key is unset, calls to user-added local servers are additionally limited to 60 seconds by the desktop. Values outside 60–3600 are rejected at parse time (the error is listed in the diagnostics report) and the defaults apply.The timeout is global (there is no per-server or per-tool form), so size it for the slowest tool you need to complete: long-running tools on one server extend the window during which a stuck call on any server holds its turn. Cowork’s built-in shell tool runs under the same cap: a single command’s timeout_ms (itself limited to 600 seconds) cannot exceed this value.

Telemetry & updates

Setting	Type	Availability	Default	Description
Organization UUID `deploymentOrganizationUuid`	`string`	MDM + Bootstrap	—	A UUID you generate. Tags telemetry so Anthropic support can locate your fleet’s events, and namespaces each user’s local data. Not used for auth.
Block essential telemetry `disableEssentialTelemetry`	`boolean`	MDM + Bootstrap	`false`	Crash and performance reports to Anthropic. Defaults to `false`.
Block nonessential telemetry `disableNonessentialTelemetry`	`boolean`	MDM + Bootstrap	`false`	Product-usage analytics and diagnostic-report uploads. No message content. Defaults to `false`.
Block nonessential services `disableNonessentialServices`	`boolean`	MDM + Bootstrap	`false`	Connector favicons and the artifact-preview and MCP Apps widget iframe origins. Artifacts will not render. Defaults to `false`.

deploymentOrganizationUuid details

If unset, a shared placeholder UUID is used: telemetry can’t be distinguished from other unconfigured deployments, and local data is stored under the placeholder. Changing this value orphans data stored under the previous value (sessions, skills, plugins).

disableEssentialTelemetry details

“Essential” means the signals Anthropic needs to keep your deployment working: crash stacks, startup failure reasons, and version/OS metadata. No prompts, completions, file contents, or identifiers beyond a random install ID.What you lose when this is on: when a Claude Desktop build hits a bug that only reproduces on your OS version or locale, Anthropic can’t see it unless a user manually reports. Fixes ship slower.Why this is discouraged, not blocked: some air-gapped environments require zero outbound telemetry as a matter of policy. The switch exists for them. If you don’t have that constraint, leave it off.

disableNonessentialTelemetry details

“Nonessential” covers two things: product-usage analytics (which features get used, navigation patterns; no prompts or completions) and the Send action in Help → Generate Diagnostic Report. Turning this on stops both.Destinations are listed under Egress Requirements → Nonessential telemetry.

disableNonessentialServices details

“Nonessential services” covers three outbound fetches the app runs without: connector favicons (the icon proxy), the artifact-preview iframe origin, and the MCP Apps widget iframe origin (*.claudemcpcontent.com). Turning this on blocks all three.What you lose when this is on: connectors show without icons, artifacts do not render in conversations, and connectors that return MCP Apps show the text tool result instead of the widget.Destinations are listed under Egress Requirements → Nonessential services.

Auto update

Setting	Type	Availability	Default	Description
Block auto-updates `disableAutoUpdates`	`boolean`	MDM + Bootstrap	`false`	Stop Claude Desktop from fetching updates entirely (no time limit). You’ll need to push new versions yourself. Defaults to `false`.
Auto-update enforcement window `autoUpdaterEnforcementHours`	`integer`	MDM + Bootstrap	—	Hours before a downloaded update force-installs. Only applies when auto-updates are enabled. Blank = 72-hour default. Range: 1–72.
Check for updates on releases.claude.com `updateViaUpdatesHost`	`boolean`	MDM + Bootstrap	`false`	Read the update feed from releases.claude.com so api.anthropic.com can stay blocked. Defaults to `false`.

autoUpdaterEnforcementHours details

Has no effect when disableAutoUpdates is in place at launch: the updater never starts, so nothing is downloaded and this timer never arms. If the policy reaches an already-running app after an update has downloaded, that one staged update still installs on this timer; no further updates are fetched.Leaving it blank uses the 72-hour default and then waits for the machine to be idle (10+ minutes without input) before restarting; setting any explicit value (including 72) restarts once the window elapses regardless of user activity. In both cases the restart holds off while Claude is mid-task.

updateViaUpdatesHost details

By default the app asks api.anthropic.com which version to install. That host also serves the model APIs, so organizations that block un-approved LLM endpoints at the network edge end up blocking updates too.Turn this on to read the same feed from releases.claude.com, a hostname that carries no model API. api.anthropic.com can then stay blocked without breaking auto-update. Rollout behavior is unchanged; the installer download still comes from downloads.claude.ai as before.

Configuration updates

Setting	Type	Availability	Default	Description
Configuration relaunch window `relaunchEnforcementHours`	`integer`	MDM + Bootstrap	`24`	Hours a user may keep working on the old configuration after a managed-configuration change is detected. 0 = restart required at once. Blank = 24 hours. Defaults to `24`. Range: 0–336.
Configuration re-check interval `configRecheckIntervalMinutes`	`integer`	MDM + Bootstrap	`10`	Minutes between the running app’s checks for a changed managed configuration. Blank = 10 minutes. Defaults to `10`. Range: 2–30.

relaunchEnforcementHours details

Set it via MDM (plist, registry, or file) or serve it from your configuration endpoint (remote bootstrap configuration). When the running app observes a managed-configuration change it cannot apply without restarting, it shows the sidebar relaunch card and starts this window. The window starts at the running app’s next configuration re-check (the re-check interval beside it), so allow up to one re-check interval on top of this value between saving a change and the restart dialog. 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 24 hours. Set a larger value (up to 336 = 14 days) to give users longer; 0 shows the dialog at the first observation.A served value is 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. Like the update keys beside it, a value from a device-management profile that sets only app-behavior keys applies without making the rest of the configuration device-managed, and takes precedence over a served one. Because the key is grouped with the other app-behavior keys, a profile that sets any of them claims the whole group: set this key in the same profile as the update keys you deploy, or a served value is ignored on those devices and the 24-hour default applies.

configRecheckIntervalMinutes details

How often the running app re-checks its managed configuration for changes: it re-polls your configuration endpoint with a conditional request, so an unchanged configuration costs one 304 round-trip. A detected change shows the sidebar relaunch card and starts the relaunchEnforcementHours window, so a saved change reaches a running app within roughly one interval. Defaults to 10 minutes; each wait is jittered by ±10% so a fleet does not poll in lockstep. Values outside 2–30 are rejected with a parse error and the default applies.Applied without a restart: a new served value re-arms the timer at the check that delivers it, and a change to this key alone never asks for a relaunch. Set it via MDM or serve it from your configuration endpoint; like the update keys beside it, a value from a device-management profile that sets only app-behavior keys applies without making the rest of the configuration device-managed, and takes precedence over a served one. Because the key is grouped with the other app-behavior keys, a profile that sets any of them claims the whole group, and every key in it is then read from that profile alone: deploy this key in the same profile as the update keys (disableAutoUpdates, autoUpdaterEnforcementHours, …). A profile that sets the update keys without it ignores a served interval and the default applies; a profile that sets only this key ignores served update settings, so a served disableAutoUpdates no longer holds on those devices. A profile that also manages the connection itself (sets bootstrapUrl or the provider keys) follows the normal tier order instead: once a served configuration is in hand it, not the profile, supplies this key.

OTLP

Setting	Type	Availability	Default	Description
OpenTelemetry collector endpoint `otlpEndpoint`	`string`	MDM + Bootstrap	—	Where OpenTelemetry logs and metrics are sent. Leave blank to disable.
OpenTelemetry exporter protocol `otlpProtocol`	`enum`	MDM + Bootstrap	`http/protobuf`	Transport protocol for the OpenTelemetry exporters. One of: `http/protobuf`, `http/json`, `grpc`. Defaults to `http/protobuf`.
OpenTelemetry exporter headers `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.
Collector authentication `otlpAuthMode`	`enum`	MDM + Bootstrap	—	inference-credential sends the user’s inference bearer token to the collector as Authorization: Bearer. One of: `none`, `inference-credential`.
OpenTelemetry headers helper script `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.
OpenTelemetry resource attributes `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.
Desktop telemetry export level `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`.
Content capture categories `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`.
Export traces `otlpTracesEnabled`	`boolean`	MDM + Bootstrap	—	Also export OpenTelemetry traces from Cowork tasks and Code sessions. Uses Claude Code’s session tracing.

otlpProtocol details

Code sessions export over the protocol set here. Chats and Cowork tasks export over http/protobuf instead of grpc on Windows, and on other platforms whenever the Claude Code engine is given an HTTP proxy (the operating system’s proxy, egressProxyUrl or egressProxyPacUrl, or HTTPS_PROXY / HTTP_PROXY in a Claude Code settings file); the application log notes the substitution. The desktop application’s own events always go over http/json to <endpoint>/v1/logs. None of this changes the endpoint, so choose grpc only for a collector that also serves OTLP/HTTP at the same address; otherwise keep http/protobuf and point otlpEndpoint at the collector’s OTLP/HTTP receiver (conventionally port 4318).

otlpAuthMode details

inference-credential adds Authorization: Bearer <token> to every export, using the token the app currently holds for the inference provider, with no helper script to deploy. The collector must accept that token as issued: a gateway OIDC token carries the gateway’s audience, Microsoft Entra on Foundry issues the Foundry resource’s token, and Vertex workforce identity forwards a Google Cloud access token; static gateway and Bedrock keys are forwarded as-is. Because the token can also call inference as the user, use this only for a collector you operate; for anything else, use the headers helper script with an ingest-scoped credential. Kinds that never produce a bearer (AWS SigV4 kinds on Bedrock, Google ADC / OAuth files on Vertex, API-key kinds) export without it — use the helper script instead. Cowork tasks pick up the current token each time they start; a Code session keeps the token it started with for as long as it stays open; the desktop’s own event exporter uses the current token on every flush. Before sign-in, exports go out unauthenticated. An Authorization header printed by the headers helper script wins over this.

otlpHeadersHelper details

Absolute path to an executable that prints a single JSON object of HTTP headers on stdout, e.g. {"Authorization": "Bearer …"}. The desktop runs it (no arguments; output cached for a few minutes, and a failure is not retried for 30 seconds) whenever it needs collector headers and merges the result over OpenTelemetry exporter headers and the Collector authentication header (the helper wins on conflict). Cowork tasks get the current output when they start; Code sessions and host-run Cowork sessions are also given the script as Claude Code’s own otelHeadersHelper, so an open session re-runs it as tokens rotate (on Windows this applies to .exe, .cmd and .bat helpers; a .ps1 helper applies at session start only); the desktop’s own event exporter re-runs it per flush. Session start waits at most two seconds for a slow helper and otherwise proceeds without its headers until it finishes. Use this when the collector needs a credential the inference sign-in cannot provide, when the collector token rotates, or when the config comes from a hosted admin console, which cannot store header values. If the helper fails, telemetry is sent without its headers — check the app log.

otlpResourceAttributes details

Extra resource attributes to attach to every span, metric, and log sent to your collector. When End-user attribution is on and no enduser.id is set here, the desktop fills it with the signed-in user’s runtime identity; a value you set here always wins. process.owner (the OS login name) is always emitted; set it here to override.

otlpContentCapture details

Each category enables a class of raw content in OpenTelemetry events sent to your collector (this data never reaches Anthropic):

userPrompts — user-typed prompt text
assistantResponses — assistant message text
toolDetails — tool input arguments, e.g. the web-search query string
toolContent — tool output content, e.g. fetched page text or command stdout
rawApiBodies — full inference API request and response bodies

These mirror Claude Code’s OTEL_LOG_* env vars; see the Claude Code monitoring docs.

otlpTracesEnabled details

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. When otlpEndpoint is set, this key alone decides whether those sessions export traces: leaving it unset or false keeps traces off even if Claude Code’s own settings or managed settings (for example a managed-settings.json on the device) turn tracing on. Without otlpEndpoint it has no effect. The span structure may evolve between Claude Code releases; see the Claude Code monitoring docs.

Limits

Session retention

Setting	Type	Availability	Default	Description
Chat retention period `chatSessionRetentionDays`	`integer`	MDM + Bootstrap	—	Delete chats, with their files, after this many days without activity. Unset: kept until the user deletes them. Projects and memory stay. Range: 1–3650.
Cowork retention period `coworkSessionRetentionDays`	`integer`	MDM + Bootstrap	—	Delete Cowork tasks, with their uploads and outputs, after this many days without activity. Unset: kept until the user deletes them. Spaces and memory stay. Range: 1–3650.
Code retention period `codeSessionRetentionDays`	`integer`	MDM + Bootstrap	—	Delete Code sessions, conversation included, after this many days without activity. Unset: kept until the user deletes them. Uncommitted work stays on disk. Range: 1–3650.
Suspend session deletion `sessionRetentionHold`	`boolean`	MDM + Bootstrap	—	Suspend all automatic session deletion for these users (legal hold). While on, the retention periods above delete nothing.

chatSessionRetentionDays details

The app deletes whole sessions in the background shortly after it fetches this configuration (at launch and on each re-poll), or some minutes after launch and then daily when the configuration comes from device management alone. Idle time runs from the session’s last activity; viewing an old Code session counts as activity, viewing an old chat or Cowork task without continuing it does not durably. A session that is running or open on screen is skipped and checked again on the next pass, as is a chat or Cowork task whose folder changed on disk within the period. Pinned sessions are not exempt. Minimum 1 day; a value that cannot be read as a whole number of days deletes nothing. Set through the served configuration or in the device-management profile that carries the rest of the configuration. What it does not reach: another account’s sessions on the device (evaluated when that account signs in), Code sessions on a remote machine (SSH/WSL), Cowork background (dispatch) tasks the sidebar does not list, a chat or Cowork task whose folder cannot be located, and Claude Code files not named by a session id (prompt history, plans, shell snapshots), which keep Claude Code’s own retention. Honored only by Claude Desktop configured for a third-party model provider.

coworkSessionRetentionDays details

codeSessionRetentionDays details

sessionRetentionHold details

Meant to be set per user or group, through the served configuration’s group overrides or in the same device-management profile that carries the rest of the configuration (a profile carrying only this key makes the device profile-managed, like any policy key); a hold in the device’s profile also counts when the served configuration does not restate it. Deletion stops at the first configuration fetch that carries this value, before it takes effect as configuration at the next relaunch; a device that cannot reach its configuration server deletes nothing.

Token limits

Setting	Type	Availability	Default	Description
Max tokens per window `inferenceMaxTokensPerWindow`	`integer`	MDM + Bootstrap	—	Per-user soft cap, counted client-side over the token cap window. Not a server-enforced quota.
Token cap window `inferenceTokenWindowHours`	`integer`	MDM + Bootstrap	—	Tumbling window length for the token cap. Max 720 hours (30 days). Range: 1–720.

inferenceMaxTokensPerWindow details

Requires inferenceTokenWindowHours to also be set — without a window length the cap is inert and no limit is enforced.

inferenceTokenWindowHours details

Required when inferenceMaxTokensPerWindow is set — the cap only takes effect once both are configured.

Appearance

Setting	Type	Availability	Default	Description
End-user attribution `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.
Deployment display name `deploymentDisplayName`	`string`	MDM + Bootstrap	—	Overrides the provider label shown in the sidebar footer, user-menu header, and connection-error banner.
Deployment display subtitle `deploymentDisplaySubtitle`	`string`	MDM + Bootstrap	—	Optional detail shown after the deployment display name in the account-menu header.
Hide configuration deprecation warnings `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.
Organization banner `banner`	`object`	MDM + Bootstrap	—	A persistent banner across the top of the app window after sign-in.

endUserAttribution details

When on (default), the app resolves the signed-in user’s identity from the configured credential source (the identity provider claim, or the OS login name when no claim is available) and shows it in the sidebar footer, the account menu, and the Code session greeting. If an OpenTelemetry collector is configured, the same identity is also emitted as the enduser.id resource attribute on every span, metric, and log sent to your collector — unless you have set a static enduser.id under OpenTelemetry resource attributes, in which case your static value is kept and the runtime identity is not emitted. When off, no identity is shown in the app and no runtime enduser.id is emitted; a static enduser.id under OpenTelemetry resource attributes still passes through unchanged. This setting does not gate the process.owner resource attribute (the OS login name), which is standard OpenTelemetry process metadata and is always emitted — set a static process.owner under OpenTelemetry resource attributes to override it. Applies to both Cowork tasks and Code sessions.

deploymentDisplayName details

Set this to the name users should see for this deployment (for example, “Claude for Government”). When unset, the desktop shows the default provider label. Maximum 60 characters.

deploymentDisplaySubtitle details

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.

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.

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.

Field	Type	Default	Description
`enabled`	`boolean`	—	Turns the banner on. When false or unset, the other banner fields are ignored.
`text`	`string`	—	Single line, truncated on overflow. Maximum 200 characters.
`backgroundColor`	`string`	`#F5F5F5`	Six-digit hex (#RRGGBB). Applied exactly as configured; not theme-adapted.
`textColor`	`string`	`#000000`	Six-digit hex (#RRGGBB). Applied exactly as configured; not theme-adapted.
`linkUrl`	`string`	—	Optional HTTPS URL. The banner text becomes a link when set.

Feature discovery

Setting	Type	Availability	Default	Description
Hide feature announcements `disableFeatureDiscovery`	`boolean`	MDM + Bootstrap	`false`	Suppress unprompted feature-announcement UI: the post-update “What’s new” nudge and new-feature tips. Users can still open release notes themselves. Defaults to `false`.

disableFeatureDiscovery details

Covers the version-shipped announcement UI baked into each release: the What’s new button that appears on its own after an update, and the one-time New feature tips (coach-marks) that point out newly shipped capabilities. Useful when your organization gates feature availability and doesn’t want the app advertising capabilities you haven’t rolled out.User-initiated surfaces stay: the What’s-new menu item and header button still open the release notes on demand. Auto-update behavior is unaffected — that is governed by disableAutoUpdates and autoUpdaterEnforcementHours.

Plugins

Setting	Type	Availability	Default	Description
Organization plugin settings `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.
Plugin marketplaces `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.

orgPluginSettings details

Locks per-tool permissions on MCP servers that arrive via the org-plugins directory — one entry per server name:

[{"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
`serverName`	`string`	—	Name of the plugin-delivered MCP server this policy applies to.
`tools`	`object[]`	—	Per-tool approval locks for this server.
`tools.toolName`	`string`	—	MCP tool name as the server reports it.
`tools.permission`	`enum`	—	Approval state locked for this tool. Unlisted tools stay user-controlled. One of: `allow`, `ask`, `ask-session`, `blocked`.

allowedPluginMarketplaces details

Field	Type	Default	Description
`source`	`string`	—	Where the marketplace is fetched from: a GitHub repository (set repo), any Git remote (set url), or a hosted marketplace.json file (set url). One of: `github`, `git`, `url`.
`repo`	`string`	—	GitHub repository in owner/repo form. Case-insensitive.
`ref`	`string`	—	Commit SHA, branch, or tag. Leave empty to track the default branch; auto_install and required need a full 40-character commit SHA.
`path`	`string`	—	Folder within the repository that contains the marketplace, when it isn’t at the root.
`expectedName`	`string`	—	Rejects the marketplace if its manifest name differs.
`installationPreference`	`enum`	—	Whether users install plugins themselves or get them automatically. One of: `available`, `auto_install`, `required`.
`credentialKind`	`enum`	—	How fetches authenticate: anonymously, with the user’s git credentials, via a helper executable, or as the app does to its gateway or bootstrap server (url). One of: `anonymous`, `userGit`, `credentialHelper`, `inferenceCredential`.
`credentialHelper`	`string`	—	Executable that prints an access token for this marketplace.
`url`	`string`	—	HTTPS Git remote of the marketplace repository (git), or direct HTTPS URL of a hosted marketplace.json file (url).
`manifestSha256`	`string`	—	SHA-256 of the exact marketplace.json to accept. Without it auto_install and required act as available; a served manifest with any other digest is refused.

Source

Bootstrap

Setting	Type	Availability	Default	Description
Use bootstrap config `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`.
Bootstrap config URL `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.
Bootstrap OIDC parameters `bootstrapOidc`	`object`	MDM only	—	When set, the bootstrap request sends a Bearer token from a browser sign-in (authorization-code-with-PKCE).
Bootstrap request headers `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).
Bootstrap headers helper script `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.
Trust bootstrap-delivered settings `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.

bootstrapOidc details

Set this to use a separate identity provider (Microsoft Entra ID, Okta, Ping, or any compliant OIDC provider) for the bootstrap sign-in. The app runs an authorization-code-with-PKCE flow in the system browser. Omit to use device-code mode against the bootstrap server’s own origin.This is an object-typed key — in an MDM profile it is a single JSON-string value, not separate keys with dotted names like bootstrapOidc.clientId. Writing the sub-fields as separate registry values causes the app to silently fall through to device-code mode.

Field	Type	Default	Description
`clientId`	`string`	—	OAuth client ID of the desktop app registration at your identity provider (public client, PKCE).
`issuer`	`string`	—	HTTPS issuer with OIDC discovery. Set this, or set the authorization and token URLs instead.
`authorizationUrl`	`string`	—	HTTPS authorization endpoint. Used with the token URL when no issuer is set.
`tokenUrl`	`string`	—	HTTPS token endpoint. Used with the authorization URL when no issuer is set.
`scopes`	`string`	—	Space-separated; the token’s audience must match what your bootstrap server validates.
`redirectPort`	`integer`	—	Fixed loopback port for the sign-in redirect (http://127.0.0.1:PORT/callback). Leave unset to use a free port each time.
`additionalRedirectReferrerHosts`	`string`	—	Space-separated hostnames also accepted as the referrer of the sign-in callback. Only needed when the IdP completes sign-in from a different host.

bootstrapHeaders details

Static headers sent on every request to the bootstrap config URL — for a service-account credential (Authorization: Basic …, an API key header) or a routing/tenant header. When either this or the headers helper script is set and no separate bootstrapOidc provider is configured, the app treats the headers as sufficient auth and does not require a per-user sign-in for the bootstrap fetch. These headers (and the helper script’s below) also accompany requests to a plugin marketplace this server hosts on its own origin (allowedPluginMarketplaces with credentialKind: "inferenceCredential"). Header values are masked in diagnostics and telemetry. For a rotating token, use the headers helper script instead.

bootstrapHeadersHelper details

Absolute path to an executable that prints a single JSON object of HTTP headers on stdout, e.g. {"Authorization": "Bearer …"}. The app runs it (no arguments; output cached for a few minutes) before each bootstrap config fetch and merges the result over Bootstrap request headers (the helper wins on conflict). Use this instead of embedding user:pass@ in the bootstrap URL, or when the bootstrap server needs a rotating token from a secrets manager. When either this or the static headers are set and no separate bootstrapOidc provider is configured, the app treats them as sufficient auth and does not require a per-user sign-in for the bootstrap fetch. If a per-user sign-in also runs (bootstrapOidc or the server’s own device-code flow), that Bearer token wins on Authorization.

Guides

Recommended security profiles

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

Standard
Restricted
Locked down

Recommended for most enterprise deployments. Telemetry and auto-updates stay on so Anthropic can diagnose issues and ship fixes; users can extend Claude Desktop with their own connectors.

Key	Value
`deploymentOrganizationUuid`	`<your-org-uuid>`
`autoUpdaterEnforcementHours`	`24`
`isDesktopExtensionSignatureRequired`	`true`
`otlpEndpoint`	`<your-collector>`

For regulated environments that need to control what users can connect Claude Desktop to, while keeping Anthropic supportability.

Key	Value
`deploymentOrganizationUuid`	`<your-org-uuid>`
`disableNonessentialTelemetry`	`true`
`disableNonessentialServices`	`true`
`isLocalDevMcpEnabled`	`false`
`isDesktopExtensionEnabled`	`false`
`allowedWorkspaceFolders`	`[{"path":"~/Documents/Claude"}]`
`coworkEgressAllowedHosts`	`["*.example.corp"]`
`otlpEndpoint`	`<your-collector>`

For air-gapped or maximally restricted environments. The only traffic leaving the device goes to your inference endpoint and OTLP collector, plus downloads.claude.ai for the VM bundle and Claude CLI binary at session start unless you deploy the offline installer. With this profile, Anthropic receives no telemetry or logs from the app and does not deliver updates, so your team owns log collection and update distribution. On Microsoft Foundry, the Claude models behind your inference endpoint run in an Anthropic-operated service, so conversation content still reaches Anthropic-operated infrastructure under this profile, as described under Data handling by provider.

Key	Value
`disableEssentialTelemetry`	`true`
`disableNonessentialTelemetry`	`true`
`disableNonessentialServices`	`true`
`disableAutoUpdates`	`true`
`isLocalDevMcpEnabled`	`false`
`isDesktopExtensionEnabled`	`false`
`skillCreationEnabled`	`false`
`disabledBuiltinTools`	`["WebSearch","WebFetch"]`
`coworkEgressAllowedHosts`	`[]`
`allowedWorkspaceFolders`	`[{"path":"~/Documents/Claude"}]`
`otlpEndpoint`	`<your-collector>`

Tool permissions for managed MCP servers

Each managedMcpServers entry can carry a toolPolicy that locks the approval state per tool:

"allow" — the tool runs without prompting.
"ask" — the user approves every call; no session-scoped or standing grants are offered.
"blocked" — the tool is removed from Claude’s session; connector settings show it as blocked by your organization.

Tools with no policy entry stay user-controlled (built-in connectors apply default policies to some tools — see the reference above): the user is prompted and can approve once, approve for the rest of the task (offered for tools that can modify data), or grant a standing approval unless mcpPersistentAlwaysAllowEnabled is false. Full prompt options require version 1.22209.0 or later; earlier third-party builds offered only per-call approval. The reference above also lists an "ask-session" value, which behaves exactly as "ask" and is accepted until October 7, 2026. After that date the app rejects an entry that uses it, so write "ask". Managed policies take precedence over user grants, and enforcement happens in the desktop host process, not only in the prompt UI. A deny-by-default posture — "*": "blocked" plus exact "allow" entries for approved tools — is supported, including in Code sessions (where an allowed tool still gets Claude Code’s own approval prompt). See the managedMcpServers reference for wildcard matching, precedence rules, and built-in connector defaults.

​How keys are read

​Value types

​Linux

​Reference

​Connection

​Anthropic

​Bedrock

​Foundry

​Gateway

​Models

​Vertex

​Workspace

​Authentication

​Chat surface

​Code surface

​Cowork surface

​Workspace

​Connectors

​Authentication

​Extensions

​MCP

​Telemetry & updates

​Auto update

​Configuration updates

​OTLP

​Limits

​Session retention

​Token limits

​Appearance

​Feature discovery

​Plugins

​Source

​Bootstrap

​Guides

​Recommended security profiles

​Tool permissions for managed MCP servers

How keys are read

Value types

Linux

Reference

Connection

Anthropic

Bedrock

Foundry

Gateway

Models

Vertex

Workspace

Authentication

Chat surface

Code surface

Cowork surface

Workspace

Connectors

Authentication

Extensions

MCP

Telemetry & updates

Auto update

Configuration updates

OTLP

Limits

Session retention

Token limits

Appearance

Feature discovery

Plugins

Source

Bootstrap

Guides

Recommended security profiles

Tool permissions for managed MCP servers