pitwall-runner CLI

pitwall-runner is the one binary a runner machine needs. Runners walks through installing it; this page lists what it does.

Commands

Command	Does
register --core-url URL --token TOKEN --name NAME [--labels a,b] [--capacity N] [--sharing owner_only|owner_projects] [--workspace DIR] [--no-self-update]	Exchanges a single-use registration token for the runner’s credential and writes its configuration file. The flags are described in Configuration
claude-token add --account EMAIL	Reads the token claude setup-token printed from standard input and stores it under that account’s email, replacing the email’s previous token. Up to four accounts. A running runner picks it up within a minute, with no restart
claude-token list	Each stored account by short key and email. Never a token
claude-token remove EMAIL	Drops that account’s token. The runner stops using it from its next heartbeat
claude-token	Stores a single token with no email, from standard input: how runners held a token before accounts were named by email. Still read
doctor	Checks what a job needs of this machine, prints each check as [PASS] or [FAIL], whether the runner is ready, and what puts each failed check right. Then a line for gh, [PASS] or [INFO], which only creating a project’s repository needs. Needs no registration
run	Runs in the foreground: checks itself, then heartbeats, claims and runs jobs
service install	Installs and starts a background service of the current user, no root: a systemd user unit, pitwall-runner.service, on Linux; a launchd agent, net.pitwall.runner, on macOS. Run again, it restarts the service on the current binary
service uninstall	Stops and removes the service. The configuration and the registration stay
service status	Whether the service runs, and how to stop and start it
version	The version it was built as

Exit statuses

Status	Means
0	Done
1	Failed, saying why. From doctor: a check failed
2	The command line was not understood. The usage is printed
3	The core rejected the runner’s credential: it was revoked. Register the machine again. The service does not restart on it
4	The runner replaced its own binary and must be started again. Both service managers restart on it; a service definition must never stop on it

The install script

The core serves an install script at /api/runner/install.sh. Register runner, on the Runners page, shows the whole command with a fresh token:

curl -fsSL <core>/api/runner/install.sh | sh -s -- --core-url <core> --token <token> --name <name> --labels <labels>

Every argument is handed to register untouched; --core-url is required. The script:

1. Downloads the binary for this machine, linux/amd64 or darwin/arm64, into ~/.local/bin/pitwall-runner.
2. Runs register with its arguments, then service install.
3. Ends with doctor. A failed check does not fail the install: a machine with no Claude token yet is the usual first state.

On Linux, when lingering is off for your user, it says last that the runner stops when you log out, and the loginctl enable-linger command that keeps it running.

Files

Path	Holds	Mode
~/.local/bin/pitwall-runner	The binary	0755
~/.local/bin/pitwall-runner.previous	The binary before the last update, put back if the new one never reaches the core	0755
~/.config/pitwall-runner/config.json	The core’s URL, the runner’s id and credential, labels, capacity, workspace, and whether self-update is off	0600
~/.config/pitwall-runner/claude-tokens.json	The Claude tokens agents run with, each under its account’s email	0600
~/.config/pitwall-runner/claude-token	The single token of a runner from before accounts by email. Read, never rewritten	0600
~/.config/pitwall-runner/paused-jobs.json	Jobs paused by a usage limit, so a restart loses none	0600
~/.config/pitwall-runner/agent-processes.json	The agents and check commands running now, so the next start can end what a killed runner left	0600
~/.config/pitwall-runner/faults.json	What jobs found wrong with this machine, each a failing check until it is seen right again	0600
~/.config/pitwall-runner/update.json	Where an update of the runner itself stands	0600
~/.local/share/pitwall-runner/workspace/	One checkout per project and repository, reused between jobs, and the files each job is handed, beside the checkouts and never inside one. A new project’s repository is seeded in .seeds/ there, removed after
~/.local/share/pitwall-runner/claude/	The Claude CLI configuration directory agents use, never your own ~/.claude. Its settings.json is generated on every start: do not edit it	0700

--workspace at registration moves the workspace elsewhere.