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 claude once over SSH and follow its sign-in, or run claude 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

Can the hub itself run on Linux?Yes. The installer works on Linux and sets the hub up as a systemd user service with lingering, so it starts at boot. The Mac app is Mac-only, so with a Linux hub you use a browser on your tailnet and the iPhone app. Most people run the hub on a Mac and add servers to it.
Does Commission need root on the server?No. It installs as your user in your home folder and never asks for sudo.
Does the server need to be reachable from the internet?No. Your hub reaches it over SSH, typically across your Tailscale network.
What if Claude Code is signed out on the server?Commission marks the machine as signed out and won't start runs there. Its sessions stay readable. Run claude auth login on the server, and sending works again once it's signed in.
Does it work on a cloud VM?Yes, if it meets the same requirements: glibc 2.28 or newer, systemd, git, Claude Code signed in, and SSH from your hub. Putting the VM on your tailnet means you don't have to open SSH to the internet.

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.