preloop-runner

preloop-runner [--runner-root dir] [--ca-bundle file] command [options]

preloop-runner is a native Rust reimplementation of the GitHub Actions runner listener and worker (`Runner.Listener` plus `Runner.Worker`). It registers, polls, executes, and reports using the same protocol as the official .NET runner, against GitHub or a preloop engine. The binary is a few files and about 12 MB, versus hundreds of megabytes for the official tarball that bundles Node runtimes.The clap version string includes protocol-compat 2.335.1. Workspace version is 0.34.0. Jobs can use the GitHub-current broker path (default) or the legacy Azure DevOps message-queue path (`--via azdo`). A hidden worker subcommand is spawned per job and reads NDJSON on stdin; it is not part of the operator surface.Install the standalone binary from GitHub Releases, or `install.sh --runner`, which places it on `PATH` (commonly `~/.local/bin`). Container image: `ghcr.io/preloopdev/preloop-runner`. The preloop CLI's own `install.sh` also drops a Linux guest copy at `<prefix>/lib/preloop/runner/<triple>/preloop-runner` for microVM jobs.

--runner-root dir

Runner root directory (default: current directory). Global

PEM CA bundle for custom certificate trust. Also honors SSL_CERT_FILE. Global

Print usage. Every subcommand accepts it too

Print the crate version and protocol compatibility tag

configure --url url --token token

Register with a GitHub repository or organization. --token also reads PRELOOP_RUNNER_TOKEN. --name defaults to the hostname. --labels is a comma-separated list. --work is the work directory name relative to the runner root (default `_work`). --runner-group defaults to `default`. --unattended skips prompts. --replace overwrites an existing runner with the same name. --ephemeral deregisters after one job. --no-externals skips downloading Node.js externals

Start the listener: poll for jobs and spawn workers. --once exits after one job. --via defaults to broker

Deregister this runner

Parse and expand a workflow YAML file without executing it. --workspace-root is the repository root used to collect local reusable workflows

PRELOOP_RUNNER_TOKEN

Registration token for configure when --token is omitted

Default path for --ca-bundle

This binary is the runner, not the Preloop control plane. To run `.github/workflows` locally in microVMs, use preloop. configure needs a registration token from GitHub (or from a preloop server). The official runner still works against a preloop engine unchanged; this binary is the smaller replacement. Protocol compatibility is pinned in the version string and can lag GitHub's newest runner release.

preloop-runner ships in the preloopdev/preloop workspace as crate preloop-runner, MIT-licensed, alongside the preloop CLI.

preloop(1), act(1), gh(1), git(1)

Source code · Documentation