Skip to content
CommandChain CommandChain CommandChain Docs

Install a runner

A runner is a small service on a machine you own that executes your team’s work inside a sandbox. Until one is connected, your agents can plan but cannot execute. This page is the happy path from a single command to a paired runner. For adapters, security, credentials, and day-2 operations, see runners and execution.

What you’ll need

Section titled “What you’ll need”
  • A Linux machine (kernel 5.13 or newer) or a macOS machine.
  • The address of your CommandChain instance.

Install and pair

Section titled “Install and pair”

  1. Run the installer

    Section titled “Run the installer”

    On the machine that should execute your work, run the one-liner, pointing it at your workspace address.

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

    You can also open Settings, then Runners, then Add runner in the app to get the same command with your server URL already filled in.

    The installer needs no administrator rights and no runtime. There is no Node, no build step, and no token to paste. It downloads one executable for your CPU, verifies it against the release checksums, installs the coding-agent tool, checks that this machine can actually contain an agent, opens your browser to pair, and leaves the runner running as a user-level service in your home directory.

  2. Approve it in your browser

    Section titled “Approve it in your browser”

    The installer opens a device-code approval page in your browser. Sign in if prompted, then check that the runner name matches the machine you just ran the installer on, and select Approve. You never paste a token into the terminal: the credential comes back over the wire into a private file and is never printed.

    The pairing approval page, where you confirm the runner that asked to join your workspace.

  3. Confirm it is online

    Section titled “Confirm it is online”

    Once the runner sends its first heartbeat, the approval page shows it as connected. You can re-check from the machine at any time:

    Terminal window
    sh install.sh --status

Re-running and removing

Section titled “Re-running and removing”

Re-running the installer is a safe upgrade. It keeps your pairing, replaces the program, and rolls back if a new release cannot stay up.

Terminal window
sh install.sh --server <your-commandchain-url>   # upgrade, keep pairing
sh install.sh --uninstall                        # stop and remove the service
sh install.sh --uninstall --purge                # also delete credentials and workspaces

Next steps

Section titled “Next steps”

Your runner is paired, and the capabilities that were locked during setup are now available.