How to run Claude Code on a Linux server and control it from your phone
Install Claude Code on the server and sign in, make sure your hub Mac can SSH into
it with a key or Tailscale SSH, then add it to Commission with
commission machine add you@server. Commission installs a small host
there as your user, without root, and reaches it over SSH. The server's sessions
then appear beside your Mac's, on every device, including your phone.
What the server needs
- Linux on x86-64 or ARM64 with glibc 2.28 or newer: Debian 10, Ubuntu 18.10, RHEL 8 or later, and most others. Alpine and other musl systems aren't supported yet.
- systemd, which runs Commission's host as a user service, and git.
-
Claude Code installed and signed in as the user you'll SSH in as. Run
claudeonce over SSH and follow its sign-in, or runclaude auth login. - SSH access from your hub with a key, or Tailscale SSH. No ports need to be open beyond SSH, and no root.
Add it
In Commission, open Machines, choose Add machine and enter the SSH address, with a name if you like. Or, from the terminal on your hub:
commission machine add you@server.your-tailnet.ts.net
Without --name, the machine is named after the first part of its host
name, so server.your-tailnet.ts.net becomes server.
Commission connects with your own SSH setup and checks the server first: its platform, Claude Code and its sign-in, git and systemd. Then it shows you a plan of every file it will write and, the first time, the server's SSH host key fingerprint, and asks once. Nothing is written before you confirm. It installs into your home folder, runs as you and never needs sudo. It then waits until the machine is online.
What runs on the server
The host is a self-contained bundle with its own Node runtime, so it doesn't touch the server's Node or your shell files. It runs as a systemd user service, and each session runs in its own unit, so restarting the host doesn't stop a session that's working.
Commission turns on lingering for your user, which lets the host start at boot without anyone logging in. Most distributions allow that for your own user. If yours refuses, Commission warns you, and the host stops when you log out.
The host listens only on the server's loopback interface. Your hub reaches it through an SSH tunnel, so nothing new is exposed on the network.
Use it
Start a session in any folder on the server from your Mac or phone, and follow it like any other: replies, approvals, diffs and a real terminal in the session's folder. If the connection drops, work on the server keeps running and Commission keeps reconnecting.
If the server reboots, its sessions are still there when it's back, and a turn that was cut off continues on its own. Any that can't wait in Activity with Resume. You can also open a shell on the server without starting a session, from Machines › Terminals.
A bigger job can use several machines too. A coordinator breaks a goal into sessions on the server and your other machines, and you approve the merges. Running Claude Code on multiple machines explains how.
Tailscale SSH
Machines you reach with Tailscale SSH work without an SSH key. If your tailnet's SSH policy is set to check mode, Tailscale asks you to approve the connection in a browser. Commission shows Approve in Tailscale in the Mac app, the browser and the phone, waits up to ten minutes, and carries on by itself once you approve. Setting the policy action to accept for your own devices avoids the prompt. Using Claude Code over Tailscale covers Serve, SSH and check mode together.
Other Macs and Windows PCs
Other Macs are added the same way. Turn on Remote Login in System Settings first. After a Mac restarts, someone has to log in at it before its host can start, and Commission says so.
Windows 10 (1903 or newer) and Windows 11 PCs with the OpenSSH server work too, though their setup is still rough while Commission is in beta.
Keep it up to date
When a new version is out, Update all on the Machines page prepares
every machine's update, lets you review and untick any, and installs them together.
From the terminal, commission machine update server updates one machine.
commission doctor
checks a machine's setup and says how to fix what it finds.
Questions
Related
Add your first server in two commands
Install the hub on your Mac:
curl -fsSL https://commission.sh/install | sh
Then add the server:
commission machine add you@server.your-tailnet.ts.net
Prefer an app? The Mac app sets up the hub for you, and adds machines from its Machines page.