Runners

A runner is somewhere builds can execute. Walis ships with one built in.

The local runner

local runs inside the API process. Its concurrency comes from Concurrent build limit in Settings → Build — that is what the slot count reflects.

Remote agents

walis-runner is a self-contained binary. It needs no runtime installed on the target machine:

walis-runner \
  --server https://walis.example.com/ \
  --name builder-01 \
  --labels linux,docker

The agent polls, claims work with POST /api/runners/{name}/claim — the response contains the steps the server has already planned — reports each step's output and result, then closes the build out. Artifacts go up separately.

The step loop is the same code locally and remotely (BuildStepSequence in Walis.Core); the only difference is whether the sink writes to the database or posts HTTP. A step behaves the same way on a remote agent as it does on an API node.

Slots, labels and heartbeats

Concept	Meaning
Slots	How many builds this runner will accept at once.
Labels	Free-form tags — macos, arm64, docker. Descriptive.
Heartbeat	Reported every minute. Silent for five minutes and the runner is marked offline.

Runner-offline can raise a notification. Stop accepting work drains a runner without deleting it: running builds finish, new ones are not claimed.

Work pinned to an offline runner

Builds assigned to a runner that is not connected stay queued. They are not reassigned and not dropped. This is deliberate — a job pinned to the machine with the signing key should wait for that machine, not quietly run somewhere else — but it does mean a queue that will not drain is usually a runner that has not come back.