One change
Configuration reference
third-party/claude-desktop/configuration
Nearest release: v2.1.246, published an hour after this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
third-party/claude-desktop/configuration Changed · +122 / -34 lines
from line 78
| <span id="inferencecustomheaders" />Custom inference headers<br />`inferenceCustomHeaders` | `object` | MDM + Bootstrap | — | Extra headers on every inference request — routing and tenant headers only (org IDs, Bedrock Guardrails). No credentials; use the credential helper for tokens. Previously named `inferenceGatewayHeaders`. | | <span id="inferencesessionlifetimesec" />Sign-in session lifetime<br />`inferenceSessionLifetimeSec` | `integer` | MDM + Bootstrap | — | How long a sign-in stays valid under your IdP’s session policy. Shows a re-authenticate banner before it expires. | | <span id="inferencecredentialhelper" />Helper script<br />`inferenceCredentialHelper` | `string` | MDM + Bootstrap | — | Absolute path to an executable that prints the credential, optionally with per-request headers. | -| <span id="inferencecredentialhelperttlsec" />Helper script TTL<br />`inferenceCredentialHelperTtlSec` | `integer` | MDM + Bootstrap | `3600` | Helper output is cached for this many seconds. Re-runs at the next session start after expiry. Defaults to `3600`. | +| <span id="inferencecredentialhelperttlsec" />Helper script TTL<br />`inferenceCredentialHelperTtlSec` | `integer` | MDM + Bootstrap | `3600` | Helper output is cached for this many seconds; once it expires the helper re-runs without a relaunch (before the next turn when set above 120). Defaults to `3600`. | | <span id="inferencecredentialhelpertimeoutsec" />Credential helper timeout<br />`inferenceCredentialHelperTimeoutSec` | `integer` | MDM + Bootstrap | `60` | Maximum wait for the helper executable to finish. Raise this if the helper opens a browser for interactive sign-in. Defaults to `60`. Range: 1–600. | | <span id="inferencecredentialhelpersilentrefreshenabled" />Re-run helper for silent refresh<br />`inferenceCredentialHelperSilentRefreshEnabled` | `boolean` | MDM + Bootstrap | `true` | On credential expiry, re-run the helper (CLAUDE\_HELPER\_CONTEXT=mid-session-refresh) to recover silently. Turn off if the helper can’t run non-interactively. Defaults to `true`. | | <span id="usercontentrendererurl" />Artifact preview iframe origin<br />`userContentRendererUrl` | `string` | MDM + Bootstrap | — | HTTPS origin of the user-content-renderer deployment used for artifact and file previews. Defaults to the commercial host when unset. |
from line 222
### Models -| Setting | Type | Availability | Default | Description | -| ----------------------------------------------------------------------------------- | ---------- | --------------- | ------- | --------------------------------------------------------------------------------------------------------------------- | -| <span id="modeldiscoveryenabled" />Model discovery<br />`modelDiscoveryEnabled` | `boolean` | MDM + Bootstrap | — | Auto-populate the model picker from the provider at launch. | -| <span id="modelprefer1mcontext" />Default to 1M context<br />`modelPrefer1mContext` | `boolean` | MDM + Bootstrap | — | When a user has no saved selection, start the picker on the 1M-context variant of the default model if it offers one. | -| <span id="inferencemodels" />Model list<br />`inferenceModels` | `object[]` | MDM + Bootstrap | — | Override the auto-discovered model list. First entry is the default. | +| Setting | Type | Availability | Default | Description | +| ---------------------------------------------------------------------------------------------------- | ---------- | --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| <span id="modeldiscoveryenabled" />Model discovery<br />`modelDiscoveryEnabled` | `boolean` | MDM + Bootstrap | — | Auto-populate the model picker from the provider at launch. | +| <span id="modelprefer1mcontext" />Default to 1M context<br />`modelPrefer1mContext` | `boolean` | MDM + Bootstrap | — | When a user has no saved selection, start the picker on the 1M-context variant of the default model if it offers one. | +| <span id="inferencemodels" />Model list<br />`inferenceModels` | `object[]` | MDM + Bootstrap | — | Override the auto-discovered model list. First entry is the default. | +| <span id="inferencemodelpricingenabled" />Show estimated cost<br />`inferenceModelPricingEnabled` | `boolean` | MDM + Bootstrap | — | Show an estimated cost on the Usage page, at Anthropic list price for any model without a rate below. | +| <span id="inferencemodelpricingmultiplier" />Price multiplier<br />`inferenceModelPricingMultiplier` | `number` | MDM + Bootstrap | — | Scales every estimated cost (0.85 = 85% of the price); between 0 and 1. Takes effect in a future release; until then turns are estimated at list price. Range: 0–1. | +| <span id="inferencemodelpricing" />Model pricing<br />`inferenceModelPricing` | `object[]` | MDM + Bootstrap | — | Per-model rates replacing Anthropic list price in the Usage page’s estimate. Takes effect in a future release; until then turns are estimated at list price. | <AccordionGroup> <Accordion title="modelDiscoveryEnabled details">
from line 251
[{"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. + **Default to 1M context** (`prefer1m`) makes the 1M-context variant the default picker selection when this entry is the default model (the first entry); users can still switch to the standard variant, and an explicit user pick is always kept. No effect without `supports1m`. Under dynamic discovery (no explicit list), the equivalent flat key in the **Models** group applies instead: ```json theme={null}
from line 280
| `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. | </Accordion> + + <Accordion title="inferenceModelPricingEnabled details"> + Off unless set: the Usage page shows token counts only, since the app cannot know your negotiated provider rates. `true` turns on a USD estimate priced at Anthropic's published list price; `inferenceModelPricingMultiplier` and `inferenceModelPricing` refine it and each also turns the estimate on by itself. 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. + </Accordion> + + <Accordion title="inferenceModelPricingMultiplier details"> + Mirrors Claude Code's managed `modelPricing.multiplier`: a number in (0, 1] applied to every computed cost, whether the model was priced at Anthropic list price or by an `inferenceModelPricing` row — use it for a flat contracted discount. Setting it also turns the Usage page's estimate on. Takes effect in a future release, once Desktop bundles a Claude Code version that reads it; until then turns are estimated at Anthropic list price. Ignored when a machine-level Claude Code managed `modelPricing` is present. + </Accordion> + + <Accordion title="inferenceModelPricing details"> + Each row replaces Anthropic list price for one model in the Usage page's estimate, in USD per million tokens (`inputPerMtok`, `outputPerMtok`, `cacheReadPerMtok`, `cacheWritePerMtok` — all four required; `cacheWritePerMtok` prices both 5-minute and 1-hour cache writes); any row also turns the estimate on. Mirrors Claude Code's managed `modelPricing.overrides`, and `name` is matched the same way: a built-in Claude model ID (e.g. `claude-sonnet-4-6`, or its Bedrock, Vertex, or Foundry ID) covers every dated and provider spelling of that model; any other value — a gateway alias, an inference-profile ARN — matches that exact ID only (case-insensitive) and wins over a built-in row. An ID Claude Code cannot map to a Claude model at all gets no estimate until a row here prices it. `inferenceModelPricingMultiplier` still applies on top of a row. These rates take effect in a future release, once Desktop bundles a Claude Code version that reads them; until then turns are estimated at Anthropic list price. + + ```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). | + </Accordion> </AccordionGroup> ### Vertex
from line 383
### Workspace -| Setting | Type | Availability | Default | Description | -| -------------------------------------------------------------------------------------------------- | ---------- | ---------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -| <span id="disabledbuiltintools" />Disabled built-in tools<br />`disabledBuiltinTools` | `string[]` | MDM + Bootstrap | — | Built-in tools removed from Cowork. | -| <span id="disablebundledskills" />Disable bundled skills and workflows<br />`disableBundledSkills` | `boolean` | MDM + Bootstrap | — | Disables Claude Code’s bundled skills and workflows (deep-research and similar). Use where WebFetch/WebSearch aren’t available. | -| <span id="skillcreationenabled" />Allow user-created skills<br />`skillCreationEnabled` | `boolean` | MDM + Bootstrap | — | Allow users to create and upload their own skills. When off, the creation and upload surfaces are hidden and the agent’s skill-creation tools are disabled. | -| <span id="builtintoolpolicy" />Built-in tool policy<br />`builtinToolPolicy` | `object` | MDM + Bootstrap | — | Per-tool approval policy for built-in tools. “ask” requires user approval before each call; “allow” is the default. | -| <span id="automodeenabled" />Allow Auto mode<br />`autoModeEnabled` | `boolean` | MDM + Bootstrap | `false` | Offer Auto mode in the Cowork and Code permission selectors. Claude decides which actions need approval. Defaults to `false`. | -| <span id="toolsearchenabled" />Enable tool search<br />`toolSearchEnabled` | `boolean` | MDM + Bootstrap | `false` | Load MCP tool schemas on demand (tool search) instead of inlining every schema into context. Defaults to `false`. | -| <span id="allowedworkspacefolders" />Allowed workspace folders<br />`allowedWorkspaceFolders` | `object[]` | MDM + Bootstrap | — | Folders where Claude may work. Applies to both Cowork and Code sessions. Leave unset for unrestricted access. | -| <span id="coworkegressallowedhosts" />Allowed egress hosts<br />`coworkEgressAllowedHosts` | `string[]` | MDM + Bootstrap | — | Hostnames the agent’s tools may reach from Cowork and Code sessions. Also surfaced under Egress Requirements. | -| <span id="requirecoworkfullvmsandbox" />Require full VM sandbox<br />`requireCoworkFullVmSandbox` | `boolean` | MDM + Bootstrap · Deprecated | `false` | Runs tools inside an isolated VM instead of the host. Stronger isolation; slower file access and no host-process tools. Defaults to `false`. | +| Setting | Type | Availability | Default | Description | +| -------------------------------------------------------------------------------------------------------------------- | ---------- | ---------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| <span id="userpluginmarketplacesenabled" />Allow user-added plugin marketplaces<br />`userPluginMarketplacesEnabled` | `boolean` | MDM + Bootstrap | — | Allow users to add plugin marketplaces themselves. When off, the add-marketplace surfaces are hidden and in-app adds are refused. | +| <span id="userpluginuploadsenabled" />Allow user-added plugins<br />`userPluginUploadsEnabled` | `boolean` | MDM + Bootstrap | — | Allow users to add their own plugins. When off, every in-app option for adding one is hidden and uploads that still reach the app are refused. | +| <span id="disabledbuiltintools" />Disabled built-in tools<br />`disabledBuiltinTools` | `string[]` | MDM + Bootstrap | — | Built-in tools, or argument-scoped permission rules such as Read(\*\*/.env), denied in Cowork and Code. | +| <span id="disablebundledskills" />Disable bundled skills and workflows<br />`disableBundledSkills` | `boolean` | MDM + Bootstrap | — | Disables Claude Code’s bundled skills and workflows (deep-research and similar). Use where WebFetch/WebSearch aren’t available. | +| <span id="skillcreationenabled" />Allow user-created skills<br />`skillCreationEnabled` | `boolean` | MDM + Bootstrap | — | Allow users to create and upload their own skills. When off, the creation and upload surfaces are hidden and the agent’s skill-creation tools are disabled. | +| <span id="builtintoolpolicy" />Built-in tool policy<br />`builtinToolPolicy` | `object` | MDM + Bootstrap | — | Approval policy per built-in tool or argument-scoped rule such as Bash(curl \*). “ask” requires user approval before each matching call; “allow” is the default. | +| <span id="automodeenabled" />Allow Auto mode<br />`autoModeEnabled` | `boolean` | MDM + Bootstrap | `false` | Offer Auto mode in the Cowork and Code permission selectors. Claude decides which actions need approval. Defaults to `false`. | +| <span id="toolsearchenabled" />Enable tool search<br />`toolSearchEnabled` | `boolean` | MDM + Bootstrap | `false` | Load MCP tool schemas on demand (tool search) instead of inlining every schema into context. Defaults to `false`. | +| <span id="skipwebfetchpreflight" />Skip WebFetch domain check<br />`skipWebFetchPreflight` | `boolean` | MDM + Bootstrap | — | Skip Claude Code’s WebFetch domain lookup against api.anthropic.com in Code sessions. Off by default; turn on when that host is blocked. | +| <span id="allowedworkspacefolders" />Allowed workspace folders<br />`allowedWorkspaceFolders` | `object[]` | MDM + Bootstrap | — | Folders where Claude may work. Applies to both Cowork and Code sessions. Leave unset for unrestricted access. | +| <span id="coworkegressallowedhosts" />Allowed egress hosts<br />`coworkEgressAllowedHosts` | `string[]` | MDM + Bootstrap | — | Hostnames the agent’s tools may reach from Cowork and Code sessions. Also surfaced under Egress Requirements. | +| <span id="requirecoworkfullvmsandbox" />Require full VM sandbox<br />`requireCoworkFullVmSandbox` | `boolean` | MDM + Bootstrap · Deprecated | `false` | Runs tools inside an isolated VM instead of the host. Stronger isolation; slower file access and no host-process tools. Defaults to `false`. | +| <span id="organizationinstructions" />Organization instructions<br />`organizationInstructions` | `string` | MDM + Bootstrap | — | Appended to Claude’s system prompt in Chat, Cowork, and Code. Guidance the model follows, not an enforced control. Up to 3,000 characters. | <AccordionGroup> + <Accordion title="userPluginMarketplacesEnabled details"> + When on (default), users can add plugin marketplaces from the plugin browser. Set to `false` to block user marketplace adds: the add-marketplace surfaces are hidden, and the app refuses adds that still reach it (deep links, stale UI). + + This is a feature-availability control enforced in the app, not a data boundary: marketplaces already registered on the user's machine (or registered outside the app, for example by the Claude Code CLI or by editing Claude Code's plugin files) are not removed or blocked by this key. Marketplaces provisioned by your organization (`allowedPluginMarketplaces`) are unaffected. + + This key applies only while the app runs in third-party mode. If users could otherwise sign in to Claude.ai on the device, also set `disableDeploymentModeChooser` so the app stays in third-party mode. + </Accordion> + + <Accordion title="userPluginUploadsEnabled details"> + When on (default), users can upload plugin files and create plugins with Claude. Set to `false` to stop users adding plugins of their own: every in-app option for doing so is hidden, and the app refuses uploads that still reach it. + + This is a feature-availability control enforced in the app, not a data boundary: plugins already installed (or placed on disk outside the app) are not removed or blocked by this key. Plugins from organization-provisioned marketplaces and the organization plugins directory are unaffected. + + This key applies only while the app runs in third-party mode. If users could otherwise sign in to Claude.ai on the device, also set `disableDeploymentModeChooser` so the app stays in third-party mode. + </Accordion> + + <Accordion title="disabledBuiltinTools details"> + Each entry is a Claude Code tool name (`Bash`, `Read`, `Write`, `Edit`, `Glob`, `Grep`, `NotebookEdit`, `WebFetch`, `WebSearch`, `Task`, `TodoWrite`, `TaskCreate`, `TaskUpdate`, `TaskGet`, `TaskList`, `TaskStop`, `Skill`, `REPL`, `JavaScript`, `AskUserQuestion`, `ToolSearch`, `SendUserMessage`) or an argument-scoped [permission rule](https://code.claude.com/docs/en/permissions#permission-rule-syntax) for one of them (any except `WebSearch` and `WebFetch`, which take the bare name only) — for example `Bash(curl *)`, `Read(//etc/**)`, or `Edit(**/*.env)`. A bare name covers every call to the tool (`Tool(*)` means the same and is stored as the bare name); an argument-scoped rule covers only matching calls and is evaluated by Claude Code's own rule matcher, in every permission mode including Auto and bypass. Claude Code matches a scope for `Bash(…)` (a command pattern) and for file-path patterns written as `Read(…)` (matched for every file-reading tool: `Read`, `Grep`, `Glob`) or `Edit(…)` (every file-editing tool: `Edit`, `Write`, `NotebookEdit`) — it does not consult a path pattern written against any other file tool; other tools take the bare name or Claude Code's generic `Tool(<field>:<pattern>)` form. `WebFetch` and `WebSearch` are whole-tool only: per-host web access is a single control, the egress host settings (`coworkEgressAllowedHosts`), which the Cowork sandbox and Code sessions both enforce, and web search runs server-side at the inference provider where no host list applies — a scoped `WebFetch(…)` or `WebSearch(…)` entry is not a usable rule here (the deny list still hands a scoped `WebFetch(…)` entry to Code sessions as written; Cowork never sees it). An entry Claude Code would not enforce as written raises a configuration warning. + + Argument-scoped `Bash(…)` rules apply to Code sessions and to Cowork sessions running inside the VM sandbox (`requireFullVmSandbox`); Cowork otherwise runs shell commands through a sandboxed `bash` workspace tool that honors the bare name only. Cowork sessions inside the VM sandbox see connected folders at sandbox paths (`/sessions/…/mnt/<folder>/…`), so a file pattern spelled as a host absolute path (`Read(//Users/**)`) does not match there — write patterns that must hold in every Cowork mode folder-relative or `**/`-anchored (`Read(**/secrets/**)`, `Edit(**/*.env)`), or use a read-only `allowedWorkspaceFolders` entry. In Code side chats, and in Cowork sessions that run tools on the host, an **ask** entry on a file tool (`Read`, `Write`, `Edit`, `Glob`, `Grep`) blocks matching calls instead of prompting; Code sessions and VM-sandboxed Cowork sessions show the approval prompt. An **ask** entry, bare or argument-scoped, also turns off the app's remembered “always allow” choices for that whole tool, so each prompted call to it is confirmed individually. Argument-scoped rules reach sessions through Claude Code's managed-settings channel, so Claude Code managed settings delivered any other way — server-managed settings from the Claude admin console or a gateway, an MDM profile, or a [managed-settings file](https://claude.com/docs/third-party/claude-desktop/code#interaction-with-claude-code%E2%80%99s-own-managed-settings) — replace the argument-scoped **ask** rules (and any deny rule whose pattern contains `)` followed by a space or comma) unless that source sets `parentSettingsBehavior` to `"merge"`; bare names and other deny rules are enforced either way. + + The argument-scoped syntax requires the Claude Desktop release it first shipped in or newer — hold off deploying argument-scoped entries until your whole fleet is on that build (note `disableAutoUpdates` pins builds): an older build passes an argument-scoped **deny** entry through to Claude Code unchanged, but drops an argument-scoped **ask** entry as an unknown key — recorded there as a managed-configuration error (which, until that client updates, also blocks WSL sessions on Windows) — and the tool runs at its default (no prompt). + + An entry that is not a usable rule at all (a lowercase tool name, an unbalanced parenthesis, a scoped `WebFetch(…)` or `WebSearch(…)`) is also kept — the deny-list is served exactly as written — and raises a configuration warning. + </Accordion> + <Accordion title="skillCreationEnabled details"> When on (default), users can create new skills and upload skill files in the app. Set to `false` to block user skill creation: the skill-creation and upload surfaces are hidden (the `skill_creation` feature is served as blocked by the organization), and the agent's skill-creation tools (saving skills from a conversation, skill proposals) are not offered in sessions — the same effect as turning off the **User-created skills** organization setting available to claude.ai enterprise admins.
from line 433
</Accordion> <Accordion title="builtinToolPolicy details"> - `ask-session` is accepted for compatibility and treated as `ask`. To remove a tool entirely, use **Disabled built-in tools** instead. + 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) for one of them (any except `WebSearch` and `WebFetch`, which take the bare name only) — for example `Bash(curl *)`, `Read(//etc/**)`, or `Edit(**/*.env)`. A bare name covers every call to the tool (`Tool(*)` means the same and is stored as the bare name); an argument-scoped rule covers only matching calls and is evaluated by Claude Code's own rule matcher, in every permission mode including Auto and bypass. Claude Code matches a scope for `Bash(…)` (a command pattern) and for file-path patterns written as `Read(…)` (matched for every file-reading tool: `Read`, `Grep`, `Glob`) or `Edit(…)` (every file-editing tool: `Edit`, `Write`, `NotebookEdit`) — it does not consult a path pattern written against any other file tool; other tools take the bare name or Claude Code's generic `Tool(<field>:<pattern>)` form. `WebFetch` and `WebSearch` are whole-tool only: per-host web access is a single control, the egress host settings (`coworkEgressAllowedHosts`), which the Cowork sandbox and Code sessions both enforce, and web search runs server-side at the inference provider where no host list applies — a scoped `WebFetch(…)` or `WebSearch(…)` entry is not a usable rule here (the deny list still hands a scoped `WebFetch(…)` entry to Code sessions as written; Cowork never sees it). An entry Claude Code would not enforce as written raises a configuration warning. + + Argument-scoped `Bash(…)` rules apply to Code sessions and to Cowork sessions running inside the VM sandbox (`requireFullVmSandbox`); Cowork otherwise runs shell commands through a sandboxed `bash` workspace tool that honors the bare name only. Cowork sessions inside the VM sandbox see connected folders at sandbox paths (`/sessions/…/mnt/<folder>/…`), so a file pattern spelled as a host absolute path (`Read(//Users/**)`) does not match there — write patterns that must hold in every Cowork mode folder-relative or `**/`-anchored (`Read(**/secrets/**)`, `Edit(**/*.env)`), or use a read-only `allowedWorkspaceFolders` entry. In Code side chats, and in Cowork sessions that run tools on the host, an **ask** entry on a file tool (`Read`, `Write`, `Edit`, `Glob`, `Grep`) blocks matching calls instead of prompting; Code sessions and VM-sandboxed Cowork sessions show the approval prompt. An **ask** entry, bare or argument-scoped, also turns off the app's remembered “always allow” choices for that whole tool, so each prompted call to it is confirmed individually. Argument-scoped rules reach sessions through Claude Code's managed-settings channel, so Claude Code managed settings delivered any other way — server-managed settings from the Claude admin console or a gateway, an MDM profile, or a [managed-settings file](https://claude.com/docs/third-party/claude-desktop/code#interaction-with-claude-code%E2%80%99s-own-managed-settings) — replace the argument-scoped **ask** rules (and any deny rule whose pattern contains `)` followed by a space or comma) unless that source sets `parentSettingsBehavior` to `"merge"`; bare names and other deny rules are enforced either way. + + The argument-scoped syntax requires the Claude Desktop release it first shipped in or newer — hold off deploying argument-scoped entries until your whole fleet is on that build (note `disableAutoUpdates` pins builds): an older build passes an argument-scoped **deny** entry through to Claude Code unchanged, but drops an argument-scoped **ask** entry as an unknown key — recorded there as a managed-configuration error (which, until that client updates, also blocks WSL sessions on Windows) — and the tool runs at its default (no prompt). + + An entry that is not a usable rule at all (a lowercase tool name, an unbalanced parenthesis, a scoped `WebFetch(…)` or `WebSearch(…)`) is dropped and recorded as a configuration error, like any other unreadable managed value. `ask-session` is accepted for compatibility and treated as `ask`. To remove a tool or deny a rule entirely, use **Disabled built-in tools** instead. </Accordion> <Accordion title="autoModeEnabled details">
from line 458
Claude Desktop otherwise suppresses **all** of Claude Code's experimental beta features on 3P deployments (it pins `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` into session environments, because strict gateways reject unrecognized beta headers and fields). Enabling this key lifts that suppression, so other experimental betas — for example, on gateway- and Foundry-backed deployments, `context_management` request fields on models that support them — are re-enabled as well. This matches the request surface terminal Claude Code presents through the same gateway by default. Leave unset to keep the conservative default. </Accordion> + <Accordion title="skipWebFetchPreflight details"> + Before fetching a page, Claude Code's WebFetch tool asks `api.anthropic.com` whether the domain is on Anthropic's content blocklist, and refuses the fetch if that lookup cannot complete. Third-party deployments route inference elsewhere and often block `api.anthropic.com` at the firewall; with the lookup on, every WebFetch in Code sessions then fails with "Unable to verify if domain … is safe to fetch", and where the host is reachable, every fetched hostname is sent to Anthropic. (Cowork sessions fetch through the app's own allowlisted fetch and never run this lookup.) + + Off (default): the lookup runs as it does today, so `api.anthropic.com` must be reachable from users' machines for Code-session WebFetch to work (listed under Egress Requirements). Set to `true` when users' machines cannot reach `api.anthropic.com` (corporate firewall, government network) or you do not want fetched hostnames sent there: Code sessions then fetch without the lookup and never contact that host for it. This is the same `skipWebFetchPreflight` setting Claude Code reads from its own [managed-settings](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. + </Accordion> + <Accordion title="allowedWorkspaceFolders details"> Paths can reference `~` and these environment variables, expanded per user: `%OneDrive%`, `%OneDriveCommercial%`, `%OneDriveConsumer%`, `%APPDATA%`, `%LOCALAPPDATA%`, `%USERNAME%`, `%XDG_DOCUMENTS_DIR%`. The set is fixed; an entry that references any other `%VAR%`, or one that is unset on the device, is ignored.
from line 479
<Accordion title="coworkEgressAllowedHosts details"> Applies to **both** Cowork and Code. 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); a separately deployed Claude Code managed-settings file on the endpoint takes precedence by default. - Does **not** apply to Web Search, which runs server-side at your inference provider rather than from the sandbox. + Does **not** apply to Web Search, which runs server-side at your inference provider rather than from the sandbox. Per-host control for the agent's web access lives here; to turn `WebFetch` or `WebSearch` off entirely, or to require approval for each call, list the bare tool name in `disabledBuiltinTools` or `builtinToolPolicy`. Only affects **tool calls**. Inference and MCP traffic are covered by their own allowlists elsewhere. When unset, only the inference endpoint is reachable from the sandbox; the agent's package installs (pip/npm) and web fetches will fail with a 403.
from line 489
Hosts you add here also need to be open on your network firewall, on the listed ports. See **Egress Requirements** for the full allowlist. </Accordion> + + <Accordion title="organizationInstructions details"> + Free-text instructions from your organization that Claude Desktop appends, in a clearly delimited block, after its own system prompt in **Chat**, **Cowork**, and **Code** (every chat, task, and Code session, including the sub-agents they spawn): for example house style, data-handling rules, or topics to decline. The model is told these instructions come from the organization's administrator and take priority over a user's personal preferences. + + This is guidance the model follows, not an enforced control: like any system-prompt text it steers the model's behavior and is usually honored, but it does not guarantee an outcome and is not a substitute for the restriction keys (tool policy, egress allowlist, folder allowlist). The app's own system prompt is never replaced or shortened by this key; in Code sessions it is added after Claude Code's own prompt and any `CLAUDE.md` instructions still apply. + + Read from the app's loaded configuration when a session starts; a changed value generally takes effect for sessions started after the next app launch. Leading and trailing whitespace is trimmed; an empty string is treated as unset. Maximum 3,000 characters; a longer value is rejected (the key is ignored with a configuration error) rather than truncated. Line breaks are preserved when the value is delivered as JSON, a bootstrap response, a `.mobileconfig` profile, or a `.reg` file; the Group Policy (ADMX) and Intune text box for this setting is single-line. + </Accordion> </AccordionGroup> ## Connectors
from line 541
| <span id="managedmcpservers" />Managed MCP servers<br />`managedMcpServers` | `object[]` | MDM + Bootstrap | — | Org-pushed MCP servers: remote (HTTP/SSE) or local (stdio command). May embed bearer tokens. | | <span id="mcppersistentalwaysallowenabled" />Allow persistent tool approvals<br />`mcpPersistentAlwaysAllowEnabled` | `boolean` | MDM + Bootstrap | `true` | Offer the persistent “Always allow” approval options for MCP tools. Disable to keep tool approvals per-call or session-scoped only. Defaults to `true`. | | <span id="islocaldevmcpenabled" />Allow user-added MCP servers<br />`isLocalDevMcpEnabled` | `boolean` | MDM + Bootstrap | `true` | Local stdio servers added via the Developer settings. Remote servers come from the managed list above or organization plugins. Defaults to `true`. | +| <span id="mcptooltimeoutsec" />MCP tool call timeout<br />`mcpToolTimeoutSec` | `integer` | MDM + Bootstrap | — | Per-call timeout for MCP tool calls, in seconds. Default 180 (3 minutes). Range: 60–3600. | <AccordionGroup> <Accordion title="managedMcpServers details">
from line 602
This key governs the chat and Cowork surfaces. Code sessions use a separate permission path this key does not cover — govern Code tool approvals with per-tool `toolPolicy` entries, whose `blocked` and `ask` values are forwarded there. </Accordion> + + <Accordion title="mcpToolTimeoutSec details"> + Sets the per-call timeout the agent applies to every MCP tool call; a call that runs longer fails with a timeout error the model can see. Cowork and chat sessions default to 180 seconds. Code sessions have no desktop-imposed MCP tool timeout today, so setting this key introduces one there as well. The desktop's own request deadlines toward MCP servers — the managed servers above and, where `isLocalDevMcpEnabled` permits them, user-added local servers — follow this value so they never cut a call short first; while the key is unset, calls to user-added local servers are additionally limited to 60 seconds by the desktop. Values outside 60–3600 are rejected at parse time (the error is listed in the diagnostics report) and the defaults apply. + + The timeout is global (there is no per-server or per-tool form), so size it for the slowest tool you need to complete: long-running tools on one server extend the window during which a stuck call on any server holds its turn. Cowork's built-in shell tool runs under the same cap: a single command's `timeout_ms` (itself limited to 600 seconds) cannot exceed this value. + </Accordion> </AccordionGroup> ## Telemetry & updates
from line 807
</Accordion> <Accordion title="allowedPluginMarketplaces details"> - | Field | Type | Default | Description | - | ------------------------ | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | `source` | `string` | — | Where the marketplace is fetched from: a GitHub repository (set repo), any Git remote (set url), or a hosted marketplace.json file (set url). One of: `github`, `git`, `url`. | - | `repo` | `string` | — | GitHub repository in owner/repo form. Case-insensitive. | - | `ref` | `string` | — | Commit SHA, branch, or tag. Leave empty to track the default branch. | - | `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 inference does (url sources the gateway hosts). 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. Required when Installation is auto\_install or required; a served manifest with any other digest is refused. | + | 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. | + | `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. Required when Installation is auto\_install or required; a served manifest with any other digest is refused. | </Accordion> </AccordionGroup>
from line 853
</Accordion> <Accordion title="bootstrapHeaders details"> - Static headers sent on every request to the bootstrap config URL — for a service-account credential (`Authorization: Basic …`, an API key header) or a routing/tenant header. When either this or the headers helper script is set and no separate `bootstrapOidc` provider is configured, the app treats the headers as sufficient auth and does not require a per-user sign-in for the bootstrap fetch. Header values are masked in diagnostics and telemetry. For a rotating token, use the headers helper script instead. + 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. </Accordion> <Accordion title="bootstrapHeadersHelper details">