Home Docs Claude Documentation 4 Sep 2026

One change · claude-docs

Configuration reference changedthird-party/claude-desktop/configuration

Nearest release: v2.1.260, published 4 hours before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.

Recorded here 4 Sep 2026 02:37 UTC

Lines+72added

Lines−44removed

From line 116 where the diff opens

First seen 14 Aug 2026 this site's first read of the page

Recorded edits50to this page, all time

The whole hunk

from line 116, old and new numbered

lines

from line 116

116116 </Accordion>

117117

118118 <Accordion title="egressProxyUrl details">

119 Pins the app (sign-in, the connection test, model discovery, MCP servers, plugins), the Claude Code engine behind Chat, Cowork, and Code, and on macOS and Windows the Cowork workspace VM (the agent's shell, package-install, `git`, and plugin commands, and the whole engine under `requireFullVmSandbox`) to one HTTP proxy. Use it when your gateway or the internet is reachable only through a corporate proxy and you cannot rely on the system proxy. It is a reachability setting, not an egress control.

119 Pins the app (sign-in, the connection test, model discovery, MCP servers, plugins), the Claude Code engine behind Chat, Cowork, and Code, and on macOS and Windows the Cowork workspace VM (the agent's shell, package-install, `git`, and plugin commands, and the whole engine under `requireCoworkFullVmSandbox`) to one HTTP proxy. Use it when your gateway or the internet is reachable only through a corporate proxy and you cannot rely on the system proxy. It is a reachability setting, not an egress control.

120120

121121 The value is an `http://` or `https://` URL, usually with a port. SOCKS proxies and embedded credentials (`user:pass@`) are rejected. Give a local forwarding proxy on the device as `http://127.0.0.1:port`; an `https://` loopback address cannot be verified from inside the Cowork workspace VM. Requests to `localhost`, `127.0.0.1`, `[::1]`, and `*.local` names bypass the proxy so local MCP servers keep working; everything else goes through it, and if the proxy is unreachable requests fail rather than connect directly. The engine receives it as `HTTPS_PROXY` and `HTTP_PROXY` with a matching `NO_PROXY`; if Claude Code managed settings on the device set those variables, they win for the engine on the host. Traffic that never uses this proxy: the Cowork workspace VM on Linux, credential and header helper scripts, the update download, the Windows sign-in broker, and pages opened in the system browser.

122122

from line 359

360360| ---------------------------------------------------------------------------------------------------------------- | --------- | --------------- | ------- | -------------------------------------------------------------------------------------------------------------------- |

363363

364364### Chat surface

365365

from line 380

380380| ------------------------------------------------------------------------------------------ | ---------- | ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |

383384

384385<AccordionGroup>

385386 <Accordion title="sshHostAllowlist details">

from line 392

391392

392393 If this key is unset, an `sshHostAllowlist` in Claude Code's own managed-settings file on the device still applies; when both are set, this key wins where the app's configuration is admin-managed (MDM, the admin console, or a device-managed bootstrap URL) and otherwise applies only while that file sets none. `allowedWorkspaceFolders` still applies on the remote host.

393394 </Accordion>

395

396 <Accordion title="sshClientPath details">

397 Pins which OpenSSH client the app runs wherever it starts `ssh`: evaluating the user's SSH configuration (`ssh -G`), making the SSH connection and its channels, and the Code tab's terminal. `ssh-keygen` and `ssh-add` are taken from the same directory when they exist there, otherwise from PATH. The program must be OpenSSH 7.6 or newer; on macOS and Linux a wrapper script that ends in one is accepted, on Windows it must be a native `.exe` (not a .cmd, .bat or .ps1 script). When this key is set and the program is missing, cannot be run, or is too old, SSH sessions fail with an error telling the user to ask their IT administrator (the configured path is in its details) — the app never falls back to another ssh. On Windows, where SSH connections do not yet run through an ssh program, the key currently affects configuration evaluation and the terminal only.

398 </Accordion>

394399</AccordionGroup>

395400

396401### Cowork surface

from line 406

401406

402407### Workspace

403408

405| -------------------------------------------------------------------------------------------------------------------- | ---------- | ---------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

411| Built-in tool policy `builtinToolPolicy` | `object` | MDM + Bootstrap | — | Approval policy per built-in tool or argument-scoped rule such as Bash(curl \*). “ask” requires user approval before each matching call; “allow” is the default. Deprecated: `builtinToolPolicy: "ask-session"` (accepted until October 7, 2026); use "ask". If it is still present after that, the entry will be read as "ask" (approval on every call), like any unrecognized value. |

410| ----------------------------------------------------------------------------------------------------------------------------------- | ---------- | ---------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

416| Built-in tool policy `builtinToolPolicy` | `object` | MDM + Bootstrap | — | Approval policy per built-in tool or argument-scoped rule such as Bash(curl \*). “ask” requires user approval before each matching call; “allow” is the default. Deprecated: `builtinToolPolicy: "ask-session"` (accepted until October 7, 2026); use "ask". If it is still present after that, the entry will be read as "ask" (approval on every call), like any unrecognized value. |

422| Block reads outside working directories `blockReadsOutsideWorkingDirectories` | `boolean` | MDM + Bootstrap | — | Keep Claude from reading files outside a Code session’s working directories. File tools refuse such reads; sandboxed shell commands lose the home directory. |

419426

420427<AccordionGroup>

421428 <Accordion title="userPluginMarketplacesEnabled details">

from line 444

437444 <Accordion title="disabledBuiltinTools details">

438445 Each entry is a Claude Code tool name (`Bash`, `Read`, `Write`, `Edit`, `Glob`, `Grep`, `NotebookEdit`, `WebFetch`, `WebSearch`, `Task`, `TodoWrite`, `TaskCreate`, `TaskUpdate`, `TaskGet`, `TaskList`, `TaskStop`, `Skill`, `REPL`, `JavaScript`, `AskUserQuestion`, `ToolSearch`, `SendUserMessage`) or an argument-scoped [permission rule](https://code.claude.com/docs/en/permissions#permission-rule-syntax) such as `Bash(curl *)` or `Edit(**/*.env)`. A bare name covers every call; a scoped rule covers matching calls in every permission mode, including Auto and bypass. Scopes are matched for `Bash(…)` (a command pattern) and for file paths written as `Read(…)` (covers `Read`, `Grep`, `Glob`) or `Edit(…)` (covers `Edit`, `Write`, `NotebookEdit`); other tools take `Tool(<field>:<pattern>)`. `WebSearch` and `WebFetch` are bare-name only: per-host web access is `coworkEgressAllowedHosts`.

439446

440 Scoped `Bash(…)` rules apply in Code sessions and in VM-sandboxed Cowork sessions (`requireFullVmSandbox`); Cowork's own sandboxed shell honors bare names only. Anchor file patterns with `**/` (`Read(**/secrets/**)`), because in the VM sandbox a host absolute path does not match. Scoped rules need a build that supports them across the whole fleet (`disableAutoUpdates` pins builds): an older build passes a scoped entry to Claude Code unchecked. An entry whose pattern contains `)` followed by a space or comma is enforced only through Claude Code's managed-settings channel, so another Claude Code [managed-settings source](https://claude.com/docs/third-party/claude-desktop/code#interaction-with-claude-code%E2%80%99s-own-managed-settings) replaces it unless that source sets `parentSettingsBehavior` to `"merge"`; every other entry is enforced either way.

447 Scoped `Bash(…)` rules apply in Code sessions and in VM-sandboxed Cowork sessions (`requireCoworkFullVmSandbox`); Cowork's own sandboxed shell honors bare names only. Anchor file patterns with `**/` (`Read(**/secrets/**)`), because in the VM sandbox a host absolute path does not match. Scoped rules need a build that supports them across the whole fleet (`disableAutoUpdates` pins builds): an older build passes a scoped entry to Claude Code unchecked. An entry whose pattern contains `)` followed by a space or comma is enforced only through Claude Code's managed-settings channel, so another Claude Code [managed-settings source](https://claude.com/docs/third-party/claude-desktop/code#interaction-with-claude-code%E2%80%99s-own-managed-settings) replaces it unless that source sets `parentSettingsBehavior` to `"merge"`; every other entry is enforced either way.

441448

442449 An unusable entry (a lowercase tool name, an unbalanced parenthesis, a scoped `WebSearch(…)` or `WebFetch(…)`) is kept, because the deny list is served exactly as written, and raises a configuration warning.

443450 </Accordion>

from line 469

462469 In Code sessions, a separately deployed Claude Code [managed-settings](https://claude.com/docs/third-party/claude-desktop/code#interaction-with-claude-code%E2%80%99s-own-managed-settings) file that sets `disableAutoMode` to `"disable"` overrides this key and keeps Auto mode hidden.

463470 </Accordion>

464471

472 <Accordion title="disableBypassPermissionsMode details">

473 When set to `true`, sessions cannot run in bypass permissions mode: the app stops offering the mode in Code and Cowork, and a session that requests it anyway is downgraded. This is the `disableBypassPermissionsMode` setting from the `permissions` section of Claude Code's [managed settings](https://claude.com/docs/third-party/claude-desktop/code#interaction-with-claude-code%E2%80%99s-own-managed-settings); a separately deployed Claude Code managed-settings file that sets it to `"disable"` also removes the mode, whichever source sets it.

474

475 Unset (default): users the deployment otherwise allows can choose bypass permissions mode.

476 </Accordion>

477

465478 <Accordion title="toolSearchEnabled details">

466479 When enabled, Cowork, Code, and Chat sessions place only tool names in context up front, and Claude fetches a tool's full schema the first time it needs it. Use this when many MCP tools are configured and their inlined schemas crowd out the context window (sessions that compact every turn or two). Enable it only if your endpoint forwards and accepts the request shape it will receive; when it does not, requests fail with HTTP 400. Leave unset to keep the conservative default.

467480

from line 500

488501 </Accordion>

489502

503 <Accordion title="blockReadsOutsideWorkingDirectories details">

504 When set to `true`, Code sessions refuse reads outside their working directories (the session folder plus any `allowedWorkspaceFolders`). The file tools (Read, Grep, Glob) refuse them in every permission mode; where Claude Code's sandbox runs (macOS, or Linux and SSH hosts with bubblewrap, once `allowedWorkspaceFolders` or an egress allowlist is also configured) shell commands cannot see the home directory and other user folders (`/Users`, `/home`, mounted volumes) and a read there is refused with no prompt; elsewhere (Windows, Linux without bubblewrap, or neither folders nor an egress allowlist configured) such shell reads prompt for approval. The app keeps the user's git configuration files (which may themselves embed credentials such as URL tokens; a symlinked one stays hidden), its own Claude Code installation, and the session's plugin and attachment folders readable (not on a Windows SSH host, where plugin files and attachments stay out of the file tools' reach under the block). An allowed folder that is or contains the home directory leaves it readable.

505

506 Users can re-open folders (even their whole home) in their own Claude Code settings with `sandbox.filesystem.allowRead` or `permissions.additionalDirectories`; settings files tracked in a git repository cannot. The key travels on Claude Code's managed-settings channel: another Claude Code managed-settings source replaces it unless that source sets `parentSettingsBehavior` to `"merge"`, and one that sets `sandbox.filesystem.allowManagedReadPathsOnly` reduces it to approval prompts. This is `permissions.blockReadsOutsideWorkingDirectories` in Claude Code's [managed settings](https://claude.com/docs/third-party/claude-desktop/code#interaction-with-claude-code%E2%80%99s-own-managed-settings).

507

508 Unset (default): nothing changes.

509 </Accordion>

510

490511 <Accordion title="coworkEgressAllowedHosts details">

491512 Applies to **both** Cowork and Code, and only to **tool calls**. In Cowork it governs the sandbox's web fetch, shell commands, and package installs; in Code sessions it is [translated into Claude Code's network sandbox allowlist](https://claude.com/docs/third-party/claude-desktop/code#applied-as-managed-policy), where a separately deployed Claude Code managed-settings file takes precedence by default. It does **not** cover Web Search (which runs at your inference provider), inference, or MCP traffic. When unset, only the inference endpoint is reachable from the sandbox, so the agent's package installs and web fetches fail with a 403.

492513

493514 Entries are exact hostnames (`api.github.com`), wildcards (`*.corp.com` matches subdomains at any depth, not `corp.com` itself), or `*` to allow all. IP addresses match only when listed exactly. `localhost` and private-network addresses are always blocked for web fetch; shell commands and package installs run in a network sandbox that reaches only the listed hosts plus your inference provider. With `*`, that sandbox is disabled and web fetch still blocks private addresses.

494515

495 Any entry except bare `*` may carry a `:port` suffix (`internal.corp.com:8443`, `*.corp.com:8443`) restricting it to that port. IPv6 literals are not supported. An invalid entry is dropped (with a warning in the app log) and the rest keep working. Ports are enforced for the Cowork sandbox's web fetch, shell, and package-install egress; plugin CLIs ignore port-scoped entries for now, and the Code translation treats them as the bare host. Deploy port-scoped entries only once your whole fleet is on a build that supports them (`disableAutoUpdates` pins builds): on an older build one such entry invalidates the sandbox's whole shell and package-install allowlist for the session.

516 Any entry except bare `*` may carry a `:port` suffix (`internal.corp.com:8443`, `*.corp.com:8443`) restricting it to that port. IPv6 literals are not supported. An invalid entry is dropped (with a warning in the app log) and the rest keep working; an unreadable value counts as an empty list. Ports are enforced for the Cowork sandbox's web fetch, shell, and package-install egress; plugin CLIs ignore port-scoped entries for now, and the Code translation treats them as the bare host. Deploy port-scoped entries only once your whole fleet is on a build that supports them (`disableAutoUpdates` pins builds): on an older build one such entry invalidates the sandbox's whole shell and package-install allowlist for the session.

496517

497518 Listed hosts also need to be open on your network firewall.

498519 </Accordion>

from line 535

514535

515536<AccordionGroup>

516537 <Accordion title="claudeAiImport details">

518 | ------------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

522 | `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`. |

539 | -------------------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

543 | `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`. |

523544 </Accordion>

524545</AccordionGroup>

525546

from line 658

637658 <Accordion title="disableEssentialTelemetry details">

638659 "Essential" means the signals Anthropic needs to keep your deployment working: **crash stacks**, **startup failure reasons**, and **version/OS metadata**. No prompts, completions, file contents, or identifiers beyond a random install ID.

639660

640 **What you lose when this is on:** when a Cowork build hits a bug that only reproduces on your OS version or locale, Anthropic can't see it unless a user manually reports. Fixes ship slower.

661 **What you lose when this is on:** when a Claude Desktop build hits a bug that only reproduces on your OS version or locale, Anthropic can't see it unless a user manually reports. Fixes ship slower.

641662

642663 **Why this is discouraged, not blocked:** some air-gapped environments require zero outbound telemetry as a matter of policy. The switch exists for them. If you don't have that constraint, leave it off.

643664 </Accordion>

from line 680

659680

660681### Auto update

661682

663| ---------------------------------------------------------------------------------------------------------- | --------- | --------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |

684| ---------------------------------------------------------------------------------------------------------- | --------- | --------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- |

667688

668689<AccordionGroup>

669690 <Accordion title="autoUpdaterEnforcementHours details">

from line 702

681702

682703### Configuration updates

683704

685| --------------------------------------------------------------------------------------------------- | --------- | -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

686| Configuration relaunch window `relaunchEnforcementHours` | `integer` | Bootstrap only | `1` | Hours a user may keep working on the old configuration after a served configuration change. 0 = restart required at once. Blank = 1 hour. Defaults to `1`. Range: 0–336. |

706| ------------------------------------------------------------------------------------------------------------- | --------- | --------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

707| Configuration relaunch window `relaunchEnforcementHours` | `integer` | MDM + Bootstrap | `24` | Hours a user may keep working on the old configuration after a managed-configuration change is detected. 0 = restart required at once. Blank = 24 hours. Defaults to `24`. Range: 0–336. |

687709

688710<AccordionGroup>

689711 <Accordion title="relaunchEnforcementHours details">

690 Served by your configuration endpoint (remote bootstrap configuration); not read from MDM (plist, registry, or file). When the running app observes a served change it cannot apply without restarting, it shows the sidebar relaunch card and starts this window. When the window ends the app blocks with a restart dialog and restarts on its own after 2 minutes with no activity (no running Claude task and no keyboard or pointer input); the user can also restart right away. Defaults to 1 hour. Set a larger value (up to 336 = 14 days) to give users longer; `0` shows the dialog at the first observation.

712 Set it via MDM (plist, registry, or file) or serve it from your configuration endpoint (remote bootstrap configuration). When the running app observes a managed-configuration change it cannot apply without restarting, it shows the sidebar relaunch card and starts this window. The window starts at the running app’s next configuration re-check (the re-check interval beside it), so allow up to one re-check interval on top of this value between saving a change and the restart dialog. When the window ends the app blocks with a restart dialog and restarts on its own after 2 minutes with no activity (no running Claude task and no keyboard or pointer input); the user can also restart right away. Defaults to 24 hours. Set a larger value (up to 336 = 14 days) to give users longer; `0` shows the dialog at the first observation.

691713

692 Read from the newest served configuration, so tightening or loosening the window takes effect at the next poll without a restart, and a change to this key alone never asks for one. Changes delivered only through MDM are read at launch and are not detected while the app runs, which is why an MDM value for this key is ignored with a warning rather than honored.

714 A served value is read from the newest served configuration, so tightening or loosening the window takes effect at the next poll without a restart, and a change to this key alone never asks for one. Like the update keys beside it, a value from a device-management profile that sets only app-behavior keys applies without making the rest of the configuration device-managed, and takes precedence over a served one. Because the key is grouped with the other app-behavior keys, a profile that sets any of them claims the whole group: set this key in the same profile as the update keys you deploy, or a served value is ignored on those devices and the 24-hour default applies.

693715 </Accordion>

716

717 <Accordion title="configRecheckIntervalMinutes details">

718 How often the running app re-checks its managed configuration for changes: it re-polls your configuration endpoint with a conditional request, so an unchanged configuration costs one `304` round-trip. A detected change shows the sidebar relaunch card and starts the `relaunchEnforcementHours` window, so a saved change reaches a running app within roughly one interval. Defaults to 10 minutes; each wait is jittered by ±10% so a fleet does not poll in lockstep. Values outside 2–30 are rejected with a parse error and the default applies.

719

720 Applied without a restart: a new served value re-arms the timer at the check that delivers it, and a change to this key alone never asks for a relaunch. Set it via MDM or serve it from your configuration endpoint; like the update keys beside it, a value from a device-management profile that sets only app-behavior keys applies without making the rest of the configuration device-managed, and takes precedence over a served one. Because the key is grouped with the other app-behavior keys, a profile that sets any of them claims the whole group, and every key in it is then read from that profile alone: deploy this key in the same profile as the update keys (`disableAutoUpdates`, `autoUpdaterEnforcementHours`, …). A profile that sets the update keys without it ignores a served interval and the default applies; a profile that sets only this key ignores served update settings, so a served `disableAutoUpdates` no longer holds on those devices. A profile that also manages the connection itself (sets `bootstrapUrl` or the provider keys) follows the normal tier order instead: once a served configuration is in hand it, not the profile, supplies this key.

721 </Accordion>

694722</AccordionGroup>

695723

696724### OTLP

from line 725

697725

699727| --------------------------------------------------------------------------------------------------- | --------- | --------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

702730| OpenTelemetry exporter headers `otlpHeaders` | `object` | MDM + Bootstrap | — | Static collector headers — routing and tenant headers only. No credentials here; use Collector authentication or the headers helper script for tokens. Deprecated: `otlpHeaders as a "Name=value,…" string or a ["Name: value", …] list` (accepted until October 7, 2026); use a JSON object such as \{"Name": "value"}. If it is still present after that, a string or list value will be rejected as malformed and no exporter headers will be sent. |

from line 769

741769

742770### Token limits

743771

745| ------------------------------------------------------------------------------------------------- | --------- | --------------- | ------- | -------------------------------------------------------------------------------------------- |

773| ------------------------------------------------------------------------------------------------- | --------- | --------------- | ------- | ---------------------------------------------------------------------------------------------- |

748776

749777<AccordionGroup>

750778 <Accordion title="inferenceMaxTokensPerWindow details">

from line 870

842870 | ------------------------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

845 | `ref` | `string` | — | Commit SHA, branch, or tag. Leave empty to track the default branch. |

873 | `ref` | `string` | — | Commit SHA, branch, or tag. Leave empty to track the default branch; auto\_install and required need a full 40-character commit SHA. |

from line 877

849877 | `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`. |

851879 | `url` | `string` | — | HTTPS Git remote of the marketplace repository (git), or direct HTTPS URL of a hosted marketplace.json file (url). |

853881 </Accordion>

854882</AccordionGroup>

855883

This page’s history 50 edits

20 Oct 2026 +5 −5
20 Oct 2026 +1064 −1114
20 Oct 2026 +64 −23
20 Oct 2026 +6 −6
19 Oct 2026 +1 −1
16 Oct 2026 +1 −1

The page’s own history →

Where it came from

The captureclaude-docs
Upstream pageclaude.com

Around it

Every changethe ledger
That day4 Sep 2026