Run Claude Code on a remote server over SSH

To run Claude Code over SSH: install it on the server, sign in with claude auth login and paste the code from your own browser, and start every session inside tmux so it survives a dropped connection. Give the server its own Git credentials rather than forwarding yours. That's the whole recipe; the details below are what makes it pleasant.

This is the hands-on companion to our guide on running Claude Code on an always-on machine, which covers picking and preparing the box. Here we assume you have a Linux server, VPS or home machine you can SSH into. If you're renting one for the job, Claude Code on a VPS covers sizing it and locking it down.

1. Connect with a key, and stay connected#

If you still type a password to log in, make a key first, on your own computer:

ssh-keygen -t ed25519
ssh-copy-id you@server

Then give the host a short name and keep idle connections from dropping, in ~/.ssh/config:

Host box
  HostName server.example.com
  User you
  ServerAliveInterval 30

ServerAliveInterval makes ssh send a small message through the connection when the server has been quiet that many seconds. The ssh_config manual explains it, and with the default ServerAliveCountMax of 3, ssh gives up on a dead server after about three missed replies. Long agent turns are often silent for minutes, and this stops a router somewhere from deciding your connection is dead.

2. Install Claude Code on the server you SSH into#

ssh box
curl -fsSL https://claude.ai/install.sh | bash
claude --version

Anthropic's setup page lists Ubuntu 20.04+, Debian 10+, Alpine 3.19+ and macOS 13+, with 4 GB of RAM or more, as of 22 October 2026. Native installs update themselves; claude doctor checks the install without starting a session. Anthropic's apt, dnf and apk repositories, and the install errors that come up mostly on small servers, are in install Claude Code on Linux.

3. Sign in without a browser on the server#

Run claude auth login. It prints a link. Open it on your own computer, approve, and the browser shows a code. Paste it into the SSH session at Paste code here if prompted.

Anthropic's login troubleshooting explains why: over SSH, "the browser usually opens on a different host and its redirect can't reach Claude Code's local callback server". If the link wraps across lines and won't click, press c at the prompt to copy it.

For scripts and CI, claude setup-token prints a one-year token you set as CLAUDE_CODE_OAUTH_TOKEN. It only makes model requests, so it can't start Remote Control.

4. Run every session inside tmux#

A session started in a plain SSH shell dies when the connection does. A train tunnel or a laptop lid is enough to lose an hour of agent work.

tmux new -s api        # a named session; run `claude` in it
# Ctrl-b d             # detach: tmux and Claude keep running
tmux ls                # list sessions
tmux attach -t api     # come back, from any computer

From the tmux wiki: detaching leaves "the tmux session and any programs inside it running in the background". One tmux session per project, or one window per agent, keeps several agents apart.

Three things that trip people up inside tmux:

• Copying text. Claude Code can't reach your laptop's clipboard from a server. Outside tmux it sends copied text to your terminal with OSC 52, which some terminals ignore (iTerm2 until you allow it, macOS Terminal not at all). The troubleshooting page has the workarounds; the simplest is your terminal's own selection key while you drag.
• Scrolling back. Whether the mouse wheel reaches Claude's conversation depends on its renderer and on set -g mouse on: Claude Code in tmux: scrolling, focus and display fixes.
• One folder, several agents. Two claude sessions in the same checkout edit the same files. Give each its own git worktree (claude --worktree name) or its own clone.

5. Handle Git keys on the server#

The agent needs to fetch and push. Three ways, best first:

1. The server's own sign-in: gh auth login on the server, or a key made there and added to your account.
2. A deploy key per repository, when the server should touch only one repo.
3. Agent forwarding (ssh -A): your laptop's keys, used from the server. We avoid it. The OpenSSH manual says it "should be enabled with caution": anyone on the server who can get past the file permissions on the forwarded socket can use your loaded keys to authenticate as you while you're connected. They can't copy the keys, but they don't need to. An agent running shell commands as you on that server can reach that socket too.

6. See the dev server from your laptop#

When the agent starts a dev server on port 3000 on the server, forward it to your own machine:

ssh -L 3000:localhost:3000 box

Then open http://localhost:3000 on your laptop. Add a LocalForward 3000 localhost:3000 line to the Host box block if you want it every time.

What SSH alone doesn't give you#

This setup works. Its limits show up as soon as there's more than one agent:

• One terminal at a time. You see whichever tmux window you're looking at. A question an agent asked twenty minutes ago in another window sits there, waiting.
• No phone view. An SSH app on a phone works, but a full terminal UI on a phone screen is hard going. An iPad with a keyboard fares better, especially over mosh (Claude Code on an iPad). Anthropic's Remote Control is the official answer: run claude remote-control on the server (inside tmux) and reach it from the Claude app. It needs a Pro, Max, Team or Enterprise plan, not an API key (on Team and Enterprise an Owner turns it on first), and in server mode it exits after about 10 minutes without a network. Our guide on running Claude Code from your phone compares the options.
• Every CLI by hand. Claude Code updates itself; Codex, Gemini CLI and the others each have their own install and sign-in.
• When an account runs out, the session stops and waits until you sign in to another one.

How Shuriken does it: add the server from the app#

In Shuriken, the same machine is a server, and you add it from the app instead of living in its terminal.

1. Open Settings › Devices › Add device and choose A server.
2. Pick Linux, macOS or Windows. The app gives you install steps made for your account, valid for an hour.
3. Paste them into your SSH session, once. Day to day, you don't need SSH for it after that.

The installer sets up Git, the GitHub CLI, ripgrep, Claude Code, Codex and the CLIs for the providers you have sources for, asks for your GitHub sign-in, and says which step it's on. The server then runs as a service that starts with the machine and restarts on its own, and it updates itself only to releases we signed, waiting until no agent is mid-turn.

What changes day to day:

• No sign-in on the server. Your sources (the accounts and keys you add to Shuriken) reach it end-to-end encrypted from the app.
• Every chat in one list, each on its own branch in its own worktree, instead of tmux windows. A chat that needs you says so.
• From your phone, through the web app in any browser, not a terminal.
• Hot swapping: when one of your accounts nears its limit, Shuriken moves the server's chats to another of your accounts or sources and they keep going. Use only accounts you own and are entitled to use; providers' terms may not allow sharing a subscription sign-in.

On the Free plan a server is one of your two linked devices; Pro has no device limit. The server page has the short version. If you'd rather stop juggling tmux windows, download Shuriken and add your box as a server.