Runner commands
Every command is champrep-code-runner <command>. Add -h to any command to
see its options, for example champrep-code-runner service -h.
Everyday commands
Section titled “Everyday commands”| Task | Command |
|---|---|
| Connect this machine to a runner | champrep-code-runner register --url https://code.champrep.com |
| Run in this terminal | champrep-code-runner run |
| Install as a service and start it | champrep-code-runner service install |
| Is it running? | champrep-code-runner service status |
| Stop it (running jobs finish first) | champrep-code-runner service stop |
| Start it again | champrep-code-runner service start |
| Check the runner’s token | champrep-code-runner verify |
| Show the installed version | champrep-code-runner version |
| Check the configuration file | champrep-code-runner check-config |
Run in a terminal
Section titled “Run in a terminal”champrep-code-runner runThe runner keeps running and picks up jobs until you stop it. Press Ctrl+C once to stop after running jobs finish; press it again to interrupt them.
Run as a service
Section titled “Run as a service”A service starts the runner at boot and restarts it after a failure. Register
the machine first: service install refuses a configuration without runners.
sudo champrep-code-runner service install # install, enable at boot and startchamprep-code-runner service status # running, stopped or not installedsudo champrep-code-runner service stop # running jobs finish firstsudo champrep-code-runner service startsudo champrep-code-runner service uninstall # stop and remove the serviceservice status prints running, stopped or not installed. It exits with
code 3 when the service is not running, so scripts can check it.
| Option | Meaning |
|---|---|
--config PATH | The configuration the service uses. |
--name NAME | The service name. Use different names to run several runners with different configurations on one machine. |
--user USER | Run the service as this user instead of root or LocalSystem. |
As root, the runner installs a systemd service named champrep-code-runner. As
another user it installs a user service, which runs while you are logged in
(use loginctl enable-linger to keep it running). You can also use systemd
directly:
systemctl status champrep-code-runnerjournalctl -u champrep-code-runner -f # follow the logsFor the Docker executor, the service user needs access to the Docker socket, which is equivalent to root on that machine. Use a dedicated build machine.
As root, the runner installs a LaunchDaemon (com.champrep.code-runner) that
starts at boot. As another user, it installs a LaunchAgent that runs while you
are logged in, which suits jobs that need the keychain, the simulator or code
signing. Logs:
tail -f /Library/Logs/champrep-code-runner.log # LaunchDaemontail -f ~/Library/Logs/champrep-code-runner.log # LaunchAgentWindows
Section titled “Windows”From an elevated PowerShell prompt:
champrep-code-runner.exe service installGet-Service champrep-code-runnerThe service runs the binary from where it is, so copy it somewhere stable
first. Logs go to champrep-code-runner.log next to the configuration
(%ProgramData%\champrep-runner\).
All commands
Section titled “All commands”| Command | What it does |
|---|---|
register | Check a runner token and add the runner to the configuration. |
verify [--name N] | Check the configured runners’ tokens; exits 1 when one is invalid. |
run | Run until stopped. --log-file PATH writes logs to a file. |
run-single [--name N] [--max-jobs 1] | Run jobs of one runner, then exit. Useful for short-lived machines. |
service install|start|stop|status|uninstall | Manage the runner as a service. |
reset-token [--name N] | Get a new token and store it. The old token keeps working for a short grace period. |
unregister --name N or --all | Remove this machine’s runner from the configuration and from CHAMPREP Code. |
check-config | Validate the configuration file and print warnings. |
version | Print the version, revision and platform. |
Every command accepts --config PATH to use another configuration file.
Health checks and metrics
Section titled “Health checks and metrics”Start the runner with a listen address to expose health and metrics endpoints:
champrep-code-runner run --listen-address 127.0.0.1:9252| Path | Meaning |
|---|---|
/healthz | 200 while the process runs. |
/readyz | 200 when every runner is verified and requesting jobs. |
/metrics | Prometheus metrics: jobs running, finished and failed, and more. |
Logs are structured JSON and never contain tokens, variables or job output.