Run Claude Code on a remote server and manage it from your Mac

Why run coding agents on a server

• They keep going when your laptop is closed, asleep or offline.
• Builds and test runs use the server's CPU and memory, not your laptop's.
• An agent on a separate box can only touch what is on that box.
• Linux toolchains, containers and services run where they will be deployed.

The cost is distance. Every session is one SSH hop away, and the usual signs that an agent is waiting, a bell or a banner, do not reach your Mac on their own. Most of this guide is about closing that gap.

Any Linux VPS or spare machine works. Claude Code supports Ubuntu 20.04 or later, Debian 10 or later and Alpine Linux 3.19 or later, with 4 GB of RAM or more on x64 or ARM64 (system requirements).

1. Set up SSH from your Mac

Use key-based login and give the server a short name. On your Mac:

# make a key if you don't have one
ssh-keygen -t ed25519

# copy it to the server
ssh-copy-id you@203.0.113.7

Then add a host alias to ~/.ssh/config:

Host devbox
    HostName 203.0.113.7
    User you

Now ssh devbox logs you in. herdr and Cadence both accept this alias.

2. Install and sign in to Claude Code

On the server:

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

Clone your project and run claude in it. The first run asks you to sign in. With no browser on the server, press c to copy the login URL, open it on your Mac, sign in, and paste the code back at the Paste code here if prompted line. On Linux the login is stored in ~/.claude/.credentials.json, readable only by your user (authentication).

For a box that only runs scripts, claude setup-token on your Mac prints a one-year token you can set as CLAUDE_CODE_OAUTH_TOKEN on the server. That token can only make model requests, so it cannot start Remote Control sessions.

Sessions on the server draw on the same plan as your Mac sessions when you sign in with the same account. The server also needs its own git access to push branches. A deploy key or a token scoped to one repository is safer than copying your personal key there.

3. Keep sessions running with tmux

A plain ssh devbox followed by claude ends when the connection drops. Start agents inside tmux instead:

ssh devbox
tmux new -s agents       # first window: run claude
# Ctrl-b c   new window for a second agent
# Ctrl-b w   list windows
# Ctrl-b d   detach; everything keeps running

tmux attach -t agents    # later, from any machine

Install tmux with the package manager (sudo apt install tmux on Debian and Ubuntu). If a session did end, claude --continue in the same folder picks up the most recent conversation. For two agents in one repository, give each its own worktree with claude --worktree <name>, as the multiple agents guide explains.

4. Use herdr and connect the server as a machine

herdr is a free, open-source terminal runtime built for coding agents. Like tmux, it keeps sessions running after you detach. It also reads each pane and marks the agent in it as working, blocked or idle. On the server:

curl -fsSL https://herdr.dev/install.sh | sh
herdr                  # starts or attaches to the default session
# Ctrl-b v   split right, then run claude or codex in the new pane
# Ctrl-b q   detach; the server and its agents keep running

herdr on your Mac can show that server next to your local agents. Check that ssh devbox works, then on your Mac:

herdr machine add devbox --label "Build box"
herdr machine list

Each machine keeps its own herdr server, so a lost connection or a sleeping laptop does not stop the agents on it. herdr reconnects on its own and shows the server's last known state dimmed until it does. To disconnect, run herdr machine remove <profile-id> with the id from herdr machine list. Details are in herdr's connecting machines docs.

5. Know when a server agent needs you

Hooks that post macOS notifications do nothing on a server, because it has no desktop. These do work:

• A push hook. The ntfy script in Claude Code on iPhone runs unchanged on Linux and sends to your phone or the ntfy web app.
• Terminal notifications over SSH. In Ghostty, Kitty and iTerm2, Claude Code's built-in desktop notification travels back over SSH to your Mac (iTerm2 needs one alert setting turned on). Inside tmux, add set -g allow-passthrough on to ~/.tmux.conf so it gets through. The notifications guide covers the settings.
• Remote Control. Start claude --remote-control inside tmux on the server and the session appears in the Claude app and at claude.ai/code. Anthropic's docs recommend tmux or screen for exactly this case. It needs a claude.ai login, not a setup token.
• herdr's state marks, if you keep herdr open on your Mac with the machine connected.

6. Cadence 0.5.7: agents on other machines

Cadence is a free Mac app that puts every coding agent in one Inbox. Since version 0.5.7 that includes agents on your Linux servers, which Cadence reaches through herdr over your Mac's own SSH.

1. In Cadence, open Settings → Agents → Other machines and copy the command it shows. It already contains your Mac's SSH public key:

   curl -fsSL https://cadencevoice.ai/machine.sh | sh -s -- ssh-ed25519 AAAA...

2. Run it on the server. It installs herdr unless it is already there and adds your Mac's public key to ~/.ssh/authorized_keys, marked cadence. That is all it does. Nothing on the server connects to Cadence, its relay or your phone, and no token or password is involved. You can read the script before you run it.
3. Back in Cadence, add the server by its SSH address, such as you@203.0.113.7 or an alias like devbox, with an optional name.
4. On the server, start agents inside herdr: run herdr, then claude or codex in a pane.

The server's agents then get dots on the toolbar, cards in the Inbox and rows in the panel, labeled with the server's name. You answer their questions and send them messages from your Mac, or from your iPhone if you are in the iPhone beta.

Good to know:

• Starting and ending agents on a server still happens on the server.
• If your Mac has no SSH key in ~/.ssh, ssh you@server has to work from Terminal some other way, such as through a key agent.
• If the server is new to your Mac, run ssh to it once in Terminal and accept its host key. Settings tells you when that is needed.
• Removing the server in Settings leaves its agents running there.
• Your phone reaches server agents through your Mac, so Cadence has to be running on an awake Mac for that.

Security basics

• Run agents as a normal user, not root.
• Keep SSH key-only, and limit who can reach it, for example with a firewall or a VPN.
• Give the server only the credentials the work needs: a repository-scoped deploy key, not your personal key or cloud admin keys.
• Remember that anything on the box is in reach of the agent, including .env files.
• Use --dangerously-skip-permissions only on a disposable machine with nothing to lose.

Common questions