Runners
A runner is a separate process that takes checks off the forge. It can be on the forge's machine, on another machine or in a rented one. It needs two things: the forge's URL and a token. Nothing dials in to it, it shares no disk with the forge, and it never sees the forge's data directory or database.
Off by default. With FORGE_CHECKS_PLACEMENT=runner the forge offers a check's
steps to runners, and never needs one: with no runner connected the check
runs on the forge's machine at once, as process does; when runners are
connected and none takes the job in 5 seconds it runs on the forge's machine
too.
Start one, in two lines
An admin enrols it (admin scope; the token is shown this once):
curl -X POST -H "Authorization: Bearer " -H 'content-type: application/json' -d '{"name":"mac"}' /api/v1/admin/runners
On the machine that will run checks, from a checkout of the forge or its image:
FORGE_URL=https://your.forge FORGE_RUNNER_TOKEN=forge_runner_… bun src/runner/main.ts
GET /api/v1/admin/runners lists the enrolled runners and when each last
asked for work; DELETE /api/v1/admin/runners/<id> removes one: its token
stops at once and a job it held is queued again. A check's page and the
terminal's run list say "Ran on runner mac" for a check one took.
The machine needs what the checks need: git and bun, and whatever the
repository's check calls. The forge's image has all of it, and bubblewrap
and socat for cells.
FORGE_RUNNER_DIR is where it keeps its scratch and its store (default: a
forge-runner directory under the temp directory), FORGE_RUNNER_JOBS how
many jobs it runs at once (default 1).
What a job is
Plain data, made by the forge from the repository's forge.json as it would
run the check itself:
| Field | What |
|---|---|
commit | the exact commit under test: for a pull, its merge into the base as it stands |
base, depth | the commit a fast check diffs against, and how deep to fetch |
steps | the recipe in order: install, then check, each a command |
env | the check's own variables (CI, FORGE_*), never the forge's |
limits, timeoutS | cores, memory and disk as declared; seconds a step may take |
egress, egressMode | the hosts the steps may reach besides the forge |
cell | required when the code is an outside contributor's: no cell, no run |
cache | names a runner may keep things under: the repository, the tree, the base |
With the job comes a lease of 30 seconds, renewed by every report, and a job token that works for this one job while the lease lives.
What a runner does
- Claims:
POST /api/v1/runner/claimwith its runner token, held open until a
job is offered. Of two runners asking at once, one gets a job.
- Fetches the job's commit from the job's own git door
(/api/v1/runner/jobs/<id>/git) with the job token, into a bare mirror it
keeps per repository, so the next job fetches only new objects.
- Runs the steps in the cell the forge uses (bubblewrap on Linux): the
checkout and a home are the only places to write, the forge and the declared hosts the only way out. Where the machine has no cells it says so, runs the steps as plain processes, and hands back any job that requires a cell.
- Streams the log every second (
POST /api/v1/runner/jobs/<id>), reports each
step's result, and removes its scratch.
A runner that goes silent loses its lease: the job is queued again, and the check's try count does not move. Twice, and the forge runs it itself.
What a runner decides, and what it does not
The forge keeps the queue, the claim on the check, the budget and the record. A runner's answer stands only as: green, the check command's exit code, or its timeout. The forge runs the check on its own machine when the install failed on the runner, when the step ended any other way (a signal, a limit, a full disk there), and when one or two tests failed: those are re-run alone to tell a flake from a red, which a runner cannot do yet.
Only a pull's check goes to a runner. The default branch's own check and a verification after landing keep what they measured (the build cache, the impact map, kept results) from the checkout, and a runner cannot send those back yet, so they stay on the forge's machine. For the same reason a runner's check starts without them: correct, and slower than the forge's own.
What a runner can and cannot see
- Can: the commit of each job it claims and that commit's history; the
names and tips of that repository's branches (the advertisement); the job's recipe and variables. It can append to that check's log and end that job.
- Cannot: fetch any other object of that repository, or anything of
another repository; push; read an issue, a page, the API or the MCP. Its two tokens are not account tokens: every other door treats them as no credential at all. A job token dies with its lease.
- A runner token can claim any job on the desk, so enrol machines you trust
with every repository whose checks run here. Without cells, a check runs as the runner's own user on that machine.
A runner's requests are counted like a stranger's (600 a minute from one address); one job is about 60 a minute.
Code: src/checks/runner_jobs.ts (the desk), src/checks/runner_step.ts (the
forge's side), src/runner/main.ts (the runner), src/http/api/runners.ts.
Tests: test/checks-runner-placement.test.ts. Epic: #13652.