Home Docs Claude Documentation

One capture · claude-docs

One read of Claude Documentationclaude-docs-20261026T033705Z

3 pages moved out of 280 read.

Pages moved 3 significant first

Pages read 280 in this capture

Captured 26 Oct 2026 03:37 UTC

Corpus hash 4a8c00b54136 corpus-hash

What this read moved

1-3 of 3

third-party/claude-desktop/installation Changed · +10 / -0 lines

### SSH remote sessions with the offline installer

from line 202

202202

203203Pair the offline installer with [`disableAutoUpdates`](https://claude.com/docs/third-party/claude-desktop/configuration#disableautoupdates). The app cannot reach the update feed from an air-gapped network, and you update the fleet by distributing each new offline installer through your MDM. Also set [`modelCatalogEnabled`](https://claude.com/docs/third-party/claude-desktop/configuration#modelcatalogenabled) to `false`, or point [`modelCatalogUrl`](https://claude.com/docs/third-party/claude-desktop/configuration#modelcatalogurl) at a mirror inside your network. Otherwise the app tries to fetch the signed model catalog from `downloads.claude.ai` at launch and every 5 to 15 minutes after that, and while those requests fail the model picker keeps the names and effort options that ship with the app. With updates and the catalog fetch handled this way, the only egress an air-gapped deployment needs is your inference provider; see [Telemetry and egress](https://claude.com/docs/third-party/claude-desktop/telemetry.md#required-egress-paths).

204204

205### SSH remote sessions with the offline installer

206

207With the offline installer, neither the device nor the host needs to reach `downloads.claude.ai` to set up a Linux host for an [SSH remote session](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions.md). The installed Claude Desktop package then includes copies of the two programs that Claude Desktop [puts on a host](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions.md#host-requirements), the remote server and the Claude Code engine. Claude Desktop uses those copies without a setting.

208

209* **Linux hosts**: both programs are included for x64 and arm64, with glibc or musl. Claude Desktop uploads them over the SSH connection. Expect an upload for each user account on a host and each Claude Desktop version, of about 3 MB for the remote server and 100 MB for the engine.

210* **macOS and Windows hosts**: neither program is included. Where `downloads.claude.ai` is blocked, the session fails with a message that the installer doesn't include the programs, so connect to Linux hosts only.

211* **Updates of both programs**: the Claude Desktop version determines the version of both programs. With [`disableAutoUpdates`](https://claude.com/docs/third-party/claude-desktop/configuration#disableautoupdates) set, both programs change on your hosts only when you distribute a new installer. Claude Desktop also starts the engine with [`DISABLE_AUTOUPDATER`](https://code.claude.com/docs/en/env-vars) set to `1`, which turns off the engine's background updates.

212

213The host still has to reach your inference endpoint and, if configured, your OTLP collector. See [Host requirements](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions.md#host-requirements).

214

205215## Updates

206216

207217By default, Claude Desktop downloads updates from Anthropic's update server automatically and applies them the next time the app restarts. If the app hasn't restarted within 72 hours of downloading an update, it restarts itself, waiting for 10 minutes of user inactivity before doing so. This enforcement is always on and offers no in-app prompt to defer the restart; the `autoUpdaterEnforcementHours` key tunes the 72-hour window rather than enabling it.

third-party/claude-desktop/ssh-remote-sessions Changed · +82 / -3 lines

### Policy status on the remote host ### Use the OpenSSH client of Git for Windows

from line 246

246246

247247### Sandbox status on the remote host

248248

249Claude Desktop asks Claude Code on the host whether the [sandbox](https://claude.com/docs/third-party/claude-desktop/code.md#applied-as-managed-policy) from your Claude Desktop policy is turned on and running there. The answer is Claude Code's own report, and it doesn't compare each allowed host or folder. Your policy includes the sandbox, and Claude Desktop asks, unless `coworkEgressAllowedHosts` contains `*` and `allowedWorkspaceFolders` is unset. Requires Claude Desktop 2.26454.0 or later.

249Claude Desktop asks Claude Code on the host whether the [sandbox](https://claude.com/docs/third-party/claude-desktop/code.md#applied-as-managed-policy) from your Claude Desktop policy is turned on and running there. If `coworkEgressAllowedHosts` contains `*` and `allowedWorkspaceFolders` is unset, your policy has no sandbox, and Claude Desktop doesn't ask. Requires Claude Desktop 2.26454.0 or later.

250250

251The answer is Claude Code's own report, and Claude Desktop compares only part of it with your policy:

252

253* **Folders**: Claude Desktop doesn't compare the folders that the sandbox allows with the folders in your policy.

254* **Network hosts**: if the answer lists the network hosts that the sandbox allows, and a network host from your policy is missing from the list, Claude Desktop reports the reason `overridden`. Claude Desktop doesn't check for network hosts that the remote host's own settings add. Requires Claude Desktop 3.6556.1 or later.

255

251256When the sandbox isn't confirmed, the session continues and shell commands can run outside the sandbox. To keep Claude Code from starting on a host whose operating system has no sandbox or that lacks a dependency, set [`sandbox.failIfUnavailable`](https://code.claude.com/docs/en/sandboxing#enforce-sandboxing-with-managed-settings) to `true` and [`parentSettingsBehavior`](https://claude.com/docs/third-party/claude-desktop/code#interaction-with-claude-code%E2%80%99s-own-managed-settings) to `"merge"` in the host's Claude Code managed settings. With `"merge"`, that setting applies together with your policy.

252257

253258Find the message, or the `reason` your collector received, for the cause and the fix.

from line 264

259264| Your organization's sandbox policy isn't fully applied on `<host>`, so shell commands there may run outside it | `overridden` | Claude Code managed settings on the host replace your policy, even when they say nothing about the sandbox, or they turn the sandbox off or loosen it | Set `parentSettingsBehavior` to `"merge"` in the host's managed settings, and remove `sandbox` values there that conflict with your policy |

260265| No message | `unknown` | Claude Code gives no answer that Claude Desktop can read | In a session on that host, ask Claude to run the two commands under [Confirm commands run inside the sandbox](https://code.claude.com/docs/en/sandboxing#confirm-commands-run-inside-the-sandbox) |

261266

267The fix for the `overridden` message and the fix for the message under [Policy status on the remote host](#policy-status-on-the-remote-host) start at the same setting, `parentSettingsBehavior`. With Claude Desktop 3.6556.1 or later, a session that shows one of the two messages doesn't add the other until the first no longer applies. Your collector still receives the event of the check whose message is held back, and the **Sandbox** row of `/status` still shows the sandbox's state.

268

262269To check one session, have the user open it, wait until Claude has finished replying, and enter `/status` in the message box. Where your policy includes the sandbox, the **Session info** card shows what Claude Desktop last learned in a **Sandbox** row. Requires Claude Desktop 2.31226.0 or later. Find the value's `reason` in the table of messages and reasons for the cause and the fix:

263270

264271* **On · Strict**: no reason. Claude Code reports the sandbox from your policy turned on and running.

from line 285

278285

279286The event doesn't name the host. To find the host, ask the user that the [user attribution](https://claude.com/docs/third-party/claude-desktop/telemetry.md#user-attribution) attributes identify.

280287

288### Policy status on the remote host

289

290To find a host that doesn't apply your policy, Claude Desktop asks Claude Code on the host which permission rules apply there. In the answer, Claude Desktop looks for the deny and ask rules sent with your policy. Requires Claude Desktop 3.6556.1 or later.

291

292Keys that produce such rules include:

293

294* [`builtinToolPolicy`](https://claude.com/docs/third-party/claude-desktop/configuration#builtintoolpolicy) entries other than `allow`

295* Scoped [`disabledBuiltinTools`](https://claude.com/docs/third-party/claude-desktop/configuration#disabledbuiltintools) entries such as `Bash(curl *)`

296* [Read-only folders](#read-only-folders-on-the-remote-host)

297* A managed MCP server's `toolPolicy` entries set to `blocked` or `ask`

298

299The check fails if Claude Code lists none of those rules as managed policy, or itself reports that it left out the sent policy. The session continues and shows this message, unless it already shows the `overridden` message under [Sandbox status on the remote host](#sandbox-status-on-the-remote-host):

300

301```text theme={null}

302Your organization's policy isn't fully applied on <host>. Ask your admin to check parentSettingsBehavior in that host's Claude Code managed settings.

303```

304

305A session that shows one of the two messages doesn't add the other until the first no longer applies. Your collector still receives the event of the check whose message is held back.

306

307To fix the host, set `parentSettingsBehavior` to `"merge"` in the host's Claude Code managed settings, which otherwise replace your policy. See [Managed configuration on the remote host](#managed-configuration-on-the-remote-host). Claude Desktop asks again when Claude Code starts, when Claude Desktop rejoins a running Claude Code process, and after each turn. Once the check passes again, a session that still shows the message also shows "Your organization's policy applies on `<host>` again."

308

309With [`otlpEndpoint`](https://claude.com/docs/third-party/claude-desktop/configuration#otlpendpoint) set, your collector receives a `desktop_ssh_policy_check_failed` event under the `service.name` value `claude-desktop` when the check fails, unless [`otlpDesktopLogLevel`](https://claude.com/docs/third-party/claude-desktop/configuration#otlpdesktoploglevel) is `off`. A session can send the event more than once, for example after Claude Code or Claude Desktop restarts, so count distinct `session_id` values rather than events. No event marks the recovery. The event carries these attributes:

310

311* **`reason`**: `rules` when Claude Code lists none of the sent rules as managed policy, or `claude_code` when Claude Code itself reports that it left out the sent policy

312* **`session_id`**: Claude Desktop's ID for the session

313* **`backend_kind`**: `ssh`

314

315The event doesn't name the host. To find the host, identify the user from the event's [user attribution](https://claude.com/docs/third-party/claude-desktop/telemetry.md#user-attribution) attributes, and ask that user.

316

317The absence of the message and the event doesn't show that a host applies your policy:

318

319* **Any host**: the answer is Claude Code's own report from the host, not proof. A failed check blocks nothing.

320* **A host that lists at least one sent rule**: the check passes as soon as Claude Code lists one sent rule as managed policy. That holds even if the host's own managed settings supply that rule or replace other parts of your policy.

321* **A policy without a deny or ask rule**: Claude Desktop shows no message and sends no event, unless Claude Code itself reports that it left the policy out.

322* **A Claude Code version on the host that doesn't report its permission rules**: Claude Desktop shows no message and sends no event.

323* **A restart of Claude Desktop**: a session that showed the message doesn't show it again until Claude Code has answered again.

324

281325## Host requirements

282326

283327The host needs the following.

from line 402

358402

359403Where the session's terminal can't use that connection, and always with the built-in client, the terminal runs its own `ssh`, which applies the entry's forwarding and Kerberos delegation settings. With `ForwardAgent yes` in the entry, that `ssh` forwards the user's SSH agent to the host.

360404

405### Use the OpenSSH client of Git for Windows

406

407To have Windows devices connect with an OpenSSH client that isn't Microsoft's, such as the `ssh.exe` of Git for Windows, name the client in [`sshClientPath`](https://claude.com/docs/third-party/claude-desktop/configuration#sshclientpath). Unless `sshClientPath` names another client, the OpenSSH client that makes the connection on a Windows device is Microsoft's. Placing another client first on the `PATH` never lets that client make the connection. Requires Claude Desktop 3.6556.1 or later.

408

409Name another client only on devices with one user, not on devices that several users share.

410

411The client that you name makes the connection only if all of these conditions hold:

412

413* **Folder**: the program is an `.exe` file under Program Files or Program Files (x86).

414* **Version**: the program is OpenSSH 8.5 or later. To check, run the program with `-V` in a Command Prompt window, for example `"C:\Program Files\Git\usr\bin\ssh.exe" -V`.

415* **`sshClientPath` and `sshTransport`**: `sshClientPath` holds the program's absolute path, and [`sshTransport`](https://claude.com/docs/third-party/claude-desktop/configuration#sshtransport) is `system-openssh`.

416* **Source of both settings**: both values come from [machine policy](https://claude.com/docs/third-party/claude-desktop/mdm.md#4-deploy-the-configuration) under `HKLM\SOFTWARE\Policies\Claude`, or from the [bootstrap server](https://claude.com/docs/third-party/claude-desktop/bootstrap.md) that machine policy names. Values from a user's own configuration file or from `HKCU` don't count. Neither do values from an admin-console organization that a user's own sign-in points the device to.

417* **Trial start**: in each run of Claude Desktop, before the first connection, Claude Desktop starts the program without connecting. The program must accept the arguments and options that Claude Desktop passes. The `ssh.exe` of a current Git for Windows takes them.

418

419Before you deliver `sshClientPath` and `sshTransport`, check for these devices:

420

421* **Devices without the program**: with no file at the path that `sshClientPath` names, every SSH connection fails, whatever the value of `sshTransport`, and Claude Desktop's built-in SSH client doesn't take over. Install the program first, or deliver both settings only to devices that have it. A device that gets neither setting connects as before.

422* **Devices with a bootstrap server**: once loaded, the server's response replaces machine policy's values, even for a setting that the response leaves out. Return both settings in the response as well as in machine policy. Return `sshClientPath` only to Windows devices, because SSH connections fail on a macOS or Linux device that gets a Windows path.

423

424If `sshTransport` is `system-openssh` and any other condition in the list doesn't hold, connections fail with the card "Ask your IT administrator to fix the configured SSH program". Claude Desktop never runs another `ssh` in the program's place.

425

426With `system-openssh` and a client named in `sshClientPath`, Claude Desktop's built-in client tries the connection in one case only. In that case the program's file exists, but Windows won't start the program, or the program gives no answer when Claude Desktop starts it without connecting. That case ends as soon as the program has answered once since Claude Desktop opened.

427

428To find the condition that doesn't hold, select **View details** on the card and read the line that starts with `Claude needs:`. `ssh.log` in the [logs directory](https://claude.com/docs/third-party/claude-desktop/data-storage.md#where-data-lives) on the device names the condition too. The card says less in these cases:

429

430* **The source of both settings is what fails**: the `Claude needs:` line names only Microsoft's OpenSSH, and the reason is in `ssh.log`.

431* **The path isn't absolute, isn't an `.exe` file, or names no file**: **View details** shows no `Claude needs:` line, and `ssh.log` says only that the program is missing or can't be used.

432

433With a client that isn't Microsoft's, plan for the following:

434

435* **SSH files**: Claude Desktop points the client at the `.ssh` folder of the user's Windows profile. Git Bash on the same device can use another folder, so an SSH key or a `known_hosts` entry that works in Git Bash can be missing for Claude Desktop. **View details** on a failed sign-in then names both folders. For system-wide settings the client reads `etc\ssh` under Git's folder, not `%ProgramData%\ssh`.

436* **Prompts**: Claude Desktop asks for a password, a one-time code, or a key passphrase only on a direct connection. A connection is direct if the SSH configuration gives the host no jump host, `ProxyCommand`, `KnownHostsCommand`, `PKCS11Provider`, or `SecurityKeyProvider`, and holds no `Match exec` line. Claude Desktop must also be able to confirm that the client uses the Windows profile's `.ssh` folder.

437* **Sign-ins where Claude Desktop can't ask**: only an SSH key that needs nothing typed signs in. A sign-in that needs a prompt fails with the card "Ask your IT administrator about your organization's SSH program", and `ssh.log` names the cause.

438* **Application control**: allow the client and the `ssh-keygen.exe` beside the client in your application control policy, as well as Claude Desktop's own [sign-in helpers](#this-computer-won%E2%80%99t-start-claude%E2%80%99s-ssh-sign-in-helper). Claude Desktop tests its prompts with that `ssh-keygen.exe`. While the test fails, only an SSH key that needs nothing typed signs in.

439

361440## Troubleshoot

362441

363442### Your organization doesn't allow this SSH connection

from line 453

374453

375454### SSH to this device isn't available

376455

377The host resolves to the device itself (`localhost`, `127.0.0.1`, or a tunnel or port forward that ends on the device) while `allowedWorkspaceFolders` restricts workspace folders. A session over SSH to the device reaches the same disk the policy restricts, so it is refused. Connect to a different host, or use a local session. Before Claude Desktop 2.31226.0, the card's title was "SSH to this machine isn't available".

456The host resolves to the device itself (`localhost`, `127.0.0.1`, or a tunnel or port forward that ends on the device) while `allowedWorkspaceFolders` restricts workspace folders. A session over SSH to the device reaches the same disk the policy restricts, so it is refused. Connect to a different host, or use a local session unless `disableDesktopLocalSessions` turns those off. Before Claude Desktop 2.31226.0, the card's title was "SSH to this machine isn't available".

378457

379458### SSH sessions can't use your model provider settings

380459

from line 476

397476* **"Ask your IT administrator to install Microsoft OpenSSH 9.4 or newer, then quit and reopen Claude"**: `sshTransport` is `system-openssh`, and the app found no usable OpenSSH client on the device. Install the client.

398477* **"Quit and reopen Claude; if this comes back, ask your IT administrator to let Claude use the system OpenSSH client"**: the device couldn't start the OpenSSH client earlier in this run of the app (see [Host requirements](#host-requirements)).

399478

400Where the app can name no step, the card's title gives the cause: `<host> needs a jump host, which Claude can't use here`, with the text "A ProxyCommand for this host may work instead, once you quit and reopen Claude.", or `Claude can't check <host>'s key here`.

479Where the app can name no step, the card's title gives the cause, either `<host> needs a jump host, which Claude can't use here` or `Claude can't check <host>'s key here`.

401480

402481These cards require Claude Desktop 2.31226.0 or later. Before Claude Desktop 2.31226.0, the built-in client refused a `ProxyJump` host with a message that suggests `ProxyCommand`.

403482

third-party/claude-desktop/telemetry Changed · +3 / -3 lines

from line 62

6262

6363The export carries logs and metrics. Cowork sessions, Code sessions, and the desktop application's own events arrive under the `service.name` values `cowork`, `claude-code-desktop`, and `claude-desktop` respectively. With [Unified Claude](https://claude.com/docs/third-party/claude-desktop/unified-claude.md) on, a Cowork session started from the home screen also arrives under `cowork`. The export isn't checked against the [agent egress allowlist](#required-egress-paths), so `otlpEndpoint` doesn't need an entry in `coworkEgressAllowedHosts`; your perimeter firewall still needs to allow the host.

6464

65For collector authentication headers, extra resource attributes, and the log level of the desktop application's own event stream, see [`otlpHeaders`, `otlpResourceAttributes`, and `otlpDesktopLogLevel`](https://claude.com/docs/third-party/claude-desktop/configuration#otlpheaders) in the configuration reference. Events on the `claude-desktop` stream include `desktop_ssh_sandbox_check_failed`, described under [Sandbox status on the remote host](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions.md#sandbox-status-on-the-remote-host).

6666

6767### Collector endpoint and headers

6868

from line 289

289289| `hcaptcha.com`, `*.hcaptcha.com` | Users sign in with **Sign in with Claude Console** (the [Claude API](https://claude.com/docs/third-party/claude-desktop/claude-api.md) with no static key or credential helper). The Claude Console sign-in and approval pages open in the user's default browser and run a browser check from these hosts. Allow them even when the in-app Egress list doesn't show them. If they're blocked, signing in or approving can fail with a message that the browser couldn't be verified |

290290| `claude.ai`, `hcaptcha.com`, `*.hcaptcha.com`, `api.anthropic.com`, `storage.googleapis.com` | [Import from claude.ai](https://claude.com/docs/third-party/claude-desktop/import.md) is enabled (`claudeAiImport` with `enabled` set to `true`). Used only while a user signs in to claude.ai and fetches an export in the import wizard; importing a downloaded export file needs none of them. The two `hcaptcha.com` entries serve the browser check on the claude.ai sign-in and approval pages |

291291| `releases.claude.com` | The [built-in browser](https://claude.com/docs/third-party/claude-desktop/browser.md) is turned on (`builtinBrowserEnabled` set to `true`), for its [site safety check](https://claude.com/docs/third-party/claude-desktop/browser.md#site-safety-check) |

292| `downloads.claude.ai` | [SSH remote sessions](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions.md) are enabled (`sshHostAllowlist` set). With the offline installer, needed only for connections to hosts other than Linux x64 and arm64, because that installer bundles the remote components for those hosts (see [Host requirements](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions.md#host-requirements)) |

292| `downloads.claude.ai` | [SSH remote sessions](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions.md) are enabled (`sshHostAllowlist` set). Devices need it to download the remote server. For SSH hosts it is optional: a host downloads the Claude Code engine itself if it can reach this hostname, and otherwise the device downloads the engine and uploads it. With the offline installer, needed only for connections to hosts other than Linux x64 and arm64, because that installer bundles the remote components for those hosts (see [Host requirements](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions.md#host-requirements)) |

293293

294294## Disabling all Anthropic-bound connections

295295

from line 308

308308

309309These optional features add hosts back when you turn them on:

310310

311* [SSH remote sessions](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions.md) download the remote-session components from `downloads.claude.ai`. The offline installer bundles those components for Linux x64 and arm64 hosts, so devices installed with it download them only when connecting to hosts on other platforms. See [SSH remote sessions with the offline installer](https://claude.com/docs/third-party/claude-desktop/installation.md#ssh-remote-sessions-with-the-offline-installer).

312312* **Sign in with Claude Console** (the [Claude API](https://claude.com/docs/third-party/claude-desktop/claude-api.md) with no static key or credential helper) loads a browser check from `hcaptcha.com` and `*.hcaptcha.com` on the Claude Console sign-in and approval pages.

313313* [Import from claude.ai](https://claude.com/docs/third-party/claude-desktop/import.md) reaches `claude.ai`, `api.anthropic.com`, and `storage.googleapis.com` (for the export download) only while a user signs in to claude.ai and fetches an export in the import wizard. The claude.ai sign-in and approval pages also load a browser check from `hcaptcha.com` and `*.hcaptcha.com`.

314314* The [built-in browser](https://claude.com/docs/third-party/claude-desktop/browser.md) contacts `releases.claude.com` for its [site safety check](https://claude.com/docs/third-party/claude-desktop/browser.md#site-safety-check).