Claude Code over SSH: run it on a remote machine

Three ways to work on a remote machine

Running Claude Code somewhere else means one of these, and they are not interchangeable. Pick the one that matches what you have in front of you, because the rest of this page is about the first.

• A desktop SSH session: the app connects for you, installs Claude Code on the far machine, and gives you a session window.
• A terminal on the remote machine: you open the connection yourself and type claude there. The tmux guide covers keeping that alive after you disconnect.
• A dashboard that can drive one session on another host: Omniscio does this with its own SSH remotes, and this page ends there.

If your question is about isolating a session on the machine you are already on, that is a different subject: the sandbox guide covers confining commands locally, which is not the same as running them elsewhere.

What an SSH session actually is

In a Desktop SSH session, Claude Code runs on the remote machine and the desktop app is your interface. The documented uses are the obvious ones: code that lives on a cloud VM, a dev container, or a server with particular hardware or dependencies. The command line is the other surface Anthropic lists for remote servers, and it needs no app at all.

The remote can run Linux, macOS or Windows, and the app installs Claude Code there on the first connection. Permission modes, connectors, plugins and MCP servers all work in the session. One exception is worth knowing early: with a third-party provider, SSH sessions need their own setup, so the provider's documentation owns that case.

What the server has to be able to do

A Linux or macOS remote needs a supported processor, an SSH server with SFTP, an install folder that is not mounted noexec (mounted so that programs there cannot run), a working shell, and network access. SFTP is the requirement people trip on, because a plain SSH server can be running happily without it: the server's sshd_config needs a Subsystem sftp line, and you can test it from your own computer by connecting with sftp to the same host and port. A working server shows the sftp> prompt.

If the server is limited to one session per connection, know the arithmetic before you blame the network. The app logs in at least twice each time it connects or reconnects, plus one more login for each terminal tab and for each session running a command that starts with !. Commands that Claude runs cost no extra login. In that situation the documented fixes are updating the desktop app, making sure it connects through the OpenSSH client on Windows, or raising MaxSessions on the server.

On the remote side, the app keeps its helper and Claude Code under ~/.claude/remote/ in the home directory of the user who connects, so that folder cannot be on a noexec mount and the account wants about 1 GB free. Network requests go out from the remote machine, since that is where Claude Code is running. If the machine cannot download Claude Code at all, the app downloads it on your computer and uploads it, and everything else still leaves from the remote.

Two cases behave differently. On a Windows remote machine, Claude Code runs on native Windows, where it runs commands unsandboxed, which is a fact about that platform rather than a setting. And if the place you want Claude to work is inside a container that publishes no SSH port, the route is a ProxyCommand in your SSH config, which is the line that tells SSH how to open the connection through another program, because the app does not run the entry's RemoteCommand.

The key, and the host key

The connection form asks for a host written as user@hostname or the name of a host in ~/.ssh/config, a port that defaults to 22, and a private-key path you can leave empty to let your own SSH config or SSH agent supply it. On macOS and Linux the app connects by running your OpenSSH client, so it reads ~/.ssh/config and takes the entry's host name, user, identity file, certificate file, proxy jump and proxy command. Naming a Host entry is usually easier than filling the form in by hand.

A machine behind a bastion is reached with ProxyJump set in that entry. Where an administrator restricts hosts, the jump host has to be allowed too, and ssh -G prints the hostname an allow-list has to contain.

Checking the machine before you trust it

A host key is what a remote machine presents to prove which machine it is, and a fingerprint is a short form of that key. When you trust a key, your computer saves it and connects to whatever presents it on later connections, which is exactly why it is worth checking the first time: something between you and the machine may be answering instead. If you manage the machine, read its own fingerprint on that machine with ssh-keygen -lf on its host-key file, at its console or over a connection you already trust, and compare it with the one you were shown. If they differ, or you cannot check, you do not connect.

When the app refuses a key, the wording names where it happened: a failed connection card says the host key verification failed, or that the host denied the connection on verification, and the prompt box says the host key changed or is not trusted. A session that was working can also disconnect with a line saying the key changed.

What runs on which machine

The split that surprises people is the environment. An SSH session does not inherit the variables from the remote user's shell profile, even when a terminal on that machine sees them. So a proxy or a custom certificate has to be declared under env in ~/.claude/settings.json on the remote machine itself. Without it the session can hang, or fail with a line saying the connection to the API failed, or that authentication failed, and signing in again fixes nothing. A custom CA file goes in NODE_EXTRA_CA_CERTS, because a CA named by SSL_CERT_FILE in that settings file is not trusted.

Files and tools follow the same rule. In an SSH session the file pane is view-only, so edits are asked for in the conversation or made in a terminal. The terminal is available, with a limit on Windows remote machines. Skills are read from the remote host's home directory rather than from your own machine, so a skill you rely on has to exist over there.

MCP servers behave the same way. A server listed in ~/.claude.json or a project's .mcp.json has to be set up on the remote machine, and the command its stdio transport runs has to be installed there, because that is where it starts.

Keeping a session alive

Claude Code runs on the remote machine under a helper the app installs there, so a running task does not need your SSH connection to keep going. That covers a closed lid, a dropped network and a quit app, on Claude Desktop v2.31226.0 or later. It does not cover everything, and the limit that bites is the sign-in: a Claude account sign-in is renewed for the task only while the app is running and connected, so after you disconnect that sign-in can expire and the task stops with it, sometimes within minutes. Keep the computer awake and online if a task has to run overnight.

Two more endings belong to the machine rather than the sign-in. If the remote restarts, or ends your processes when the SSH connection closes, the running task ends and nothing restarts it while you are away. And on a Linux or macOS remote, if the app does not connect for 30 days, the helper stops and ends every Claude Code process running under it. A session you end from the app stops that session's process; a process that finished its task keeps running until then.

In a plain terminal on the remote machine there is no helper at all, so survival is your job: start claude inside tmux or screen and the session outlives the connection. The tmux guide is the whole of that technique, including what breaks inside a multiplexer.

Ports, the clipboard and alerts

A dev server running on the remote machine is reached by forwarding its port yourself, from a terminal on your computer, with ssh -N -L and the host you connect to. Then localhost on that port is the remote one. If SSH prints open failed: administratively prohibited, the server will not forward TCP, and that is AllowTcpForwarding in its sshd_config.

The clipboard is the other surprise. Over SSH, Claude Code cannot run a clipboard tool on your machine. Outside tmux, selecting text or running /copy sends it to your terminal as an OSC 52 escape sequence, and your terminal decides whether that reaches the clipboard. The /copy command reports that it copied whether or not the text arrived, and the selection notice says how many characters went out that way. If your terminal ignores OSC 52, either hold the terminal's own selection key while you drag and copy the usual way, or set CLAUDE_CODE_DISABLE_MOUSE=1 on the remote machine so the terminal handles selection for the whole session.

Alerts do cross the connection: a desktop notification reaches your local machine over SSH, so a remote session can still tell you it needs you. Whether it appears depends on your terminal forwarding it, which the terminal documentation covers.

When it will not connect

A failed connection card carries a title and a code, and the code is the whole diagnosis. If the message on your screen is not on this page, the Claude Code error messages guide covers the wider family. Six of them have a documented fix of their own: SFTP being off on the server, SFTP failing to start on it, a server that allows too few sessions per connection, a machine out of disk space or quota, no space left on your own computer, and Claude Code failing to start on the host. The last one is the one to re-read rather than retry blind, because the card's own advice is to run the command it names on the remote machine and see whether Claude Code answers there.

Connections that close before anyone logs in

Some servers log connections that arrive and vanish without a login. The app does that on purpose when it tests whether a machine answers: it opens the port and closes it without sending anything, and a burst of eight in about two minutes is normal after a failure. The lines differ by OpenSSH version; on 8.3 to 9.4 they are a kex_exchange_identification error followed by the address and port. Two things can turn those tests into a real problem. A ban list that counts connections which never try to log in will count them, though the stock normal mode of fail2ban counts none of them, so a ban in that mode has another cause. And OpenSSH 9.8 and later can refuse the address itself for exactly that behaviour, with a log line ending penalty: connections without attempting authentication; the answer there is PerSourcePenaltyExemptList in sshd_config, naming the addresses people connect from.

When the sandbox is what blocks it

If a session can reach the internet but every SSH command fails, check whether a Claude Code sandbox is on. A sandbox blocks plain ssh, scp and rsync, and on macOS it also fails git fetch, pull and push against an SSH remote even when the host is allowed. On Linux and WSL2 the git commands work once the host is allowed. This is the same local isolation the sandbox guide covers, seen from the far side.

What people are still reporting

Anthropic's tracker has five open reports about this surface, and they are worth reading before you assume your setup is wrong. Two are requests for the in-app Browser inside an SSH session, and a third reports that the Browser pane tools are unavailable in an SSH session while they work in a local one. One reports a connection failing during the setup step with a reset connection against a container host. One reports SSH and Remote Control sessions not being grouped by project folder, and not appearing in the desktop app on the remote machine. All five are the reporters' own accounts of what they saw, not Anthropic's description of the product.

SSH or Remote Control

They answer opposite questions, which is why one does not replace the other. Remote Control connects claude.ai/code or the Claude app to a session running on your own machine, and Claude keeps running locally the whole time, so code execution and file access stay where they were. An SSH session puts the work on the other machine instead. The practical consequence is what happens when a connection ends: Remote Control goes offline if the process on your machine stops, and an SSH session keeps running under the remote helper.

So the choice is about where the code has to be. If the code and the hardware are on the remote machine, SSH is the answer. If the machine is yours and you want to watch it from a phone or another computer, Remote Control is the answer, and the phone guide covers the wider picture of working away from the desk.

When someone else runs the machines

Two managed-machine controls change what a session may do. sshHostAllowlist limits which hosts a session may reach, only the desktop app reads it, and an empty array turns SSH sessions off entirely. Turning local sessions off on a managed device makes the app refuse a session on the device itself, including an SSH connection back to the same machine, which is how a deployment pushes everyone onto a remote box.

A claude://code/new link goes the other way. It can name a connection host, a port, a folder and a prompt, and the app asks you to confirm the connection before it uses it, but the link itself cannot carry a key file, a password or a command.

SSH remotes in Omniscio

Omniscio is the desktop app we make for running many Claude Code sessions at once, and it has its own version of this: SSH Remote runs a session's Claude CLI on one of your machines and you drive it from the app. It is per session, chosen on the blank-session screen from the Run chip, with Local one row away, so local and remote sessions sit side by side in the same project.

Settings has an SSH Remotes tab with an Add Remote form: name, host, port (22 by default), username, an optional private-key path, and a Proxy Jump field. Import from SSH Config fills the host list from your own ~/.ssh/config, and Test connection reports whether the handshake works. Quick Connect goes further: given a password login for the machine, it generates an Ed25519 keypair, installs the public half there and saves the remote against the private key, which the app keeps in its own data folder with file mode 0600. Host keys go into the app's own known-hosts file, separate from ~/.ssh/known_hosts, and a key that changed is rejected rather than accepted.

Which engine runs there is decided by the engine, and the Run chip tells you rather than letting a session quietly run on the wrong computer. The native Claude engine is the one this feature is built around. A remote row is offered for an engine the app admits to your own host and is greyed out with the reason for one it does not, and the app refuses a launch that names a host for an engine it would not admit, so nothing lands on your own computer by surprise. On your own host the session uses that machine's own Claude login unless you switch on Use this computer's Claude accounts, which is offered for the native Claude engine. On a Linux or macOS host each project gets its own folder under the remote's working directory, created on first use and then kept for that session.

Two settings and one reading habit are worth knowing before you rely on it. Keep sessions working while this computer sleeps is off until you switch it on, covers your own Linux machines, needs Node.js there, and the session keeps spending while it runs. Use this computer's Claude accounts is a per-remote switch that starts off. A file a remote session printed opens read-only, tagged Remote · read-only, so looking at the far side never changes it. None of this is on a phone: the SSH settings family is refused over the mobile bridge, so the remote picker is desktop only.

The library page for the feature is at docs.omniscio.com/library/ssh-remote, the features page lists the rest of what the app does, and the download page has the installers.

Sources

Every Anthropic behaviour on this page rests on one of these, and the date beside each one is the day we read it. The Omniscio section rests on our own source code, and the fact ledger kept with this page's source in our repository names the file behind each claim.

• The desktop application, for the SSH sessions chapter: the connection form, the remote machine requirements, the host-key check, the SSH configuration, jump hosts, containers, proxies and CA certificates, the view-only file pane, skills and MCP servers on the remote, keeping a task running while disconnected, port forwarding, and every failure card code quoted above. Read October 27, 2026.
• Remote Control, for what Remote Control is, the sentence that execution stays on your machine, the local-process requirement, and running a terminal session inside tmux or screen on a remote machine. Read October 27, 2026.
• Troubleshooting, for copying over SSH, the OSC 52 sequence, what /copy reports, and CLAUDE_CODE_DISABLE_MOUSE. Read October 27, 2026.
• Terminal configuration, for the desktop notification that reaches your machine over SSH. Read October 27, 2026.
• Sandboxing, for plain ssh, scp and rsync failing in a sandbox, and the git-over-SSH behaviour on macOS. Read October 27, 2026.
• Settings reference, for sshHostAllowlist and the managed-device setting that refuses sessions on the device. Read October 27, 2026.
• Platforms and integrations, for the surfaces Anthropic lists for terminal workflows and remote servers. Read October 27, 2026.
• Issue 97729, open, for the request that the in-app Browser work in SSH remote sessions. Read October 27, 2026.
• Issue 98288, open, for Browser pane tools being unavailable in SSH sessions. Read October 27, 2026.
• Issue 98091, open, for a connection failing during the setup step against a container host. Read October 27, 2026.
• Issue 99563, open, for SSH and Remote Control sessions not being grouped by project folder. Read October 27, 2026.
• Issue 103737, open, for Browser pane support in SSH sessions in the desktop app. Read October 27, 2026.

This page did not test any connection, and it names no version of Claude Code or of the desktop app as current. Where a version floor appears, it is Anthropic's own and it is quoted as a floor.

Common questions

Does Claude Code run on the remote machine, or on mine?

On the remote machine. In a Desktop SSH session the Claude Code process, its tools and its files all live on the host you connect to, and the desktop app is the window you type into. Your own machine only holds the connection.

Why does my SSH session hang or say Authentication failed?

The session is probably missing a proxy or certificate variable. On a Linux remote, put HTTPS_PROXY and NODE_EXTRA_CA_CERTS under env in that machine's ~/.claude/settings.json, not only in its shell profile, because an SSH session does not read those files.

How do I keep a session running after I close the laptop?

Desktop installs a helper on the remote machine, so a running task survives the connection dropping. It does not survive everything: a Claude account sign-in is renewed only while Desktop runs and is connected, so the task can stop once that expires, and a machine that kills your processes when the connection closes ends it too.

Is SSH the same as Remote Control?

No. SSH moves the work to the other machine: Claude Code executes there and the files are there. Remote Control keeps the session on your own machine and shows it on another device. One is about where the work runs, the other about where you watch it.