runnerd
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, slots from how long jobs waited (
runnerd initturns this on), so you don't tune it by hand. - Slots share one build cache that the default branch writes, and a fresh runner can wait ready for the next job.
- Every queued job shows why it waits;
runnerctl insightsreports 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
|
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.
Send a job here with:
runs-on:
Serve only private repositories: on a public one, anyone who opens a pull request can run code on this host.
Requirements
- Linux x86-64 with cgroup v2, and Docker with the systemd cgroup driver. Runner images are linux/amd64 only.
- Sysbox.
runnerd doctorprints install commands for common distros. - A systemd slice whose
MemoryMaxis the runners' budget;initprints one. - The GitHub CLI, logged in with the
reposcope.
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
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:
The Gradle build cache test also needs the network:
License
MIT