Runner CLI

commandchain-runner is the program the runner installer puts at ~/.local/bin/commandchain-runner. The installer runs it for you, so most people never type these commands. They are here for when you need them.

$ commandchain-runner --help
Usage: commandchain-runner [options] [command]

Universal Agent Runner for CommandChain

Options:
  -V, --version            output the version number
  -h, --help               display help for command

Commands:
  connect [options] [url]  Pair with a running CommandChain instance and begin
                           processing runs
  start [options]          Register with a CommandChain instance and begin
                           processing runs (legacy BYO + managed pool)
  status                   Show saved runner credentials
  logout [url]             Remove saved credentials for a CommandChain instance
  doctor                   Check that this machine can contain a coding agent,
                           and report what it achieved
  creds                    Capture and manage coding-agent credentials for
                           cloud runners
  version                  Print the runner version
  help [command]           display help for command

Containment is checked before anything goes out on the wire

connect and start both prove this machine can contain a coding agent before they request a code, read a saved credential, or register. If it cannot, nothing is sent and the process exits. There is no flag, environment variable, or saved credential that skips this. See doctor.

connect

Pairs with a CommandChain instance through the browser and then processes runs. This is the command the installer uses and the one to use by hand.

commandchain-runner connect                             # pairs with http://localhost:7000
commandchain-runner connect https://your-commandchain
commandchain-runner connect https://your-commandchain --display-name maya-macbook --no-open

Argument	Default	Does
[url]	COMMANDCHAIN_URL, else http://localhost:7000	Base URL of the CommandChain core to pair with

Flag	Default	Does
--display-name <name>	<user>@<hostname>	The name you approve in the browser and see in the fleet. Unique within a workspace
--workspace-root <dir>	COMMANDCHAIN_WORKSPACE_ROOT, else ~/.commandchain/workspaces	Where repository checkouts live
--poll-interval-ms <ms>	2000	Heartbeat interval
--callback-port <port>	0	Local callback API port. 0 picks a free one
--tui	off	Open the terminal observation view. Closing it with q does not stop the runner
--force-pair	off	Ignore any saved credential and pair again
--pair-only	off	Pair and exit, without processing runs. The installer uses this, then hands running to the service manager
--no-open	off	Do not try to open a browser. Print the URL instead
--commandchain-agent-path <path>	found on PATH	Override the path to the commandchain-agent binary
--claude-path <path>	found on PATH	Override the path to the claude binary
-h, --help		Print help for this command

The runner detects its coding agents at startup and refuses to continue if it finds none. See coding agents, and pairing for the browser half of the flow.

start

The older flag-driven flow. It registers with a preconfigured credential rather than pairing in a browser, which is why it exists for platform-managed runners and for automation that cannot open a browser.

COMMANDCHAIN_URL=https://your-commandchain \
COMMANDCHAIN_TENANT_ID=your-workspace \
COMMANDCHAIN_RUNNER_CREDENTIAL=... \
commandchain-runner start --display-name my-runner --adapter claude-code-cli

Flag	Default	Does
--commandchain-url <url>	COMMANDCHAIN_URL	Base URL of the control plane
--tenant-id <id>	COMMANDCHAIN_TENANT_ID	Workspace this runner serves
--tenant-credential <secret>	COMMANDCHAIN_RUNNER_CREDENTIAL	Bootstrap credential used to register
--display-name <name>	COMMANDCHAIN_RUNNER_NAME	Runner name
--workspace-root <dir>	COMMANDCHAIN_WORKSPACE_ROOT, else ~/.commandchain/workspaces	Where checkouts live
--adapter <id>	auto-detected	Adapter to advertise. Repeat the flag for several
--poll-interval-ms <ms>	2000	Heartbeat interval
--callback-port <port>	0	Local callback API port
--tunnel-max-sessions <n>	5	Concurrent live-app tunnel sessions
--commandchain-agent-path <path>	COMMANDCHAIN_AGENT_PATH	Path to the commandchain-agent binary
--claude-path <path>	CLAUDE_PATH	Path to the claude binary
--tui	off	Terminal observation view
-h, --help		Print help for this command

A self-hosted runner whose credential resolves to a different workspace than --tenant-id exits rather than serving the wrong one.

Prefer connect

connect needs no credential in your shell history, no workspace id, and no adapter list. Use start only when a browser is genuinely unavailable.

status

Prints the pairings saved on this machine. Never prints credential material.

$ commandchain-runner status
Credentials file: /home/maya/.commandchain/runner.json

  https://your-commandchain
    tenant       alpenglow
    runnerId     32c152e4-3d5e-49a1-b3df-20b95c0a74b6
    displayName  maya-macbook
    adapters     claude-code-cli, commandchain-agent-cli
    pairedAt     2026-07-18T09:14:22.104Z

With nothing paired:

$ commandchain-runner status
No paired instances.
Run "commandchain-runner connect" to pair with a CommandChain server.

logout

Removes the saved credential for one instance. The runner in your fleet is untouched: revoke it in the app if you want it gone from there too.

commandchain-runner logout                            # http://localhost:7000
commandchain-runner logout https://your-commandchain

Argument	Default	Does
[url]	http://localhost:7000	Which pairing to forget

doctor

Proves this machine can contain a coding agent, by building a real sandbox policy and running a real process through it. Deliberately flagless: there is nothing to configure about the question, and no way to skip, weaken, or declare a result the machine did not earn.

$ commandchain-runner doctor
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.

Exit code 0 means contained, non-zero means not. Proving containment with doctor reads the output in full and lists the failure cases.

creds

Captures the coding CLIs’ own logins from this machine and manages the copies stored for your workspace. Full context in agent credentials.

$ commandchain-runner creds --help
Usage: commandchain-runner creds [options] [command]

Capture and manage coding-agent credentials for cloud runners

Commands:
  push [options]            Read the coding CLIs' native credentials on this
                            machine and upload them
  list [options]            Show the agent credentials stored server-side
                            (metadata only)
  rm [options] <agentKind>  Remove one stored agent credential

Every subcommand accepts --url <url>, which defaults to COMMANDCHAIN_URL and then to http://localhost:7000. All three authenticate with the pairing credential in ~/.commandchain/runner.json, so this machine has to be paired first.

creds push

commandchain-runner creds push                     # all three, whatever is found
commandchain-runner creds push --agent claude-code

Flag	Default	Does
--agent <kind>	all	One of claude-code, codex, gemini
--accept-oauth-risk	off	Acknowledge the risk of uploading a subscription login, for non-interactive use
--url <url>	COMMANDCHAIN_URL, else http://localhost:7000	Which paired instance to upload to

Two rules are enforced here rather than left to you:

• A provider API key wins over a subscription login when both are on the machine, because a key is revocable and avoids the provider’s terms-of-service question. push says which it chose and why.
• A subscription login needs explicit acknowledgment. Interactively you type i understand; non-interactively you pass --accept-oauth-risk. Without it the upload aborts with a non-zero exit.

creds list

commandchain-runner creds list
commandchain-runner creds list --json

Flag	Default	Does
--json	off	Print the same records as JSON, for scripts
--url <url>	COMMANDCHAIN_URL, else http://localhost:7000	Which paired instance to ask

Output is metadata only. No token material is ever returned by the server, so none can be printed.

$ commandchain-runner creds list
AGENT        AUTH      EXPIRES                   UPDATED
claude-code  oauth     2026-08-17T09:14:22.000Z  2026-07-18T09:14:25.881Z

creds rm

commandchain-runner creds rm claude-code

Argument	Does
<agentKind>	One of claude-code, codex, gemini

Flag	Default	Does
--url <url>	COMMANDCHAIN_URL, else http://localhost:7000	Which paired instance to remove it from

version

$ commandchain-runner version
0.1.2

commandchain-runner --version prints the same string. Release history is in release notes.

Next steps

• Runner environment variables: everything the runner reads from its environment.
• Install a runner: the installer’s own flags, which are separate from these.
• Runner troubleshooting: symptom-first fixes.