Runner troubleshooting

Start here:

sh install.sh --status                    # is it installed, and is it running
commandchain-runner doctor                # can this machine contain an agent
tail -f ~/.local/state/commandchain-runner/runner.log   # Linux
tail -f ~/Library/Logs/commandchain-runner/runner.log   # macOS

On Linux you can also follow the service directly with journalctl --user -u commandchain-runner -f. For more detail in the log, restart the runner with LOG_LEVEL=debug.

The terminal sits at “Waiting for approval”

The runner is fine. It is waiting for a person.

Open the URL it printed and approve the code. If the browser did not open by itself, that is expected on a machine with no desktop session; copy the URL to a browser where you are signed in.
Sign in first if prompted. The code survives the sign-in redirect, so you land back on the approval page.
Check you are approving in the right workspace. The code only exists in the workspace whose address you passed to --server.
Codes expire after ten minutes. If it expired, run the installer again to get a fresh one.

”This code has expired”

Run the installer again on the machine. The new code is valid for another ten minutes, and nothing about your earlier progress is lost.

”A runner named … is already registered in this workspace”

Approval fails with a conflict:

A runner named "maya-macbook" is already registered in this workspace.
Remove the old runner first, or rerun the installer with a different name.

A display name is unique in a workspace, and retiring a runner does not release its name. This normally happens after --uninstall --purge on a machine that was paired before, because the purge deleted the credential and the machine has to pair again.

Pair it under a new name:

sh install.sh --server https://your-commandchain --display-name maya-macbook-2

The installer refuses: this machine cannot contain a coding agent

This is the boundary check failing, and it is not overridable. Run commandchain-runner doctor for the reason, then:

Linux, kernel too old or Landlock inactive. Landlock needs kernel 5.13 or newer and has to be in the active security-module stack. Check with cat /sys/kernel/security/lsm and look for landlock.
macOS, sandbox-exec missing. It ships with macOS at /usr/bin/sandbox-exec. If it is not there, or something else on PATH is answering to that name, that is the problem.
Container or virtual machine. Many container runtimes block the system calls the boundary needs. A managed runner is the answer there.

See doctor for the full failure table.

macOS: the installer stops before installing anything

no GUI session, so launchd cannot supervise the runner from here (macOS refuses
unprivileged service registration outside a console login).

macOS only lets an unprivileged user register a background service from inside their own desktop login session. Over plain SSH to a Mac with nobody logged in at the screen, there is no such session, and every unprivileged alternative is refused by the operating system.

The installer stops before writing anything, and your pairing and credentials are already saved, so:

Log in on that Mac’s console once, in person or over Screen Sharing.
Re-run the installer. It completes immediately, reusing what it already has.

Or use a managed runner for that machine. The installer never asks for sudo and never works around this.

Linux: “no usable user service manager”

The installer needs a reachable systemd --user manager, not merely systemctl on PATH. Containers, docker exec shells, some SSH sessions, and non-systemd distributions have the binary and no user manager behind it.

The runner is installed but `commandchain-runner` is not found

! /home/maya/.local/bin is not on your PATH - add it to use `commandchain-runner` directly.

The service does not care, and it is already running. This only affects you typing the command. Add the directory to your shell configuration:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

An adapter is missing

The runner logs each coding agent it looked for when it starts:

Adapter detected                                  claude-code-cli (claude)
Adapter not on PATH (install "codex" to enable)   codex
Adapter not on PATH (install "gemini" to enable)  gemini

That is informational: a runner with one adapter is a working runner. It matters only when a run is dispatched for a tool this machine does not have, in which case the run waits rather than running with the wrong one.

Install the tool, then restart the runner so it re-detects:

npm install -g @openai/codex
sh install.sh --server https://your-commandchain

See coding agents.

Runs fail with no coding-agent credential

The runner reached the point of starting the agent and had nothing to authenticate with. Capture your login from a machine you are signed in on:

commandchain-runner creds push --agent claude-code

Then check what is stored:

commandchain-runner creds list

A credential that has expired shows in Settings, then Coding Agents as Needs refresh. Log in with the tool again on your own machine, then push again. See agent credentials.

The fleet says stale or offline

A runner reports in on a short interval, and the fleet grades it on how recently it did. Gaps mean the process is not running, or cannot reach your workspace.

sh install.sh --status. If state is not running, the service is down.
Read the log. A runner that starts and immediately exits says why in its first few lines.
Did the machine sleep? A closed laptop stops heartbeating. It comes back by itself on wake.
Did you log out? On Linux a user service stops with your last session unless lingering is enabled:
Terminal window
```
loginctl enable-linger "$USER"
```
Can it reach the workspace? curl -sSf https://your-commandchain/health from that machine.

The service will not stay up after an upgrade

The installer detects this and rolls back to the release that could stay up, so the runner you end up with is a working one. The log from the failed start is still on disk and is the place to look. Pin to a known-good release while you investigate:

sh install.sh --server https://your-commandchain --version v1.2.0

A run left uncommitted changes behind

If a previous attempt failed mid-work, the runner stashes what it found before starting the next one and logs a warning naming the stash. Nothing is discarded. Look in the repository workspace:

cd ~/.commandchain/workspaces/<repository>
git stash list

See workspaces and git.

Next steps

doctor: the containment check, in full.
Upgrades and uninstall: getting back to a clean state.
Troubleshooting and FAQ: everything outside runners.