Page history
Configuration reference
third-party/claude-desktop/configuration
History
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">
third-party/claude-desktop/configuration Changed · +7 / -7 lines
from line 191
**The gateway MUST validate `iss` AND `aud`, not just the signature.** Signature + issuer alone accepts *any* token from the same tenant, including tokens issued to unrelated apps. In `id_token` mode the audience is the `clientId`: - ```yaml theme={null} theme={null} + ```yaml theme={null} # LiteLLM example — `audience` is REQUIRED, not optional general_settings: litellm_jwtauth:
from line 244
**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} theme={null} + ```json theme={null} [{"name": "claude-sonnet-5", "supports1m": true}, "claude-opus-4-8"] ``` **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} theme={null} + ```json theme={null} [{"name": "claude-opus-4-8", "supports1m": true, "prefer1m": true}] ``` **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} theme={null} + ```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} theme={null} + ```json theme={null} [{"name": "us.anthropic.claude-opus-4-8", "anthropicFamilyTier": "opus"}] ```
from line 704
<Accordion title="orgPluginSettings details"> Applies `toolPolicy` locks to MCP servers that arrive via the org-plugins directory, keyed by server name. Either shape is accepted; when hand-authoring a profile, use the legacy record shape until your fleet floor parses the canonical array form: - ```json theme={null} theme={null} + ```json theme={null} {"mcpServers": {"internal-search": {"toolPolicy": {"delete_document": "blocked"}}}} ```
from line 807
</Tab> <Tab title="Locked down"> - For air-gapped or maximally restricted environments. **The only traffic leaving the device goes to your inference endpoint and OTLP collector.** With this profile, Anthropic has zero remote visibility, so your team owns log collection and update distribution. + For air-gapped or maximally restricted environments. **The only traffic leaving the device goes to your inference endpoint and OTLP collector.** 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 | | --------------------------------------------------------------- | --------------------------------- |
third-party/claude-desktop/configuration Changed · +7 / -7 lines
from line 18
The local location is a directory: `_meta.json` records which saved configuration is applied, and each configuration is a `<id>.json` file alongside it. The in-app configuration window writes here. -When a managed source is present, it wins and locally written values are ignored. The exception is a managed source that sets only the update keys (`disableAutoUpdates` and `autoUpdaterEnforcementHours`): those two keys are enforced from the managed source, but the rest of the configuration stays local and user-editable. Configuration is read **once at launch**, so fully quit and reopen the app after any change. 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. +When a managed source is present, it wins and locally written values are ignored. The exception is a managed source that sets only the update keys (`disableAutoUpdates`, `autoUpdaterEnforcementHours`, and `updateViaUpdatesHost`): those keys are enforced from the managed source, but the rest of the configuration stays local and user-editable. Configuration is read **once at launch**, so fully quit and reopen the app after any change. 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. <Note> 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.
from line 191
**The gateway MUST validate `iss` AND `aud`, not just the signature.** Signature + issuer alone accepts *any* token from the same tenant, including tokens issued to unrelated apps. In `id_token` mode the audience is the `clientId`: - ```yaml theme={null} + ```yaml theme={null} theme={null} # LiteLLM example — `audience` is REQUIRED, not optional general_settings: litellm_jwtauth:
from line 244
**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} + ```json theme={null} theme={null} [{"name": "claude-sonnet-5", "supports1m": true}, "claude-opus-4-8"] ``` **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} + ```json theme={null} theme={null} [{"name": "claude-opus-4-8", "supports1m": true, "prefer1m": true}] ``` **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} + ```json theme={null} 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} + ```json theme={null} theme={null} [{"name": "us.anthropic.claude-opus-4-8", "anthropicFamilyTier": "opus"}] ```
from line 704
<Accordion title="orgPluginSettings details"> Applies `toolPolicy` locks to MCP servers that arrive via the org-plugins directory, keyed by server name. Either shape is accepted; when hand-authoring a profile, use the legacy record shape until your fleet floor parses the canonical array form: - ```json theme={null} + ```json theme={null} theme={null} {"mcpServers": {"internal-search": {"toolPolicy": {"delete_document": "blocked"}}}} ```
third-party/claude-desktop/configuration Changed · +10 / -10 lines
from line 524
## Telemetry & updates -| Setting | Type | Availability | Default | Description | -| ---------------------------------------------------------------------------------------------------------- | --------- | --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| <span id="deploymentorganizationuuid" />Organization UUID<br />`deploymentOrganizationUuid` | `string` | MDM + Bootstrap | — | A UUID you generate. Tags telemetry so Anthropic support can locate your fleet’s events, and namespaces each user’s local data. Not used for auth. | -| <span id="disableessentialtelemetry" />Block essential telemetry<br />`disableEssentialTelemetry` | `boolean` | MDM + Bootstrap | `false` | Crash and performance reports to Anthropic. Defaults to `false`. | -| <span id="disablenonessentialtelemetry" />Block nonessential telemetry<br />`disableNonessentialTelemetry` | `boolean` | MDM + Bootstrap | `false` | Product-usage analytics and diagnostic-report uploads. No message content. Defaults to `false`. | -| <span id="disablenonessentialservices" />Block nonessential services<br />`disableNonessentialServices` | `boolean` | MDM + Bootstrap | `false` | Connector favicons, the connector directory (MCP registry) lookup, and the artifact-preview and MCP Apps widget iframe origins. Artifacts will not render. Defaults to `false`. | +| Setting | Type | Availability | Default | Description | +| ---------------------------------------------------------------------------------------------------------- | --------- | --------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| <span id="deploymentorganizationuuid" />Organization UUID<br />`deploymentOrganizationUuid` | `string` | MDM + Bootstrap | — | A UUID you generate. Tags telemetry so Anthropic support can locate your fleet’s events, and namespaces each user’s local data. Not used for auth. | +| <span id="disableessentialtelemetry" />Block essential telemetry<br />`disableEssentialTelemetry` | `boolean` | MDM + Bootstrap | `false` | Crash and performance reports to Anthropic. Defaults to `false`. | +| <span id="disablenonessentialtelemetry" />Block nonessential telemetry<br />`disableNonessentialTelemetry` | `boolean` | MDM + Bootstrap | `false` | Product-usage analytics and diagnostic-report uploads. No message content. Defaults to `false`. | +| <span id="disablenonessentialservices" />Block nonessential services<br />`disableNonessentialServices` | `boolean` | MDM + Bootstrap | `false` | Connector favicons and the artifact-preview and MCP Apps widget iframe origins. Artifacts will not render. Defaults to `false`. | <AccordionGroup> <Accordion title="deploymentOrganizationUuid details">
from line 547
<Accordion title="disableNonessentialTelemetry details"> "Nonessential" covers two things: **product-usage analytics** (which features get used, navigation patterns; no prompts or completions) and the **Send** action in Help → Generate Diagnostic Report. Turning this on stops both. - Destination for both: `claude.ai`. Already listed under Egress Requirements → Nonessential telemetry. + Destinations are listed under Egress Requirements → Nonessential telemetry. </Accordion> <Accordion title="disableNonessentialServices details"> - "Nonessential services" covers four outbound fetches the app runs without: **connector favicons** (the icon proxy), the **connector directory** lookup (the Anthropic MCP registry), the **artifact-preview** iframe origin, and the **MCP Apps widget** iframe origin (`*.claudemcpcontent.com`). Turning this on blocks all four. + "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, the connector directory can't be fetched, artifacts do not render in conversations, and connectors that return MCP Apps show the text tool result instead of the widget. + **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. </Accordion>
third-party/claude-desktop/configuration Changed · +11 / -1 lines
from line 489
| `readOnly` | `boolean` | — | Offer only read tools — the server registers no write tools at all. | | `transport` | `enum` | — | How the app connects: Streamable HTTP or legacy SSE for remote servers, or a local command over stdio. One of: `http`, `sse`, `stdio`. | | `url` | `string` | — | HTTPS endpoint of the remote MCP server. | - | `oauth` | `object` | — | OAuth settings for a remote server: true to auto-register a client, or an object with a pre-registered client ID, tenant, and scope. | + | `oauth` | `object` | — | OAuth for a remote server: true to auto-register a client, a pre-registered client ID with tenant and scope, or mode “hosted” for an Anthropic-signed identity. | | `oauth.clientId` | `string` | — | OAuth client ID from your IdP app registration. Leave unset to auto-register (dynamic client registration) and only narrow scopes. | | `oauth.clientSecret` | `string` | — | Only for IdPs whose token endpoint requires a client secret (e.g. Box). Leave blank for PKCE-only public clients. | | `oauth.clientSecretHelper` | `string` | — | Executable that prints the client secret on stdout. Overrides the inline value. |
from line 743
| <span id="bootstrapenabled" />Use bootstrap config<br />`bootstrapEnabled` | `boolean` | MDM only | `true` | Fetch and apply the URL above at launch. Turn off to keep the URL saved but skip the fetch. Defaults to `true`. | | <span id="bootstrapurl" />Bootstrap config URL<br />`bootstrapUrl` | `string` | MDM only | — | HTTPS endpoint that returns a per-user JSON config overlay. Values from the response override local settings and become read-only. | | <span id="bootstrapoidc" />Bootstrap OIDC parameters<br />`bootstrapOidc` | `object` | MDM only | — | When set, the bootstrap request sends a Bearer token from a browser sign-in (authorization-code-with-PKCE). | +| <span id="bootstrapheaders" />Bootstrap request headers<br />`bootstrapHeaders` | `object` | MDM only | — | HTTP headers sent on every bootstrap config fetch. Use this instead of embedding user:pass@ in the URL. | +| <span id="bootstrapheadershelper" />Bootstrap headers helper script<br />`bootstrapHeadersHelper` | `string` | MDM only | — | Absolute path to an executable that prints a JSON object of bootstrap request headers. Merged over the static headers; the helper wins. | | <span id="trustbootstrapdelivery" />Trust bootstrap-delivered settings<br />`trustBootstrapDelivery` | `boolean` | MDM only | `false` | Skip the per-user consent prompt for sign-in targets, inference endpoints, helper scripts, and connectors the bootstrap server delivers. Defaults to `false`. Previously named `trustBootstrapLocalExec`. | <AccordionGroup>
from line 762
| `scopes` | `string` | — | Space-separated; the token’s audience must match what your bootstrap server validates. | | `redirectPort` | `integer` | — | Fixed loopback port for the sign-in redirect ([http://127.0.0.1:PORT/callback](http://127.0.0.1:PORT/callback)). Leave unset to use a free port each time. | | `additionalRedirectReferrerHosts` | `string` | — | Space-separated hostnames also accepted as the referrer of the sign-in callback. Only needed when the IdP completes sign-in from a different host. | + </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. + </Accordion> + + <Accordion title="bootstrapHeadersHelper details"> + Absolute path to an executable that prints a single JSON object of HTTP headers on stdout, e.g. `{"Authorization": "Bearer …"}`. The app runs it (no arguments; output cached for a few minutes) before each bootstrap config fetch and merges the result over **Bootstrap request headers** (the helper wins on conflict). Use this instead of embedding `user:pass@` in the bootstrap URL, or when the bootstrap server needs a rotating token from a secrets manager. When either this or the static headers are set and no separate `bootstrapOidc` provider is configured, the app treats them as sufficient auth and does not require a per-user sign-in for the bootstrap fetch. If a per-user sign-in also runs (`bootstrapOidc` or the server’s own device-code flow), that Bearer token wins on `Authorization`. </Accordion> </AccordionGroup>
third-party/claude-desktop/configuration Changed · +59 / -57 lines
from line 73
## Connection -| Setting | Type | Availability | Default | Description | -| ------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | --------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| <span id="inferencecustomheaders" />Custom inference headers<br />`inferenceCustomHeaders` | `object` | MDM + Bootstrap | — | Extra HTTP headers sent on every inference request to the configured provider. For tenant routing, org IDs, Bedrock Guardrails, etc. 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="inferencecredentialhelpertimeoutsec" />Credential helper timeout<br />`inferenceCredentialHelperTimeoutSec` | `integer` | MDM + Bootstrap | `60` | Maximum wait for the helper executable to finish. Raise this if the helper opens a browser for interactive sign-in. Defaults to `60`. Range: 1–600. | -| <span id="inferencecredentialhelpersilentrefreshenabled" />Re-run helper for silent refresh<br />`inferenceCredentialHelperSilentRefreshEnabled` | `boolean` | MDM + Bootstrap | `true` | On credential expiry, re-run the helper (CLAUDE\_HELPER\_CONTEXT=mid-session-refresh) to recover silently. Turn off if the helper can’t run non-interactively. Defaults to `true`. | -| <span id="usercontentrendererurl" />Artifact preview iframe origin<br />`userContentRendererUrl` | `string` | MDM + Bootstrap | — | HTTPS origin of the user-content-renderer deployment used for artifact and file previews. Defaults to the commercial host when unset. | -| <span id="inferenceprovider" />Inference provider<br />`inferenceProvider` | `enum` | MDM + Bootstrap | — | Selects the inference backend. Setting this key activates third-party mode. One of: `gateway`, `anthropic`, `bedrock`, `mantle`, `vertex`, `foundry`. | -| <span id="inferencecredentialkind" />Credential kind<br />`inferenceCredentialKind` | `enum` | MDM + Bootstrap | — | Selects the credential source. When set, only that source is used (no fallback). One of: `static`, `helper-script`, `interactive`, `vendor-profile`, `oauth`, `workforce`. | +| Setting | Type | Availability | Default | Description | +| ------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | --------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| <span id="inferencecustomheaders" />Custom inference headers<br />`inferenceCustomHeaders` | `object` | MDM + Bootstrap | — | Extra headers on every inference request — routing and tenant headers only (org IDs, Bedrock Guardrails). No credentials; use the credential helper for tokens. Previously named `inferenceGatewayHeaders`. | +| <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="inferencecredentialhelpertimeoutsec" />Credential helper timeout<br />`inferenceCredentialHelperTimeoutSec` | `integer` | MDM + Bootstrap | `60` | Maximum wait for the helper executable to finish. Raise this if the helper opens a browser for interactive sign-in. Defaults to `60`. Range: 1–600. | +| <span id="inferencecredentialhelpersilentrefreshenabled" />Re-run helper for silent refresh<br />`inferenceCredentialHelperSilentRefreshEnabled` | `boolean` | MDM + Bootstrap | `true` | On credential expiry, re-run the helper (CLAUDE\_HELPER\_CONTEXT=mid-session-refresh) to recover silently. Turn off if the helper can’t run non-interactively. Defaults to `true`. | +| <span id="usercontentrendererurl" />Artifact preview iframe origin<br />`userContentRendererUrl` | `string` | MDM + Bootstrap | — | HTTPS origin of the user-content-renderer deployment used for artifact and file previews. Defaults to the commercial host when unset. | +| <span id="inferenceprovider" />Inference provider<br />`inferenceProvider` | `enum` | MDM + Bootstrap | — | Selects the inference backend. Setting this key activates third-party mode. One of: `gateway`, `anthropic`, `bedrock`, `mantle`, `vertex`, `foundry`. | +| <span id="inferencecredentialkind" />Credential kind<br />`inferenceCredentialKind` | `enum` | MDM + Bootstrap | — | Selects the credential source. When set, only that source is used (no fallback). One of: `static`, `helper-script`, `interactive`, `vendor-profile`, `oauth`, `workforce`. | <AccordionGroup> <Accordion title="inferenceCustomHeaders details"> Sent on every inference and model-discovery request (joined into the CLI's `ANTHROPIC_CUSTOM_HEADERS`). - Use this for fleet-wide constants. 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). + 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). </Accordion> <Accordion title="inferenceCredentialHelper details">
from line 191
**The gateway MUST validate `iss` AND `aud`, not just the signature.** Signature + issuer alone accepts *any* token from the same tenant, including tokens issued to unrelated apps. In `id_token` mode the audience is the `clientId`: - ```yaml theme={null} theme={null} theme={null} theme={null} theme={null} + ```yaml theme={null} # LiteLLM example — `audience` is REQUIRED, not optional general_settings: litellm_jwtauth:
from line 244
**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} theme={null} theme={null} theme={null} theme={null} + ```json theme={null} [{"name": "claude-sonnet-5", "supports1m": true}, "claude-opus-4-8"] ``` **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} theme={null} theme={null} theme={null} theme={null} + ```json theme={null} [{"name": "claude-opus-4-8", "supports1m": true, "prefer1m": true}] ``` **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} theme={null} theme={null} theme={null} theme={null} + ```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} theme={null} theme={null} theme={null} theme={null} + ```json theme={null} [{"name": "us.anthropic.claude-opus-4-8", "anthropicFamilyTier": "opus"}] ```
from line 279
### Vertex -| Setting | Type | Availability | Default | Description | -| ------------------------------------------------------------------------------------------------------------------------------ | -------- | --------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| <span id="inferencevertexprojectid" />GCP project ID<br />`inferenceVertexProjectId` | `string` | MDM + Bootstrap | — | Google Cloud project ID for Vertex AI inference. | -| <span id="inferencevertexregion" />GCP region<br />`inferenceVertexRegion` | `string` | MDM + Bootstrap | — | GCP region where your Vertex AI Claude models are deployed. | -| <span id="inferencevertexbaseurl" />Vertex AI base URL<br />`inferenceVertexBaseUrl` | `string` | MDM + Bootstrap | — | PSC endpoint, if using one. | -| <span id="inferencevertexoauthclientid" />Vertex OAuth client ID<br />`inferenceVertexOAuthClientId` | `string` | MDM + Bootstrap | — | Desktop-app OAuth client ID. Enables Sign in with Google instead of a credentials file. | -| <span id="inferencevertexoauthclientsecret" />Vertex OAuth client secret<br />`inferenceVertexOAuthClientSecret` | `string` | MDM + Bootstrap | — | Secret for the Desktop-app OAuth client above. | -| <span id="inferencevertexoauthscopes" />Vertex OAuth scopes<br />`inferenceVertexOAuthScopes` | `string` | MDM + Bootstrap | — | Override the Google OAuth scopes (space-separated). Leave blank for the default. | -| <span id="inferencevertexoauthloginhint" />Vertex OAuth login hint<br />`inferenceVertexOAuthLoginHint` | `string` | MDM + Bootstrap | — | Pre-fill Google's account chooser and forward to your federated IdP. \{username} expands to the OS login name. | -| <span id="inferencevertexworkforceaudience" />Workforce Identity audience<br />`inferenceVertexWorkforceAudience` | `string` | MDM + Bootstrap | — | Workforce-pool provider audience. When set, sign-in uses your own IdP plus a GCP STS exchange instead of a Google identity. | -| <span id="inferencevertexworkforceuserproject" />Workforce Identity billing project<br />`inferenceVertexWorkforceUserProject` | `string` | MDM + Bootstrap | — | GCP project for STS billing and quota. Defaults to the Vertex project ID above. | -| <span id="inferencevertexworkforceauthflow" />Workforce Identity sign-in flow<br />`inferenceVertexWorkforceAuthFlow` | `enum` | MDM + Bootstrap | — | How the IdP sign-in runs: system browser (default) or the OS Microsoft Entra broker. One of: `browser`, `broker`. | -| <span id="inferencevertexworkforceoidc" />Workforce Identity IdP (OIDC)<br />`inferenceVertexWorkforceOidc` | `object` | MDM + Bootstrap | — | Your organization’s OIDC IdP. The app runs an authorization-code-with-PKCE flow against this issuer and exchanges the returned ID token at GCP STS. | -| <span id="inferencevertexcredentialsfile" />GCP credentials file path<br />`inferenceVertexCredentialsFile` | `string` | MDM + Bootstrap | — | Absolute path to service-account JSON. Leave blank to fall back to ADC. | +| Setting | Type | Availability | Default | Description | +| ------------------------------------------------------------------------------------------------------------------------------ | -------- | --------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| <span id="inferencevertexprojectid" />GCP project ID<br />`inferenceVertexProjectId` | `string` | MDM + Bootstrap | — | Google Cloud project ID for Vertex AI inference. | +| <span id="inferencevertexregion" />GCP region<br />`inferenceVertexRegion` | `string` | MDM + Bootstrap | — | GCP region where your Vertex AI Claude models are deployed. | +| <span id="inferencevertexbaseurl" />Vertex AI base URL<br />`inferenceVertexBaseUrl` | `string` | MDM + Bootstrap | — | PSC endpoint, if using one. | +| <span id="inferencevertexoauthclientid" />Vertex OAuth client ID<br />`inferenceVertexOAuthClientId` | `string` | MDM + Bootstrap | — | Desktop-app OAuth client ID. Enables Sign in with Google instead of a credentials file. | +| <span id="inferencevertexoauthclientsecret" />Vertex OAuth client secret<br />`inferenceVertexOAuthClientSecret` | `string` | MDM + Bootstrap | — | Secret for the Desktop-app OAuth client above. Google classifies installed-app client secrets as non-confidential, so this may be set from hosted config. | +| <span id="inferencevertexoauthscopes" />Vertex OAuth scopes<br />`inferenceVertexOAuthScopes` | `string` | MDM + Bootstrap | — | Override the Google OAuth scopes (space-separated). Leave blank for the default. | +| <span id="inferencevertexoauthloginhint" />Vertex OAuth login hint<br />`inferenceVertexOAuthLoginHint` | `string` | MDM + Bootstrap | — | Pre-fill Google's account chooser and forward to your federated IdP. \{username} expands to the OS login name. | +| <span id="inferencevertexworkforceaudience" />Workforce Identity audience<br />`inferenceVertexWorkforceAudience` | `string` | MDM + Bootstrap | — | Workforce-pool provider audience. When set, sign-in uses your own IdP plus a GCP STS exchange instead of a Google identity. | +| <span id="inferencevertexworkforceuserproject" />Workforce Identity billing project<br />`inferenceVertexWorkforceUserProject` | `string` | MDM + Bootstrap | — | GCP project for STS billing and quota. Defaults to the Vertex project ID above. | +| <span id="inferencevertexworkforceauthflow" />Workforce Identity sign-in flow<br />`inferenceVertexWorkforceAuthFlow` | `enum` | MDM + Bootstrap | — | How the IdP sign-in runs: system browser (default) or the OS Microsoft Entra broker. One of: `browser`, `broker`. | +| <span id="inferencevertexworkforceoidc" />Workforce Identity IdP (OIDC)<br />`inferenceVertexWorkforceOidc` | `object` | MDM + Bootstrap | — | Your organization’s OIDC IdP. The app runs an authorization-code-with-PKCE flow against this issuer and exchanges the returned ID token at GCP STS. | +| <span id="inferencevertexcredentialsfile" />GCP credentials file path<br />`inferenceVertexCredentialsFile` | `string` | MDM + Bootstrap | — | Absolute path to service-account JSON. Leave blank to fall back to ADC. | <AccordionGroup> <Accordion title="inferenceVertexWorkforceAuthFlow details">
from line 372
</Accordion> <Accordion title="builtinToolPolicy details"> - `ask-session` applies to connector tool policies only — written here it is treated as `ask`. To remove a tool entirely, use **Disabled built-in tools** instead. + `ask-session` is accepted for compatibility and treated as `ask`. To remove a tool entirely, use **Disabled built-in tools** instead. </Accordion> <Accordion title="autoModeEnabled details">
from line 412
Accepts exact hostnames (`api.github.com`), wildcards (`*.corp.com` matches subdomains at any depth — `docs.corp.com` and `a.b.corp.com` both match), and `*` to allow all. `*.corp.com` does not match `corp.com` itself; add both if you need the apex. IP addresses only match when listed exactly — wildcards never match IP addresses, so an unlisted IP destination is blocked. `localhost` and private-network addresses are blocked in the sandbox's web fetch regardless of this list; shell commands and package installs run inside a network sandbox that can only reach hosts on this list (plus your inference provider's endpoints). With `*`, the network 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 that entry to the named port; an entry with no port allows any port. A port on a wildcard applies to every matched subdomain. IPv6 literals are not supported. Entries outside this grammar are dropped individually, with a warning naming the entry in the app log; the remaining valid entries keep working. Port restrictions are enforced for the Cowork sandbox's web fetch today. The sandbox's shell and package-install egress enforces them once the app ships a VM image whose sandbox runtime supports ports; until then a port-scoped host is unreachable from shell (fails closed). Plugin CLIs additionally keep their own stricter in-VM filter and treat port-scoped entries as absent for now. In Code sessions, the Claude Code translation treats a port-restricted entry as its bare host (any port). The `:port` syntax requires the Claude Desktop release it first shipped in or newer — hold off deploying port-scoped entries until your whole fleet is on that build (note `disableAutoUpdates` pins builds); on older builds a port-scoped entry invalidates the sandbox's whole shell and package-install allowlist for the session (the older sandbox runtime rejects the entire list), and web fetch simply never matches it. + Any entry except bare `*` may carry a `:port` suffix (`internal.corp.com:8443`, `*.corp.com:8443`) restricting that entry to the named port; an entry with no port allows any port. A port on a wildcard applies to every matched subdomain. IPv6 literals are not supported. Entries outside this grammar are dropped individually, with a warning naming the entry in the app log; the remaining valid entries keep working. Port restrictions are enforced for the Cowork sandbox's web fetch and for its shell and package-install egress. Plugin CLIs additionally keep their own stricter in-VM filter and treat port-scoped entries as absent for now. In Code sessions, the Claude Code translation treats a port-restricted entry as its bare host (any port). The `:port` syntax requires the Claude Desktop release it first shipped in or newer — hold off deploying port-scoped entries until your whole fleet is on that build (note `disableAutoUpdates` pins builds); on older builds a port-scoped entry invalidates the sandbox's whole shell and package-install allowlist for the session (the older sandbox runtime rejects the entire list), and web fetch simply never matches it. 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>
from line 420
## Connectors -| Setting | Type | Availability | Default | Description | -| ----------------------------------------------------------------------- | -------- | --------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -| <span id="claudeaiimport" />Claude.ai data import<br />`claudeAiImport` | `object` | MDM + Bootstrap | — | Lets users import Claude.ai chats and projects, plus earlier Claude sessions on this computer, into this deployment. Off unless `enabled` is true. | +| Setting | Type | Availability | Default | Description | +| ----------------------------------------------------------------------- | -------- | --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| <span id="claudeaiimport" />Claude.ai data import<br />`claudeAiImport` | `object` | MDM + Bootstrap | — | Lets users import Claude.ai chats and projects, plus earlier Claude sessions on this computer, into this deployment when `enabled` is true. | <AccordionGroup> <Accordion title="claudeAiImport details"> | Field | Type | Default | Description | | ---------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | `enabled` | `boolean` | `false` | Lets users import a Claude.ai data export and earlier Claude sessions on this computer from Settings → Import. When false, that page says import is off. | + | `enabled` | `boolean` | `false` | Lets users import a Claude.ai data export and earlier Claude sessions on this computer from Settings → Import. Doesn’t affect a provisioned sign-in import. | + | `exportEnabled` | `boolean` | `false` | Lets users export this computer’s chats, Cowork tasks, and Code sessions as a zip another install can import. No effect unless `enabled` is true. | | `bannerBehavior` | `enum` | — | Prompt to import at the top of a new chat or task. `detect`: only when earlier Claude sessions are found on this computer. `show`: always. Hidden when unset. One of: `off`, `detect`, `show`. | </Accordion> </AccordionGroup>
from line 465
<Accordion title="managedMcpServers details"> For OAuth-authenticated entries, the app builds the redirect URI as `http://<callbackHost>:<callbackPort>/callback`; register that exact value with the OAuth provider. Tokens refresh automatically during a session, so users aren't interrupted when the initial access token expires. - `toolPolicy` locks the per-tool approval state, keyed by tool name. Keys may contain `*` wildcards (`"read_*"` matches every tool whose name starts with `read_`; matching is anchored and `*` is the only wildcard, identical to Claude Code permission-rule globs). An exact-name key wins over matching wildcard keys, with two exceptions in the stricter direction: in Code sessions, forwarded `blocked`/`ask` wildcard rules take precedence over a less strict exact key, and in chat approval flows and always-allow persistence a wildcard `ask` key keeps every matching tool behind a per-call prompt (no persistent always-allow), and a wildcard `ask-session` key likewise keeps every matching tool on the ask-session clamp, even when a more permissive exact-name key matches — for direct (imperative) tool invocations such as artifact or widget tool calls, the exact-name key still decides. When several wildcard keys match a tool, the strictest applies (blocked > ask > ask-session > allow). `"blocked"` removes the tool from the session and labels it admin-blocked. `"ask"` requires approval on every call (Allow once / Deny only; no persistent always-allow). `"ask-session"` requires approval on the tool's first use per session; a session-scoped **Allow for this task** covers the rest of that session, a new session re-prompts, and persistent always-allow stays unavailable. Scheduled tasks do not honor ask-session grants: every run prompts and blocks until attended, exactly as `ask` (use `allow` for tools that must run unattended). `"allow"` pre-approves. Tools **not listed** follow the user's choice: the prompt offers a persistent Always allow, except for tools that can modify data, which instead show a session-scoped **Allow for this task** alongside **Allow for all tasks** with a malicious-instruction warning. In Code sessions, `blocked`/`ask`/`ask-session` are forwarded as Claude Code permission rules (`ask-session` as an ask rule, with the once-per-session behavior applied by the desktop); `allow` is not. + `toolPolicy` locks the per-tool approval state, keyed by tool name. Keys may contain `*` wildcards (`"read_*"` matches every tool whose name starts with `read_`; matching is anchored and `*` is the only wildcard, identical to Claude Code permission-rule globs). An exact-name key wins over matching wildcard keys, with two exceptions in the stricter direction: in Code sessions, a forwarded `ask` wildcard rule, or a `blocked` wildcard other than the bare `"*"`, takes precedence over a less strict exact key (the deny-by-default form, `"*": "blocked"` plus exact `"allow"` entries, is honored in Code sessions too), and in chat approval flows and always-allow persistence a wildcard `ask` key keeps every matching tool behind a per-call prompt (no persistent always-allow), even when a more permissive exact-name key matches — for direct (imperative) tool invocations such as artifact or widget tool calls, the exact-name key still decides. When several wildcard keys match a tool, the strictest applies (blocked > ask > allow). `"blocked"` removes the tool from the session and labels it admin-blocked. `"ask"` requires approval on every call (Allow once / Deny only; no persistent always-allow). `"ask-session"` is accepted for compatibility and behaves exactly as `"ask"`. `"allow"` pre-approves. Tools **not listed** follow the user's choice: the prompt offers a persistent Always allow, except for tools that can modify data, which instead show a session-scoped **Allow for this task** alongside **Allow for all tasks** with a malicious-instruction warning. In Code sessions, `blocked` and `ask` (including `ask-session`) are forwarded as Claude Code permission rules; `allow` is not. For the bundled Microsoft 365 connector, the send tools (`outlook_send_mail`, `outlook_send_draft`, `outlook_forward_mail`, `outlook_create_event`, `outlook_update_event`, `teams_send_chat_message`, `teams_send_channel_message`, `teams_reply_channel_message`) cannot be loosened below `ask` — an `allow` setting resolves to `ask`.
from line 478
| `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`. | | `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 HTTP headers sent on every request to the server. For values that rotate, use a headers helper instead. | + | `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. Set the provider’s auth header below. One of: `brave`, `tavily`, `exa`, `custom`. | + | `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. |
from line 587
| --------------------------------------------------------------------------------------------------- | --------- | --------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | <span id="otlpendpoint" />OpenTelemetry collector endpoint<br />`otlpEndpoint` | `string` | MDM + Bootstrap | — | Where Cowork sends OpenTelemetry logs and metrics. Leave blank to disable. | | <span id="otlpprotocol" />OpenTelemetry exporter protocol<br />`otlpProtocol` | `enum` | MDM + Bootstrap | `http/protobuf` | grpc or http/protobuf. One of: `http/protobuf`, `http/json`, `grpc`. Defaults to `http/protobuf`. | -| <span id="otlpheaders" />OpenTelemetry exporter headers<br />`otlpHeaders` | `object` | MDM + Bootstrap | — | Optional auth headers for the collector. | +| <span id="otlpheaders" />OpenTelemetry exporter headers<br />`otlpHeaders` | `object` | MDM + Bootstrap | — | Static collector headers — routing and tenant headers only. No credentials here; use Collector authentication or the headers helper script for tokens. | | <span id="otlpauthmode" />Collector authentication<br />`otlpAuthMode` | `enum` | MDM + Bootstrap | — | inference-credential sends the user’s inference bearer token to the collector as Authorization: Bearer. One of: `none`, `inference-credential`. | | <span id="otlpheadershelper" />OpenTelemetry headers helper script<br />`otlpHeadersHelper` | `string` | MDM + Bootstrap | — | Absolute path to an executable that prints a JSON object of collector headers. Merged over the static headers and Collector authentication; the helper wins. | | <span id="otlpresourceattributes" />OpenTelemetry resource attributes<br />`otlpResourceAttributes` | `object` | MDM + Bootstrap | — | Extra resource attributes to attach to every span/metric. A static enduser.id set here always wins over the runtime identity. |
from line 695
## Plugins -| Setting | Type | Availability | Default | Description | -| ------------------------------------------------------------------------------------------- | ---------- | ---------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- | -| <span id="orgpluginsettings" />Organization plugin settings<br />`orgPluginSettings` | `object[]` | MDM + Bootstrap | — | Admin policy applied to plugin-delivered MCP servers. | -| <span id="allowedpluginmarketplaces" />Plugin marketplaces<br />`allowedPluginMarketplaces` | `object[]` | MDM + Bootstrap · Beta | — | Git repositories to surface as plugin marketplaces in the Directory’s Organization tab. The app re-clones each periodically. | +| Setting | Type | Availability | Default | Description | +| ------------------------------------------------------------------------------------------- | ---------- | ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| <span id="orgpluginsettings" />Organization plugin settings<br />`orgPluginSettings` | `object[]` | MDM + Bootstrap | — | Admin policy applied to plugin-delivered MCP servers. | +| <span id="allowedpluginmarketplaces" />Plugin marketplaces<br />`allowedPluginMarketplaces` | `object[]` | MDM + Bootstrap · Beta | — | Git repositories or hosted marketplace.json URLs to surface as plugin marketplaces in the Directory’s Organization tab. The app re-fetches each periodically. | <AccordionGroup> <Accordion title="orgPluginSettings details"> Applies `toolPolicy` locks to MCP servers that arrive via the org-plugins directory, keyed by server name. Either shape is accepted; when hand-authoring a profile, use the legacy record shape until your fleet floor parses the canonical array form: - ```json theme={null} theme={null} theme={null} theme={null} theme={null} + ```json theme={null} {"mcpServers": {"internal-search": {"toolPolicy": {"delete_document": "blocked"}}}} ```
from line 719
</Accordion> <Accordion title="allowedPluginMarketplaces details"> - | Field | Type | Default | Description | - | ------------------------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | - | `source` | `string` | — | Where the marketplace is fetched from: a GitHub repository (set repo) or any Git remote (set url). One of: `github`, `git`. | - | `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 clones authenticate: anonymously, with the user’s git credentials, or via a helper executable. One of: `anonymous`, `userGit`, `credentialHelper`. | - | `credentialHelper` | `string` | — | Executable that prints an access token for this repository. | - | `url` | `string` | — | HTTPS Git remote URL for the marketplace repository. | + | 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. | </Accordion> </AccordionGroup>
third-party/claude-desktop/configuration Changed · +8 / -8 lines
from line 191
**The gateway MUST validate `iss` AND `aud`, not just the signature.** Signature + issuer alone accepts *any* token from the same tenant, including tokens issued to unrelated apps. In `id_token` mode the audience is the `clientId`: - ```yaml theme={null} theme={null} theme={null} theme={null} + ```yaml theme={null} theme={null} theme={null} theme={null} theme={null} # LiteLLM example — `audience` is REQUIRED, not optional general_settings: litellm_jwtauth:
from line 244
**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} theme={null} theme={null} theme={null} + ```json theme={null} theme={null} theme={null} theme={null} theme={null} [{"name": "claude-sonnet-5", "supports1m": true}, "claude-opus-4-8"] ``` **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} theme={null} theme={null} theme={null} + ```json theme={null} theme={null} theme={null} theme={null} theme={null} [{"name": "claude-opus-4-8", "supports1m": true, "prefer1m": true}] ``` **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} theme={null} theme={null} theme={null} + ```json theme={null} theme={null} theme={null} theme={null} 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} theme={null} theme={null} theme={null} + ```json theme={null} theme={null} theme={null} theme={null} theme={null} [{"name": "us.anthropic.claude-opus-4-8", "anthropicFamilyTier": "opus"}] ```
from line 703
<Accordion title="orgPluginSettings details"> Applies `toolPolicy` locks to MCP servers that arrive via the org-plugins directory, keyed by server name. Either shape is accepted; when hand-authoring a profile, use the legacy record shape until your fleet floor parses the canonical array form: - ```json theme={null} theme={null} theme={null} theme={null} + ```json theme={null} theme={null} theme={null} theme={null} theme={null} {"mcpServers": {"internal-search": {"toolPolicy": {"delete_document": "blocked"}}}} ```
from line 818
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 standing grants are offered. +* `"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 or grant a standing approval, depending on the tool and your organization's settings. Full prompt options require version 1.22209.0 or later; earlier third-party builds offered only per-call approval. The reference above also documents an `"ask-session"` value; its once-per-session behavior is not yet functional in shipped builds, so don't rely on it yet. 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 — works from an upcoming release, which also supersedes the Code-session wildcard-precedence note in the reference above. See the [`managedMcpServers` reference](#managedmcpservers) for wildcard matching, precedence rules, and built-in connector defaults. +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; it is accepted for compatibility and behaves exactly as `"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.
third-party/claude-desktop/configuration Changed · +18 / -18 lines
from line 28
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** (not a native plist/registry array) | `["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) | +| 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) | -<Warning> - The most common configuration mistake is writing array- or object-typed keys as native plist/registry structures. Keys like `inferenceModels`, `inferenceGatewayOidc`, `managedMcpServers`, `coworkEgressAllowedHosts`, and `otlpHeaders` must be **JSON strings**. In a `.mobileconfig`, that means a single `<string>` element containing `[...]` or `{...}` — not an `<array>`, not a `<dict>`, and not separate keys with dotted names like `inferenceGatewayOidc.clientId`. -</Warning> +<Note> + Array- and object-typed keys such as `inferenceModels`, `inferenceGatewayOidc`, `managedMcpServers`, `coworkEgressAllowedHosts`, and `otlpHeaders` are single keys whose value is a whole JSON document. The portable encoding is a JSON string, which works on every platform. In a `.mobileconfig` that is a single `<string>` element containing `[...]` or `{...}`, and on Windows a `REG_SZ` value. A macOS profile may instead carry the value as a native `<array>` or `<dict>`, which the app reads as the equivalent JSON. Separate keys with dotted names, such as `inferenceGatewayOidc.clientId`, are never read. +</Note> 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.
from line 191
**The gateway MUST validate `iss` AND `aud`, not just the signature.** Signature + issuer alone accepts *any* token from the same tenant, including tokens issued to unrelated apps. In `id_token` mode the audience is the `clientId`: - ```yaml theme={null} + ```yaml theme={null} theme={null} theme={null} theme={null} # LiteLLM example — `audience` is REQUIRED, not optional general_settings: litellm_jwtauth:
from line 244
**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} + ```json theme={null} theme={null} theme={null} theme={null} [{"name": "claude-sonnet-5", "supports1m": true}, "claude-opus-4-8"] ``` **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} + ```json theme={null} theme={null} theme={null} theme={null} [{"name": "claude-opus-4-8", "supports1m": true, "prefer1m": true}] ``` **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} + ```json theme={null} theme={null} theme={null} 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} + ```json theme={null} theme={null} theme={null} theme={null} [{"name": "us.anthropic.claude-opus-4-8", "anthropicFamilyTier": "opus"}] ```
from line 703
<Accordion title="orgPluginSettings details"> Applies `toolPolicy` locks to MCP servers that arrive via the org-plugins directory, keyed by server name. Either shape is accepted; when hand-authoring a profile, use the legacy record shape until your fleet floor parses the canonical array form: - ```json theme={null} + ```json theme={null} theme={null} theme={null} theme={null} {"mcpServers": {"internal-search": {"toolPolicy": {"delete_document": "blocked"}}}} ```
third-party/claude-desktop/configuration First recorded · 824 lines, first recorded
# Configuration reference ## How keys are read ### Value types ### Linux ## Reference ## Connection ### Anthropic ### Bedrock ### Foundry ### Gateway ### Models ### Vertex ## Workspace ### Authentication ### Chat surface ### Code surface ### Cowork surface ### Workspace ## Connectors ### Authentication ### Extensions ### MCP ## Telemetry & updates ### Auto update ### OTLP ## Limits ### Token limits ## Appearance ### Feature discovery ## Plugins ## Source ### Bootstrap ## Guides ### Recommended security profiles ### Tool permissions for managed MCP servers
The first capture of this source. The page was already there, and this is what it said.
# Configuration reference
> Every managed-configuration key Claude Desktop on 3P supports, what it controls, and recommended security profiles
<Tip>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.</Tip>
Claude Desktop on third-party (3P) is configured entirely through OS-native managed preferences: a `.mobileconfig` profile on macOS, registry policy on Windows, or a root-owned JSON file on Linux. 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/<user>/com.anthropic.claudefordesktop.plist` | `~/Library/Application Support/Claude-3p/configLibrary/` |
| Windows | `HKLM\SOFTWARE\Policies\Claude` (machine), `HKCU\SOFTWARE\Policies\Claude` (user) | `%LOCALAPPDATA%\Claude-3p\configLibrary\` |
| Linux | `/etc/claude-desktop/managed-settings.json` | `~/.config/Claude-3p/configLibrary/` |
The local location is a directory: `_meta.json` records which saved configuration is applied, and each configuration is a `<id>.json` file alongside it. The in-app configuration window writes here.
When a managed source is present, it wins and locally written values are ignored. The exception is a managed source that sets only the update keys (`disableAutoUpdates` and `autoUpdaterEnforcementHours`): those two keys are enforced from the managed source, but the rest of the configuration stays local and user-editable. Configuration is read **once at launch**, so fully quit and reopen the app after any change. 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.
<Note>
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.
</Note>
### 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** (not a native plist/registry array) | `["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) |
<Warning>
The most common configuration mistake is writing array- or object-typed keys as native plist/registry structures. Keys like `inferenceModels`, `inferenceGatewayOidc`, `managedMcpServers`, `coworkEgressAllowedHosts`, and `otlpHeaders` must be **JSON strings**. In a `.mobileconfig`, that means a single `<string>` element containing `[...]` or `{...}` — not an `<array>`, not a `<dict>`, and not separate keys with dotted names like `inferenceGatewayOidc.clientId`.
</Warning>
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.
## Connection
| Setting | Type | Availability | Default | Description |
| ------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | --------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <span id="inferencecustomheaders" />Custom inference headers<br />`inferenceCustomHeaders` | `object` | MDM + Bootstrap | — | Extra HTTP headers sent on every inference request to the configured provider. For tenant routing, org IDs, Bedrock Guardrails, etc. 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="inferencecredentialhelpertimeoutsec" />Credential helper timeout<br />`inferenceCredentialHelperTimeoutSec` | `integer` | MDM + Bootstrap | `60` | Maximum wait for the helper executable to finish. Raise this if the helper opens a browser for interactive sign-in. Defaults to `60`. Range: 1–600. |
| <span id="inferencecredentialhelpersilentrefreshenabled" />Re-run helper for silent refresh<br />`inferenceCredentialHelperSilentRefreshEnabled` | `boolean` | MDM + Bootstrap | `true` | On credential expiry, re-run the helper (CLAUDE\_HELPER\_CONTEXT=mid-session-refresh) to recover silently. Turn off if the helper can’t run non-interactively. Defaults to `true`. |
| <span id="usercontentrendererurl" />Artifact preview iframe origin<br />`userContentRendererUrl` | `string` | MDM + Bootstrap | — | HTTPS origin of the user-content-renderer deployment used for artifact and file previews. Defaults to the commercial host when unset. |
| <span id="inferenceprovider" />Inference provider<br />`inferenceProvider` | `enum` | MDM + Bootstrap | — | Selects the inference backend. Setting this key activates third-party mode. One of: `gateway`, `anthropic`, `bedrock`, `mantle`, `vertex`, `foundry`. |
| <span id="inferencecredentialkind" />Credential kind<br />`inferenceCredentialKind` | `enum` | MDM + Bootstrap | — | Selects the credential source. When set, only that source is used (no fallback). One of: `static`, `helper-script`, `interactive`, `vendor-profile`, `oauth`, `workforce`. |
<AccordionGroup>
<Accordion title="inferenceCustomHeaders details">
Sent on every inference and model-discovery request (joined into the CLI's `ANTHROPIC_CUSTOM_HEADERS`).
Use this for fleet-wide constants. 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).
</Accordion>
<Accordion title="inferenceCredentialHelper details">
Claude runs the executable with no arguments and reads **stdout** (trimmed). Exit code must be `0`; any output on **stderr** is logged but ignored. **Stdout must contain only one of the formats below** (no banners, prompts, or log lines).
**Output format** is either:
* a single bare token (the API key / bearer token), or
* a JSON object `{"token": "...", "headers": {"Name": "Value", ...}}` when per-request headers are needed (merged over **Custom inference headers**, helper wins on conflict)
The helper receives `CLAUDE_HELPER_CONTEXT` in its environment (`interactive`, `mid-session-refresh`, `background`, `scheduled-task`, `setup-test`) so it can decide whether to prompt the user — see the credential-helper docs for the full contract.
Result is cached for the TTL below. On TTL expiry the helper is re-invoked transparently (no user prompt, no relaunch).
**Expiry and refresh:** the app checks the active credential's expiry before each turn and refreshes silently when possible (re-runs the helper, or uses the stored refresh token for interactive sign-in kinds). If the provider returns HTTP 401 mid-turn, the same silent refresh is attempted before surfacing an error. When silent refresh fails, a prompt appears with a provider-specific action (re-sign-in for interactive kinds; admin-contact for static credentials). Applies to all providers, and to both Cowork and Code.
**Typical use:** a shell script that pulls from Keychain, 1Password CLI, or an internal secret broker. Example:
`security find-generic-password -s anthropic-api -w`
If this field is set, static credential fields (API key, bearer token) are ignored. The helper always wins.
</Accordion>
<Accordion title="inferenceProvider details">
The app activates 3P mode only when this is set and the required credential keys for the selected provider are present and valid; otherwise it launches in standard mode. Keys for providers other than the selected one are ignored. Each provider's required keys are documented on its dedicated page under Inference providers.
</Accordion>
</AccordionGroup>
### Anthropic
| Setting | Type | Availability | Default | Description |
| ------------------------------------------------------------------------------------ | -------- | --------------- | ------- | --------------------------------------------------------------------------------------------- |
| <span id="inferenceanthropicapikey" />Claude API key<br />`inferenceAnthropicApiKey` | `string` | MDM + Bootstrap | — | Leave blank to fetch a key via browser sign-in, or to supply the key via a credential helper. |
### Bedrock
| Setting | Type | Availability | Default | Description |
| ------------------------------------------------------------------------------------------------ | -------- | --------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
| <span id="inferencebedrockregion" />AWS region<br />`inferenceBedrockRegion` | `string` | MDM + Bootstrap | — | AWS region for the Bedrock runtime endpoint. |
| <span id="inferencebedrockbaseurl" />Bedrock base URL<br />`inferenceBedrockBaseUrl` | `string` | MDM + Bootstrap | — | For VPC endpoints or gateway proxies. Host origin only. |
| <span id="inferencebedrockservicetier" />Bedrock service tier<br />`inferenceBedrockServiceTier` | `enum` | MDM + Bootstrap | — | Sent as the X-Amzn-Bedrock-Service-Tier header. Leave unset for on-demand. One of: `flex`, `priority`. |
| <span id="inferencebedrockbearertoken" />AWS bearer token<br />`inferenceBedrockBearerToken` | `string` | MDM + Bootstrap | — | Static bearer token for inference. For providers that support profile or helper-script credentials, prefer those. |
| <span id="inferencebedrockssostarturl" />AWS SSO start URL<br />`inferenceBedrockSsoStartUrl` | `string` | MDM + Bootstrap | — | Enables in-app AWS sign-in (no AWS CLI needed). Set with the three SSO fields below. |
| <span id="inferencebedrockssoregion" />AWS SSO region<br />`inferenceBedrockSsoRegion` | `string` | MDM + Bootstrap | — | IAM Identity Center home region. |
| <span id="inferencebedrockssoaccountid" />AWS SSO account ID<br />`inferenceBedrockSsoAccountId` | `string` | MDM + Bootstrap | — | 12-digit AWS account ID assigned to users in IAM Identity Center. |
| <span id="inferencebedrockssorolename" />AWS SSO role name<br />`inferenceBedrockSsoRoleName` | `string` | MDM + Bootstrap | — | IAM Identity Center permission-set name granting bedrock:InvokeModel\* on the account above. |
| <span id="inferencebedrockprofile" />AWS profile name<br />`inferenceBedrockProfile` | `string` | MDM + Bootstrap | — | AWS named profile to use for Bedrock inference credentials. |
| <span id="inferencebedrockawsdir" />AWS config directory<br />`inferenceBedrockAwsDir` | `string` | MDM + Bootstrap | — | Folder with AWS config/credentials. Defaults to \~/.aws when no bearer token is set. |
| <span id="inferencebedrockawsclipath" />AWS CLI path<br />`inferenceBedrockAwsCliPath` | `string` | MDM + Bootstrap | — | Absolute path to the aws executable. Leave unset to find it on PATH. |
<AccordionGroup>
<Accordion title="inferenceBedrockServiceTier details">
Tier availability varies by model and region. Reserved capacity uses a provisioned-throughput ARN as the model ID instead of this setting. Older bundled Claude Code CLI versions ignore this key.
</Accordion>
</AccordionGroup>
### Foundry
| Setting | Type | Availability | Default | Description |
| ---------------------------------------------------------------------------------------------------- | -------- | --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| <span id="inferencefoundryresource" />Azure AI Foundry resource name<br />`inferenceFoundryResource` | `string` | MDM + Bootstrap | — | Azure AI Foundry resource name used to construct the endpoint URL. |
| <span id="inferencefoundryapikey" />Azure AI Foundry API key<br />`inferenceFoundryApiKey` | `string` | MDM + Bootstrap | — | API key for Azure AI Foundry inference. |
| <span id="inferencefoundrytenantid" />Entra ID tenant ID<br />`inferenceFoundryTenantId` | `string` | MDM + Bootstrap | — | Directory (tenant) ID of the Entra ID app registration that has the Cognitive Services scope. |
| <span id="inferencefoundryclientid" />Entra ID client ID<br />`inferenceFoundryClientId` | `string` | MDM + Bootstrap | — | Application (client) ID of the Entra ID app registration. Device-code sign-in requires the app to allow public client flows. |
| <span id="inferencefoundryauthflow" />Entra ID sign-in flow<br />`inferenceFoundryAuthFlow` | `enum` | MDM + Bootstrap | — | How Entra sign-in runs: device code (default), system browser, or the OS identity broker. One of: `device-code`, `browser`, `broker`. |
<AccordionGroup>
<Accordion title="inferenceFoundryAuthFlow details">
* **`device-code`** (default) — shows a code to enter at microsoft.com/devicelogin. The app registration must have **Allow public client flows** enabled.
* **`browser`** — opens the system browser for an authorization-code (PKCE) sign-in on a loopback redirect URI. The app registration must include `http://127.0.0.1/callback` under the **Mobile and desktop applications** platform (Entra ignores the loopback port, but not the path). Works with **Allow public client flows** disabled, and is unaffected by Conditional Access policies that block device-code authentication.
* **`broker`** — signs in through the OS identity broker (Web Account Manager on Windows, Company Portal on macOS), so it can satisfy Conditional Access policies that require a compliant/managed device or token protection. The app registration must include the broker redirect URIs `ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}` (Windows) and `msauth.com.anthropic.claudefordesktop://auth` (macOS) under the **Mobile and desktop applications** platform. Not supported on Linux.
App versions that predate this key always use device code; versions that predate the broker option treat `broker` as unset and use device code.
</Accordion>
</AccordionGroup>
### Gateway
| Setting | Type | Availability | Default | Description |
| -------------------------------------------------------------------------------------------------- | -------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| <span id="inferencegatewaybaseurl" />Gateway base URL<br />`inferenceGatewayBaseUrl` | `string` | MDM + Bootstrap | — | Full URL of the inference gateway endpoint. |
| <span id="inferencegatewayapikey" />Gateway API key<br />`inferenceGatewayApiKey` | `string` | MDM + Bootstrap | — | API key for the configured inference gateway. |
| <span id="inferencegatewayauthscheme" />Gateway auth scheme<br />`inferenceGatewayAuthScheme` | `enum` | MDM + Bootstrap | `bearer` | How the gateway credential is sent on the wire (Authorization: Bearer vs x-api-key header). One of: `bearer`, `x-api-key`. Defaults to `bearer`. |
| <span id="inferencegatewayoidcauthflow" />Gateway sign-in flow<br />`inferenceGatewayOidcAuthFlow` | `enum` | MDM + Bootstrap | — | How the IdP sign-in runs: system browser (default) or the OS Microsoft Entra broker. One of: `browser`, `broker`. |
| <span id="inferencegatewayoidc" />Gateway SSO IdP (OIDC)<br />`inferenceGatewayOidc` | `object` | MDM + Bootstrap | — | External IdP for gateway sign-in. The user’s token from this issuer is sent to the gateway as the Bearer credential. |
<AccordionGroup>
<Accordion title="inferenceGatewayOidcAuthFlow details">
* **`browser`** (default) — opens the system browser for an authorization-code (PKCE) sign-in on a loopback redirect URI. See the **IdP setup** notes on `inferenceGatewayOidc` for redirect-URI registration.
* **`broker`** — signs in through the OS identity broker (Web Account Manager on Windows, Company Portal on macOS). Requires the IdP to be **Microsoft Entra ID** — the `issuer` on `inferenceGatewayOidc` must be `https://login.microsoftonline.com/{tenant-id}/v2.0`. The broker satisfies Conditional Access policies that require a compliant/managed device or token protection, and needs no `127.0.0.1/callback` loopback redirect. The Entra app registration must include the broker redirect URIs `ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}` (Windows) and `msauth.com.anthropic.claudefordesktop://auth` (macOS) under the **Mobile and desktop applications** platform. Not supported on Linux.
Broker mode mints a token in the customer's own Entra tenant with the customer-configured `scopes`, and forwards it to the customer's own gateway; both endpoints of that trust relationship are inside the customer's control.
</Accordion>
<Accordion title="inferenceGatewayOidc details">
**External IdP mode.** The app discovers `<issuer>/.well-known/openid-configuration`, runs an OIDC authorization-code-with-PKCE flow in the system browser with `clientId`, and sends the resulting token as `Authorization: Bearer` on every inference request — see **Bearer token type** below for how the gateway validates it.
**Bearer token type.** `id_token` (the default) sends the OIDC ID token — the gateway validates signature + `iss` + `aud`, where `aud` is the `clientId` configured here. `access_token` sends the OAuth access token — the gateway validates as an OAuth resource server against the audience/scope the IdP issued the token for; set `scopes` to the gateway's registered API scope (required in this mode). Use `access_token` for gateways that expect a resource-server token (Portkey, Kong, Envoy JWT filter, AWS API Gateway authorizers).
**The gateway MUST validate `iss` AND `aud`, not just the signature.** Signature + issuer alone accepts *any* token from the same tenant, including tokens issued to unrelated apps. In `id_token` mode the audience is the `clientId`:
```yaml theme={null}
# LiteLLM example — `audience` is REQUIRED, not optional
general_settings:
litellm_jwtauth:
public_key_url: https://login.microsoftonline.com/<tenant>/discovery/v2.0/keys
audience: <clientId> # ⚠ omitting this accepts any token from the tenant
```
**IdP setup.** The app's loopback callback binds `http://127.0.0.1:<port>/callback` (RFC 8252 §7.3). Register `127.0.0.1`; most IdPs do **not** treat `localhost` and `127.0.0.1` as interchangeable. **Entra:** register a public-client app, add a *Mobile and desktop applications* redirect URI of `http://127.0.0.1/callback`. (Microsoft's docs say the path is wildcarded for loopback; in practice it is not: `http://127.0.0.1` without `/callback` fails with `AADSTS50011`. The port IS wildcarded.) Grant `openid profile email offline_access` (delegated, no admin consent); in `access_token` mode **also** add the gateway API's delegated permission under *API permissions* (and ensure the gateway's own app registration exposes that scope via *Expose an API*) — without it Entra rejects the sign-in with `AADSTS65001`. **Okta:** register a *Native* app with the exact redirect URI `http://127.0.0.1:<port>/callback` and set `redirectPort` here to that port (Okta requires an exact match).
**Refresh:** `offline_access` returns a refresh token; the app refreshes the bearer silently before expiry. When refresh fails (revoked, idle past the IdP's window), the user re-authenticates in the browser. **Google Workspace caveat (`id_token` mode only):** Google never returns `id_token` on a refresh-token grant, so a Google-backed gateway in `id_token` mode will prompt a browser sign-in roughly once per ID-token TTL (\~1h). Entra and Okta return a fresh `id_token` and are unaffected; `access_token` mode is unaffected on all IdPs.
**Leave this unset** for a gateway that hosts its own RFC 8414 metadata at `<baseUrl>/.well-known/oauth-authorization-server` (the original gateway-as-AS path).
| Field | Type | Default | Description |
| --------------------------------- | --------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientId` | `string` | — | OAuth client ID of the desktop app registration at your identity provider (public client, PKCE). |
| `issuer` | `string` | — | HTTPS issuer with OIDC discovery. Set this, or set the authorization and token URLs instead. |
| `authorizationUrl` | `string` | — | HTTPS authorization endpoint. Used with the token URL when no issuer is set. |
| `tokenUrl` | `string` | — | HTTPS token endpoint. Used with the authorization URL when no issuer is set. |
| `bearerTokenType` | `enum` | `id_token` | Which token to send as the gateway bearer. Use access token for gateways that validate as an OAuth resource server. One of: `id_token`, `access_token`. |
| `scopes` | `string` | — | Space-separated scopes. Required in access-token mode: set the gateway’s API scope. offline\_access is appended automatically unless disabled below. |
| `appendOfflineAccess` | `boolean` | `true` | Automatically append offline\_access to scopes so the IdP returns a refresh token for silent refresh. |
| `resource` | `string` | — | Absolute URL identifying the gateway as the access-token audience. Sent as the RFC 8707 resource parameter when set; leave unset for Microsoft Entra ID. |
| `redirectPort` | `integer` | — | Fixed loopback port for the sign-in redirect ([http://127.0.0.1:PORT/callback](http://127.0.0.1:PORT/callback)). Leave unset to use a free port each time. |
| `additionalRedirectReferrerHosts` | `string` | — | Space-separated hostnames also accepted as the referrer of the sign-in callback. Only needed when the IdP completes sign-in from a different host. |
</Accordion>
</AccordionGroup>
### 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. |
<AccordionGroup>
<Accordion title="modelDiscoveryEnabled details">
Auto-populate the model picker from the provider's model-list endpoint at launch. For gateway and Anthropic providers, a config that doesn't set this key skips discovery automatically when the model list below already makes it unnecessary; the toggle here only sets it explicitly on or off. Turn off if the endpoint isn't reachable from your network, or to use a fixed list. When off, the model list below is required and must use full model IDs (aliases like sonnet/opus are resolved via discovery).
</Accordion>
<Accordion title="modelPrefer1mContext details">
When a user has no saved selection, start the picker on the 1M-context variant of the default model (the first listed model, or the first model your endpoint returns under discovery) if it offers one. A saved selection is always kept; users who picked a model before this version need to pick the 1M row once, after which it persists. Equivalent to setting `prefer1m` on the default entry of `inferenceModels`, but also applies under dynamic discovery.
</Accordion>
<Accordion title="inferenceModels details">
Use the **provider's exact model ID**: Vertex publisher IDs (`claude-sonnet-5`), Bedrock inference-profile IDs (`us.anthropic.claude-sonnet-5`), or Foundry deployment names. The first entry is the default. 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"]
```
**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}
[{"name": "claude-opus-4-8", "supports1m": true, "prefer1m": true}]
```
**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. |
</Accordion>
</AccordionGroup>
### Vertex
| Setting | Type | Availability | Default | Description |
| ------------------------------------------------------------------------------------------------------------------------------ | -------- | --------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| <span id="inferencevertexprojectid" />GCP project ID<br />`inferenceVertexProjectId` | `string` | MDM + Bootstrap | — | Google Cloud project ID for Vertex AI inference. |
| <span id="inferencevertexregion" />GCP region<br />`inferenceVertexRegion` | `string` | MDM + Bootstrap | — | GCP region where your Vertex AI Claude models are deployed. |
| <span id="inferencevertexbaseurl" />Vertex AI base URL<br />`inferenceVertexBaseUrl` | `string` | MDM + Bootstrap | — | PSC endpoint, if using one. |
| <span id="inferencevertexoauthclientid" />Vertex OAuth client ID<br />`inferenceVertexOAuthClientId` | `string` | MDM + Bootstrap | — | Desktop-app OAuth client ID. Enables Sign in with Google instead of a credentials file. |
| <span id="inferencevertexoauthclientsecret" />Vertex OAuth client secret<br />`inferenceVertexOAuthClientSecret` | `string` | MDM + Bootstrap | — | Secret for the Desktop-app OAuth client above. |
| <span id="inferencevertexoauthscopes" />Vertex OAuth scopes<br />`inferenceVertexOAuthScopes` | `string` | MDM + Bootstrap | — | Override the Google OAuth scopes (space-separated). Leave blank for the default. |
| <span id="inferencevertexoauthloginhint" />Vertex OAuth login hint<br />`inferenceVertexOAuthLoginHint` | `string` | MDM + Bootstrap | — | Pre-fill Google's account chooser and forward to your federated IdP. \{username} expands to the OS login name. |
| <span id="inferencevertexworkforceaudience" />Workforce Identity audience<br />`inferenceVertexWorkforceAudience` | `string` | MDM + Bootstrap | — | Workforce-pool provider audience. When set, sign-in uses your own IdP plus a GCP STS exchange instead of a Google identity. |
| <span id="inferencevertexworkforceuserproject" />Workforce Identity billing project<br />`inferenceVertexWorkforceUserProject` | `string` | MDM + Bootstrap | — | GCP project for STS billing and quota. Defaults to the Vertex project ID above. |
| <span id="inferencevertexworkforceauthflow" />Workforce Identity sign-in flow<br />`inferenceVertexWorkforceAuthFlow` | `enum` | MDM + Bootstrap | — | How the IdP sign-in runs: system browser (default) or the OS Microsoft Entra broker. One of: `browser`, `broker`. |
| <span id="inferencevertexworkforceoidc" />Workforce Identity IdP (OIDC)<br />`inferenceVertexWorkforceOidc` | `object` | MDM + Bootstrap | — | Your organization’s OIDC IdP. The app runs an authorization-code-with-PKCE flow against this issuer and exchanges the returned ID token at GCP STS. |
| <span id="inferencevertexcredentialsfile" />GCP credentials file path<br />`inferenceVertexCredentialsFile` | `string` | MDM + Bootstrap | — | Absolute path to service-account JSON. Leave blank to fall back to ADC. |
<AccordionGroup>
<Accordion title="inferenceVertexWorkforceAuthFlow details">
* **`browser`** (default) — opens the system browser for an authorization-code (PKCE) sign-in on a loopback redirect URI. See the **IdP setup** notes on `inferenceGatewayOidc` for redirect-URI registration; the same rules apply here.
* **`broker`** — signs in through the OS identity broker (Web Account Manager on Windows, Company Portal on macOS). Requires the workforce-pool IdP to be **Microsoft Entra ID** — the `issuer` on `inferenceVertexWorkforceOidc` must be `https://login.microsoftonline.com/{tenant-id}/v2.0`. The broker satisfies Conditional Access policies that require a compliant/managed device or token protection, and needs no `127.0.0.1/callback` loopback redirect. The Entra app registration must include the broker redirect URIs `ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}` (Windows) and `msauth.com.anthropic.claudefordesktop://auth` (macOS) under the **Mobile and desktop applications** platform. Not supported on Linux.
Cut at 300 lines.