[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:
- Enable Remote Login on a macOS machine (System Settings → General → Sharing)
- In Claude Desktop on another Mac, add an SSH connection to the macOS host
- Confirm the "Connect to SSH host?" prompt
- 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.
5 Comments
Hey — I'd be happy to submit a PR for this, but the docs (desktop.md) don't appear to be in the open-source repo. If there's a docs repo or contribution path I'm missing, let me know and I'll send a PR.
In the meantime, here are the exact copy suggestions:
1. SSH sessions section — add after intro paragraph
2. "What's not available in Desktop" section — add bullet
Both placements mirror the existing pattern for ARM64 limitations already on that page.
Issue #25804 Verification
Title: [DOCS] Desktop SSH sessions page doesn't mention Linux-only host requirement
Issue Date: 2026-02-14
Verification Date: 2026-03-17
Status: PARTIALLY RESOLVED
---
Issue Summary
This issue reports that the SSH sessions documentation does not explicitly state that the remote host must be running Linux.
---
Verification Results
Claim 1: No mention of Linux-only host requirement in SSH section
Status: PARTIALLY RESOLVED
At https://code.claude.com/docs/en/desktop, the SSH sessions section states:
The section describes use cases ("cloud VMs, dev containers, or servers") which implicitly suggest Linux, but does not explicitly state "Linux-only" or "Linux host required." The only explicit Linux mention in the page is in a separate "What's not available in Desktop" section referring to the desktop app client, not the SSH host.
Verdict: The docs mention that Claude Code must be installed on the remote machine, which partially addresses the requirement (since Claude Code CLI only supports Linux/macOS). However, there is no explicit "Linux host required" statement in the SSH section.
---
Current State
| Claim | Status |
|-------|--------|
| No Linux-only host requirement stated | PARTIALLY RESOLVED — says "must be installed" but doesn't state Linux explicitly |
---
References
---
Conclusion & Recommendation
Primary Concern: SSH docs don't explicitly state the remote host must be Linux.
Resolution Status: PARTIALLY RESOLVED
Recommendation: KEEP OPEN
The "must be installed on the remote machine" note partially addresses this, but an explicit platform requirement would prevent user confusion.
I rechecked the current desktop docs today and the SSH section still doesn't mention that remote hosts must be Linux. This still looks open, since macOS SSH targets would still fail with the darwin platform error and no prior warning.
Issue #25804 Verification
Title: [DOCS] Desktop SSH sessions page doesn't mention Linux-only host requirement
Issue Date: 2026-02-14
Verification Date: 2026-04-27
Status: RESOLVED
Issue Summary
The issue reported that the SSH sessions section on the Desktop docs page did not mention platform requirements for remote hosts. Users connecting to macOS (darwin) hosts received the error "Unsupported remote platform: darwin. Only Linux hosts are supported for SSH connections" with no prior warning in the documentation.
Verification Results
Claim 1: No platform requirements mentioned in SSH sessions section
docs/code.claude.com/docs/en/desktop.md:540now explicitly state: "The remote machine must run Linux or macOS. Desktop installs Claude Code on the remote machine automatically the first time you connect."6784268), which changed the previous text ("Claude Code must be installed on the remote machine") to include the explicit platform requirement.Claim 2: Missing from "What's not available in Desktop" limitations section
Claim 3: Users get "Unsupported remote platform: darwin" error with no warning
Current State
| Aspect | Before Issue | Current State |
|--------|-------------|---------------|
| Platform requirement in SSH section | Not mentioned | "The remote machine must run Linux or macOS" (line 540) |
| Auto-install wording | "Claude Code must be installed on the remote machine" | "Desktop installs Claude Code on the remote machine automatically the first time you connect" |
| "What's not available" section | No SSH limitation | No SSH limitation (appropriate — macOS is now supported) |
Suggested Fix
N/A — The documentation has been updated to address all concerns raised in the issue.
References
desktop.md:540— "The remote machine must run Linux or macOS. Desktop installs Claude Code on the remote machine automatically the first time you connect."6784268(2026-04-14)Conclusion & Recommendation
Primary Concern: The SSH sessions section lacked platform requirement documentation, causing users to discover macOS incompatibility only after completing the full SSH setup flow.
Resolution Status: RESOLVED. The docs now explicitly state "The remote machine must run Linux or macOS" in the SSH sessions section (line 540). Additionally, macOS SSH support appears to have been added, resolving both the documentation gap and the underlying platform limitation.
Recommendation: Close as completed. Both suggested improvements from the issue (Option A: note in SSH section, and implicitly Option B: no longer needed as a limitation) have been addressed.
This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.