Skip to content
Documentation

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.

TaskCommand
Connect this machine to a runnerchamprep-code-runner register --url https://code.champrep.com
Run in this terminalchamprep-code-runner run
Install as a service and start itchamprep-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 againchamprep-code-runner service start
Check the runner’s tokenchamprep-code-runner verify
Show the installed versionchamprep-code-runner version
Check the configuration filechamprep-code-runner check-config
Terminal window
champrep-code-runner run

The 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.

A service starts the runner at boot and restarts it after a failure. Register the machine first: service install refuses a configuration without runners.

Terminal window
sudo champrep-code-runner service install # install, enable at boot and start
champrep-code-runner service status # running, stopped or not installed
sudo champrep-code-runner service stop # running jobs finish first
sudo champrep-code-runner service start
sudo champrep-code-runner service uninstall # stop and remove the service

service status prints running, stopped or not installed. It exits with code 3 when the service is not running, so scripts can check it.

OptionMeaning
--config PATHThe configuration the service uses.
--name NAMEThe service name. Use different names to run several runners with different configurations on one machine.
--user USERRun 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:

Terminal window
systemctl status champrep-code-runner
journalctl -u champrep-code-runner -f # follow the logs

For 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:

Terminal window
tail -f /Library/Logs/champrep-code-runner.log # LaunchDaemon
tail -f ~/Library/Logs/champrep-code-runner.log # LaunchAgent

From an elevated PowerShell prompt:

Terminal window
champrep-code-runner.exe service install
Get-Service champrep-code-runner

The 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\).

CommandWhat it does
registerCheck a runner token and add the runner to the configuration.
verify [--name N]Check the configured runners’ tokens; exits 1 when one is invalid.
runRun 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|uninstallManage 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 --allRemove this machine’s runner from the configuration and from CHAMPREP Code.
check-configValidate the configuration file and print warnings.
versionPrint the version, revision and platform.

Every command accepts --config PATH to use another configuration file.

Start the runner with a listen address to expose health and metrics endpoints:

Terminal window
champrep-code-runner run --listen-address 127.0.0.1:9252
PathMeaning
/healthz200 while the process runs.
/readyz200 when every runner is verified and requesting jobs.
/metricsPrometheus metrics: jobs running, finished and failed, and more.

Logs are structured JSON and never contain tokens, variables or job output.