CI runners

A runner is a program on your own machine that runs the CI jobs of a repository. Nerudo sends each job to a runner with the job's labels. The runner reports the logs and the result. The result decides whether a change lands.

Each job runs in a fresh job machine. The runner removes the machine when the job ends. Only the job's workspace and step scripts go into the machine. The runner's credential stays on the host.

The runner connects out to Nerudo over HTTPS. It needs no inbound port.

Choose a runner

All drivers give the job machine a read-only root filesystem and no Linux capabilities. Each job machine has CPU and memory limits. Only the Kubernetes driver also limits the workspace disk. See Runner limits.

Download the runner

The current version is 0.2.0. Each signed release of the nerudo/runner repository has these files:

The Linux binaries are static. They need no system libraries.

To install with the script:

1. Open a terminal on the runner host.
2. Enter curl -fsSL https://nerudo.dev/install/runner.sh | sh.

The script selects the file for your operating system and processor. It checks the archive digest against the signed release. It installs nerudo-runner in ~/.local/bin. It does not install a container runtime.

To install by hand:

1. Open the Packages tab of nerudo/runner.
2. Download the archive for your host and SHA256SUMS.
3. Enter shasum -a 256 -c SHA256SUMS --ignore-missing.
4. Extract the archive.
5. Move nerudo-runner to a directory on your PATH.

Enter nerudo-runner --version to see the installed version and platform.

Register the runner

An owner or admin of the repository's organization approves each runner once. The approval uses a passkey.

1. On the runner host, enter nerudo-runner login --repo OWNER/REPO --name NAME --labels LABELS.
2. Send the page address and the code to an owner or admin.
3. The owner or admin opens the page.
4. The owner or admin examines the code, the repository, the runner name, and the labels.
5. The owner or admin approves with a passkey.

The runner saves its credential in ~/.config/nerudo-runner/runner.json. The file is private. Use a new --state path for each runner.

Labels — Names that connect jobs to runners. A job runs only on a runner that has all of the job's labels. The [ci] labels of the repository's nerudo.toml set the job labels.

Approve only machines that you control. A runner's results decide which changes land.

Check the runner

1. Enter the daemon command of your guide, with doctor in place of daemon.

For example, nerudo-runner doctor --driver podman --image docker.io/library/ubuntu:24.04.

doctor checks the state file, the connection to Nerudo, and the runner credential. It checks the runtime and its permissions. Then it starts a real job machine, runs a short probe, and removes the machine. Each failed check shows the next action.

Find your runners

1. Open the repository.
2. Select Pipelines.

The Runners table shows each runner's status, labels, version, and platform. The platform shows the driver, the operating system, and the job machine limits.

online — The runner called Nerudo in the last 60 seconds.

busy — The runner runs a job now.

offline — The runner did not call Nerudo in the last 60 seconds.

Each job page shows a Runner machine panel. It shows the machine name, the node, the image, and the limits. It also shows peak memory, CPU, and workspace size.

Update the runner

1. Stop the runner service.
2. Install the new version.
3. Start the runner service.

The saved registration stays the same. A running job is cancelled when the runner stops. Nerudo sends a cancelled job to a runner again.

Remove a runner

From a signed-in terminal (nerudo auth login):

1. Enter nerudo runners list --repo OWNER/REPO.
2. Find the runner's id.
3. Enter nerudo runners remove --repo OWNER/REPO --id ID.

The removed runner's next call is refused. Delete its state file on the host.

Related guides

• Troubleshoot a runner
• Runner limits