Install Claude Code on the remote host, not locally against a mounted filesystem. Sign in by running claude and pasting back the login code the browser shows, which is the normal path over SSH, or use claude setup-token and CLAUDE_CODE_OAUTH_TOKEN for an unattended box. Always run inside tmux so a dropped connection does not kill the session. Latency comes from the model round trip, not from SSH, so a remote agent feels no slower than a local one.
- Install on the remote host, never locally against SSHFS or a network mount.
- Browser login works over SSH: paste the code the browser shows back into the terminal.
- For unattended boxes,
claude setup-tokenthenCLAUDE_CODE_OAUTH_TOKEN. - Always
tmux. SSH drops eventually, and it drops mid-edit. - SSH adds tens of milliseconds against a model round trip measured in seconds.
claude --remote-controllets you check in from a phone without another SSH client.
Setting it up
Install on the remote host
ssh you@server
curl -fsSL https://claude.ai/install.sh | bash
exec $SHELL -l
claude doctorThe native installer needs no Node.js and installs into your home directory, so no root is involved. On Debian, Ubuntu, Fedora, RHEL or Alpine you can install from the signed package repositories instead, which fits better if the box is configuration-managed.
Sign in without a local browser
Run claude and follow the prompt. The browser cannot reach the callback server inside your SSH session, so it shows you a login code instead of redirecting. Paste that code at the Paste code here if prompted prompt. This is the expected path over SSH, not a workaround, and it keeps the session on your subscription.
# no browser at all, or an unattended box
# on your laptop:
claude setup-token
# on the server:
export CLAUDE_CODE_OAUTH_TOKEN="<token>"
claudeThe token lasts a year, is printed once and never saved, and requires a paid plan. For genuinely automated work, use ANTHROPIC_API_KEY instead: a subscription is licensed for interactive use by one person, and a cron job is not that.
Run inside tmux
tmux new -s agent
cd ~/projects/thing
claude
# detach with ctrl-b d, then later:
tmux attach -t agentWithout this, closing your laptop kills the agent mid-edit. With it, you reattach and the session is exactly where you left it.
Surviving a bad connection
| Tool | Survives | Notes |
|---|---|---|
tmux | Disconnects, laptop closing, reboots of your machine | Essential. Non-negotiable, really. |
mosh | Roaming, high latency, sleep | Local echo makes typing feel instant |
ssh -o ServerAliveInterval=30 | Idle timeouts | Stops NAT quietly dropping the connection |
autossh | Reconnecting automatically | Belt and braces on top of tmux |
Host devbox
HostName 10.0.0.5
User you
ServerAliveInterval 30
ServerAliveCountMax 6
ControlMaster auto
ControlPath ~/.ssh/cm-%r@%h:%p
ControlPersist 10mWhere the latency actually is
People expect a remote agent to feel sluggish and are surprised when it does not. The reason is the ratio.
Rough contributions to the time between prompt and reply.
| Component | Typical |
|---|---|
| SSH round trip | 10 to 80 ms |
| File reads on the remote | Fast; they are local to the agent |
| Model round trip | 2,000 to 30,000 ms |
The same logic applies inside WSL, where working on /mnt/c from a Linux-side agent crosses a translation layer on every read. Different mechanism, identical symptom: everything is fine except that it is inexplicably slow.
Checking in without another SSH client
The awkward part of a remote agent is not running it, it is knowing when it wants something. Remote Control closes that gap: the session keeps running on the server, and you steer it from a browser or the Claude mobile app.
claude --remote-control "api migration"
# or, from inside a session already running
/remote-controlWhat the model is, and what it is not. As of August 2026, research preview.
| Property | Detail |
|---|---|
| Where code runs | Still the remote host; the browser is a window |
| Inbound ports | None. The session makes outbound HTTPS requests only |
| Credential | A claude.ai login. API keys and setup-token tokens are refused |
| Endpoint | Requires api.anthropic.com; a custom ANTHROPIC_BASE_URL disables it |
| If the process dies | The session ends, which is why tmux still matters |
| Network outage | Reconnects automatically; roughly 10 minutes offline ends it |
While Remote Control is connected, the transcript is stored on Anthropic servers so the conversation stays in sync across devices. Execution and filesystem access stay on your machine. If that trade is not one you want on a particular host, the setting to turn it off entirely is disableRemoteControl.
Working across several machines
Once agents are running on more than one host, the problems stop being technical and become organisational: which box is running what, whether the long job finished, and how to read a diff without opening a shell to look.
| Number of hosts | What works |
|---|---|
| 1 | tmux, one window per session |
| 2 to 3 | tmux plus named SSH config entries and ControlMaster |
| Several, plus a laptop | A workbench that aggregates sessions across hosts |
Questions people ask
Install it on the remote host with the native installer, sign in by pasting the login code the browser shows, and run it inside tmux so the session survives a dropped connection.
Run claude and paste the login code the browser displays at the Paste code here if prompted line. That is the normal path over SSH. For an unattended box, run claude setup-token on a machine with a browser and set CLAUDE_CODE_OAUTH_TOKEN on the server.
Only if you started it inside tmux or screen. Otherwise the process is killed with the shell, potentially mid-edit. Detach with ctrl-b d and reattach with tmux attach.
No. SSH adds tens of milliseconds against a model round trip measured in seconds. What is slow is running the agent locally against a remote filesystem, where every one of hundreds of file reads pays the network cost.
No. The agent reads constantly and every read would cross the network. Install it on the machine that holds the files, and use SSH only to reach the terminal.
Yes. Start it with claude --remote-control, or run /remote-control in a running session, and open it from claude.ai or the Claude mobile app. It makes outbound HTTPS requests only and opens no inbound ports, and it needs a claude.ai login rather than an API key.
Most often because the box is authenticated with CLAUDE_CODE_OAUTH_TOKEN or an API key. Those credentials can make model requests but cannot establish a Remote Control session. A custom ANTHROPIC_BASE_URL also disables it.
Yes. Beyond a couple, the difficulty is keeping track of them rather than running them, which is what a workbench that aggregates sessions across hosts is for. Give each session its own git worktree so agents on one box do not collide.
Sources
Every figure above was read from these pages on August 2026. Vendors reprice without notice; if you find a stale number, tell us.