runnerd-web 0.0.23

The web dashboard runnerd serves on loopback: a client of the daemon's API
Documentation

runnerd

CI Release crates.io MSRV License: MIT Docs

runnerd runs ephemeral GitHub Actions runners on one Linux host. Each job gets a fresh container; the repositories you configure share slots inside a memory budget.

  • It records every job's memory and CPU use and sizes each profile from it: memory from peaks, CPUs from averages and from how often the CPU cap throttled a job, slots from how long jobs waited (runnerd init turns this on), so you don't tune it by hand.
  • Runners share one build cache (Gradle, sccache, Bazel, Turborepo, Nx) that the default branch writes, and GitHub Actions' cache is served from the host's disk. A job starts in the slot that ran it last, and a fresh runner can wait ready for the next job.
  • Every queued job shows why it waits; runnerctl insights reports slow and flaky jobs and what the minutes would have cost on GitHub-hosted runners.
  • A failed job's runner can be kept, so you can open a shell in it.
  • Runners are unprivileged: they run under Sysbox with their own Docker Engine.

It is in early development.

flowchart TB
    github["GitHub<br/>queued jobs, JIT runners, steps"]
    subgraph daemon["runnerd serve"]
        engine["engine"] --- history[("job history<br/>SQLite")]
        api["API: JSON and events<br/>on a Unix socket"]
        web["dashboard<br/>127.0.0.1:7477"]
    end
    subgraph slice["runnerd.slice: MemoryMax is the budget"]
        jvm1["jvm 1"]
        jvm2["jvm 2"]
        node1["node 1"]
        mirror["Docker Hub mirror"]
    end
    github <-->|"HTTPS, the gh CLI's token"| engine
    engine -->|"Docker API: one container per job"| slice
    runnerctl["runnerctl, runnerctl tui"] --> api
    browser["browser"] --> web
    web --> api
    api --> engine

Quick start

curl -fsSL https://github.com/ayagmar/runnerd/releases/latest/download/install.sh | sh
runnerd init halyard/ledger halyard/storefront

init writes a config sized for the host and a systemd user unit, then runs runnerd doctor and prints the steps left. It never runs anything as root: it prints those commands (usually the slice and Sysbox) for you to run.

systemctl --user daemon-reload
systemctl --user enable --now runnerd
runnerctl status

Send a job here with:

runs-on: [self-hosted, linux, x64]

Serve only private repositories: on a public one, anyone who opens a pull request can run code on this host. runnerd init and runnerd doctor warn for a public one.

Requirements

  • Linux x86-64 with cgroup v2, and Docker with the systemd cgroup driver. Runner images are linux/amd64 only.
  • Sysbox. runnerd doctor prints install commands for common distros.
  • A systemd slice whose MemoryMax is the runners' budget; init prints one.
  • The GitHub CLI, logged in with the repo scope.

Other ways to install (a pinned version, a prefix, attestation checks, cargo install) are on the Install page.

Documentation

https://ayagmar.github.io/runnerd/: Install, Configuration, Admission and sizing, Running, Insights and notifications, Dashboard and CLI. ARCHITECTURE.md says where the code lives and docs/adr why.

Building

cargo build --release

Before sending a change, run "The gate" in AGENTS.md; CI runs the same. CONTRIBUTING.md covers CI jobs and releases.

Tests that start real containers are ignored by default and need Docker with Sysbox and the images:

docker build --target jvm -t runnerd-runner:jvm image
docker build --target base -t runnerd-runner:base image
cargo test -p runnerd-core --test docker_smoke --test cache_reseed --test slot_docker_store -- --ignored

The Gradle build cache test also needs the network:

cargo test -p runnerd-core --test build_cache_gradle -- --ignored
docker rmi runnerd-test-build-cache

License

MIT