Skip to main content
This page takes you from a clean machine to one workflow running locally. Local runs use your working tree, including uncommitted and untracked files, and they need no GitHub credential. Before you start, confirm the host can run microVMs and has room for the default image. Install lists the requirements. The short version:
  • macOS, Linux on x86_64 or aarch64, or Windows through WSL2.
  • About 60 GB of free disk on the volume that holds Preloop’s VM data. The default image downloads about 9.6 GB and can peak near 60 GB while it unpacks.

​
1. Install the CLI

Homebrew and npm install the same release binaries:
The installer script works too, and it also installs the Linux guest runner that microVM jobs need.

​
2. Configure the engine

Each flag answers one step of init: init writes ~/.preloop/config.toml and checks the host’s disk, architecture, and hypervisor. If a check fails, it stops with exit code 3 and names what is short.
Run preloop init with no flags in a terminal to answer each step interactively. To see the host report without changing anything, run preloop init --probe --json.

​
3. Start the engine

The engine listens on 127.0.0.1:9090. Leave it running in this terminal and stop it with Ctrl-C. If serve asks whether to run init first, answer n to continue with the official image. You can re-run init at any time to change the image or the credential.

​
4. Run a workflow

In a second terminal, change to a repository that has workflows and run one:
  • -f selects the workflow. A bare file name resolves inside .github/workflows/. If the repository has exactly one workflow, you can omit -f.
  • --event simulates the trigger that starts the run. It defaults to push. For pull_request workflows, pass --event pull_request. The run then tests the merge with the base branch, which is fetched from origin.
  • The run snapshots your working tree, so you do not need to commit or push first.
The first job downloads and prepares the official image, so it takes longer than later jobs. Follow the run with:
preloop run does not start an engine: only preloop serve and preloop init --mode foreground do. If no engine answers at PRELOOP_URL, the command exits non-zero naming the endpoint it probed — start preloop serve in another terminal first.
If a step fails in an interactive terminal, the job pauses instead of being torn down. Attach to it with preloop debug. The debugging guide covers the verdicts you can issue.

​
Next steps