Claude Code over SSH: run it on remote machines and servers

Can you use Claude Code over SSH?

Yes. The simplest way to use Claude Code over SSH is to log in to the remote machine, install Claude Code there, and run claude in your project. Claude Code then works on the remote machine's files and runs commands there, exactly as it would locally.

There are four common setups, depending on how you like to work:

This guide walks through each one, plus the sign-in, clipboard and keep-alive issues that come up over SSH.

How do you install and run Claude Code on a remote machine?

SSH in and install Claude Code with the native installer from the setup docs:

ssh you@devbox
curl -fsSL https://claude.ai/install.sh | bash
cd ~/projects/my-app
claude

Claude Code is now running on devbox. It reads and edits files there, runs that machine's tools, and sends its API requests from that machine, so the machine needs network access to Anthropic. Your settings, CLAUDE.md files, skills and MCP servers are the ones on the remote machine, not on your laptop.

If the remote machine runs Linux, check the system requirements first. The Desktop docs add that on Linux, Claude Code needs glibc 2.17 or later, or musl, and musl-based distributions such as Alpine need a few extra packages. The Linux guide covers installation on each distribution.

How do you sign in to Claude Code over SSH?

Sign-in is the step that trips people up, because the browser can't open on a headless server. The authentication docs cover it:

1. Run claude and start the login.
2. If no browser opens, press c to copy the login URL.
3. Open the URL in a browser on your own computer and sign in.
4. If the browser shows a login code instead of redirecting back, paste it into the SSH terminal at the Paste code here if prompted prompt.

The docs explain why step 4 happens: the browser "can't reach Claude Code's local callback server, which is common in WSL2, SSH sessions, and containers."

For a machine where nobody signs in interactively, such as a CI runner, claude setup-token generates a one-year OAuth token. It prints the token and doesn't save it; you set it as CLAUDE_CODE_OAUTH_TOKEN on the machine that needs it. An API key in ANTHROPIC_API_KEY also works; see the API key guide.

The macOS Keychain over SSH

If you SSH into a Mac, the login Keychain is often locked. When the Keychain rejects the write, Claude Code stores your login in ~/.claude/.credentials.json with file mode 0600, the same storage it uses on Linux. To move it back into the encrypted Keychain, run claude doctor, unlock the Keychain, and log in again:

security unlock-keychain ~/Library/Keychains/login.keychain-db

More sign-in fixes are in the login issues guide.

How do you keep a session running after you disconnect?

Run Claude Code inside tmux or screen. If your SSH connection drops, the claude process keeps going and you reattach later. Anthropic's Remote Control docs give the same advice: "If you run claude from a terminal on a remote machine, start it inside tmux or screen to keep the session running after you disconnect from SSH."

These are standard tmux commands, not Claude Code features:

tmux new -s claude
claude
# detach with Ctrl+B then D, reattach later with:
tmux attach -t claude

Inside tmux, Shift+Enter submits instead of adding a newline, and notifications don't reach your terminal. The terminal config docs fix both with these lines in ~/.tmux.conf:

set -g allow-passthrough on
set -g focus-events on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'

Run tmux source-file ~/.tmux.conf to apply them. If a stalled SSH connection ever freezes the session, Claude Code v2.1.261 or later supports CLAUDE_CODE_NONBLOCKING_STDOUT=1, which writes terminal output through a non-blocking file descriptor. Other variables like it are in the environment variables guide.

Does copy, paste and notification work over SSH?

Mostly, with some terminal setup.

Clipboard. Claude Code on a remote machine can't run a clipboard tool on your laptop. Outside tmux, /copy and text selection send the text to your terminal as an OSC 52 escape sequence, and your terminal decides whether to accept it. iTerm2 ignores it until you turn on Settings > General > Selection > Applications in terminal may access clipboard, and macOS Terminal.app doesn't support OSC 52. Workarounds from the troubleshooting docs:

• Hold your terminal's native-selection key while dragging (Option in iTerm2, Fn in Terminal.app), then copy normally.
• Set CLAUDE_CODE_DISABLE_MOUSE=1 on the remote machine so your terminal handles selection.
• In the /copy picker, press w to write the selection to a file instead.

Notifications. Desktop notifications reach your local machine over SSH. Ghostty and Kitty forward them without setup; iTerm2 needs forwarding turned on.

Browser steps. Some commands print a URL when no browser can open, such as /usage-credits on v2.1.205 or later. For an MCP server's OAuth flow, run claude mcp login <name> --no-browser to print the authorization URL.

How do Desktop SSH sessions work?

The Claude desktop app can run Claude Code on a remote machine while you use the app as the interface. The Desktop docs describe this as useful "for working with codebases that live on cloud VMs, dev containers, or servers with specific hardware or dependencies."

To set one up:

1. Open the environment selector under the prompt box and choose New environment.
2. On the SSH tab, choose Add SSH connection… and enter a name, the SSH host (user@hostname or a host from ~/.ssh/config), an optional port and an optional key.
3. Pick a folder on the remote machine and click Create environment.

Desktop installs Claude Code on the remote machine the first time you connect, under ~/.claude/remote/. The remote machine can run Linux, macOS or Windows. A Linux or macOS machine needs an x86_64 or arm64 processor, an SSH server with SFTP turned on, an install folder (~/.claude/remote/) that isn't on a noexec mount, and about 1 GB of free space for each user who connects.

On macOS and Linux, Desktop runs your own OpenSSH client, so ProxyJump, IdentityFile and other settings in ~/.ssh/config apply. MCP servers from ~/.claude.json or a project's .mcp.json have to be set up on the remote machine. Administrators can limit which hosts people may connect to with the sshHostAllowlist managed setting. More on the app is in the Desktop guide.

How do you check on a remote session from your phone?

Use Remote Control. Start it on the remote machine, ideally inside tmux:

claude remote-control --name "devbox"

The terminal shows a session URL, and pressing the spacebar shows a QR code. Open it in the Claude app or at claude.ai/code, and you are driving the session running on the remote machine. Remote Control needs a Pro, Max, Team or Enterprise plan and a claude.ai login; API keys are not supported. Setup and limits are in the Remote Control guide.

What about VS Code, JetBrains and dev containers?

If you already use remote development in an IDE, Claude Code runs on the remote side. For JetBrains Remote Development, the JetBrains docs say to install the plugin on the remote host through Settings → Plugin (Host), not on your local client. In a VS Code window connected to an SSH host, the VS Code docs say to edit ~/.claude/settings.json on that host, not on your local computer.

A dev container is another way to run Claude Code in an isolated environment, locally or on a remote Docker host. The docs warn against mounting host secrets such as ~/.ssh into the container; prefer repository-scoped or short-lived tokens. See the devcontainer guide for a full setup.

Bring your prompts and skills to every machine

The awkward part of working across machines is that your personal skills live in ~/.claude/skills/ on each one. Kipt keeps prompts and Agent Skills as Markdown in a private GitHub repo you own, so on a fresh server you can install every skill into Claude Code with one command: npx skills add https://github.com/<you>/<repo>.git --all -g.