> ## Documentation Index
> Fetch the complete documentation index at: https://claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuration reference
> Every managed-configuration key Claude Desktop on 3P supports, what it controls, and recommended security profiles
Most settings on this page are easier to configure in the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration). 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](/docs/third-party/claude-desktop/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//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 `.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](/docs/third-party/claude-desktop/mdm#update-keys-and-managed-precedence) (the update keys `disableAutoUpdates`, `autoUpdaterEnforcementHours`, and `updateViaUpdatesHost`, the lifecycle keys `relaunchEnforcementHours` and `configRecheckIntervalMinutes`, or the [network proxy keys](/docs/third-party/claude-desktop/network-proxy#pin-a-proxy-from-managed-configuration)): 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`](#configrecheckintervalminutes), 10 minutes by default), prompts the user to restart, and requires the restart after [`relaunchEnforcementHours`](#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](/docs/third-party/claude-desktop/mdm#4-deploy-the-configuration) has the exact rule. See [Deploy with MDM](/docs/third-party/claude-desktop/mdm#update-keys-and-managed-precedence) 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`](#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 `` element containing `[...]` or `{...}`, and on Windows a `REG_SZ` value. A macOS profile may instead carry the value as a native `` or ``, 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](#reference) — no wrapper object, no nesting:
```json theme={null}
{
"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](/docs/third-party/claude-desktop/bootstrap), or both. Its second line is the Claude Desktop version that added the key. For how the keys under **Models** work together, see [Models and effort levels](/docs/third-party/claude-desktop/models).
## Connection
| Setting | Type | Availability | Default | Description |
| ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | --------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Custom inference headers
`inferenceCustomHeaders` | `object` | MDM + Bootstrap
Added in 1.8089.0 | — | 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
Added in 1.14271.0 | — | 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
Added in 1.2581.0 | — | Absolute path to an executable that prints the credential, optionally with per-request headers. |
| Helper script (Windows)
`inferenceCredentialHelperWindows` | `string` | MDM + Bootstrap
Added in 2.2553.0 | — | Absolute path of the helper executable on Windows devices, used there instead of Helper script. Leave unset to use Helper script on every operating system. |
| Helper script arguments
`inferenceCredentialHelperArgs` | `string[]` | MDM + Bootstrap
Added in 2.110.0 | — | Arguments passed to the helper script, one per entry, in order. Leave unset to run it with none. |
| Helper script TTL
`inferenceCredentialHelperTtlSec` | `integer` | MDM + Bootstrap
Added in 1.2581.0 | `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
Added in 1.8089.0 | `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
Added in 1.10628.0 | `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
Added in 1.44121.1 | — | 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
Added in 1.44121.1 | — | 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
Added in 1.52386.0 | — | 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
Added in 1.24012.0 | — | 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
Added in 1.2581.0 | — | 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
Added in 1.8555.0 | — | 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. |
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).
Claude runs the executable with the entries of **Helper script arguments** as its arguments (none by default) 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 -w`
If this field is set, static credential fields (API key, bearer token) are ignored. The helper always wins.
When one configuration serves both Windows and macOS or Linux devices, set **Helper script** to the macOS/Linux path and this to the Windows path (`C:\...` or `C:/...`). Windows devices run this executable with the same arguments, timeout, TTL and environment as **Helper script**; macOS and Linux devices ignore it. An invalid value here stops the connection on Windows devices only. Desktop releases that predate this setting ignore it and run **Helper script** on every operating system.
Each entry reaches the executable as one argument, exactly as written: `["--environment", "production"]` runs `helper --environment production`. Use it to keep one installed script and let the configuration each user receives decide what it does (which environment, tenant or vault to read), instead of packaging a script per case.
Entries may not be empty and may not contain a double quote (`"`), a percent sign (`%`) or control characters, on any platform: a Windows `.cmd`/`.bat` helper receives its arguments through `cmd.exe`, where those characters would change the command. A `.cmd`/`.bat` script sees each argument quoted (`%1` is `"production"`, `%~1` strips the quotes); `.ps1`, `.exe` and POSIX helpers receive them bare. Arguments are visible in the diagnostic report and to other processes on the machine, so do not put secrets in them; the helper exists to fetch the secret.
A changed list takes effect the way a changed path does.
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.
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.
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.
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
Added in 1.8089.0 | — | 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
Added in 1.2581.0 | — | AWS region for the Bedrock runtime endpoint. |
| Bedrock base URL
`inferenceBedrockBaseUrl` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | For VPC endpoints or gateway proxies. Host origin only. |
| Bedrock service tier
`inferenceBedrockServiceTier` | `enum` | MDM + Bootstrap
Added in 1.5186.0 | — | 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
Added in 1.2581.0 | — | Static bearer token for inference. For providers that support profile or helper-script credentials, prefer those. |
| AWS SSO start URL
`inferenceBedrockSsoStartUrl` | `string` | MDM + Bootstrap
Added in 1.6259.0 | — | Enables in-app AWS sign-in (no AWS CLI needed). Set with the three SSO fields below. |
| AWS SSO region
`inferenceBedrockSsoRegion` | `string` | MDM + Bootstrap
Added in 1.6259.0 | — | IAM Identity Center home region. |
| AWS SSO account ID
`inferenceBedrockSsoAccountId` | `string` | MDM + Bootstrap
Added in 1.6259.0 | — | 12-digit AWS account ID assigned to users in IAM Identity Center. |
| AWS SSO role name
`inferenceBedrockSsoRoleName` | `string` | MDM + Bootstrap
Added in 1.6259.0 | — | IAM Identity Center permission-set name granting bedrock:InvokeModel\* on the account above. |
| AWS profile name
`inferenceBedrockProfile` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | AWS named profile to use for Bedrock inference credentials. |
| AWS config directory
`inferenceBedrockAwsDir` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | Folder with AWS config/credentials. Defaults to \~/.aws when no bearer token is set. |
| AWS CLI path
`inferenceBedrockAwsCliPath` | `string` | MDM + Bootstrap
Added in 1.13576.0 | — | Absolute path to the aws executable. Leave unset to find it on PATH. |
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
Added in 1.2581.0 | — | Azure AI Foundry resource name used to construct the endpoint URL. |
| Azure AI Foundry base URL
`inferenceFoundryBaseUrl` | `string` | MDM + Bootstrap
Added in 2.110.0 | — | Full base URL for a gateway or proxy in front of Foundry, path included (replaces [https://RESOURCE.services.ai.azure.com/anthropic](https://RESOURCE.services.ai.azure.com/anthropic)). |
| Azure AI Foundry API key
`inferenceFoundryApiKey` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | API key for Azure AI Foundry inference. |
| Entra ID tenant ID
`inferenceFoundryTenantId` | `string` | MDM + Bootstrap
Added in 1.9255.0 | — | Directory (tenant) ID of the Entra ID app registration that has the Cognitive Services scope. |
| Entra ID client ID
`inferenceFoundryClientId` | `string` | MDM + Bootstrap
Added in 1.9255.0 | — | 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
Added in 1.19367.0 | — | How Entra sign-in runs: device code (default), system browser, or the OS identity broker. One of: `device-code`, `browser`, `broker`. |
Set this only when the app reaches Foundry through a gateway or proxy you run, such as Azure API Management. Requests go to `/v1/messages` instead of `https://.services.ai.azure.com/anthropic/v1/messages`, carrying the same credential and headers the app would send to Foundry: each user's Entra ID token for the Azure Cognitive Services audience as `Authorization: Bearer` with Entra sign-in, otherwise the API key or the credential helper's output. Claude Code sessions receive the value as `ANTHROPIC_FOUNDRY_BASE_URL`, so use the same value you would give Claude Code in a terminal. `inferenceFoundryResource` is still required and should name the resource behind the gateway; the app sends nothing to the resource directly while this is set. Must be https, or http to a proxy at a loopback address on the device itself (127.0.0.1, localhost or \[::1]).
* **`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
Added in 1.2581.0 | — | Full URL of the inference gateway endpoint. |
| Stream idle timeout
`inferenceStreamIdleTimeoutSec` | `integer` | MDM + Bootstrap
Added in 1.44121.1 | — | 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
Added in 1.2581.0 | — | API key for the configured inference gateway. |
| Gateway auth scheme
`inferenceGatewayAuthScheme` | `enum` | MDM + Bootstrap
Added in 1.3036.0 | `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
Added in 1.25927.0 | — | 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
Added in 1.6889.0 | — | External IdP for gateway sign-in. The user’s token from this issuer is sent to the gateway as the Bearer credential. |
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.
* **`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 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.
**External IdP mode.** The app discovers `/.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 `/.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 callback is `http://127.0.0.1:/callback` by default (`http://localhost:/callback` with `redirectHost: "localhost"`); register exactly the one you use 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:/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. Leave unset to use a free port each time. |
| `redirectHost` | `enum` | — | Use localhost only if your IdP’s registered redirect URI specifies it. One of: `127.0.0.1`, `localhost`. |
| `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
Added in 1.8089.0 | — | Auto-populate the model picker from the provider at launch. |
| Default to 1M context
`modelPrefer1mContext` | `boolean` | MDM + Bootstrap
Added in 1.28929.0 | — | 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
Added in 1.2581.0 | — | Override the auto-discovered model list. First entry is the default. |
| Default model effort
`defaultModelEffort` | `enum` | MDM + Bootstrap
Added in 2.110.0 | — | Effort level the default model (the first listed model) starts at, instead of Anthropic’s recommended level: low, medium, high, xhigh or max. One of: `low`, `medium`, `high`, `xhigh`, `max`. |
| Always start with the default model
`alwaysStartWithDefaultModel` | `boolean` | MDM + Bootstrap
Added in 2.110.0 | — | When true, each new conversation or task starts on the default model, and a person’s model and effort changes are no longer saved as their default. |
| Show estimated cost
`inferenceModelPricingEnabled` | `boolean` | MDM + Bootstrap
Added in 1.37937.0 | — | 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
Added in 1.37937.0 | — | Scales every estimated cost (0.85 = 85% of the price); between 0 and 1. Range: 0–1. |
| Model pricing
`inferenceModelPricing` | `object[]` | MDM + Bootstrap
Added in 1.37937.0 | — | Per-model rates replacing Anthropic list price in the Usage page’s estimate. |
| Model catalog metadata
`modelCatalogEnabled` | `boolean` | MDM + Bootstrap
Added in 2.110.0 | — | Label and describe the model picker’s entries from the published Claude Code model catalog, instead of the app’s built-in table. |
| Model catalog URL
`modelCatalogUrl` | `string` | MDM + Bootstrap
Added in 2.110.0 | — | Fetch the model catalog and its signature file from this URL (a mirror inside your network serving Anthropic’s published files) instead of downloads.claude.ai. |
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).
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.
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:
```json theme={null}
[{"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:
```json theme={null}
[{"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:
```json theme={null}
[{"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. |
| `maxEffort` | `enum` | — | Highest effort level offered for this model; higher levels are hidden and never requested by Claude Desktop. An unrecognized value caps the model at low. One of: `low`, `medium`, `high`, `xhigh`, `max`. |
The effort level the default model (the first `inferenceModels` entry, or the first model your endpoint returns under discovery) starts at in Chat, Cowork and Code, in place of Anthropic's recommended level for that model: one of `low`, `medium`, `high`, `xhigh`, `max`. It is a starting point, not a lock: a person's own effort choice for that model still applies unless `alwaysStartWithDefaultModel` is on, and other models keep their recommended level. A level the model doesn't offer falls to the nearest level it offers below it (its lowest level when none is lower), and it never exceeds that model's `maxEffort`. In Code sessions a `CLAUDE_CODE_EFFORT_LEVEL` environment variable or an `effortLevel` in Claude Code's own settings still takes precedence, as it does over any picker default.
When `true`, each new conversation or task in Chat, Cowork and Code starts on the default model (the first `inferenceModels` entry), and the model and effort choices a person makes are no longer saved as their defaults. When unset or `false`, a person's last model and effort choice is remembered per tab, as before. Choices saved before the setting was turned on are kept and apply again if it is turned off.
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.
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.
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.
```json theme={null}
{"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). |
When on (the default), the app reads the model catalog Anthropic publishes for Claude Code (a signed document fetched from `downloads.claude.ai`, or from `modelCatalogUrl` when that is set, and verified against a key built into the app; a copy bundled with the app is used until one has been fetched, or when the host is unreachable) and uses it to fill in each picker entry's display name, description, and thinking/effort options in the Chat, Cowork, and Code tabs. It never changes which models are offered, their order, or the default model (the first `inferenceModels` entry): those, 1M-context variants, and `labelOverride` still come from `inferenceModels` / discovery, and a model the catalog does not list keeps the built-in label. Set `modelCatalogEnabled: false` to keep the built-in labels and make no catalog fetch. Applies to deployments configured on the device or by a bootstrap server; an install managed from the Claude admin console takes its model names and options from the console's settings and never fetches the catalog.
When set, the app fetches the catalog document and its signature file (the same URL with `.raw-sig.json` appended to the path) from this URL instead of `https://downloads.claude.ai/model-catalog/v1/catalog.json`, for a gateway or mirror inside your network serving Anthropic's two published files byte-for-byte. The document is still verified against the key built into the app, so an edited or re-signed copy is refused and the app keeps its last verified copy (or the bundled one); there is no key to configure. `https://` is required (`http://` only to a loopback address, and only when set on the device itself; a bootstrap server may not deliver a loopback or non-`https://` value); the server must answer the GET directly (redirects are not followed) and may honor `If-None-Match` with `304`, and must serve a document at least as new as the one the install last accepted (or the bundled seed) — an older one is refused and re-fetched on the retry interval until the mirror catches up. Ignored when `modelCatalogEnabled` is `false`, and on an install managed from the Claude admin console (which never fetches the catalog). A value that is not a valid URL, names a link-local or cloud-metadata host (e.g. `169.254.169.254`, `metadata.google.internal`), or is a loopback / non-`https://` value a bootstrap server delivers, turns the catalog fetch off (no fallback to `downloads.claude.ai`); the last fetched or bundled copy keeps labelling the pickers. On an install configured for a bootstrap server, the default location is not fetched until the server's configuration applies after sign-in, so a device does not poll `downloads.claude.ai` while the server may yet name a mirror; a mirror URL set on the device, cached earlier, or served in a pre-sign-in subset still fetches. Diagnostics report the location only as `hosted`, `custom`, `invalid` or `pending`; the value itself is treated like `bootstrapUrl`: host name only in telemetry, printed in full in the diagnostics bundle.
### Vertex
| Setting | Type | Availability | Default | Description |
| ------------------------------------------------------------------------------------------------------------------------------ | -------- | --------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GCP project ID
`inferenceVertexProjectId` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | Google Cloud project ID for Vertex AI inference. |
| GCP region
`inferenceVertexRegion` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | GCP region where your Vertex AI Claude models are deployed. |
| Vertex AI base URL
`inferenceVertexBaseUrl` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | PSC endpoint, if using one. |
| Vertex OAuth client ID
`inferenceVertexOAuthClientId` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | Desktop-app OAuth client ID. Enables Sign in with Google instead of a credentials file. |
| Vertex OAuth client secret
`inferenceVertexOAuthClientSecret` | `string` | MDM + Bootstrap
Added in 1.2581.0 | — | 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
Added in 1.2581.0 | — | Override the Google OAuth scopes (space-separated). Leave blank for the default. |
| Vertex OAuth login hint
`inferenceVertexOAuthLoginHint` | `string` | MDM + Bootstrap
Added in 1.12603.0 | — | 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
Added in 1.10628.0 | — | 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
Added in 1.10628.0 | — | GCP project for STS billing and quota. Defaults to the Vertex project ID above. |
| Workforce Identity sign-in flow
`inferenceVertexWorkforceAuthFlow` | `enum` | MDM + Bootstrap
Added in 1.25927.0 | — | 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
Added in 1.10628.0 | — | 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
Added in 1.2581.0 | — | Absolute path to service-account JSON. Leave blank to fall back to ADC. |
* **`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 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.
| 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. Leave unset to use a free port each time. |
| `redirectHost` | `enum` | — | Use localhost only if your IdP’s registered redirect URI specifies it. One of: `127.0.0.1`, `localhost`. |
| `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
Added in 1.3834.0 | `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
Added in 1.6889.0 | `false` | Stop external apps and websites from opening Claude Desktop via claude:// links. Defaults to `false`. |
### Built-in browser
| Setting | Type | Availability | Default | Description |
| ----------------------------------------------------------------------------------------------------------------------------------- | ---------- | -------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Allow the built-in browser
`builtinBrowserEnabled` | `boolean` | MDM + Bootstrap
Added in 2.2553.0 | `false` | Offer the built-in browser in Cowork and Code sessions so users and Claude can open and work with web pages. Site sign-ins stay on the device until cleared. Defaults to `false`. |
| Default site policy in the built-in browser
`builtinBrowserDefaultDomainPolicy` | `enum` | MDM + Bootstrap
Added in 2.2553.0 | `allow` | Whether Claude may open sites in the built-in browser by default; the allowed or blocked list is the exception. Mirrors the Claude in Chrome site policy. One of: `allow`, `block`. Defaults to `allow`. |
| Allowed sites in the built-in browser
`builtinBrowserAllowedDomains` | `string[]` | MDM + Bootstrap
Added in 2.2553.0 | — | Sites Claude may open, read, and act on in the built-in browser when the default site policy is block. Users can still view other sites. |
| Blocked sites in the built-in browser
`builtinBrowserBlockedDomains` | `string[]` | MDM + Bootstrap
Added in 2.2553.0 | — | Sites Claude may not open, read, or act on in the built-in browser when the default site policy is allow. Users can still view them. |
When enabled, Cowork and Code sessions get a built-in browser pane. Users can open any site in it, and Claude can open, read, and act on pages with its browser tools after the user approves each site (private-network addresses ask again per action unless the user always allows that host). Pages load directly from the user's machine, so your network controls apply; sign-ins and cookies from the pane stay in the app's browser profile on the device until cleared.
Off (default): no browser pane; Code sessions keep the localhost-only preview for dev servers. When `bootstrapUrl` is set, put this key in the served configuration: a device-profile value alone leaves the browser off. On an install managed from the Claude admin console this follows the console's Built-in browser switch.
Before Claude works with a public site, the app checks its address (query removed) against Anthropic's site safety list on `releases.claude.com`, signed out, with no account, organization, or device identifier (Claude admin console installs: as the signed-in member on `api.anthropic.com`). Listed sites stay blocked to Claude regardless of the keys below. Private addresses, internal-suffix or single-label names, and names resolving to private addresses are never sent (a name under a public domain is checked even if only your VPN resolves it). Allow `releases.claude.com` through your firewall: if a check fails, users can browse but Claude's page tools stay off for that site.
Restrict where Claude may browse with `builtinBrowserDefaultDomainPolicy` and its two site lists. A separately deployed Claude Code [managed-settings](https://claude.com/docs/third-party/claude-desktop/code#interaction-with-claude-code%E2%80%99s-own-managed-settings) file still applies: `disableBrowserExternalNavigation: true` keeps the browser off even with this key on, and `browserExternalPageTools: "disabled"` keeps the pane but turns Claude's page tools off for external sites. Takes effect after the app restarts.
Applies when `builtinBrowserEnabled` is on, in both Cowork and Code sessions, and decides which sites Claude may open, read, or act on with its browser tools; users can still view any site themselves. `allow` (default): every site except entries in `builtinBrowserBlockedDomains`. `block`: no site except entries in `builtinBrowserAllowedDomains`. Under either policy `coworkEgressAllowedHosts`, when set to anything but `*`, is an outer bound: sites outside it are refused to Claude in the browser too. A site on Anthropic's site safety list stays blocked to Claude under either policy (see `builtinBrowserEnabled`). A value that cannot be read is treated as `block` until it is fixed.
The policy also limits what pages load: a page in the pane, including one a user opened, cannot load frames, scripts, images, or other content from a site the policy does not admit (a blocked page a user opens still loads content from its own site). Under `block`, or with a `coworkEgressAllowedHosts` list, include the CDN and API hosts your allowed sites depend on.
This key and the two site lists work the same way as the Claude in Chrome site policy in the admin console. They are set separately here, except on an install managed from the Claude admin console, where they follow your organization's browser site permissions there.
Used when `builtinBrowserDefaultDomainPolicy` is `block`; ignored under `allow`. A site matching an entry is one Claude may open and work with using its browser tools; every other external site is treated as blocked by your organization: Claude cannot open it, cannot read or act on it, and frames, popups, and redirects into it from a page Claude is working on are refused. A user can still type its address and view it themselves. Listing a site here never overrides Anthropic's site safety list (see `builtinBrowserEnabled`).
Entries use the same grammar as `coworkEgressAllowedHosts`, except that bare `*` is dropped: as in Claude in Chrome, no allowed-sites entry opens every site. Set the policy to `allow` for that. A wildcard whose base is a public suffix (`*.co.uk`, `*.github.io`) is likewise ignored so an entry can never open a whole shared registry. Any other entry outside that grammar is kept but matches nothing (the app log and the editor name it); a value that cannot be read at all allows nothing until it is fixed. `localhost` dev servers are always reachable, so listing them changes nothing.
Empty or unset (default): under `block`, Claude may open no external site. On an install managed from the Claude admin console this follows your organization's browser site permissions there.
Used when `builtinBrowserDefaultDomainPolicy` is `allow` (the default); ignored under `block`. A site matching an entry is treated as blocked by your organization: Claude cannot open it, cannot read or act on it with its browser tools, and frames, popups, and redirects into it from a page Claude is working on are refused. A user can still type its address and view it themselves: the pane shows a "blocked by your organization's policy" banner and Claude's tools stay off there. To take the external browser away from users as well, deploy Claude Code's `disableBrowserExternalNavigation` managed setting instead. A blocked site is refused before the site safety check, so its address is never sent to Anthropic.
Entries use the same grammar as `coworkEgressAllowedHosts`; `*` blocks every external site. An entry outside that grammar is kept but matches nothing (the app log and the editor name it); a value that cannot be read at all blocks every external site until it is fixed. `localhost` dev servers are never affected.
Use this key for exceptions inside an allowed egress wildcard or when egress is open. Empty or unset (default): no sites beyond the egress list are blocked. On an install managed from the Claude admin console this follows your organization's browser site permissions there.
### Chat surface
| Setting | Type | Availability | Default | Description |
| ---------------------------------------------------------------------------------------------------------- | --------- | --------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Allow Chat
`chatTabEnabled` | `boolean` | MDM + Bootstrap
Added in 1.13576.0 | — | Enable Chat. Quick questions and drafting. |
| Advanced file analysis
`chatAdvancedFileAnalysisEnabled` | `boolean` | MDM + Bootstrap
Added in 1.14271.0 | — | 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. |
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
Added in 1.2581.0 | `true` | Enable Code. Claude writes and runs code. Defaults to `true`. |
| SSH host allowlist
`sshHostAllowlist` | `string[]` | MDM + Bootstrap · Beta
Added in 1.40609.0 | — | 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
Added in 1.46388.1 | — | 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
Added in 1.52386.0 | — | 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`. |
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 permitted likewise on the system-OpenSSH engine (the default on macOS and Linux; see `sshTransport`) and refused, with a message suggesting `ProxyCommand`, by the built-in SSH library.
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.
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.
`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
Added in 1.9659.0 | `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
Added in 1.37937.0 | — | 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
Added in 1.37937.0 | — | 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
Added in 1.2581.0 | — | 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
Added in 1.15962.0 | — | 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
Added in 1.25927.0 | — | 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. |
| Allow scheduled tasks
`scheduledTasksEnabled` | `boolean` | MDM + Bootstrap
Added in 2.110.0 | — | Allow scheduled tasks in Cowork and Code. When off, the Scheduled page is hidden, existing tasks stop running, and Claude cannot create new ones. |
| Built-in tool policy
`builtinToolPolicy` | `object` | MDM + Bootstrap
Added in 1.8089.0 | — | 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
Added in 1.10628.0 | `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
Added in 1.46388.1 | — | 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
Added in 1.21459.0 | `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
Added in 1.37937.0 | — | 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
Added in 1.2581.0 | — | 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
Added in 1.46388.1 | — | 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
Added in 1.2581.0 | — | 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
Added in 1.2581.0 | `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
Added in 1.37937.0 | — | Appended to Claude’s system prompt in Chat, Cowork, and Code. Guidance the model follows, not an enforced control. Up to 3,000 characters. |
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.
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.
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](https://code.claude.com/docs/en/permissions#permission-rule-syntax) such as `Bash(curl *)` or `Edit(**/*.env)`. A bare name covers every call (a bare `Bash` entry also covers the `PowerShell` tool); 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(:)`. `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 fleet-wide build support (`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](https://claude.com/docs/third-party/claude-desktop/code#interaction-with-claude-code%E2%80%99s-own-managed-settings) 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.
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`).
When on (default), users can schedule Cowork tasks and Code sessions to run later or on a recurring schedule, and Claude can create such schedules when asked.
Set to `false` to turn scheduled tasks off for every user. The Scheduled section in Cowork and the routines list in the Code tab are hidden, together with every other place a schedule can be created. Tasks that already exist on a device no longer run; they are kept, not deleted, and run again once the key is removed or set to `true`. Claude is not offered the tools that create, change or run these tasks, and sessions start without Claude Code's own in-session scheduling tools (the `/loop` command, its cron tools and its wake-up timer).
It does not remove task files already on the user's machine. A change takes effect at the next app launch.
Keys use the same tool names and argument-scoped rule syntax as **Disabled built-in tools** (`disabledBuiltinTools`), and scopes apply in the same sessions. A bare `Bash` key also governs Claude Code's `PowerShell` tool (its shell on Windows PCs without Git for Windows); argument-scoped `Bash(…)` keys do not. 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.
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](https://claude.com/docs/third-party/claude-desktop/code#interaction-with-claude-code%E2%80%99s-own-managed-settings) file that sets `disableAutoMode` to `"disable"` overrides this key and keeps Auto mode hidden.
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](https://claude.com/docs/third-party/claude-desktop/code#interaction-with-claude-code%E2%80%99s-own-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.
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.
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](https://claude.com/docs/third-party/claude-desktop/code#interaction-with-claude-code%E2%80%99s-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.
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. An empty list allows no folder at all; unset leaves access unrestricted.
| 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`. |
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](https://claude.com/docs/third-party/claude-desktop/code#interaction-with-claude-code%E2%80%99s-own-managed-settings).
Unset (default): nothing changes.
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](https://claude.com/docs/third-party/claude-desktop/code#applied-as-managed-policy), 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. A list other than `*` also bounds where Claude may browse in the built-in browser. 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.
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
Added in 1.10628.0 | — | Lets users import Claude.ai chats and projects, plus earlier Claude sessions on this computer, when `enabled` is true. `automatic3pImport` is a separate switch. |
| 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
Added in 1.19367.0 | `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`. |
`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
Added in 1.2581.0 | `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
Added in 1.2581.0 | `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. |
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
Added in 1.2581.0 | — | 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
Added in 1.24012.9 | `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
Added in 1.2581.0 | `true` | Local stdio servers added via the Developer settings. Remote servers come from the managed list above or organization plugins. Defaults to `true`. |
| Allowed plugin MCP servers
`allowedPluginMcpServers` | `object[]` | MDM + Bootstrap
Added in 2.2553.0 | — | Servers plugins may connect in sessions, beyond the managed list above and organization plugins. An empty list allows none; unset keeps today’s rules. |
| MCP tool call timeout
`mcpToolTimeoutSec` | `integer` | MDM + Bootstrap
Added in 1.37937.0 | — | Per-call timeout for MCP tool calls, in seconds. Default 180 (3 minutes). Range: 60–3600. |
For OAuth-authenticated entries, the app builds the redirect URI as `http://:/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, legacy SSE, or a local command (stdio). policy-only connects to nothing; it only sets a plugin server’s tool policy. One of: `http`, `sse`, `stdio`, `policy-only`. |
| `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 that require one (e.g. Box). Hosted config can store only a Google Desktop-app secret (GOCSPX-…); for other IdPs use the client secret helper. |
| `oauth.clientSecretHelper` | `string` | — | Executable that prints the client secret on stdout as a JSON object with a single clientSecret key; any other output is rejected. 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. |
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.
Unset (default): with managed servers listed, sessions take MCP servers only from plugins and the desktop; with no managed servers listed, nothing is restricted.
When set, Cowork, Chat and Code sessions connect the managed list above and the servers the desktop serves from the administrator's org-plugins directory, plus only servers declared by other plugins (user-installed or marketplace) that match an entry. An entry in the managed list above with `transport: "policy-only"` sets a plugin server's tool permissions but does not admit it; to admit that server, list the server's own URL here. Claude Code configuration-file servers (`~/.claude.json`, a project's `.mcp.json`, `claude mcp add`) are never connected. With the key set, the desktop starts no plugin server on the computer itself, whatever the entries say. The one exception is the MCP servers it serves to sessions from the org-plugins directory. Each entry is a URL pattern in Claude Code's form, `{"serverUrl": "https://*.example.com/*"}` (`*` wildcards; a host `*` spans `a.b`): a plugin's remote server connects when its URL matches an entry. No entry admits a plugin's local (stdio) server, and an empty list admits no plugin server. Other shapes, the `serverName` and `serverCommand` forms included, are dropped and reported; a value that is not a list, or has no readable entry, locks sessions to the managed list and the org-plugins directory's servers, and stops every other desktop-started plugin server. User-added local servers and extensions keep their own keys.
Coexistence with another Claude Code managed-settings source on the device: see [managed settings](https://claude.com/docs/third-party/claude-desktop/code#interaction-with-claude-code%E2%80%99s-own-managed-settings).
| Field | Type | Default | Description |
| ----------- | -------- | ------- | ------------------------------------------------------------------- |
| `serverUrl` | `string` | — | URL pattern a plugin’s remote server must match, with \* wildcards. |
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
Added in 1.2581.0 | — | 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
Added in 1.2581.0 | `false` | Crash and performance reports to Anthropic. Defaults to `false`. |
| Block nonessential telemetry
`disableNonessentialTelemetry` | `boolean` | MDM + Bootstrap
Added in 1.2581.0 | `false` | Product-usage analytics and diagnostic-report uploads. No message content. Defaults to `false`. |
| Block nonessential services
`disableNonessentialServices` | `boolean` | MDM + Bootstrap
Added in 1.2581.0 | `false` | Connector favicons and the artifact-preview and MCP Apps widget iframe origins. Artifacts will not render. Defaults to `false`. |
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).
"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.
"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.
"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
Added in 1.2581.0 | `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
Added in 1.2581.0 | — | 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
Added in 1.26832.0 | `false` | Read the update feed from releases.claude.com so api.anthropic.com can stay blocked. Defaults to `false`. |
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.
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
Added in 1.40609.0 | `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
Added in 1.46388.1 | `10` | Minutes between the running app’s checks for a changed managed configuration. Blank = 10 minutes. Defaults to `10`. Range: 2–30. |
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 without a restart once two re-checks in a row have served it, 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.
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 once two checks in a row have served 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
Added in 1.2581.0 | — | Where OpenTelemetry logs and metrics are sent. Leave blank to disable. |
| OpenTelemetry exporter protocol
`otlpProtocol` | `enum` | MDM + Bootstrap
Added in 1.2581.0 | `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
Added in 1.2581.0 | — | 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
Added in 1.30096.1 | — | 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
Added in 1.30096.1 | — | 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
Added in 1.5354.0 | — | 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
Added in 1.9255.0 | `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
Added in 1.15962.0 | — | 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
Added in 1.22209.0 | — | Also export OpenTelemetry traces from Cowork tasks and Code sessions. Uses Claude Code’s session tracing. |
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 `/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).
`inference-credential` adds `Authorization: Bearer ` 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.
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.
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.
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](https://code.claude.com/docs/en/monitoring-usage).
Enables Claude Code's session tracing (`CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` + `OTEL_TRACES_EXPORTER=otlp`) in spawned Cowork tasks and Code sessions. Each user interaction exports a trace whose spans and events carry `trace_id`/`span_id`, enabling end-to-end correlation in your observability backend (metrics do not carry trace context; correlate those via `session.id`). Traces go to the collector endpoint and protocol configured above. 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](https://code.claude.com/docs/en/monitoring-usage).
## Limits
### Session retention
| Setting | Type | Availability | Default | Description |
| ------------------------------------------------------------------------------------------------- | --------- | --------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Chat retention period
`chatSessionRetentionDays` | `integer` | MDM + Bootstrap
Added in 1.52386.0 | — | 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
Added in 1.52386.0 | — | 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
Added in 1.52386.0 | — | 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
Added in 1.52386.0 | — | Suspend all automatic session deletion for these users (legal hold). While on, the retention periods above delete nothing. |
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.
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.
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.
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
Added in 1.2581.0 | — | Per-user soft cap, counted client-side over the token cap window. Not a server-enforced quota. |
| Token cap window
`inferenceTokenWindowHours` | `integer` | MDM + Bootstrap
Added in 1.2581.0 | — | Tumbling window length for the token cap. Max 720 hours (30 days). Range: 1–720. |
Requires `inferenceTokenWindowHours` to also be set — without a window length the cap is inert and no limit is enforced.
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
Added in 1.25927.0 | — | 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
Added in 1.24012.0 | — | Overrides the provider label shown in the sidebar footer, user-menu header, and connection-error banner. |
| Deployment display subtitle
`deploymentDisplaySubtitle` | `string` | MDM + Bootstrap
Added in 1.24012.0 | — | Optional detail shown after the deployment display name in the account-menu header. |
| Hide configuration deprecation warnings
`disableConfigDeprecationWarnings` | `boolean` | MDM + Bootstrap
Added in 1.40609.0 | — | 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
Added in 1.7196.0 | — | A persistent banner across the top of the app window after sign-in. |
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.
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.
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.
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.
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
Added in 1.21459.0 | `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`. |
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
Added in 1.8089.0 | — | 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
Added in 1.17377.1 | — | Git repositories or hosted marketplace.json URLs to surface as plugin marketplaces in the Directory’s Organization tab. The app re-fetches each periodically. |
Locks per-tool permissions on MCP servers provided by any installed plugin — from the org-plugins directory or a plugin marketplace, remote or run locally — one entry per server name (compared case-insensitively):
```json theme={null}
[{"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 is for the same server (same URL, else same name), that entry decides alone: its `toolPolicy` (if any) applies and the entry here is ignored. A value that cannot be read blocks every tool of every plugin-provided MCP server no Managed MCP servers entry covers.
For a plugin server that Claude Code launches or connects to itself (a marketplace plugin's), the permissions travel on Claude Code's managed-settings channel: another Claude Code [managed-settings source](https://claude.com/docs/third-party/claude-desktop/code#interaction-with-claude-code%E2%80%99s-own-managed-settings) on the device replaces them unless that source sets `parentSettingsBehavior` to `"merge"`. `blocked` on a server the app connects to itself holds either way.
| 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`. |
| 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
Added in 1.10628.0 | `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
Added in 1.10628.0 | — | 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
Added in 1.10628.0 | — | 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
Added in 1.32885.1 | — | 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
Added in 1.32885.1 | — | 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
Added in 1.26832.0 | `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. |
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. Leave unset to use a free port each time. |
| `redirectHost` | `enum` | — | Use localhost only if your IdP’s registered redirect URI specifies it. One of: `127.0.0.1`, `localhost`. |
| `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. |
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.
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.
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`](#deploymentorganizationuuid) | `` |
| [`autoUpdaterEnforcementHours`](#autoupdaterenforcementhours) | `24` |
| [`isDesktopExtensionSignatureRequired`](#isdesktopextensionsignaturerequired) | `true` |
| [`otlpEndpoint`](#otlpendpoint) | `` |
For regulated environments that need to control what users can connect Claude Desktop to, while keeping Anthropic supportability.
| Key | Value |
| --------------------------------------------------------------- | --------------------------------- |
| [`deploymentOrganizationUuid`](#deploymentorganizationuuid) | `` |
| [`disableNonessentialTelemetry`](#disablenonessentialtelemetry) | `true` |
| [`disableNonessentialServices`](#disablenonessentialservices) | `true` |
| [`isLocalDevMcpEnabled`](#islocaldevmcpenabled) | `false` |
| [`isDesktopExtensionEnabled`](#isdesktopextensionenabled) | `false` |
| [`allowedWorkspaceFolders`](#allowedworkspacefolders) | `[{"path":"~/Documents/Claude"}]` |
| [`coworkEgressAllowedHosts`](#coworkegressallowedhosts) | `["*.example.corp"]` |
| [`otlpEndpoint`](#otlpendpoint) | `` |
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](/docs/third-party/claude-desktop/installation#offline-installation). 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](/docs/third-party/claude-desktop/overview#data-handling-by-provider).
| Key | Value |
| --------------------------------------------------------------- | --------------------------------- |
| [`disableEssentialTelemetry`](#disableessentialtelemetry) | `true` |
| [`disableNonessentialTelemetry`](#disablenonessentialtelemetry) | `true` |
| [`disableNonessentialServices`](#disablenonessentialservices) | `true` |
| [`disableAutoUpdates`](#disableautoupdates) | `true` |
| [`modelCatalogEnabled`](#modelcatalogenabled) | `false` |
| [`isLocalDevMcpEnabled`](#islocaldevmcpenabled) | `false` |
| [`isDesktopExtensionEnabled`](#isdesktopextensionenabled) | `false` |
| [`skillCreationEnabled`](#skillcreationenabled) | `false` |
| [`disabledBuiltinTools`](#disabledbuiltintools) | `["WebSearch","WebFetch"]` |
| [`coworkEgressAllowedHosts`](#coworkegressallowedhosts) | `[]` |
| [`allowedWorkspaceFolders`](#allowedworkspacefolders) | `[{"path":"~/Documents/Claude"}]` |
| [`otlpEndpoint`](#otlpendpoint) | `` |
### Tool permissions for managed MCP servers
Each [`managedMcpServers`](#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`](#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](#managedmcpservers) for wildcard matching, precedence rules, and built-in connector defaults.