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 workflow.jsonc descriptor. The default is boardwalk/linux, so most workflows never set it.

Choosing where runs execute

There are three ways to run Boardwalk, and which one fits comes down to how much has to stay inside your own network. The same workflow package runs unchanged in all three, so this is an operational choice, not a rewrite.

So if the requirement is strictly that data cannot leave your network, the answer is the fully self-hosted open source engine. Self-hosted runners keep compute and the working tree on your hardware but still talk to the hosted control plane, so they answer "run it on our machines" rather than "air-gap it." Everything else is the managed cloud, which the rest of this page covers.

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 permissionscope 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.

Hosted runners

Hosted runners are Boardwalk-operated Linux microVMs. Boardwalk provisions, isolates, scales, and destroys them; you just name a label.

Isolation and the broker

Every 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.

Suspend on waits

Because the whole VM is the durable unit, a wait (sleep, a human-input gate, a workflows.call() child) suspends the VM as a memory snapshot and restores it later exactly where it left off: idle costs nothing, and the program simply continues. Suspension semantics, and why waits are free, are covered in Human-in-the-loop.

Scratch working directory

The working directory is scratch by default and wiped after the run; opt into a persistent workspace when a workflow needs state across runs.

Egress

Outbound network is governed by the workflow's egresspolicy, enforced fail-closed at the host: a custom allowlist blocks every other destination, with the platform's own endpoints always reachable.

Runner images

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

The one hosted label today is boardwalk/linux, the general-purpose default: Linux with Node, Python, git, and common CLIs preinstalled.

"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 and no deadline. A suspended wait is free, so a run can span days without burning anything. The cap that matters is the budget: max_compute_seconds meters active compute only (a parked sleep or human-input wait does not count), and a breach parks the run for approve-and-resume rather than killing it, alongside max_usd and max_tokens.

"budget": { "max_compute_seconds": 21600 } // pause for approval after 6 hours on-CPU

Browser and desktop

Every hosted run boots an ambient graphical desktop with headful Chromium and a pinned Playwright MCP server already installed. computer.openBrowser() opens Chromium on that desktop and gives the workflow a browser session it can drive in code or hand to an agent() leaf; the full surface is in Browser use.

computer.openDesktop() hands an agent that same desktop rather than a browser, for work that lives in an application instead of a page: screenshots, clicks, typing, scrolling and drags against whatever is on screen. See Desktop use.

Custom container

When your tools need an environment the stock images don't provide, point the descriptor's containerfield at 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, common CLIs, Chromium, and the first-class Playwright MCP browser surface described above. Use a custom image for a different browser build, native system libraries, a JVM, a database client, or a compiler toolchain the stock 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). The full guide, including quickstart, fleet enrollment, the security model, and private networks, is at Self-hosted runners.

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