Skip to main content
preloop-runner is a single binary that replaces the official actions/runner on a host. It keeps the same configure, run, and remove workflow as the official config.sh and run.sh. It registers with a GitHub repository or organization, or with a Preloop control plane, and runs jobs directly on the host. It needs no control plane, no VM runtime, and no background services.

​
When to use it

Use the standalone runner for self-hosted GitHub runners on Linux or macOS hosts, when you want a small binary and low memory use per runner. Use the control plane when you want jobs isolated in microVMs, local runs of your workflows against your working tree, or pause-on-failure debugging.

​
What it does

  • Registers a self-hosted runner with a GitHub repository or organization, or with a Preloop control plane.
  • Polls for jobs, runs them, streams console output, and reports step status, logs, and results.
  • Runs run: steps, JavaScript actions on Node 20 or 24, composite actions, and Docker actions. Job containers (container: and services:) run through the docker CLI on the host.
  • Does not update itself. Upgrade by installing a newer binary.
  • Includes lint, which parses a workflow file and expands its jobs without running them.

​
Platforms

The Linux binaries target glibc (-gnu builds). Windows is not published. On Windows, run the Linux binary under WSL2.

​
How it compares

The repository’s runner comparison ran both runners against the same Preloop server, executing the same two-step workflow, on an Apple M1 Pro under macOS. Each value is the median of three runs. The official runner was actions/runner v2.336.0. The official package bundles Node 20 and Node 24, which accounts for most of its 434 MB. The preloop-runner measurement skipped those runtimes with --no-externals, so the second install-size row is the like-for-like comparison. Without them, the official install is about seven times larger. In the repository’s light conformance run, 14 workflows produced no differences between the official runner and preloop-runner. These measurements come from one machine. Expect different numbers on your hardware.

​
Next steps

Install

Install the binary, register it, and run it as a service.

Configuration

Every command, flag, and environment variable.

Architecture

How the listener and the per-job worker process jobs.

Comparison

How preloop-runner compares with other local runners.