Runners

A runner is the machine a run executes on. Every run gets a fresh, isolated runner; the workflow picks which kind with the runs_on field in its meta. The default is boardwalk/linux, so most workflows never set it.

The model

Runners follow the GitHub Actions runner model, not its protocol: label-based selection, a fresh isolated runner per run, hosted and self-hosted pools, public image definitions, and an explicit permission scope per run. The contract is Boardwalk-native (no workflow YAML, no GitHub runner protocol). One mental model covers both kinds: a hosted runner is just a Boardwalk-operated runner pool. The only difference is who owns the pool's lifecycle, Boardwalk or you.

Either way the runner is credential-less: it never holds your org's secrets or cloud keys. It reaches the control plane with a short-lived per-run token and brokers everything it needs (secrets, artifacts, inference) through that token, so a compromised run can't reach beyond what its manifest allowed.

Hosted runners

Hosted runners are Boardwalk-operated Linux machines. Boardwalk provisions, isolates, scales, and destroys them; you just name a label. The working directory is scratch by default and wiped after the run (opt into a persistent workspacewhen a workflow needs state across runs). Outbound network is governed by the workflow's egresspolicy. What's installed on each image is documented in the public runner-images repo, the trust surface for exactly what your code runs inside.

Labels

runs_on: "boardwalk/linux",

Machine size

Size is a separate knob from the label, independent of the image. Pass the object form of runs_on to ask for more CPU and memory; the default is small.

runs_on: { label: "boardwalk/linux", size: "xlarge" },

Run duration

Hosted runs are long-lived: there is no hard cap. A run gets a 4-hour wall-clock default; raise or lower it with the duration budget. The clock is per attempt, so a run that restarts after a crash gets the full window again.

budget: { max_duration_seconds: 6 * 60 * 60 }, // allow up to 6 hours

Custom container

When your tools need an environment the stock images don't provide, point meta.containerat any OCI image and the run's tools execute inside it. The Boardwalk runtime still wraps it (broker, artifacts, logs), so the workflow program and its SDK calls are unchanged.

container: { image: "ghcr.io/acme/build-env:1.4" },

This is the path for anything heavier than the stock images carry. They include Node, Python, git, and common CLIs, but not large runtimes such as a headless browser: to drive Playwright or Puppeteer, point container at an image with Chromium and the browser deps baked in, then bashand your program use it like any other tool. The same goes for a JVM, a database client, or a compiler toolchain the base image doesn't ship.

Self-hosted runners

Self-hosted runners are your own machines, registered as a named pool, that take run assignments from the hosted control plane. They're the path for compute Boardwalk doesn't host: machines on your private network, GPU boxes, or macOS (which can't be containerized, so it's never a hosted image). Setup is one command on the machine:

boardwalk runner start --org your-org

A workflow targets a pool by name (or omits pool for the default one):

runs_on: { kind: "self-hosted", pool: "my-macs", labels: ["macos"] },

The same assignment contract and credential-less broker apply: a self-hosted runner connects outbound and holds no platform secrets, so registering one never hands your machine the keys to your org. The run executes on your hardware, so code and the working tree stay local, but run events, logs, and artifacts still stream to the hosted control plane. The full guide, including fleet enrollment, the security model, and private networks, is at Self-hosted runners. This is different from self-hosting Boardwalk: a self-hosted runner is your compute attached to the hosted platform, whereas self-hosting runs the whole open source engine, control plane and all, on your own infrastructure. When the requirement is that nothing leaves your network, that is the one to reach for.