The runner screen

Run commandchain-runner on the runner machine, with no options, to open the runner screen. It is the main way to set up and run a runner. It shows the next thing to do under NEXT STEP; press enter to do it.

commandchain-runner

You do not need to remember any other command. Whatever is left to do, the screen names it and offers it as one key. When the app or these docs say to open the runner on that machine with commandchain-runner and follow its prompt, this is the screen they mean.

What it walks you through

The screen works out the next step on its own, in this order, and moves on by itself as each one is done:

1. Containment check. The runner proves this machine can run coding agents safely before anything is sent to CommandChain. If it cannot, the screen says why and what to change, and press enter to check again. See proving containment with doctor.
2. Install a coding CLI. When none of Claude Code, Codex or Gemini CLI is on this machine, press enter to choose one. Each installs as you, with the vendor’s own installer.
3. Pair with your workspace. Approve the runner in your browser; enter reopens the approval page if you closed it. The runner carries on by itself once you approve. If pairing does not finish, press enter to pair again. See pairing.
4. Sign the runner in. The screen suggests a coding CLI, and enter signs in to it in your browser. The runner keeps its own sign-in on this machine; your own sign-in is not used or changed, and the runner uploads its sign-in only if you choose to push it for managed runs. Press s to choose another CLI or to use an API key instead.
5. Ready. The screen shows ● Ready and which coding CLIs the runner is signed in to, and the runner waits for work.

The runner starts taking work as soon as it is paired, so the setup wizard in your browser can follow along while you finish the last step here.

Keys

The menu on the left holds everything that is optional. Nothing there blocks the next step, and every key works at any time.

Key	Does
enter	Do the next step shown under NEXT STEP
i	Install a CLI
s	Sign-ins: sign this runner in to a coding CLI, or out of one
f	Full setup: switch between the runner’s own sign-in and your full CLI setup. See sign-in only or full setup
c	Managed login: upload a login for runs on CommandChain’s managed servers, or this runner’s own sign-in when that is the only one on the machine. See managed runner credentials
r	Check again. This also re-checks the installed toolchains and reports them to CommandChain right away
e	Read the errors this runner has reported
q	Quit, or Close screen when the runner already runs in the background

The arrow keys move into the menu, where enter picks the highlighted row. Esc goes back to the next step.

Inside Sign-ins (s):

Key	Does
enter	Sign in with your browser
d	Sign in with a device code (Codex only)
a	Sign in with an API key, typed at a hidden prompt
x	Sign out. Runs already going finish with the current sign-in
esc	Close

While a sign-in runs, the coding CLI’s own login takes over the terminal. When it finishes, the runner screen comes back and says whether the runner is signed in.

When the runner already runs in the background

A runner installed the default way runs on this screen, in the terminal you started it in, and stops when you close it. A runner installed with --service is already running in the background, so commandchain-runner opens the same screen for that service rather than starting a second runner; the status line then reads running in the background with the service’s process id.

Sign-ins and full setup made there reach it within a minute, and closing the screen leaves it running. Press q to close the screen.

Pressing r there re-checks the installed toolchains, and the background runner reports them within 30 seconds.

Restart commands are needed only for a newly installed CLI, so the background runner offers it for work:

systemctl --user restart commandchain-runner                    # Linux
launchctl kickstart -k gui/$(id -u)/ai.commandchain.runner      # macOS

The screen cannot show the background runner's live runs

In the background, the service does the work, so this screen shows its status and sign-ins but not the progress of a run. Follow a run in the app instead.

Without a screen

In a service, in CI or with --plain, there is no screen, and every step has a command instead: doctor for containment, agents install for a CLI, connect --pair-only for pairing, and signin --agent <kind> for the sign-in. COMMANDCHAIN_RUNNER_PLAIN=1 does the same as --plain. See the runner CLI reference.

Next steps

• Sign-in only or full setup: what a run signs in with, and how to change it.
• Runner CLI: the same steps as commands, for scripts.
• Troubleshooting: when a step will not finish.