# runnerd
[](https://github.com/ayagmar/runnerd/actions/workflows/ci.yml)
[](https://github.com/ayagmar/runnerd/releases/latest)
[](https://crates.io/crates/runnerd)
[](rust-toolchain.toml)
[](LICENSE)
[](https://ayagmar.github.io/runnerd/)
runnerd runs ephemeral GitHub Actions runners on one Linux host: a fresh container per job, sized from what the repositories you serve have used.
## Install
```sh
```
`init` writes a config sized for the host and a systemd user unit, runs `runnerd doctor` and prints the steps left. It never runs anything as root; the slice and Sysbox commands it prints are yours to run. Then:
```sh
systemctl --user daemon-reload
systemctl --user enable --now runnerd
runnerctl status
```
Point a job at the host with `runs-on: [self-hosted, linux, x64]`. Serve private repositories only: on a public one, anyone who opens a pull request can run code on this host.
## Requirements
- Linux with cgroup v2, and Docker with the systemd cgroup driver.
- [Sysbox](https://github.com/nestybox/sysbox) and a systemd slice whose `MemoryMax` is the runners' budget.
- The [GitHub CLI](https://cli.github.com), logged in with the `repo` scope.
Binaries ship for x86_64 and aarch64; the runner images are linux/amd64 only, so on aarch64 build the `base` stage of `image/Dockerfile` on the host.
## Documentation
Full docs: <https://ayagmar.github.io/runnerd/>. [Install](https://ayagmar.github.io/runnerd/start/install/) covers pinned versions and attestation checks, [Configuration](https://ayagmar.github.io/runnerd/reference/configuration/) every key, [Why is my job waiting?](https://ayagmar.github.io/runnerd/guides/waiting/) every reason a job gives, and [Security model](https://ayagmar.github.io/runnerd/security/) what jobs, the token and the dashboard can reach.
[ARCHITECTURE.md](https://github.com/ayagmar/runnerd/blob/main/ARCHITECTURE.md) says where the code lives, [docs/adr](https://github.com/ayagmar/runnerd/blob/main/docs/adr/README.md) why, and [CONTRIBUTING.md](https://github.com/ayagmar/runnerd/blob/main/CONTRIBUTING.md) how to send a change.
## Building
```sh
cargo build --release
```
Run "The gate" in [AGENTS.md](https://github.com/ayagmar/runnerd/blob/main/AGENTS.md) before sending a change. Tests that start real containers are ignored by default and need Docker with Sysbox and the images:
```sh
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:
```sh
cargo test -p runnerd-core --test build_cache_gradle -- --ignored
docker rmi runnerd-test-build-cache
```
## License
MIT