SSH remote sessions in Claude Desktop on 3P

​

How a remote session works

1. 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 to change either default), applies the host’s entry from the device’s ~/.ssh/config (see SSH configuration on the device), and prompts in the app if the host asks for a password or a one-time code.
2. 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 lists every path) and reuses them on later connections.
3. 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 from the device and exposes them to the engine as tools.
4. 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.

• Rejoins: on a macOS or Linux device, Claude Desktop 2.42304.0 or later tries to rejoin an engine that 2.42304.0 or later started. If it rejoins, a turn still running goes on. It can fail to rejoin, for example after some Claude Desktop updates or after a change to the managed configuration since the engine started. After a quit it never rejoins on a Windows device, and never rejoins an engine that an earlier version started.
• Replaces: otherwise, Claude Desktop ends the engine and starts a fresh one from the transcript stored on the host. A turn that finished while the app was closed is shown in full, and a turn that still runs is cut short. If the turn stays stopped, the user sends a message to continue it.

• The user archives or deletes the session.
• The user reopens the session and Claude Desktop ends the engine to start a fresh one.
• The host restarts.
• 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.
• 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.
• 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. There the engine is called Claude Code, and the remote server the helper.

• File tools under a folder restriction: if you set allowedWorkspaceFolders, Claude Desktop checks each file read, search, and edit before it happens. While Claude Desktop is disconnected, each of these calls waits up to 10 minutes and then fails.
• Tools that your policy sets to ask: if builtinToolPolicy sets a bare tool name, such as Bash, to ask, Claude Desktop is consulted before each call to that tool. While Claude Desktop is disconnected, each call waits up to 10 minutes and then fails.
• Tools from MCP servers that run on the device: these include your managed MCP servers (see Where MCP servers run in a remote session). While Claude Desktop is disconnected, each call to one of their tools fails after about 30 seconds. The 30-second limit requires Claude Desktop 2.2553.0 or later.

​

Account that a remote session runs under

​

Alert the user with hooks on the host

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [{ "type": "command", "command": "/path/to/alert-user.sh" }]
      }
    ],
    "Stop": [
      { "hooks": [{ "type": "command", "command": "/path/to/alert-user.sh" }] }
    ],
    "StopFailure": [
      { "hooks": [{ "type": "command", "command": "/path/to/alert-user.sh" }] }
    ]
  }
}

• A permission prompt waits for the user’s answer: the Notification hook runs once the prompt has waited about six seconds
• Claude finishes responding: the Stop hook runs
• An API error, such as an authentication error, ends the turn: the StopFailure hook runs in place of Stop

• Each file read, search, and edit, if you set allowedWorkspaceFolders
• Each call to a tool that builtinToolPolicy sets to ask by its bare name, such as Bash
• Each call to a tool from an MCP server that runs on the device

​

Where MCP servers run in a remote session

• Managed MCP servers, and servers from plugins in the org-plugins directory: the device. Claude Desktop connects to the remote (HTTP or SSE) MCP servers and starts the local (stdio) ones on the device, and exposes them to the engine as tools.
• Local servers that a user adds under Settings > Developer: the host, not the device. Claude Desktop sends the host a server’s command, its arguments, and only those of its environment variables whose names start with MCP_ or are one of a few fixed logging and runtime names, such as DEBUG and NODE_ENV. A secret in an argument or in an MCP_ variable reaches the host. On a Linux or macOS host, Claude Desktop leaves out a server whose command is a path under a macOS or Windows folder, such as /Applications/ or C:\.
• 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.
• 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.

​

Enable SSH remote sessions

• *.dev.example.com matches dev.example.com and any subdomain of it at any depth.
• Matching is case-insensitive and ignores a user@ prefix.
• An IP address entry matches only that address.
• Entries do not restrict the port.
• A value that is not an array of strings counts as [].

{
  "sshHostAllowlist": ["*.dev.example.com"]
}

​

Interaction with Claude Code managed settings on the device

1. sshHostAllowlist from the Claude Desktop configuration, when that configuration is delivered by an administrator: through machine-scoped device management (HKLM policy on Windows, a configuration profile on macOS, /etc/claude-desktop on Linux), through the Enterprise Admin Console, or by a bootstrap server the app trusts (a bootstrapUrl set through device management or covered by trustBootstrapDelivery; see Keys that require user consent). User-scope registry policy (HKCU) counts as applied locally.
2. sshHostAllowlist from Claude Code’s managed settings on the device.
3. sshHostAllowlist from a Claude Desktop configuration the user applied locally in the in-app configuration window.
4. Off.

​

Devices that move to an admin console organization

• 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.
• Which SSH client: the console’s sshTransport and sshClientPath apply. A key that the console leaves unset takes its default under Host requirements. Until the app has downloaded the console’s configuration at a launch, both keys count as unset.

• Keep the device on its profile: set disableDeploymentModeChooser to true. The app ignores the admin console, and the sign-in screen doesn’t offer Or sign in with Claude.ai. A device that has already moved returns to its profile at its next launch.
• Allow only your organization: set forceLoginOrgUUID to your organization ID, and set the SSH keys you rely on in the console too. The key also limits standard Claude Desktop sign-in on the device to your organization.

​

Inference credentials on the remote host

​

Managed configuration on the remote host

• disableEssentialTelemetry and disableNonessentialTelemetry.
• otlpEndpoint, otlpProtocol, otlpHeaders, otlpResourceAttributes, and otlpContentCapture. Remote sessions appear in your collector under the same service.name as local Code sessions. A collector at localhost on the device is not forwarded. An otlpHeadersHelper runs on the device at session start, and the remote session keeps those headers for its lifetime.
• disabledBuiltinTools, builtinToolPolicy, autoModeEnabled, and disableBypassPermissionsMode.
• allowedWorkspaceFolders, evaluated against the host’s filesystem. ~ is the SSH user’s home on the host, %VAR% entries are ignored, and Claude Desktop refuses to start a session in a directory outside every entry, so with a fleet value such as ~/Documents/Claude, remote sessions start only under that path in the SSH user’s home. For an entry with mode set to ro, see Read-only folders on the remote host.
• blockReadsOutsideWorkingDirectories, evaluated on the host, so the working directories and the home directory it hides from shell commands are the SSH user’s there. Hiding files from shell commands needs the host’s sandbox dependencies (next item); on a host without them, or a Windows host, shell reads outside the working directories ask for approval instead, and the file-tool restriction applies regardless. Files a user attaches to a remote session stay readable, except on a Windows host, where the session’s plugin files and attachments stay outside the file tools’ reach under this key.
• coworkEgressAllowedHosts, as Claude Code managed settings. The network and filesystem sandbox it produces with allowedWorkspaceFolders depends on the host having Claude Code’s sandbox dependencies installed (see Claude Code sandboxing). Without them, commands run unsandboxed. See Sandbox status on the remote host for the message the session shows.
• managedMcpServers, as the Claude Code managed setting that keeps the session from loading MCP servers that users define in Claude Code’s own configuration on the host. The managed servers themselves are reached from the device (see Where MCP servers run in a remote session).
• Plugins from your allowed marketplaces, copied to the host. A plugin’s hooks directory is not copied, so its hooks do not run in a remote session, and a plugin whose manifest declares hooks elsewhere is not copied at all.

​

Read-only folders on the remote host

• Windows hosts.
• Hosts with their own Claude Code managed settings: Claude Code ignores the rules, and the sandbox settings that Claude Desktop supplies with them, unless those settings set parentSettingsBehavior to "merge". Under "merge" the host’s own values still win where the two differ, so sandbox.enabled set to false there leaves shell commands unsandboxed (see Interaction with Claude Code’s own managed settings).
• An entry that is or contains the SSH user’s ~/.claude folder, such as ~: Claude Code keeps its own files there. List narrower folders.

• Claude’s file tools: they refuse to create or change a file under the path, even in bypass permissions mode. A writable entry listed inside a read-only one is read-only for them too.
• Shell commands that Claude runs with its Bash tool: Claude Code’s sandbox keeps them from writing under the path on a host where it runs, which on Linux needs Claude Code’s sandbox dependencies. The sandbox doesn’t cover commands listed in Claude Code’s sandbox.excludedCommands, or a path that contains one of * ? [ ] ( ) { } | + or a double quote. It may not stop commands in a folder that is listed through a symbolic link, so list each read-only folder by its real path, and keep it outside writable entries. On a host where the sandbox doesn’t run, shell commands can still change the folder. For how the app reports that, see Sandbox status on the remote host.

​

Sandbox status on the remote host

• On · Strict: no reason. Claude Code reports the sandbox from your policy turned on and running.
• Off · can’t start: cannot_start or unsupported
• Off: overridden, and Claude Code reports no sandbox running
• On · not fully applied: overridden, and Claude Code reports a sandbox that Claude Desktop can’t match to your policy
• Couldn’t check: unknown

• reason: cannot_start, unsupported, overridden, or unknown
• sandbox_on: false when Claude Code reports no sandbox running, true when it reports one that Claude Desktop can’t match to your policy, and absent when Claude Code doesn’t say
• session_id: Claude Desktop’s ID for the session
• backend_kind: ssh

​

Host requirements

• Linux or macOS on x86_64 or arm64, or Windows on x64 or arm64.
• 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 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.
• 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.
• An SSH server that accepts several sessions on one connection. The device’s OpenSSH client on macOS and Linux, and the built-in client, open a remote session’s channels on one SSH connection, so MaxSessions 1 in the server’s sshd_config doesn’t work. OpenSSH’s default is 10. 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.
• A POSIX shell, or PowerShell on Windows.
• git on the path, for git features.
• 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.

• 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.
• 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.

• 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 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.
• 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). Blocking them does not affect the session.

​

SSH configuration on the device

• 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.
• 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.
• 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 under View details.
• With the built-in client, the host’s key must already be in the device’s ~/.ssh/known_hosts as a plain entry. The app does not prompt to accept a new key and does not evaluate @cert-authority entries, so have users connect once from a terminal before adding the host in the app.
• 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.
• 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.
• 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.
• The connection times out after 30 seconds. A larger ConnectTimeout in the host entry extends it.

• Forwarding: ForwardAgent, ForwardX11, Tunnel, LocalForward, RemoteForward, and DynamicForward.
• Kerberos delegation: GSSAPIDelegateCredentials. The host doesn’t receive the user’s Kerberos ticket over this connection, even where the entry says GSSAPIDelegateCredentials yes. A ProxyJump host is reached by a separate ssh, which applies the jump host’s own entry.
• Commands: RemoteCommand and LocalCommand.

​

Troubleshoot

​

Your organization doesn’t allow this SSH connection

​

SSH to this device isn’t available

​

SSH sessions can’t use your model provider settings

​

SSH host key verification failed

​

Ask your IT administrator to set sshTransport to system-openssh

• “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 to system-openssh.
• “Ask your IT administrator to change sshTransport from builtin to system-openssh”: your configuration sets sshTransport to builtin. Change it to system-openssh.
• “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.
• “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.
• “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.
• “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).

​

This computer won’t start Claude’s SSH sign-in helper

​

This computer’s ssh refuses a backslash or dollar sign in user names

• needs the Include line in this file to use a full path: the system’s ssh_config, or a file read through it, has an Include with a relative path. The line names the file. Write that path in full, starting with /.
• couldn't find which system ssh_config this ssh reads or couldn't write that file: have the user try again. With the second, the app couldn’t write the file in a private temporary folder.
• the name is the jump host's: the card’s title is “This computer’s ssh refuses the jump host’s user name”. In the user’s ~/.ssh/config, move the name from ProxyJump to a User line in the jump host’s own Host block.

​

Setup on the host fails after SSH connects

• [SFTP_UNAVAILABLE]: the host’s SSH server refused the SFTP subsystem. Enable Subsystem sftp in the server’s sshd_config.
• [SESSION_LIMIT]: the host’s SSH server refused to open another session on the connection. Raise MaxSessions in the server’s sshd_config, and reload the SSH server. See Host requirements.
• [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 user@build01.corp.example.com, to see what stops it. Then check the settings and files that the message names.
• [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 user@build01.corp.example.com cat. It prints hi on a host that passes input. Have the host’s administrator let commands run over SSH receive input.
• [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 gives the space the app needs.
• Unsupported remote platform: the host’s operating system or processor isn’t among those under Host requirements.
• [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).
• [NO_INSTALL_RESULT]: the remote server’s install step printed no result. A home directory mounted noexec is one cause.

​

Git commands fail with Read-only file system

​

Related

• Code in Claude Desktop on 3P
• sshHostAllowlist in the configuration reference
• Desktop and filesystem access