Short answer: Claude Code SSH means the agent runs on a remote machine (VPS, home mini, cloud VM) while you type from a laptop or phone. In 2026 you have three practical lanes: (1) Claude Desktop’s built-in SSH environment, (2) plain SSH into a tmux session that keeps claude alive, and (3) VS Code Remote-SSH with the Claude Code extension. Pick Desktop if you want a GUI and Anthropic’s installer on the host. Pick tmux if you need sessions that survive Wi‑Fi drops and phone check-ins. Treat VS Code Remote as the editor layer, not the process supervisor.
Last updated: November 7, 2026. Desktop SSH and host requirements come from Anthropic’s Claude Desktop / Code docs (including the third-party SSH remote sessions page). CLI install commands come from code.claude.com/docs setup. VS Code Remote-SSH notes come from Microsoft’s docs. Forum notes are paraphrased from recent r/ClaudeCode, r/ClaudeAI and HN threads. I used Claude Code heavily in the past; I do not have a Claude subscription now. Commands labeled “preflight on this Linux test machine” were run here only. I did not SSH into a production project server for this post.
What people mean by “Claude Code SSH”
Searchers usually want one of these outcomes:
- Code lives on a server (GPU box, always-on Mini, Hetzner VPS) and the agent should edit files there, not on a thin laptop.
- The agent keeps working after the laptop sleeps (long refactors, test loops, PR cleanup).
- Phone or cafe laptop access without copying the repo around.
Those are related but not identical. Desktop SSH and the CLI-on-host path put Claude Code on the remote filesystem. Anthropic’s Remote Control feature is different: the session still runs on a machine you own, and your phone or browser is a window into it (docs: claude remote-control / /remote-control). You can combine them (SSH into a box, start Claude inside tmux, then enable Remote Control), but SSH alone does not equal Remote Control.
If you are still choosing the product itself, see OpenClaw vs Claude Code and Claude Code pricing. This post assumes you already know you want Claude Code on a remote host.
The three lanes (pick one primary)
| Lane | Where Claude runs | Survives client disconnect? | Best for |
|---|---|---|---|
| Claude Desktop SSH | Host under ~/.claude/remote/ (Desktop installs it) | Often yes for the current turn (engine can idle on host); credential refresh needs Desktop open | Solo founders who want a GUI + folder picker |
| SSH + tmux + CLI | Your install of claude inside tmux | Yes, as long as the host stays up | Phone check-ins, flaky Wi‑Fi, always-on Mini/VPS |
| VS Code Remote-SSH | Extension host + CLI on the remote | No by default for extension-started sessions (client drop kills the extension host) | Editing + IntelliSense on remote code; use tmux for long agent runs |
Indie threads on r/ClaudeCode and r/ClaudeAI keep landing on the same stack for lane 2: Tailscale (private mesh) + SSH keys + tmux, sometimes with Mosh or Eternal Terminal when networks change a lot. HN write-ups of “local-feeling remote” setups repeat the same idea: keep Claude on an always-on box, treat the phone as a keyboard.
Lane 1: Claude Desktop SSH environment
Official Desktop docs (Code tab → environment selector) list SSH next to Local, Cloud, and WSL. Flow:
- Open New environment → SSH tab.
- Add SSH connection… with a friendly name,
user@hostname(or a Host from~/.ssh/config), optional port and key path, optional remote worktree folder. - Pick a folder on the host → Create environment.
- First connect: Desktop installs Claude Code on the remote under
~/.claude/remote/(about 1 GB free home space; home must not be mountednoexec).
Remote host requirements (from Anthropic’s SSH docs, paraphrased):
- Linux / macOS on x86_64 or arm64, or Windows on x64 / arm64
- Linux: glibc 2.17+ or musl (Alpine needs extra packages; see setup docs)
- SSH server with SFTP subsystem (
Subsystem sftpinsshd_config) - Writable home; POSIX shell or PowerShell on Windows
- Network from the host to your inference endpoint (Claude Code requests leave from the remote machine)
Enterprise / third-party Desktop builds may need an admin sshHostAllowlist before SSH environments appear. Consumer Claude.ai Desktop users usually just add the host.
Pitfalls I would watch for (from the docs + forums):
- **
MaxSessions 1** on the server: Desktop may need multiple sessions per connection. RaiseMaxSessionsor use a client/version that supports the limit. - Jump hosts / bastions: configure
ProxyJumpin~/.ssh/config. On managed Desktop, every hop may need to be allowlisted. - KillUserProcesses=yes (systemd-logind): the remote engine can die when SSH disconnects. Ask the host admin to exempt your user, or use lane 2 with a user systemd lingering / tmux under a lingering session.
- Permissions: the engine runs as the SSH user. Review that user’s
sudo, deploy keys, and DB credentials the same way you would for a human intern. Pair with hooks if you need alerts when a permission prompt waits (Claude Code hooks examples).
Desktop SSH is the cleanest “I just want it to work” path when you still use Claude Desktop day to day.
Lane 2: SSH + tmux + Claude CLI (the indie default)
This is the setup most Reddit / HN posts describe when someone asks “anyone running Claude Code over SSH from a thin client?”
On the remote host
# Install Claude Code (official native installer)
curl -fsSL https://claude.ai/install.sh | bash
# New shell, then:
claude --version
# expect something like: 2.1.x (Claude Code)
# Persist sessions across disconnects
sudo apt install tmux # or brew install tmuxFirst login often needs a browser. Do that once on the host (or with SSH port forward / claude auth flow your plan supports). Later SSH sessions reuse the stored login.
Start a durable session
tmux new -s claude
cd ~/src/your-app
claude
# Detach without killing Claude: Ctrl-b, then dReattach from any device:
ssh youruser@your-host
tmux attach -t claude
# or: tmux new -A -s claudeOptional ~/.ssh/config on your laptop so one host drops you straight into tmux:
Host claude-dev
HostName 100.x.y.z
User youruser
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
ServerAliveInterval 30
ServerAliveCountMax 3
# Uncomment to land in tmux automatically:
# RequestTTY yes
# RemoteCommand tmux new -A -s claudeNetworking: prefer Tailscale over public port 22
Forum consensus is boring and correct:
- Install Tailscale on the host and on your phone / laptop.
- SSH to the Tailscale MagicDNS name or
100.xaddress. - Keep password login off; keys only.
- Do not expose OpenSSH to the whole internet unless you enjoy ban lists.
Optional upgrades people mention: Mosh (UDP, survives sleep) or Eternal Terminal on bad cafe Wi‑Fi; Termius / Echo / similar apps on iOS.
Permissions on the remote
Do not start with YOLO on a shared VPS. When I used Claude Code, I treated remote boxes as more dangerous than a laptop: one bad rm hits the only copy of the repo. Prefer:
- A dedicated Linux user for agent work
- Read-only deploy keys where possible
- Project
CLAUDE.mdthat forbids production deploys (CLAUDE.md template) - Explicit permission prompts, or a container / worktree, before YOLO mode
Copy-paste starter prompt once you are attached:
You are working over SSH on a remote Linux box. Rules:
1) Stay inside this git repo. No sudo unless I ask.
2) Prefer git worktrees for experimental branches.
3) Before any destructive shell command, show the exact command and wait.
4) After edits, run the project's existing test/lint script if present.
5) Summarize files changed at the end of each turn.Lane 3: VS Code Remote-SSH + Claude Code
Microsoft’s Remote-SSH extension opens a remote folder with the VS Code Server on the host. The Claude Code extension installs on the remote, not on your laptop UI. Sign-in, ~/.claude, MCP servers, and the claude CLI all live on that host.
Practical setup:
- Prove
ssh user@hostworks in a normal terminal first. - Command Palette → Remote-SSH: Connect to Host… → open the project folder.
- Extensions → install Claude Code (in the remote window it should appear under the SSH host’s installed list).
- From the integrated terminal, still install the CLI if you want PATH access:
curl -fsSL https://claude.ai/install.sh | bashAnthropic’s own note (repeated in community guides): installing the extension does not put claude on your shell PATH.
The big VS Code pitfall
Community reports (and tooling built around the problem) agree: a Claude session started from the extension is parented by the VS Code extension host. When your laptop disconnects long enough for that host to die, the agent dies with it. Raising remote.SSH.reconnectionGraceTime only delays the funeral.
Workarounds that actually match how Claude Code works:
- Run long jobs in a tmux CLI session on the host (lane 2), use VS Code only as the editor.
- Or turn on Remote Control (
/remote-control) so you can steer from claude.ai / the phone while the process stays on the host (still needs the host process alive; wrap with tmux if you SSH’d in). - Forward ports in VS Code when you need to browse a remote
localhost:3000on your laptop (Remote-SSH Ports view).
Tunnel and jump-host pitfalls
| Symptom | Likely cause | Fix |
|---|---|---|
| Desktop / SSH hangs at connect | Bastion needs interactive OTP every hop | Use key+agent auth; reduce hops; raise ConnectTimeout |
| Works in terminal, fails in Desktop | Built-in SSH client vs system OpenSSH differences | Prefer system OpenSSH; fix ProxyJump in ~/.ssh/config |
| Auth works, agent can’t reach API | Host firewall / no egress | Open HTTPS from the host, not only from your laptop |
| Session dies on disconnect | KillUserProcesses or no tmux | tmux + lingering, or Desktop engine with logind exemption |
| SFTP fails, shell works | Subsystem sftp disabled | Enable SFTP (Desktop uses it for install/transfer) |
| Double CPU / file watchers | Local + remote extensions both indexing | Trim remote extensions; keep heavy ones remote-only |
For a jump host in OpenSSH:
Host bastion
HostName bastion.example.com
User you
IdentityFile ~/.ssh/id_ed25519
Host private-dev
HostName 10.0.0.12
User you
ProxyJump bastion
IdentityFile ~/.ssh/id_ed25519Test with ssh private-dev before you wire Desktop or VS Code to the same Host name.
Remote preflight checklist (run on the host)
I keep a small stub script for this. On this Linux test machine it printed: user box, tmux 3.5a, git 2.47.3, home writable, no ssh client package and no claude CLI installed (labeled preflight only).
#!/usr/bin/env bash
set -euo pipefail
echo "user=$(whoami) host=$(hostname)"
command -v claude && claude --version || echo "install claude first"
command -v tmux && tmux -V || echo "install tmux"
command -v git && git --version || echo "install git"
df -h "$HOME" | tail -1
# From your laptop (not on the host): sftp user@hostIf home is noexec or almost full, Desktop SSH install will fail in confusing ways. Fix disk and mount options before debugging the app.
My take (past Claude Code use)
When I still ran Claude Code daily, SSH was less about “remote magic” and more about where the files and credentials live. A thin Windows laptop + a Linux box with the real toolchain beat fighting path and permission issues locally. The setups that failed were the ones that mixed layers: VS Code Remote for a six-hour agent loop, or YOLO on a jump host that also held production keys.
What I would do as a solo founder in 2026:
- Always-on Mini or small VPS on Tailscale.
tmux+ CLI for anything longer than a coffee.- Desktop SSH when I want diffs and a mouse.
- VS Code Remote for reading code, not for babysitting the agent process.
- Same security checklist energy as a vibe-coded launch (security checklist).
If you want a fully local / offline agent instead of a remote cloud subscription, that is a different post: local AI agent.
FAQ
Is Claude Code SSH the same as Remote Control?
No. SSH decides which machine runs the engine. Remote Control decides whether your phone or browser can steer a session that is already running on a machine you own. Docs cover claude remote-control and /remote-control separately from Desktop SSH environments.
Can I run Claude Code on a headless VPS with no desktop?
Yes. Install the CLI, authenticate once, run under tmux. You do not need a GUI on the VPS. Desktop SSH is optional sugar if you use Claude Desktop locally.
Does VS Code Remote-SSH keep Claude running after I close my laptop?
Not reliably for extension-started sessions. Use tmux (or Desktop’s remote engine behavior) for persistence. See the pitfall section above.
What about WSL?
Desktop also offers a WSL environment on Windows (Claude Code runs inside the distro). That is local virtualization, not SSH to a remote host. For true remote Linux, use SSH lanes above. Older queue items like “claude code wsl” are a separate topic.
How do I avoid burning the remote box with YOLO?
Keep prompts manual on shared hosts, scope credentials, use worktrees, and read the YOLO mode post before you skip permissions. SSH multiplies blast radius; it does not reduce it.