One read of Claude Documentationclaude-docs-20261101T203712Z
2 pages moved out of 281 read.
Pages moved
2
significant first
Pages read
281
in this capture
Captured
20:37 UTC
Corpus hash
a93fee448d8a
corpus-hash
What this read moved
1-2 of 2third-party/claude-desktop/ssh-remote-sessions Changed · +180 / -41 lines
### Hosts without SFTP ### Use an OpenSSH client installed per user ### Ask your IT administrator to fix the configured SSH program
from line 10
1010
1111## How a remote session works
1212
131. **Connect.** The user picks an SSH host from the environment picker in Code, or adds one by entering its address, port, and an identity file. Claude Desktop connects through the device's OpenSSH client on macOS and Linux, or its built-in SSH client on Windows (see [Host requirements](#host-requirements) to change either default), applies the host's entry from the device's `~/.ssh/config` (see [SSH configuration on the device](#ssh-configuration-on-the-device)), and prompts in the app if the host asks for a password or a one-time code.
131. **Connect.** The user picks an SSH host from the environment picker in Code, or adds one by entering its address, port, and an identity file. Claude Desktop connects through the device's OpenSSH client, or in some cases through its built-in SSH client (see [Host requirements](#host-requirements)), applies the host's entry from the device's `~/.ssh/config` (see [SSH configuration on the device](#ssh-configuration-on-the-device)), and prompts in the app if the host asks for a password or a one-time code.
14142. **Deploy.** Claude Desktop places a remote server and the Claude Code engine under `~/.claude/remote/` in the SSH user's home directory on the host ([Host requirements](#host-requirements) lists every path) and reuses them on later connections.
15153. **Run.** The remote server starts the engine on the host with the inference credential and policy from your managed configuration. Every file read, edit, shell command, and git operation runs on the host, in the working directory the user chose there. Claude Desktop connects to [managed MCP servers](https://claude.com/docs/third-party/claude-desktop/extensions.md#managed-mcp-servers-admin) from the device and exposes them to the engine as tools.
16164. **Stream.** Claude's responses and tool output stream back to Claude Desktop. Permission prompts appear in Claude Desktop, and the engine waits on the host until the user answers.
from line 30
3030* The user reopens the session and Claude Desktop ends the engine to start a fresh one.
3131* The host restarts.
3232* After an update that includes a new remote server, Claude Desktop replaces the host's remote server at a later connection. This ends the engines under the old server. Claude Desktop can put the replacement off while it believes that work is running on that host.
33* After an update that includes a newer Claude Code, the user sends a message in the session. Claude Desktop 4.29.0 or later can then replace the engine with the newer version, if the engine has reported that it has no background or scheduled work.
3334* On a Linux or macOS host, 30 days pass without a connection from Claude Desktop to the remote server. The remote server then stops and ends its engines. Requires Claude Desktop 1.52386.0 or later.
3435* Someone ends the engine's process on the host. To list or end the engines and the remote server yourself on a Linux or macOS host, see [Files and processes on the remote machine](https://code.claude.com/docs/en/desktop#files-and-processes-on-the-remote-machine). There the engine is called Claude Code, and the remote server the helper.
3536
from line 106
105106* **Servers bundled in any other plugin that Claude Desktop copies to the host**: the host. The engine starts the plugin's local servers there, and connects to its remote MCP servers from there.
106107* **Servers in Claude Code's own configuration on the host**: the host. The engine reads files such as `~/.claude.json` in the SSH user's home directory and a project's `.mcp.json`, and starts their local servers and connects to their remote MCP servers from there.
107108
109With the device's OpenSSH client, the user's first message can wait up to ten seconds, with the line `Setting up your MCP servers on <host>…` under it. This can happen after a session starts, and after a quit, once Claude Desktop rejoins the running engine. Claude Desktop is handing the engine the local servers that the user added under **Settings > Developer**. If the engine doesn't get them in time, the message goes anyway, and the conversation shows `This message went without your MCP servers. If you need them, send it again once they're connected.` If the task needs those servers, have the user wait until Claude finishes responding, then send the message again. Requires Claude Desktop 4.4212.0 or later.
110
108111[`isLocalDevMcpEnabled`](https://claude.com/docs/third-party/claude-desktop/configuration#islocaldevmcpenabled), `managedMcpServers`, `allowedPluginMcpServers`, and `deniedPluginMcpServers` decide which of these servers a remote session loads, as they do for a local Code session (see [Applied as managed policy](https://claude.com/docs/third-party/claude-desktop/code.md#applied-as-managed-policy)). If the host has its own Claude Code managed settings, those take precedence over the Claude Code policy these keys produce (see [Managed configuration on the remote host](#managed-configuration-on-the-remote-host)).
109112
110113## Enable SSH remote sessions
from line 155
152155
153156Claude Desktop checks jump hosts in the `ProxyJump` that the device's `~/.ssh/config` sets for the session's host, or in a `ProxyCommand` written as `ssh -W %h:%p <host>`. If one that it checks isn't on the allowlist when the app connects or reconnects a session, the connection fails. When the user starts a session or sends a message, they see [Your organization doesn't allow this SSH connection](#your-organization-doesn%E2%80%99t-allow-this-ssh-connection), and the card's details give that jump host's `HostName`.
154157
155Find the names to add in a terminal on a user's device. Skip `proxyjump` lines on devices that use the built-in client, which [refuses every `ProxyJump`](#ssh-configuration-on-the-device), listed or not.
158Find the names to add in a terminal on a user's device. Skip `proxyjump` lines only on devices where the built-in client makes every connection, for example with `sshTransport` set to `builtin`. The built-in client [refuses every `ProxyJump`](#ssh-configuration-on-the-device), listed or not.
156159
1571601. Run `ssh -G` with a host that users connect to, for example `ssh -G build01`. Look for a `proxyjump` line, or a `proxycommand` line written as `ssh -W %h:%p <host>`. The command still counts with any of `-l`, `-p`, `-J`, `-q`, `-v`, `-N`, `-T`, `-x`, or `-a`, and the hosts after `-J` are jump hosts too. If a `proxycommand` line runs a program other than `ssh`, add nothing for it.
1581612. Run `ssh -G` with each jump host on that line, without any `:port`, and note the `hostname` that it prints. If the output for the first jump host on that line has a line of either kind, repeat this step with it. Ignore such a line in a later jump host's output.
from line 183
180183After the move, `sshHostAllowlist`, `sshTransport`, and `sshClientPath` from the profile, or from the profile's bootstrap server, don't apply, even where the console leaves them unset. For the profile's other settings, see [Which settings apply on a device with a managed profile](https://claude.com/docs/third-party/claude-desktop/admin-console.md#which-settings-apply-on-a-device-with-a-managed-profile).
181184
182185* **Which hosts**: the console's `sshHostAllowlist` applies. If the console leaves the key unset (**Not set**), or the app hasn't yet downloaded the console's configuration at this launch (the copy a device keeps of the last download holds no lists), `sshHostAllowlist` from Claude Code's managed settings on the device applies. With neither, SSH remote sessions are off.
183* **Which SSH client**: the console's `sshTransport` and `sshClientPath` apply. A key that the console leaves unset takes its default under [Host requirements](#host-requirements). Until the app has downloaded the console's configuration at a launch, both keys count as unset.
186* **Which SSH client**: the console's `sshTransport` and `sshClientPath` apply. On a Windows device, a client that the console's `sshClientPath` names makes the connection only if it is Microsoft's OpenSSH. With `system-openssh`, SSH connections fail under any other client. A key that the console leaves unset takes its default under [Host requirements](#host-requirements). Until the app has downloaded the console's configuration at a launch, both keys count as unset, so no client is pinned. Until then the built-in client makes the connection on a Windows device, even where the console sets `system-openssh`. The device's OpenSSH client makes it on a macOS or Linux device, even where the console sets `builtin`.
184187
185188To prevent or limit the move, set one of these keys in the profile itself:
186189
from line 331
328331
329332* Linux or macOS on x86\_64 or arm64, or Windows on x64 or arm64.
330333* On a Linux host, glibc 2.17 or later, or musl. The Claude Code engine is a single executable, and its glibc build links only against glibc's own libraries. Version 2.17 is the oldest glibc that build can load, and Claude Code's [system requirements](https://code.claude.com/docs/en/setup#system-requirements) still apply. To see the host's C library and its version, run `ldd --version` on the host. For a musl host, see [Alpine Linux and musl-based distributions](https://code.claude.com/docs/en/setup#alpine-linux-and-musl-based-distributions).
331* An SSH server with the SFTP subsystem. On Windows, Microsoft's OpenSSH Server; with other SSH servers, the engine does not survive a dropped connection.
332* If devices connect with Claude Desktop's built-in SSH client (the default on Windows devices), an SSH server that accepts several sessions on one connection. The built-in client can't connect where the server's `sshd_config` sets `MaxSessions 1`. Raise that limit, for example to OpenSSH's default of 10, or see [Hosts that allow one session per connection](#hosts-that-allow-one-session-per-connection).
334* An SSH server. On Windows, Microsoft's OpenSSH Server; with other SSH servers, the engine does not survive a dropped connection.
335* The SSH server's SFTP subsystem. For a Linux or macOS host that lacks it, see [Hosts without SFTP](#hosts-without-sftp).
336* If devices connect with Claude Desktop's built-in SSH client, an SSH server that accepts several sessions on one connection. Before Claude Desktop 4.5284.0, that client is the default on Windows devices, and later it still connects to hosts already in use. The built-in client can't connect where the server's `sshd_config` sets `MaxSessions 1`. Raise that limit, for example to OpenSSH's default of 10, or see [Hosts that allow one session per connection](#hosts-that-allow-one-session-per-connection).
333337* The server doesn't need to allow TCP, Unix socket, agent, or X11 forwarding. A `ProxyJump` host must allow TCP forwarding to the host's SSH port.
334338* A POSIX shell, or PowerShell on Windows.
335339* `git` on the path, for git features.
336340* A home directory that the SSH user can write to and run programs from, with about 1 GB of disk space for the three Claude Code versions the app keeps and a fourth while an update installs. A home directory mounted `noexec` doesn't work.
337341
338The device needs the OpenSSH client (`ssh` and `ssh-keygen`). Claude Desktop runs the first `ssh` on the user's `PATH`; to pin a specific OpenSSH installation instead, set [`sshClientPath`](https://claude.com/docs/third-party/claude-desktop/configuration#sshclientpath) (beta, Claude Desktop 1.46388.1 or later) to the program's absolute path, and `ssh-keygen` is then taken from the same directory when present. If the pinned program is missing or cannot be run, SSH connections fail with an error that shows the configured path, rather than falling back to another `ssh`. For the `ssh` that carries the connection on a Windows device, see [Prepare Windows devices for the OpenSSH client](#prepare-windows-devices-for-the-openssh-client).
342The device needs the OpenSSH client (`ssh` and `ssh-keygen`). Claude Desktop runs the first `ssh` on the user's `PATH`. For the `ssh` that carries the connection on a Windows device, see [Prepare Windows devices for the OpenSSH client](#prepare-windows-devices-for-the-openssh-client).
339343
340On macOS and Linux, Claude Desktop makes the SSH connection by running the device's OpenSSH client, so your own OpenSSH build's Kerberos (GSSAPI), certificate, and `ssh_config` support handles authentication. The program is the one `sshClientPath` names, or else the first `ssh` on the user's `PATH`, and it must be OpenSSH 7.6 or newer. On Windows, the app's built-in SSH client makes the connection by default, and the app runs the device's OpenSSH tools to evaluate the user's SSH configuration, look up host keys, and run the session's terminal. To have the device's OpenSSH client carry the connection on Windows too, set [`sshTransport`](https://claude.com/docs/third-party/claude-desktop/configuration#sshtransport) (beta) to `system-openssh`; a client that the app finds itself must be Win32-OpenSSH 9.4 or newer. On a Windows device with no usable OpenSSH client and no `sshClientPath`, the built-in client is used regardless. For what to check first, see [Prepare Windows devices for the OpenSSH client](#prepare-windows-devices-for-the-openssh-client). Set `sshTransport` to `builtin` to use the built-in client on every platform. A change applies to new connections, and sessions that are already connected keep their client.
344To pin a specific OpenSSH installation instead, set [`sshClientPath`](https://claude.com/docs/third-party/claude-desktop/configuration#sshclientpath) (beta, Claude Desktop 1.46388.1 or later) to the program's absolute path:
341345
342The built-in client also makes the connection in these cases:
346* **Companion tools**: Claude Desktop takes `ssh-keygen` and `ssh-add` from the same directory when they exist there. Otherwise it takes `ssh-keygen` from the user's `PATH`, and `ssh-add` from the operating system's own OpenSSH or else the `PATH`.
347* **macOS and Linux devices**: the program can be a wrapper script that runs an OpenSSH client.
348* **Windows devices**: the program must be an `.exe` file, not a `.cmd`, `.bat`, or `.ps1` script. Stricter rules apply to its version and folder. See **Client version** under [Prepare Windows devices for the OpenSSH client](#prepare-windows-devices-for-the-openssh-client), and [Use the OpenSSH client of Git for Windows](#use-the-openssh-client-of-git-for-windows). For a value that starts with `%LOCALAPPDATA%\`, see [Use an OpenSSH client installed per user](#use-an-openssh-client-installed-per-user).
349* **A program that can't be used**: if the pinned program is missing, or on macOS and Linux can't be run, SSH connections fail with an error that shows the configured path. Where the OpenSSH client makes the connection, they also fail if the program is older than OpenSSH 7.6. Claude Desktop never runs another `ssh` program in its place. On Windows, if the program exists but can't be started, Claude Desktop's built-in client can still make the connection.
350* **Every source of settings**: a bootstrap server or the Enterprise Admin Console that leaves `sshClientPath` out cancels the value that device management sets. A bootstrap server does so once its response has loaded at a launch, and the console as soon as the app starts. Claude Desktop then chooses the `ssh` program as if you had pinned nothing. Set the key everywhere you manage settings. From a bootstrap server, return each platform's path only to devices of that platform.
343351
352Claude Desktop makes the SSH connection by running the device's OpenSSH client, so your own OpenSSH build's Kerberos (GSSAPI), certificate, and `ssh_config` support handles authentication. The program is the one `sshClientPath` names, or else, on macOS and Linux, the first `ssh` on the user's `PATH`, and it must be OpenSSH 7.6 or later. On Windows, the device's OpenSSH client is the default in Claude Desktop 4.5284.0 or later, and only for hosts that are new to the device. See [Prepare Windows devices for the OpenSSH client](#prepare-windows-devices-for-the-openssh-client).
353
354To use one client for every host, set [`sshTransport`](https://claude.com/docs/third-party/claude-desktop/configuration#sshtransport) (beta) to `system-openssh` or `builtin`. Both apply on every platform. A change applies to new connections, and sessions that are already connected keep their client.
355
356* **`system-openssh`**: use the device's OpenSSH client.
357* **`builtin`**: use the app's built-in SSH client. The app still runs the device's OpenSSH tools to evaluate the user's SSH configuration, look up host keys, and run the session's terminal. The in-app help and some cards call this client the built-in library.
358* **`auto`**: the same as leaving the key unset.
359* **Any other value**: the app can't read it, for example a misspelling, and the built-in client makes every connection.
360
361The built-in client also makes the connection in these cases, and on Windows in the cases under [Prepare Windows devices for the OpenSSH client](#prepare-windows-devices-for-the-openssh-client):
362
344363* **The device can't start the OpenSSH client**: while `sshTransport` is unset or `auto` and `sshClientPath` is unset, the built-in client makes every connection until Claude Desktop restarts. Requires Claude Desktop 2.7032.0 or later.
345364* **Claude Desktop is installed from the Microsoft Store**: the built-in client makes the connection unless `sshTransport` is `system-openssh`. With `system-openssh`, the device's OpenSSH client makes the connection, but the app can't show its prompts for a password, a one-time code, or a key passphrase, or its question about a host key that isn't on record. Use a sign-in method that needs no prompt, such as a key held by the SSH agent, and have users connect to each host once from a terminal before adding it in the app, so that the host's key is in the user's `known_hosts` file.
346365
from line 376
357376
358377Each side of a remote session needs its own network access.
359378
360* Devices installed with the regular installer must reach `downloads.claude.ai`: Claude Desktop downloads the remote server there and uploads it to the host over SFTP. Devices installed with the [offline installer](https://claude.com/docs/third-party/claude-desktop/installation.md#offline-installation) don't: it bundles the remote server and the Claude Code engine for Linux x64 and arm64 hosts, and Claude Desktop uploads both over SFTP. Hosts on other platforms still need the download, so an offline-installed device that cannot reach `downloads.claude.ai` fails the session with a message saying the installer doesn't include remote components for that platform.
361* The host must reach your inference endpoint and, if configured, your OTLP collector, plus whatever the user's own work needs. With the regular installer, it downloads the Claude Code engine from `downloads.claude.ai` when it can; when that fails, Claude Desktop downloads the engine on the device and uploads it over SFTP. Unless you disabled telemetry, the engine on the host also reports to the same Anthropic hosts as a local Code session (see [Telemetry and egress](https://claude.com/docs/third-party/claude-desktop/telemetry.md)). Blocking them does not affect the session.
379* Devices installed with the regular installer must reach `downloads.claude.ai`: Claude Desktop downloads the remote server there and uploads it to the host. Devices installed with the [offline installer](https://claude.com/docs/third-party/claude-desktop/installation.md#offline-installation) don't: it bundles the remote server and the Claude Code engine for Linux x64 and arm64 hosts, and Claude Desktop uploads both. Hosts on other platforms still need the download, so an offline-installed device that cannot reach `downloads.claude.ai` fails the session with a message saying the installer doesn't include remote components for that platform.
380* The host must reach your inference endpoint and, if configured, your OTLP collector, plus whatever the user's own work needs. With the regular installer, it downloads the Claude Code engine from `downloads.claude.ai` when it can; when that fails, Claude Desktop downloads the engine on the device and uploads it. Unless you disabled telemetry, the engine on the host also reports to the same Anthropic hosts as a local Code session (see [Telemetry and egress](https://claude.com/docs/third-party/claude-desktop/telemetry.md)). Blocking them does not affect the session.
362381
382### Hosts without SFTP
383
384A remote session can start on a Linux or macOS host where SFTP is turned off or doesn't work. Claude Desktop then places its own setup files on the host with shell commands instead of SFTP. Before Claude Desktop 3.1623.0, setup fails on such a host.
385
386These features need SFTP, so they are off in that session. Users can keep working without them.
387
388* Image and document previews
389* File attachments
390* The Changes pane
391* Plugins that Claude Desktop copies from the device
392* Downloads of PDF and Office files: the download option is missing, or the download fails with `Couldn't download <name>`
393
394A session without SFTP needs at least the following. Where one is missing, setup fails (see [Setup on the host fails after SSH connects](#setup-on-the-host-fails-after-ssh-connects)).
395
396* **Version**: Claude Desktop 3.1623.0 or later on the device.
397* **Client**: the device's OpenSSH client makes the connection. The built-in client needs SFTP. Before Claude Desktop 4.5284.0 it is the default on Windows devices, and in Claude Desktop 4.5284.0 or later it still makes the connection in some cases. To have the device's OpenSSH client make every connection, see [Prepare Windows devices for the OpenSSH client](#prepare-windows-devices-for-the-openssh-client).
398* **Shell**: a POSIX shell on the host, with `sh` and the standard Unix tools such as `ls`, `cat`, and `rm`.
399* **Base64 decoder**: `base64` or `openssl` on the host.
400* **SHA-256 tool**: `sha256sum`, `shasum`, or `openssl` on the host.
401
402To bring back what is off, go by the second sentence of the notice that the user sees in the conversation. The notice begins, for example, "Image and document previews, file attachments, the Changes pane, and your computer's plugins are off."
403
404* **"turn on SFTP"**: the SSH server refuses SFTP. Enable `Subsystem sftp` in the server's `sshd_config`, and reload the SSH server.
405* **"see why SFTP doesn't start"**: the SSH server accepts the request for SFTP, but SFTP never starts. In a terminal on the device, run `sftp` with the same host to see what stops it, then fix that on the host.
406* **"let SFTP reach your home folder"**: over SFTP, Claude Desktop didn't find a folder it made under the SSH user's home directory, as when SFTP is confined to a folder. Set up the SSH server so that SFTP sees the home directory at the same path as the login shell does.
407* **"refused the second sign-in"**: SFTP isn't at fault. The host refused what the user entered at the sign-in for file transfer, as it can when the user enters the same one-time code twice. Claude Desktop makes that second sign-in on [hosts that allow one session per connection](#hosts-that-allow-one-session-per-connection) and from [Windows devices that use the device's OpenSSH client](#prepare-windows-devices-for-the-openssh-client). If the host refuses it each time, have the user sign in by a method that needs no prompt, such as a key that an SSH agent holds. Before Claude Desktop 4.29.0, the connection fails.
408
409After the change, or to try the sign-in again, have the user quit and reopen Claude Desktop and start a new session.
410
363411### Hosts that allow one session per connection
364412
365413A device can connect to a host whose `sshd_config` sets `MaxSessions 1` only when the device's OpenSSH client makes the connection:
366414
367415* **macOS and Linux devices**: the device's OpenSSH client is the default. The device also needs Claude Desktop 3.1623.0 or later.
368* **Windows devices**: the built-in client is the default, and it can't connect to such a host. To have the device's OpenSSH client make the connection, see [Prepare Windows devices for the OpenSSH client](#prepare-windows-devices-for-the-openssh-client).
416* **Windows devices**: the built-in client can't connect to such a host. Before Claude Desktop 4.5284.0 it is the default, and in Claude Desktop 4.5284.0 or later it still makes the connection in some cases. To have the device's OpenSSH client make every connection, see [Prepare Windows devices for the OpenSSH client](#prepare-windows-devices-for-the-openssh-client).
369417
370418Connecting to a host with this limit changes what the SSH server's log shows and how often devices sign in:
371419
from line 423
375423
376424### Prepare Windows devices for the OpenSSH client
377425
378On Windows devices, the app's built-in SSH client makes the SSH connection by default. The device's OpenSSH client makes it when you set [`sshTransport`](https://claude.com/docs/third-party/claude-desktop/configuration#sshtransport) (beta) to `system-openssh`.
426With Claude Desktop 4.5284.0 or later, a Windows device connects to each host that is new to it through the device's OpenSSH client. A host that the device already connects to stays on the app's built-in SSH client, with no action required. A new or re-imaged PC, or a virtual desktop that keeps no local app data, has no hosts in use, so every host is new to it. The same holds where the app's record of earlier connections is damaged, because the app then resets it. A host that the device last connected to before Claude Desktop 1.46388.1 can count as new too, because earlier versions may have kept no record of it. Before Claude Desktop 4.5284.0, the built-in client makes every connection on Windows unless [`sshTransport`](https://claude.com/docs/third-party/claude-desktop/configuration#sshtransport) (beta) is `system-openssh`.
379427
428Choose what your Windows devices do. For the first and the third choice, check what the device's OpenSSH client needs, under **Check what the device's OpenSSH client needs on Windows** below.
429
430* **Leave `sshTransport` unset**: new hosts and new PCs use the OpenSSH client.
431* **Keep the built-in client for every host**: set `sshTransport` to `builtin`. It holds for new hosts and new PCs too. If `sshClientPath` starts with `%LOCALAPPDATA%\`, remove it too, or SSH connections fail. See **If you set `sshTransport`** below.
432* **Use the OpenSSH client for every host**: set `sshTransport` to `system-openssh`. To go back, set `builtin`, and if `sshClientPath` starts with `%LOCALAPPDATA%\`, remove it too. See **If you set `sshTransport`** below.
433
434With `sshTransport` unset or `auto`, the built-in client still connects in these cases, and in those under [Host requirements](#host-requirements):
435
436* **Hosts already in use**: a host that the device has reached only with the built-in client stays on it. A host that the device first reaches while `builtin` is set, or while it has no usable OpenSSH client, stays on the built-in client too. The same goes for a host first reached with a `.ppk` file that the built-in client can read, or after Windows denied the sign-in helper's start.
437* **Configuration that hasn't loaded**: on a device that takes its configuration from the Enterprise Admin Console or a bootstrap server, the built-in client makes every connection at each launch until that configuration has loaded. If your bootstrap response sets `system-openssh`, set it in the registry too, so that it holds in this case.
438* **A record that can't be read**: while the app can't read its own record of earlier connections, for example while a scanner holds the file, the built-in client makes that connection, whatever the host.
439* **PuTTY key files**: a host whose identity file in the app is a PuTTY `.ppk` file that the built-in client can read, for example version 2, RSA, with no passphrase.
440* **A blocked sign-in helper**: a host that asks for a password or a one-time code, where Windows denies the app the start of its sign-in helper while a user waits for the connection. Where the helper is missing or gives no answer, or only `ssh.exe` can't start it, the sign-in fails instead.
441* **Another `ssh` program**: `sshClientPath` names an OpenSSH that isn't Microsoft's, or a Microsoft OpenSSH (Win32-OpenSSH) before 9.4. Unless the value starts with `%LOCALAPPDATA%\`, the app still runs the named program to read the user's SSH configuration and to run the session's terminal. With such a value and no `system-openssh`, the app doesn't start the program, and SSH connections fail.
442* **No usable OpenSSH client, and no `sshClientPath`**: the built-in client makes every connection, whatever `sshTransport` says. See **Devices without a usable client** below.
443* **An `sshClientPath` program that gives no answer**: the built-in client tries the connection, whatever `sshTransport` says. See [Use the OpenSSH client of Git for Windows](#use-the-openssh-client-of-git-for-windows).
444
445Four of these cases pass with time. They are configuration that hasn't loaded, a record that can't be read, an `ssh.exe` that Windows wouldn't start, and an `sshClientPath` program that gave no answer. A new host first reached in such a case isn't kept: once the case has passed, its connections use the OpenSSH client.
446
447A host under **Hosts already in use** moves to the OpenSSH client, or counts as new, in these cases. Once the OpenSSH client has connected to it, the host stays there. A connection that fails for another reason moves nothing.
448
449* **You set `system-openssh`**: once one connection has succeeded under it, the device keeps no host on the built-in client for having used it before, even if you remove the setting later. Cases such as **PuTTY key files** still apply.
450* **A host key that the built-in client can't check**: the user's `known_hosts` file has no plain entry for the host, and `ssh` would check its key against a certificate authority or another `known_hosts` file. The system-wide file is one such file. The host moves at its next connection.
451* **A jump host**: a host that is given a jump host moves at its first connection after the user has quit and reopened Claude Desktop. Until then the built-in client dials the host without the jump host.
452* **A record that is lost**: on a re-imaged PC, or once the app has reset a damaged record, every host counts as new.
453
454Nothing that a user does to a saved connection in Claude Desktop moves its host. Removing the connection and adding it again at the same address, or editing its address, keeps the client. The same machine added under another name, address, or port counts as a new host. A user who edits their own `~/.ssh/config` or `known_hosts` file can bring about the second or third case above.
455
456While hosts stay on the built-in client:
457
458* **Host key checks**: a host on the built-in client keeps that client's [host key check](#ssh-configuration-on-the-device), which reads the user's `known_hosts` file alone, not the system-wide one or a `RevokedHostKeys` file. To move those hosts to `ssh`'s own check, on a device with a usable OpenSSH client, set `sshTransport` to `system-openssh`.
459* **Which client connected**: search `ssh.log` in the [logs directory](https://claude.com/docs/third-party/claude-desktop/data-storage.md#where-data-lives) for `master ready for` (the OpenSSH client) or `[SSH2Connection] Connected to` (the built-in client). If both appear for one connection, the later one counts. For the reason, search for `this connection attempt uses`: the line ends with the source of the choice, such as `host_kept` for a host already in use. The app doesn't show which client connected, and two devices can differ at one host.
460
380461With the device's OpenSSH client on a Windows device:
381462
382* **Repeated sign-ins**: each time Claude Desktop connects or reconnects to a host, it signs in at least twice, to run commands and to transfer files, and once more for each terminal that opens. A Windows host takes at least one more sign-in each time. On a Windows device, each sign-in is a separate `ssh` process. They stay open together, so a per-user login limit on the host has to leave room for them. Claude Desktop repeats a typed password or key passphrase itself for the other sign-ins of that connection. A host that asks for a one-time code, a push approval, or a security key touch asks again at each sign-in.
463* **Repeated sign-ins**: each time Claude Desktop connects or reconnects to a host, it signs in at least twice, to run commands and to transfer files, and once more for each terminal that opens. A Windows host takes at least one more sign-in each time. On a Windows device, each sign-in is a separate `ssh` process. They stay open together, so a per-user login limit on the host has to leave room for them. Each process connects to the host by name, so a name that stands for several machines, such as a load balancer or round-robin DNS, must send all connections from one device to the same machine. Claude Desktop repeats a typed password or key passphrase itself for the other sign-ins of that connection. A host that asks for a one-time code, a push approval, or a security key touch asks again at each sign-in.
464* **Key files that other accounts can read**: `ssh` ignores a private key file that any account but the user, SYSTEM, or Administrators can read. After a sign-in fails over one, Claude Desktop tightens the file's access list where it can, and connects again. `ssh.log` records the list before and after.
383465* **Host keys that aren't on record**: where the app can show a prompt, it asks the user whether to trust the key, and records a trusted key in the user's `known_hosts` file. To distribute host keys instead, see [SSH configuration on the device](#ssh-configuration-on-the-device).
384* **Saved passwords**: when the session's host asks for the account password, the sign-in dialog has a **Remember password for `<host>`** checkbox. To turn saved passwords off, set [`disableSshSavedPasswords`](https://code.claude.com/docs/en/desktop#managed-settings) to `true` in Claude Code's managed settings on the device, by the steps for `disableDesktopLocalSessions` under [Interaction with Claude Code managed settings on the device](#interaction-with-claude-code-managed-settings-on-the-device). The dialog then has no checkbox, and the app stops using passwords that it saved earlier. It doesn't delete them.
466* **Saved passwords**: when the session's host asks for the account password, the sign-in dialog has a **Remember password for `<host>`** checkbox. To turn saved passwords off, set [`disableSshSavedPasswords`](https://code.claude.com/docs/en/desktop#managed-settings) to `true` in Claude Code's managed settings on the device, by the steps for `disableDesktopLocalSessions` under [Interaction with Claude Code managed settings on the device](#interaction-with-claude-code-managed-settings-on-the-device). The dialog then has no checkbox, and the app stops using passwords that it saved earlier. It doesn't delete them, and the user's settings no longer offer to forget one. Removing the connection in the app still deletes its saved password. Deliver the setting before devices start to use the OpenSSH client. Neither the Enterprise Admin Console nor a bootstrap server can deliver it.
385467
386Before you set `sshTransport`, check what the device's OpenSSH client needs on Windows:
468Check what the device's OpenSSH client needs on Windows:
387469
388* **One value for all platforms**: `sshTransport` has no per-platform form. A Windows registry policy reaches Windows devices only. A value from a bootstrap server or the Enterprise Admin Console reaches the macOS and Linux devices that it serves too, where the device's OpenSSH client already makes the connection by default.
389* **Devices with a bootstrap server**: an available [bootstrap response](https://claude.com/docs/third-party/claude-desktop/bootstrap.md) replaces the registry's value of `sshTransport`, even if the response leaves the key out, so return the key in the response too. If you set `sshClientPath`, return it too, but only in a response that goes to Windows devices alone. It has no per-platform form either, and SSH connections fail on a macOS or Linux device that gets a Windows path.
390* **Client version**: with no [`sshClientPath`](https://claude.com/docs/third-party/claude-desktop/configuration#sshclientpath), a usable client prints a version that starts with `OpenSSH_for_Windows_` and is 9.4 or later. Run `ssh -V` in a Command Prompt window on a device, signed in as the user. If that output is anything else, run `ssh.exe -V` in `%SystemRoot%\System32\OpenSSH` and in `%ProgramFiles%\OpenSSH`: Claude Desktop uses the first usable client that it finds, on the `PATH`, then in those two folders in that order. If you set `sshClientPath`, run that program with `-V` instead. In Claude Desktop 3.1623 and earlier, it has to pass the same test.
391* **Devices without a usable client**: on a Windows device with no usable OpenSSH client and no `sshClientPath`, the built-in client is used regardless. Add the **OpenSSH Client** optional feature in Windows and install pending Windows updates, or install [Microsoft's newer build](https://learn.microsoft.com/en-us/troubleshoot/windows-server/system-management-components/upgrade-in-box-openssh-to-latest-openssh-release). Run the version check again, then have users quit and reopen Claude Desktop.
392* **Application control**: `ssh` shows its prompts through three helper programs that ship with Claude Desktop, `claude-ssh-askpass.exe`, `claude-ssh-broker.exe`, and `claude-ssh-proxy.exe`. Allow them in your application control policy by their publisher, Anthropic, PBC. Their folder changes with each update, and the files carry no product name or version. Allow the `ssh.exe` that the version check found too. If Windows refuses to start the helpers, sign-ins that need a password, a one-time code, or a key passphrase fail, and `ssh` refuses a host whose key isn't on record. See [This computer won't start Claude's SSH sign-in helper](#this-computer-won%E2%80%99t-start-claude%E2%80%99s-ssh-sign-in-helper).
393* **Key files**: `ssh` doesn't read a PuTTY `.ppk` key file. Export the key in OpenSSH format, and have the user select the exported file as the connection's identity file.
470* **Client version**: with no [`sshClientPath`](https://claude.com/docs/third-party/claude-desktop/configuration#sshclientpath), a usable client prints a version that starts with `OpenSSH_for_Windows_` and is 9.4 or later. That is Microsoft OpenSSH, also called Win32-OpenSSH. Run `ssh -V` in a Command Prompt window on a device, signed in as the user. If that output is anything else, run `ssh.exe -V` in `%SystemRoot%\System32\OpenSSH` and in `%ProgramFiles%\OpenSSH`: Claude Desktop uses the first usable client that it finds, on the `PATH`, then in those two folders in that order. If you set `sshClientPath`, run that program with `-V` instead. With `sshTransport` unset or `auto`, or in Claude Desktop 3.1623 and earlier, it has to pass the same test. With `system-openssh`, it can instead be an OpenSSH client that isn't Microsoft's. Such a client has to meet the conditions in [Use the OpenSSH client of Git for Windows](#use-the-openssh-client-of-git-for-windows) or in [Use an OpenSSH client installed per user](#use-an-openssh-client-installed-per-user). Each section names the Claude Desktop version that it requires.
471* **Devices without a usable client**: on a Windows device with no usable OpenSSH client and no `sshClientPath`, the built-in client is used, whatever `sshTransport` says. Add the **OpenSSH Client** optional feature in Windows and install pending Windows updates, or install [Microsoft's newer build](https://learn.microsoft.com/en-us/troubleshoot/windows-server/system-management-components/upgrade-in-box-openssh-to-latest-openssh-release). Run the version check again, then have users quit and reopen Claude Desktop. Hosts that the device first reached without a usable client stay on the built-in client. To move them, set `sshTransport` to `system-openssh`.
472* **Application control**: `ssh` shows its prompts through three helper programs that ship with Claude Desktop, `claude-ssh-askpass.exe`, `claude-ssh-broker.exe`, and `claude-ssh-proxy.exe`. Allow them in your application control policy by their publisher, Anthropic, PBC. Their folder changes with each update, and the files carry no product name or version. Allow the `ssh.exe` that the version check found too. If Windows refuses to start the helpers, the app can't ask for a key passphrase, and `ssh` refuses a host whose key isn't on record. Sign-ins that need a password or a one-time code fail where `sshTransport` is `system-openssh`. Otherwise the built-in client makes them where the app itself can't start the helper. See [This computer won't start Claude's SSH sign-in helper](#this-computer-won%E2%80%99t-start-claude%E2%80%99s-ssh-sign-in-helper).
473* **Firewall and endpoint security**: allow `ssh.exe` outbound wherever you allow Claude Desktop itself. With `sshTransport` unset or `auto` and no `sshClientPath`, the built-in client takes over where Windows refuses to start `ssh.exe`, but not where `ssh.exe` starts and can't reach the network. Each connection that the OpenSSH client makes then fails or times out, and the card points to the network or the host, not to `ssh.exe`.
474* **While `ssh.exe` can't reach the network**: a host that stays on the built-in client still connects. For other hosts, set `sshTransport` to `builtin`, for Windows devices only, until you can allow `ssh.exe` (see **One value for all platforms** below). A host that the device first reaches meanwhile stays on the built-in client afterwards. The session's terminal runs `ssh.exe` with either client, so it stays blocked until then.
475* **Key files**: `ssh` doesn't read a PuTTY `.ppk` key file. Unless the host stays on the built-in client for that file (see **PuTTY key files** above), export the key in OpenSSH format, and have the user select the exported file as the connection's identity file.
394476* **SSH configuration files**: `ssh` reads the user's `~/.ssh/config` itself, and the connection fails if `ssh` rejects the file. In a Command Prompt window on a device, signed in as the user, run the usable client with `-G` and a host, for example `ssh -G build01.corp.example.com`. Use the client's full path if it isn't the first `ssh` on the `PATH`. `ssh` prints the host's settings if it accepts the file, and an error if it doesn't.
395* **Microsoft Store installs**: where Claude Desktop is installed from the Microsoft Store, it can't show `ssh`'s prompts. Use a sign-in method that needs no prompt, such as a key held by the SSH agent, and have users connect to each host once from a terminal before adding it in the app.
396477
478If you set `sshTransport`:
479
480* **One value for all platforms**: `sshTransport` has no per-platform form. A Windows registry policy reaches Windows devices only. A value from a bootstrap server or the Enterprise Admin Console reaches the macOS and Linux devices that it serves too. The device's OpenSSH client already makes the connection there by default, so `builtin` moves them to the built-in client. To change Windows devices alone from a bootstrap server, return the key only in responses that go to them.
481* **Devices with a bootstrap server**: an available [bootstrap response](https://claude.com/docs/third-party/claude-desktop/bootstrap.md) replaces the `sshTransport` and `sshClientPath` that device management sets in the registry, even if it leaves a key out. A response without `sshTransport` puts the device back on the default. A response without `sshClientPath` cancels your pin. Claude Desktop then chooses the client as if you had pinned nothing (see **Client version** above). Where the built-in client connects, the first `ssh` on the user's `PATH` reads the SSH configuration and runs the terminal. Return both keys in the response too. Return a Windows path only in responses that go to Windows devices. `sshClientPath` has no per-platform form either, and SSH connections fail on a macOS or Linux device that gets a Windows path.
482* **Keys that a bootstrap response leaves out**: where a response leaves out `sshTransport` or `sshClientPath` and the registry sets it, Claude Desktop 4.29.0 or later writes a line to `ssh.log` in the [logs directory](https://claude.com/docs/third-party/claude-desktop/data-storage.md#where-data-lives) each time it connects to an SSH host. The line contains `the device profile sets` and names the key.
483* **Devices on the Enterprise Admin Console**: the console's configuration replaces the registry's `sshTransport` and `sshClientPath`, even where the console leaves them unset. Set them in the console too. A client that isn't Microsoft's, or a value that starts with `%LOCALAPPDATA%\`, doesn't connect when it comes from the console. The console's `sshClientPath` reaches its macOS and Linux devices too, and SSH connections fail there under a Windows path. See [Devices that move to an admin console organization](#devices-that-move-to-an-admin-console-organization).
484* **When a change takes effect**: at each host's next connection. An open app takes a change in the registry at its next configuration check. From a bootstrap server or the Enterprise Admin Console, an open app applies a new value only if it is `builtin`, once two configuration checks in a row return it. Other values wait, at the latest, until the app is reopened and has downloaded the configuration. A host that is connected keeps its client until the connection drops, which can take days. To move it at once on a Windows device, have the user quit and reopen Claude Desktop. After a change to the managed configuration the reopened app can fail to rejoin the engine, and a turn that still runs on the host is then cut short, as [How a remote session works](#how-a-remote-session-works) describes. A host that connects before the reopened app has downloaded the configuration goes by the registry's value with a bootstrap server. Where the registry sets none, and with the console, see **Configuration that hasn't loaded** above.
485* **What `builtin` leaves on the device**: going back undoes nothing that was written while the OpenSSH client was in use. Saved passwords and new entries in the user's `known_hosts` file stay. The access list of a private key file that the app tightened stays too, and `ssh.log` recorded that list as it was before. The user's settings don't offer to forget a saved password under `builtin`, but removing the connection deletes it.
486
397487### SSH configuration on the device
398488
399Claude Desktop applies the host's entry in the user's `~/.ssh/config`. With the device's OpenSSH client (the default on macOS and Linux), `ssh` reads the entry itself, so settings such as `ProxyJump`, certificate host keys, and GSSAPI authentication apply, and the app still connects only to the resolved hostname that passed `sshHostAllowlist`. The built-in client (the default on Windows) applies the hostname, port, user, identity file, SSH agent, and `ProxyCommand`.
489Claude Desktop applies the host's entry in the user's `~/.ssh/config`. With the device's OpenSSH client, `ssh` reads the entry itself, so settings such as `ProxyJump`, certificate host keys, and GSSAPI authentication apply, and the app still connects only to the resolved hostname that passed `sshHostAllowlist`. The built-in client applies the hostname, port, user, identity file, SSH agent, and `ProxyCommand`.
400490
401* For hosts behind a bastion, configure a `ProxyJump` or `ProxyCommand`. `ProxyJump` works only when the device's OpenSSH client carries the connection (the default on macOS and Linux). The built-in client refuses it. For the card that the user sees, see [Ask your IT administrator to set sshTransport to system-openssh](#ask-your-it-administrator-to-set-sshtransport-to-system-openssh).
491* For hosts behind a bastion, configure a `ProxyJump` or `ProxyCommand`. `ProxyJump` works only when the device's OpenSSH client carries the connection. The built-in client refuses it. For the card that the user sees, see [Ask your IT administrator to set sshTransport to system-openssh](#ask-your-it-administrator-to-set-sshtransport-to-system-openssh).
402492* A bastion must match `sshHostAllowlist` too. See [Jump hosts and the allowlist](#jump-hosts-and-the-allowlist).
403493* With the device's OpenSSH client, OpenSSH's own host key checking applies. For a host whose key isn't on record yet, where the app can show a prompt, it shows the key's fingerprint, asks the user whether to trust it, and records a trusted key in the user's `known_hosts` file, unless the user's own SSH configuration accepts new keys without asking. The app can't show a prompt on every connection, for example when it reconnects in the background. Distribute the host keys or a host certificate authority to the devices, so that each host's key is on record before users connect. `@cert-authority` entries are honored. A key that differs from the one on record for the host is refused, whatever the entry's `StrictHostKeyChecking` says, unless another setting in the SSH configuration that applies to the host takes that check away, such as `NoHostAuthenticationForLocalhost yes` for a host on a loopback address.
404494* With the device's OpenSSH client, you can keep the app from asking users to trust the key of a host that isn't on record yet. Distribute the host keys in the client's system-wide `known_hosts` file, such as `/etc/ssh/ssh_known_hosts`, or distribute a host certificate authority. Then set `StrictHostKeyChecking yes`, for example under `Host *`, in the client's system-wide configuration file, such as `/etc/ssh/ssh_config`, which also governs other uses of that client, such as `git` over SSH. Where the SSH configuration that applies to a host has `StrictHostKeyChecking yes`, Claude Desktop doesn't ask the user to trust such a key, and `ssh` refuses the host if it can't verify the key. A key that differs from the one on record is handled the same way with or without this setting. The setting doesn't bind the user. By OpenSSH's own rules, `ssh` reads the user's `~/.ssh/config` before the system-wide file and keeps the first value it finds for a setting, so a `StrictHostKeyChecking` line there applies in place of yours. `ssh` also accepts a key that the user adds to their own `known_hosts` file, but under `yes` a connection from a terminal doesn't record the key. A user who picks a host that `ssh` refuses sees "Couldn't connect to" followed by the host, with [SSH host key verification failed](#ssh-host-key-verification-failed) under **View details**.
from line 496
406496* With the built-in client, an identity file protected by a passphrase is skipped, not prompted for. Load it into the SSH agent, or use an unencrypted key. With the device's OpenSSH client, the app asks for the passphrase once the host's key is verified, and skips the key if the user cancels.
407497* With the built-in client, a host reached through a `ProxyCommand` gets the same host key check as a host reached directly. Before Claude Desktop 2.9939.0, the built-in client skipped host key verification for such a host.
408498* With the built-in client, a host connects with its key unchecked when its entry sets `StrictHostKeyChecking no`, sets `UserKnownHostsFile` to `none` or `/dev/null`, and sets no `RevokedHostKeys`. The app shows no password or one-time code prompt for such a host, so it needs a key or SSH agent sign-in.
409* The connection times out after 30 seconds. A larger `ConnectTimeout` in the host entry extends it.
499* The connection times out after 30 seconds. A larger `ConnectTimeout` in the host entry extends it, and then applies to every try.
500* With the device's OpenSSH client on macOS and Linux, a route through a jump host or a `ProxyCommand` gets more time where no `ConnectTimeout` applies, except to a [host that allows one session per connection](#hosts-that-allow-one-session-per-connection). When a user starts a session and the first try times out, the second try has 90 seconds. The time that a sign-in dialog for a `ProxyJump` host is open doesn't count. A jump host's push approval or security key touch counts, and so does anything that a `ProxyCommand` waits for. If a connection still times out while the user types or approves, set a `ConnectTimeout` that leaves time for it. Reconnects that Claude Desktop starts on its own have 30 seconds a try, so a route that is always slow still needs `ConnectTimeout`. Before Claude Desktop 4.4212.0, the second try has 30 seconds, and the dialog's time counts.
410501
411502With either client, the connection that carries the session leaves these settings off, whatever the entry says:
412503
from line 515
424515
425516The client that you name makes the connection only if all of these conditions hold:
426517
427* **Folder**: the program is an `.exe` file under Program Files or Program Files (x86).
518* **Folder**: the program is an `.exe` file under Program Files or Program Files (x86). For a program under a user's `AppData\Local` folder, see [Use an OpenSSH client installed per user](#use-an-openssh-client-installed-per-user).
519* **Links**: with every link and junction on the path followed, the program is still under Program Files or Program Files (x86), and Windows can resolve the path. Before Claude Desktop 4.4212.0, Claude Desktop checked only the path as written, so a client that a junction places outside Program Files stops connecting when the device updates.
428520* **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`.
429521* **`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`.
430522* **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.
from line 525
433525Before you deliver `sshClientPath` and `sshTransport`, check for these devices:
434526
435527* **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.
436* **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.
528* **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. A response that leaves `sshClientPath` out cancels your choice of client, and Microsoft's OpenSSH or the built-in client then connects. 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.
437529
438530If `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.
439531
from line 543
451543* **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.
452544* **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.
453545
546### Use an OpenSSH client installed per user
547
548To have Windows devices connect with an OpenSSH client that your packaging installs under each user's `AppData\Local` folder, such as a per-user copy of Git for Windows, start the value of [`sshClientPath`](https://claude.com/docs/third-party/claude-desktop/configuration#sshclientpath) with `%LOCALAPPDATA%\`, for example `%LOCALAPPDATA%\Programs\Git\usr\bin\ssh.exe`. Such a value also needs [`sshTransport`](https://claude.com/docs/third-party/claude-desktop/configuration#sshtransport) set to `system-openssh`. Requires Claude Desktop 4.4212.0 or later. An earlier version rejects the value, and every SSH connection on that device fails, so deliver the value only to devices that have updated.
549
550> [!WARNING]
551>
552> Install the client under Program Files where your packaging allows it. Under `AppData\Local`, the user, and any program that runs as the user, can replace the client and the files that it loads. On these devices, the user can get around `sshClientPath` and `sshHostAllowlist`. A replaced client also sees SSH passwords and key passphrases, saved passwords included, and everything that the session sends and receives.
553
554Use a per-user client only on devices with one user, not on devices that several users share.
555
556The client makes the connection only if it meets the **Version**, **Source of both settings**, and **Trial start** conditions in [Use the OpenSSH client of Git for Windows](#use-the-openssh-client-of-git-for-windows), and all of these conditions too:
557
558* **Value in machine policy**: `sshClientPath` under `HKLM\SOFTWARE\Policies\Claude` is a string value (`REG_SZ`), not an expandable string (`REG_EXPAND_SZ`), and still starts with the text `%LOCALAPPDATA%\`. The tool that writes the value can expand the variable, so read the value back from the registry.
559* **Same value from the bootstrap server**: on a device with a [bootstrap server](https://claude.com/docs/third-party/claude-desktop/bootstrap.md), set the value in machine policy and in the response. The response replaces machine policy's `sshClientPath` and `sshTransport`, even if it leaves them out, so return both. Claude Desktop accepts the value from a response only if machine policy has the same value, character for character. In JSON, write each backslash twice. Return the value to Windows devices only, because SSH connections fail on a macOS or Linux device that gets it.
560* **No value from the admin console**: Claude Desktop rejects a value that the device gets from an [admin console organization](https://claude.com/docs/third-party/claude-desktop/admin-console.md), even if machine policy has the same value.
561* **Real location**: with every link and junction on the path followed, the client is in `AppData\Local` under the signed-in user's profile folder, and Windows can resolve the path. Claude Desktop checks where the client is, not who can write to its folder, so make sure that no other user can.
562* **No administrator rights**: Claude Desktop runs without administrator rights. It has those rights when it is started as administrator, and it can have them when a service, a scheduled task, or an SSH session starts it. It also has them under the built-in Administrator account, and for an administrator on a device with User Account Control turned off.
563
564If a condition doesn't hold, or `sshTransport` is unset, `auto`, or `builtin`, SSH connections fail with the card "Ask your IT administrator to fix the configured SSH program". Claude Desktop's built-in SSH client tries the connection in one case only, where the per-user client's file exists but Windows won't start it or it gives no answer.
565
566To find the cause, select **View details** on the card and read the line that starts with `ssh:`.
567
568* **The line shows `%LOCALAPPDATA%`**: Claude Desktop rejected the value, and the card says that the program is missing or can't be run, even if it is there. Check the value in machine policy, the bootstrap response, the admin console, `sshTransport`, and administrator rights. To narrow the cause down, search `ssh.log` in the [logs directory](https://claude.com/docs/third-party/claude-desktop/data-storage.md#where-data-lives) on the device for `sshClientPath begins with`. The last line that you find names the cause.
569* **The line shows a path without the variable**: in the path, `~` stands for the user's profile folder. If no line under it starts with `Claude needs:`, the user has no `.exe` file at that path. A path in another account's folder, such as `C:\Windows\System32\config\systemprofile`, means that the tool that wrote the value expanded the variable. A `Claude needs:` line that asks for Program Files means that a link leads out of the user's `AppData\Local` folder, or that the value is a full path without the variable, in the registry or in the bootstrap response.
570* **The line says that `sshClientPath` isn't a local absolute path**: the device runs an earlier version, the registry value is an expandable string, which Claude Desktop doesn't read, or the value has a mistake such as `..` or a second `%`.
571
572With a per-user client, plan for the SSH files, prompts, and sign-ins that [Use the OpenSSH client of Git for Windows](#use-the-openssh-client-of-git-for-windows) describes, and for the following:
573
574* **Application control**: allow the client and the `ssh-keygen.exe` beside the client in your application control policy. If your policy blocks the client, users don't see the card "Ask your IT administrator to fix the configured SSH program". The built-in client tries the connection, and `ssh.log` says that the program gave no answer.
575* **Upgrades**: if the name of the client's folder contains a version number, change the value in machine policy and in the bootstrap response together with each upgrade. Prefer a folder name without a version to a junction, because through a junction Claude Desktop can stop reusing saved SSH passwords.
576* **Moved or mounted profiles**: Claude Desktop looks in `AppData\Local` under the user's profile folder, even where the `LOCALAPPDATA` variable points elsewhere. It refuses a profile folder that is a UNC path, such as `\\server\profiles\user`. Where Windows mounts the profile from a profile container, test one device before you deliver the value to the others.
577* **A changed or removed value**: a running Claude Desktop can keep using the client after you change or remove the value. Have users quit and reopen Claude Desktop.
578
454579## Troubleshoot
455580
456581### Your organization doesn't allow this SSH connection
from line 602
477602
478603The host's key has changed, or it is not in the device's `~/.ssh/known_hosts` and was not trusted in the app (the built-in client never asks). Connect to the host from a terminal on the device to check and record the current key, then retry.
479604
480With the device's OpenSSH client (the default on macOS and Linux), if `StrictHostKeyChecking yes` applies to the host, connecting from a terminal doesn't record its key. Instead, check the key and add it to the system-wide `known_hosts` file, or give the host a certificate from your host certificate authority (see [SSH configuration on the device](#ssh-configuration-on-the-device)).
605With the device's OpenSSH client, if `StrictHostKeyChecking yes` applies to the host, connecting from a terminal doesn't record its key. Instead, check the key and add it to the system-wide `known_hosts` file, or give the host a certificate from your host certificate authority (see [SSH configuration on the device](#ssh-configuration-on-the-device)).
481606
482607### Ask your IT administrator to set sshTransport to system-openssh
483608
484609The built-in client made the connection, and the host needs the device's OpenSSH client. Where the app can name a step, the card's title gives it, and the card's text gives the cause, either "Claude's built-in SSH library can't connect through a jump host (ProxyJump)." or "Claude's built-in SSH library can't check host keys against a certificate authority or another known\_hosts file."
485610
486* **"Ask your IT administrator to set sshTransport to system-openssh"**: the built-in client is the device's default, and the device has a usable OpenSSH client. Set [`sshTransport`](https://claude.com/docs/third-party/claude-desktop/configuration#sshtransport) to `system-openssh`.
611* **"Ask your IT administrator to set sshTransport to system-openssh"**: the built-in client is the device's default, and the device has a usable OpenSSH client. Set [`sshTransport`](https://claude.com/docs/third-party/claude-desktop/configuration#sshtransport) to `system-openssh`. Claude Desktop 4.5284.0 or later doesn't show this title: the OpenSSH client makes the connection instead.
487612* **"Ask your IT administrator to change sshTransport from builtin to system-openssh"**: your configuration sets `sshTransport` to `builtin`. Change it to `system-openssh`.
488613* **"Ask your admin to correct the sshTransport setting"**: the app can't read the value that your configuration gives `sshTransport`, for example a misspelling, so the built-in client makes the connection. Correct the value. Requires Claude Desktop 2.37337.0 or later.
489* **"Ask your IT administrator to install Microsoft OpenSSH 9.4 or newer and set sshTransport to system-openssh, then quit and reopen Claude"**: the built-in client is the device's default, and the app found no usable OpenSSH client on the device. Install the client, and set the key.
490* **"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.
614* **"Ask your IT administrator to install Microsoft OpenSSH 9.4 or newer and set sshTransport to system-openssh, then quit and reopen Claude"**: the built-in client is the device's default, and the app found no usable OpenSSH client on the device. Install the client, and set the key. Claude Desktop 4.5284.0 or later shows the next title instead.
615* **"Ask your IT administrator to install Microsoft OpenSSH 9.4 or newer, then quit and reopen Claude"**: the app found no usable OpenSSH client on the device. Install the client. Before Claude Desktop 4.5284.0, this title appears only where `sshTransport` is `system-openssh`.
616* **"Check your network or VPN and try again, or quit and reopen Claude"**: the device's configuration from the Enterprise Admin Console or a bootstrap server hasn't loaded, so the built-in client made the connection. Requires Claude Desktop 4.5284.0 or later.
491617* **"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)).
492618
493619Where 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`.
from line 620
494620
495621These 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`.
496622
623### Ask your IT administrator to fix the configured SSH program
624
625The program that `sshClientPath` names is missing, can't be run, is too old, or on Windows doesn't meet the conditions for its kind. Claude Desktop never runs another `ssh` in its place. Select **View details** on the card for the program's path. On a Windows device, to find the condition, see [Use the OpenSSH client of Git for Windows](#use-the-openssh-client-of-git-for-windows) or [Use an OpenSSH client installed per user](#use-an-openssh-client-installed-per-user). With no `sshClientPath`, the card appears on a macOS or Linux device where `sshTransport` is `system-openssh` and the device can't start its own `ssh`. A Windows device in that state connects with the built-in client.
626
497627### This computer won't start Claude's SSH sign-in helper
498628
499On a Windows device where the device's OpenSSH client makes the connection, Windows refused to start one of the helper programs through which Claude Desktop shows `ssh`'s prompts. Without them the app can't ask for a password or a one-time code, so the user can't sign in to a host that needs one. Select **View details** on the card for the blocked program's path and the error code. Allow the helper programs as described under [Prepare Windows devices for the OpenSSH client](#prepare-windows-devices-for-the-openssh-client), then have the user try again. Requires Claude Desktop 2.37337.0 or later.
629On a Windows device where the device's OpenSSH client makes the connection, Windows refused to start one of the helper programs through which Claude Desktop shows `ssh`'s prompts. Without them the app can't ask for a password or a one-time code, so the user can't sign in to a host that needs one. In Claude Desktop 4.5284.0 or later, with `sshTransport` unset or `auto`, the [built-in client connects instead](#prepare-windows-devices-for-the-openssh-client) where the app itself can't start the helper, and this card doesn't appear. Select **View details** on the card for the blocked program's path and, where Windows gave one, the error code. Allow the helper programs as described under [Prepare Windows devices for the OpenSSH client](#prepare-windows-devices-for-the-openssh-client), then have the user try again. Requires Claude Desktop 2.37337.0 or later.
500630
501631### This computer's ssh refuses a backslash or dollar sign in user names
502632
from line 642
512642
513643SSH connected, but Claude Desktop couldn't place or start the remote server or the engine on the host. Select **View details** on the failure card to read the app's own message, which can end with a code in square brackets. Match the code, or the start of the message:
514644
515* **`[SFTP_UNAVAILABLE]`**: the host's SSH server refused the SFTP subsystem. Enable `Subsystem sftp` in the server's `sshd_config`.
645* **`[SFTP_UNAVAILABLE]`**: the host's SSH server refused the SFTP subsystem. Enable `Subsystem sftp` in the server's `sshd_config`, or see what a session needs under [Hosts without SFTP](#hosts-without-sftp).
516646* **`[SESSION_LIMIT]`**: the host's SSH server refused to open another session on the connection. If the host has to keep its `MaxSessions` limit, update the macOS or Linux device to Claude Desktop 3.1623.0 or later, and see [Hosts that allow one session per connection](#hosts-that-allow-one-session-per-connection). Otherwise, raise `MaxSessions` in the server's `sshd_config`, for example to OpenSSH's default of 10, and reload the SSH server.
517* **`[SFTP_NOT_STARTED]`**: the host's SSH server accepted the request for SFTP, but the SFTP server ended before its first answer, or text arrived in place of that answer. In a terminal on the device, run `sftp` with the same host, for example `sftp [email protected]`, to see what stops it. Then check the settings and files that the message names.
647* **`[SFTP_NOT_STARTED]`**: the host's SSH server accepted the request for SFTP, but the SFTP server ended before its first answer, or text arrived in place of that answer. In a terminal on the device, run `sftp` with the same host, for example `sftp [email protected]`, to see what stops it. Then check the settings and files that the message names, or see what a session needs under [Hosts without SFTP](#hosts-without-sftp).
518648* **`[EXEC_NO_INPUT]`**: the host's SSH server ran the app's command but passed it no input, which setup and the session's own link need. In a terminal on the device, run `echo hi | ssh` with the same host and `cat`, for example `echo hi | ssh [email protected] cat`. It prints `hi` on a host that passes input. Have the host's administrator let commands run over SSH receive input.
519649* **`[ENOSPC]` or `[EDQUOT]`**: a disk is full, or a quota is used up. In a message that starts with `Couldn't prepare the deploy locally`, the disk is the device's. In any other message it is the host's, so free space in the SSH user's home directory. [Host requirements](#host-requirements) gives the space the app needs.
520650* **`Unsupported remote platform`**: the host's operating system or processor isn't among those under [Host requirements](#host-requirements).
521651* **`[CLI_NOT_RUNNABLE]`**: the remote server installed the engine, but the engine's first run didn't start or didn't exit cleanly, so the remote server removed it. One cause is a glibc older than 2.17. Run `ldd --version` on the host to check. Before Claude Desktop 2.37337.0, the message has no code and starts with `Couldn't install the Claude CLI on the remote (cli archive)`.
522* **`[NO_INSTALL_RESULT]`**: the remote server's install step printed no result. A home directory mounted `noexec` is one cause.
652* **`[NO_INSTALL_RESULT]`**: the remote server's install step printed no result. A home directory mounted `noexec` is one cause, where the host's error message doesn't say `Permission denied` or `Operation not permitted`. Where it does, the code is `[SERVER_NOT_RUNNABLE]`. Before Claude Desktop 4.4212.0, a host with SFTP gets `[NO_INSTALL_RESULT]` in both cases.
653* **`[SETUP_DIR_NOEXEC]`**: on a [host without SFTP](#hosts-without-sftp), the host didn't run a test program from `~/.claude/remote` in the SSH user's home directory, so the app didn't copy the remote server. A home directory mounted `noexec` and a restricted login shell are two causes. Have the host's administrator let the SSH user run programs from `~/.claude/remote`.
654* **`[SERVER_NOT_RUNNABLE]`**: the remote server didn't run from `~/.claude/remote` in the SSH user's home directory, or stopped before it answered. A home directory mounted `noexec` is one cause, and security software on the host that keeps programs from running there is another. Have the host's administrator check that programs can run from that folder. Before Claude Desktop 4.4212.0, the code appears only on a [host without SFTP](#hosts-without-sftp).
655* **`[DOWNLOAD_BUSY]`**: Anthropic's download server answered that it is busy, so Claude Desktop couldn't download the engine or the remote server to the device. Claude Desktop has already waited and asked again. Have the user try again in a few minutes. If the code keeps coming back, check whether a proxy on the device's network limits downloads from `downloads.claude.ai`, because a proxy can give the same answer.
523656
524657`[SESSION_LIMIT]` and `[SFTP_NOT_STARTED]` require Claude Desktop 2.31226.0 or later, and appear only when the device's OpenSSH client makes the connection. `[SESSION_LIMIT]` appears only on macOS and Linux devices. Their cards are titled `<host> allows too few SSH sessions per connection` and `SFTP doesn't start on <host>`.
525658
526`[CLI_NOT_RUNNABLE]` and `[EXEC_NO_INPUT]` require Claude Desktop 2.37337.0 or later. `[EXEC_NO_INPUT]` appears only on Windows devices where the device's OpenSSH client makes the connection. Their cards are titled `Claude Code didn't run on <host>` and `<host> doesn't pass input to commands run over SSH`. From the same version, the card is titled `Couldn't copy Claude Code to <host>` where the app couldn't put its files on the host, and `Couldn't install Claude Code on <host>` where the engine's install failed, each for a cause with no card of its own.
659`[CLI_NOT_RUNNABLE]` and `[EXEC_NO_INPUT]` require Claude Desktop 2.37337.0 or later. `[EXEC_NO_INPUT]` appears only where the device's OpenSSH client makes the connection. Their cards are titled `Claude Code didn't run on <host>` and `Ask <host>'s administrator to let SSH commands receive input`. From the same version, the card is titled `Couldn't copy Claude Code to <host>` where the app couldn't put its files on the host, and `Couldn't install Claude Code on <host>` where the engine's install failed, each for a cause with no card of its own.
660
661Before Claude Desktop 4.29.0, the `[EXEC_NO_INPUT]` card is titled `<host> doesn't pass input to commands run over SSH`.
662
663`[SETUP_DIR_NOEXEC]` and `[SERVER_NOT_RUNNABLE]` require Claude Desktop 3.1623.0 or later. Their card is titled `Ask <host>'s administrator to let Claude's server run`.
664
665`[DOWNLOAD_BUSY]` requires Claude Desktop 4.4212.0 or later, and its card is titled `Try again in a few minutes`. Before Claude Desktop 4.4212.0, the card for `[SETUP_DIR_NOEXEC]` and `[SERVER_NOT_RUNNABLE]` is titled `Claude's server didn't run on <host>`.
527666
528667### Git commands fail with Read-only file system
529668
third-party/claude-desktop/data-storage Changed · +1 / -1 lines
from line 43
4343
4444Files in this directory are written with owner-only permissions so other OS accounts on the same machine cannot read them. The app encrypts stored sign-in tokens, API keys saved from the in-app configuration window, and similar secrets with the operating system's secure storage (see [Credentials](#credentials)). It doesn't encrypt conversations, settings, or the rest of the locally applied configuration. Protection at rest for those files depends on the device's full-disk encryption, such as FileVault or BitLocker.
4545
46The logs directory contains `main.log` (application and configuration-validation events), `cowork_vm_node.log` (sandbox VM activity), `claude.ai-web.log` (renderer events), and `mcp.log` / `mcp-server-<name>.log` (MCP connection events).
46The logs directory contains `main.log` (application and configuration-validation events), `ssh.log` (SSH connection events), `cowork_vm_node.log` (sandbox VM activity), `claude.ai-web.log` (renderer events), and `mcp.log` / `mcp-server-<name>.log` (MCP connection events).
4747
4848Separately from the application-data directory, Claude Desktop writes user-visible outputs (Artifacts and scheduled-task results) to `~/Claude/` in your home directory, or `~/Documents/Claude/` on legacy installs. This folder is intended for you to browse directly and is not removed when you delete the application-data directory. To back up a user's data, copy every location listed under [Copy the data to the new device](#copy-the-data-to-the-new-device).
4949