NERUDO
Sign in

Linux runner

The podman and docker drivers run each job in a fresh container on a Linux host. Use the static nerudo-runner binary for x86_64 or aarch64.

Before you start

  • A Linux host with cgroup v2.
  • Rootless podman 4 or later, or docker 24 or later.
  • The nerudo-runner binary. See Download the runner.
  • An OCI image that contains the job's tools.

The runner does not install or start podman or docker. If both are installed, the default driver is podman. Use --driver docker to select docker.

Rootless podman — podman that runs as an ordinary user, without root. It is the recommended runtime.

Make sure that limits apply

Rootless podman applies CPU, memory, and process limits only if systemd gives the user these cgroup controllers.

  1. Enter cat /sys/fs/cgroup/user.slice/user-$(id -u).slice/user@$(id -u).service/cgroup.controllers.
  2. Make sure that the output contains cpu, memory, and pids.

If a controller is missing, add a systemd drop-in with Delegate=cpu cpuset io memory pids for user@.service. Then restart the host.

nerudo-runner doctor fails if a job container runs without its memory limit.

Register and test

  1. Enter nerudo-runner login --repo OWNER/REPO --name linux-ci --labels LABELS.
  2. Get an owner or admin approval. See Register the runner.
  3. Enter podman pull IMAGE, or docker pull IMAGE.
  4. Enter nerudo-runner doctor --driver podman --image IMAGE --cpus 4 --memory 8G.
  5. Make sure that each check shows ok or info.
  6. Enter nerudo-runner daemon --driver podman --image IMAGE --cpus 4 --memory 8G --once.
  7. Start a CI job in the repository.

Run the runner as a systemd user service

  1. Copy cf/nerudo-runner/deploy/systemd/nerudo-runner.service to ~/.config/systemd/user/.
  2. Change --image, --cpus, and --memory in its ExecStart line.
  3. Enter loginctl enable-linger $USER.
  4. Enter systemctl --user daemon-reload.
  5. Enter systemctl --user enable --now nerudo-runner.
  6. Enter systemctl --user status nerudo-runner.

enable-linger keeps the service running when you are not signed in. Enter journalctl --user -u nerudo-runner -f to see the runner's log.

On systemctl --user stop, the runner cancels its job and removes the container before it stops.

Driver details

  • Each container gets --cpus, --memory, and --pids. Swap is off.
  • The container runs as the runner's user. With podman, --userns keep-id maps that user.
  • The container has no capabilities, no-new-privileges, and a read-only root.
  • The workspace is a host directory under --work-dir. It has no size limit.
  • /tmp is a memory file system. Files in /tmp use the job's memory.
  • The container uses the engine's default network. It can reach the host's services and other containers on that network. Run the runner on a host that has no other services, or block the bridge with firewall rules.

See also Troubleshoot a runner and Runner limits.