Skip to content

HTTP API

JSON over $XDG_RUNTIME_DIR/runnerd.sock (curl --unix-socket), mode 0600: only the user runnerd runs as may connect. Types: crates/core/src/api.rs. Times are Unix seconds, sizes bytes, CPU millicores.

Jobs, their logs, the timeline and job actions are on Jobs API.

Profiles, slots, runners, repositories with their queued jobs, the budgets.

POST /v1/repositories/{owner}/{name}/pause?force=, .../resume

Section titled “POST /v1/repositories/{owner}/{name}/pause?force=, .../resume”

409 naming the running job, unless force=true cancels its run; 204. Without {owner}/{name}, for every repository.

202; 409 while it reseeds or a record shell is open in it.

204; 409 naming the jobs that use the cache.

GET /v1/config, POST /v1/config/check, GET /v1/doctor

Section titled “GET /v1/config, POST /v1/config/check, GET /v1/doctor”

The file’s text and revision, secrets as "<secret>"; check-config on a TOML body; runnerd doctor’s checks from the daemon’s last run, at most a minute old, with whether they are current; it waits up to 20 s for a new run, then answers the last one as it stands; 503 before the first run finishes or when the last failed.

What needs attention now, most urgent first, each item worded with what clears it; revision changes with the content and counts from 1 in each daemon instance.

Checks, writes and applies it; 422 invalid, 500 not writable, 503 stopping, all leaving everything as it was. A revision older than the file (an edit, or auto sizing) answers 409.

202; true kills running jobs.

A test message to every [notify] target or the one named; 404 without targets.

GET /v1/records, DELETE /v1/records/{job}, DELETE /v1/records?all=true, ?older_than=2d

Section titled “GET /v1/records, DELETE /v1/records/{job}, DELETE /v1/records?all=true, ?older_than=2d”

The records; the ones removed (a record with a shell open stays; by job it answers 409).

POST /v1/records/{job}/shell?step=&cols=&rows= with Connection: Upgrade, Upgrade: runnerd-tty

Section titled “POST /v1/records/{job}/shell?step=&cols=&rows= with Connection: Upgrade, Upgrade: runnerd-tty”

101, then raw terminal bytes both ways; 409 when the budget is full.

GET /v1/dashboard, POST /v1/dashboard/sign-out, POST /v1/dashboard/pairings?origin=

Section titled “GET /v1/dashboard, POST /v1/dashboard/sign-out, POST /v1/dashboard/pairings?origin=”

[web] open; signs every browser out; a 5-minute login link for one of [web] origins.

Server-sent events, below.

Read-only: GET /v1/host/samples, /v1/stats, /v1/activity, /v1/sizing (advice), /v1/insights?days= (Insights; 14 days by default, 90 at most), /v1/digest, /v1/savings, /v1/caches and /v1/caches/history.

A forced pause cancels the runs of the repository’s running jobs, other jobs of those runs included, and removes a runner still running 90 s later, a restart in between or not. A paused repository’s waiting runners, warm ones too, stop at once. A pause lasts until a resume, across restarts.

job.queued, job.started, job.step and job.finished follow a job. slot.changed, budget.changed, profile.changed, profile.removed, repository.changed and repository.removed carry the state after a change, not each transition. cache.reseeded marks a new snapshot, record.created, record.deleted, record.skipped and record.gone (its image removed outside runnerd) a record’s fate, sizing.changed an auto sizing write, and runner.failed a runner that could not be registered or started (once, until one of the repository’s runners takes a job). job.sample, host.sample, log.line (logs=true) and attention.changed, which carries GET /v1/attention’s instance and new revision, are live.

Every other event has an ID. Send the last one seen as Last-Event-ID and the stream resumes after it, across daemon restarts.