Skip to content

Where each part lives

runnerd's partsThe daemon holds the engine, the history store and the socket API. Each tick the engine polls GitHub for queued jobs and registers just-in-time runners there, and starts and removes one container per runner in Docker with the sysbox runtime. The engine writes every job to the history store. The socket API serves the engine's status and the store's history as JSON and server-sent events over a Unix socket to three clients: runnerctl, runnerctl tui and the web dashboard.GitHubqueued jobs, JIT runnersDocker + sysboxone container per runnerrunnerd daemonengineeach tick: poll, plan, start and remove runnershistory storeSQLite: jobs, steps, samplessocket APIJSON and SSE, Unix socketpoll, registerstart, removerunnerctlcommands, scriptsrunnerctl tuiterminal UIdashboardrunnerd-web
The daemon is the only part that talks to GitHub and Docker. Every client reads and writes through its socket.
Part Where What it owns
Daemon, socket API crates/daemon runnerd commands; the routes clients call; [notify] deliveries
Engine crates/core/src/scheduler slot state, the tick, planning, starting and removing runners
GitHub, Docker crates/core/src/github.rs, docker.rs the only code that talks to them, behind traits the engine’s tests fake
History store crates/core/src/store.rs SQLite; one writer
Admission, sizing crates/core/src/admission, sizing predicted peaks, slot and memory advice
API types, wording crates/core/src/api what every client shows of a fact: outcomes, waits, budgets, view and column names
Dashboard crates/web server-rendered pages, charts, live updates
CLI and TUI crates/cli runnerctl; the TUI is src/tui, one module per view
Runner image image/ the images the containers start from

Contributors: ARCHITECTURE.md has the crate rules, the request path and state, and every design decision links to its ADR.