Setting Up Claude Code Over SSH on Windows or Mac

Summary: Claude Code’s Windows desktop app can SSH into a remote machine and run sessions there against your repo, MCP servers, and ~/.claude config. Setup is a four-field dialog, assuming ssh user@host (whereas that is your username and host) already works from your terminal. The non-obvious caveat: session history is siloed. The desktop app, the CLI on the remote, and the VS Code extension (if you use it) on the remote each keep separate session lists, even though they all live on the same machine.

Why bother

I generally use a Windows desktop or laptop and a Linux dev VM, sometimes with a Mac thrown into the mix. The repo, the MCP servers, the ~/.claude config with all my custom instructions and skills, the entire Claude Code workstation setup lives on the Linux box. The Windows side is the comfortable daily driver. I wanted Claude Code running on the Linux machine, driven from Windows, and while VS Code fills that role nicely I also wanted to be up to date on Anthropic’s desktop app situation.

The desktop app’s SSH option does exactly that. You can do the same thing with Codex and their Codex desktop app. The setup is straightforward:

What you need

• Claude Code desktop app installed on Windows or Mac, signed in with a Claude account that has Claude Code access
• A remote machine reachable over SSH on port 22 (or whatever port you use for SSH)
• An SSH key pair on Windows whose public half is in ~/.ssh/authorized_keys on the remote
• The remote user, hostname or IP

If ssh user@host already works from PowerShell, you are done with prereqs. The desktop app handles installing Claude Code on the remote automatically the first time you connect, so the claude binary does not need to exist there yet.

Walk-through

1. Open the desktop app and pick where Claude runs

The app opens to a “Welcome back” screen. Below the prompt box at the bottom is a small environment selector labeled “Where Claude runs.” Click it.

The popover shows Local, Cloud, Remote Control, and SSH sections. Click Add SSH host… under SSH.

2. Fill in the SSH connection dialog

• Name: anything readable that makes sense to you. Shows in your environment list.
• SSH Host: user@hostname-or-ip (fill these in with your details
• SSH Port: leave blank for 22.
• Identity File: leave blank if your default Windows OpenSSH key is already authorized on the remote.

3. Verify SSH itself before you commit

Before saving the dialog, you can also confirm SSH key auth works from PowerShell:

ssh youruser@192.168.1.10 "uname -s && whoami"

Expected output: Linux on its own line, then the username you connected as. No password prompt. If you do get a password prompt, the usual cause on Windows is that OpenSSH cannot find your key in the default location, which is C:\Users\<you>\.ssh\ looking for id_ed25519 or id_rsa. Either point the Identity File field at the real key path, or move the key to the default location. If the key is in the right place and you still get prompted, the next thing to check is whether your public key is actually in ~/.ssh/authorized_keys on the remote.

Note: do not test for the claude binary at this stage. The desktop app installs Claude Code on the remote during the first connection, so a clean remote will not have it yet.

4. Pick a folder

The folder you pick is on the remote machine, the same place you would cd to in a terminal. That path becomes the working directory for the session and the root that Claude’s tools operate against.

5. Trust the workspace

If you have used Claude Code in that folder before, a .claude/settings.local.json already exists and the app shows it. Click Trust Workspace.

That is the happy path. You can prompt the session like any local Claude Code window.

The sessions issue

Here is the part that might catch you off guard. The CLI on the remote, the Desktop app on the local and the VS Code extension all have different session histories. Same dev machine, same ~/.claude/ config, same .jsonl files on disk. So you might expect some coherency between sessions, but that is not the case:

Per Anthropic’s own sessions documentation: “The desktop app, Claude Code on the web, and the VS Code extension each maintain their own session history.”

This is not a big deal b/c you should have plenty of documentation in your projects to get going with new sessions etc. But it is still can be a bit of a pain if you just want to hop between sessions, however, a quick handoff prompt and you will hopefully be fine. 💪

In practice:

• Historical sessions on the remote (from CLI and VS Code work) do not appear in the Windows desktop app’s Recents.
• /resume, the CLI command for picking a past session, is not available in the desktop app. I tried. The reply was literally: “/resume isn’t available in this environment.”
• The desktop app starts a fresh Recents list from its own usage.

What does still merge across surfaces:

• The repo and your files on the remote (same disk).
• The ~/.claude/ config: CLAUDE.md, settings, auto-memory, MCP servers, plugins.
• Git state.
• Anthropic API quota and billing.

So the silo is purely the conversation history list. To browse historical sessions, you still need a terminal on the remote and claude --resume, or the VS Code extension’s resume picker, or there may be other solutions but this gives you the basic situation.

Quality-of-life upgrades

DHCP reservation

If your remote is on DHCP, its IP can change after a reboot and silently break your saved SSH connection. Open your router admin, set a reservation for the remote’s MAC at its current IP, and the IP stays put through future leases.

If you get stuck

Hit a snag I did not cover? Visit with your your own Claude session. Hand it the error message, point it at this post for context, and ask it to walk through your specific setup. 👍

One tip that matters: tell Claude to research before advising. App versions ship with new dialogs, defaults change, and a Claude that verifies the current state of things beats one pattern-matching from training data. Something like “check the current docs and confirm before answering” goes a long way.

The End

If ssh user@host already works from your terminal, the desktop app’s SSH connection is four fields and a folder selection. The interesting part is the session-history silo: desktop, CLI, and VS Code each keep their own Recents list, so claude --resume on the remote will not populate the desktop app’s sidebar. Happy coding!

Sources and Further Reading

• Anthropic docs: Manage sessions – definitive source for the per-surface session-history silo.
• Anthropic docs: Desktop quickstart – where the SSH environment option is introduced as one of the run-location choices.

---

Accurate at time of writing. Something off? Drop a comment.