Install a runner

One command installs a runner, and it is the same command on Linux and macOS.

curl -fsSL https://github.com/commandchain-ai/commandchain-runner-dist/releases/latest/download/install.sh \
  | sh -s -- --server https://your-commandchain

Replace https://your-commandchain with the address of your instance. Opening Settings, then Runners, then Add runner in the app gives you the same command with the address already filled in.

The installer needs no administrator rights and no runtime. There is no Node, no npm, no Docker, no build step, no GitHub account, and no token to paste. Every asset it fetches, the installer itself, the four executables, and their SHA256SUMS, comes from a public release mirror that accepts no credential.

Options

--server <url>          The instance to pair with. Required to install.
--display-name <name>   How this machine appears in CommandChain. Default: user@host.
--version <tag>         Release to install, for example v1.2.0. Default: latest.
--prefix <dir>          Where the program goes. Default: $HOME/.local/bin.
--status                Show what is installed, where the logs are, and whether it runs.
--uninstall             Stop and remove the service and the program.
--purge                 With --uninstall: also delete pairing credentials and workspaces.
--help                  This text.

Name the machine

--display-name maya-macbook is worth passing. It is the name you approve in the browser and the name you see in the fleet, and a runner’s name is unique for the lifetime of your workspace.

What just happened

The installer prints each step as it does it. Here is a real run, on a machine that had nothing installed:

$ curl -fsSL https://github.com/commandchain-ai/commandchain-runner-dist/releases/latest/download/install.sh \
    | sh -s -- --server https://your-commandchain --display-name maya-macbook

CommandChain self-hosted runner  (installer 0.1.2)
  machine   linux-x64
  server    https://your-commandchain
  prefix    /home/maya/.local/bin

1. Downloading the runner (linux-x64) from https://github.com/commandchain-ai/commandchain-runner-dist/releases/latest/download
  ✔ downloaded commandchain-runner-linux-x64 and SHA256SUMS

2. Verifying the checksum before anything is executed
  ✔ sha256 1a5389db3a465dd069489aa4dd3833b46beabf185dd88d49d79999d6d1747ab9 matches SHA256SUMS

3. Installing to /home/maya/.local/bin/commandchain-runner
  ✔ installed commandchain-runner 0.1.2

4. Installing the Claude Code CLI (native build - no Node required)
  ✔ claude at /home/maya/.local/bin/claude (2.1.218 (Claude Code))

5. Checking that this machine can contain a coding agent

commandchain-runner doctor - containment check
  host type   self_hosted
  provider    linux-landlock
  platform    linux
  tier        landlock
OK - every agent process on this machine will run inside this boundary.
  ✔ containment established (see the report above)

6. Pairing with CommandChain (https://your-commandchain)

────────────────────────────────────────────────────────────
  Pair this runner to approve it for a tenant:

     Code: 329X-4QKT
     URL:  https://your-commandchain/app/pair?code=329X-4QKT

  Waiting for approval (up to 10 min)...
────────────────────────────────────────────────────────────

✔ Paired with CommandChain.
    instance     https://your-commandchain
    tenant       alpenglow
    runnerId     32c152e4-3d5e-49a1-b3df-20b95c0a74b6
    displayName  maya-macbook
    credential   /home/maya/.commandchain/runner.json (0600, never printed)

7. Coding-agent credentials
  ✔ a Claude credential is already stored for this tenant - no provider login needed
  runs receive it for the length of one attempt and never keep it on disk

8. Installing the user service
  ✔ wrote /home/maya/.config/systemd/user/commandchain-runner.service
  ✔ commandchain-runner is running and will restart itself if it stops

Done
  ✔ the runner is installed, paired, contained, and running as a user service

    status:     sh install.sh --status
    logs:       /home/maya/.local/state/commandchain-runner/runner.log
    uninstall:  sh install.sh --uninstall

Step by step:

1. Download. One executable, chosen for your operating system and CPU, plus the release’s SHA256SUMS.

2. Verify. The checksum is checked before anything is executed. A mismatch stops the install.

3. Install the program. Into ~/.local/bin by default, or wherever --prefix says.

4. Install the coding agent. Claude Code’s own native build, which also needs no Node.

5. Prove containment. The installer runs doctor, which builds a real sandbox policy and runs a real process through it. If this machine cannot contain an agent, the install stops here and points you at a managed runner. There is no flag that turns this into a warning.

6. Pair. A device code, approved in your browser. See pairing.

7. Find the coding-agent credential. If your workspace already has one stored, nobody logs in again. If it does not, Claude Code’s own browser login runs in a dedicated setup directory, and copying that login to CommandChain is something you acknowledge explicitly.

8. Install the service. A user-level service, started immediately, restarted if it stops.

The runner also prints structured log lines

While it starts, the runner writes JSON log lines describing the boundary it established and the adapters it found. They interleave with the output above. That is normal, and the same lines land in the log file.

Where the files go

Nothing is installed outside your home directory, and nothing asks for sudo.

What	Where
The program	~/.local/bin/commandchain-runner
Pairing credential, workspaces	~/.commandchain (mode 0700)
The service	~/.config/systemd/user/ on Linux, ~/Library/LaunchAgents/ on macOS
Logs	~/.local/state/commandchain-runner/ on Linux, ~/Library/Logs/commandchain-runner/ on macOS

The pairing credential is written to a 0600 file. It is never printed, never a command-line argument, and never written into the service definition.

Keeping it running after you log out

On Linux the service runs while you are logged in. To keep it running afterwards, enable lingering for your own user:

loginctl enable-linger "$USER"

macOS needs a graphical login session

On macOS, the install command must be run from a Terminal window on the Mac itself. macOS only lets an unprivileged user register a background service from inside their own desktop login session, so over a plain SSH connection with nobody logged in at the screen the installer stops before writing anything and says so. Log in at the machine once and re-run it, or use a managed runner for that Mac. The installer never asks for sudo and never works around this.

Next steps

• Pairing: the browser approval, in detail.
• doctor: proving containment yourself.
• Upgrades and uninstall: day-2 operations.
• Troubleshooting: when one of the steps above stops.