[DOCS] Desktop SSH sessions page doesn't mention Linux-only host requirement

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/desktop

Section/Topic

"SSH sessions" subsection under "Environment configuration"

Current Documentation

The docs currently say:

SSH sessions let you run Claude Code on a remote machine while using the desktop app as your interface. This is useful for working with codebases that live on cloud VMs, dev containers, or servers with specific hardware or dependencies.

And later:

Once added, the connection appears in the environment dropdown. Select it to start a session on that machine. Claude runs on the remote machine with access to its files and tools.

No platform requirements for the remote host are mentioned anywhere in the SSH sessions section.

What's Wrong or Missing?

Claude Desktop SSH sessions only support Linux remote hosts. Connecting to a macOS (darwin) host produces the error:

"Unsupported remote platform: darwin. Only Linux hosts are supported for SSH connections."

This limitation is not documented. The SSH section describes "remote machines" generically, and the examples ("cloud VMs, dev containers, or servers") are typically Linux but not exclusively so. Users with macOS servers, Mac Studios, or Mac Minis used as remote development machines will encounter this error with no prior warning.

The "What's not available in Desktop" section at the bottom of the page lists several limitations but does not include this one.

Suggested Improvement

Option A: Add a note to the SSH sessions section

Add after the introductory paragraph:

Note: SSH sessions require a Linux remote host. macOS and Windows hosts are not supported. If you see "Unsupported remote platform: darwin," this means the remote machine is running macOS. As a workaround, SSH into the machine from your terminal and run claude directly.

Option B: Add to the "What's not available in Desktop" section

Add a bullet to the existing limitations list:

* SSH to macOS/Windows hosts: SSH sessions only support Linux remote hosts. macOS (darwin) and Windows remote machines are not supported. Use the terminal to SSH into non-Linux machines and run Claude Code directly.

Recommended: Both Option A and Option B. The limitation should appear where users configure SSH (to prevent wasted setup) and in the limitations summary (for discoverability).

Impact

High — Prevents users from using a feature. Users complete the full SSH setup flow (enabling Remote Login, adding the connection, confirming the security prompt) before discovering the limitation. The error appears only after clicking "Connect," with no way to know beforehand that macOS hosts are unsupported.

Additional Context

Affected Pages:

| Page | Section | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/desktop | SSH sessions | No mention of Linux-only host requirement |
| https://code.claude.com/docs/en/desktop | What's not available in Desktop | Missing from limitations list |

Total scope: 1 page, 2 sections

Reproduction steps:

1. Enable Remote Login on a macOS machine (System Settings → General → Sharing)
2. In Claude Desktop on another Mac, add an SSH connection to the macOS host
3. Confirm the "Connect to SSH host?" prompt
4. Observe error: "SSH connection failed" / "Unsupported remote platform: darwin. Only Linux hosts are supported for SSH connections."

Related precedent: The same page already documents a similar platform limitation for Windows ARM64: "ARM64 limitations: Windows ARM64 devices can run the desktop app but do not support local sessions. Use Remote sessions instead." The SSH Linux-only limitation deserves the same treatment.