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-python",

Machine size

Size is 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" },

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). A workflow targets a pool by name:

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. Pool registration is the forward direction of the runner system and is tracked alongside the published Linux images.

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.