> ## Documentation Index
> Fetch the complete documentation index at: https://docs.preloop.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Install the Preloop CLI, configure the engine, and run a workflow from your working tree.

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](/control-plane/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:

```sh theme={null}
brew install preloopdev/tap/preloop
# or
npm install -g @preloop-dev/cli
```

The [installer script](/control-plane/install#installer-script) works too, and it also installs the Linux guest runner that microVM jobs need.

## 2. Configure the engine

```sh theme={null}
preloop init --auth none --golden official --mode none
```

Each flag answers one step of `init`:

| Flag | Meaning |
| - | - |
| `--auth none` | Write no GitHub credential. Local runs do not need one. Add a GitHub App later to publish check runs. |
| `--golden official` | Use the official packed GitHub runner image, which Preloop downloads on first use. |
| `--mode none` | Write the configuration and start nothing. |

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

<Tip>
  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`.
</Tip>

## 3. Start the engine

```sh theme={null}
preloop serve
```

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:

```sh theme={null}
cd my-repo
preloop run -f .github/workflows/ci.yml --event push
```

* `-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.

<video controls src="https://mintcdn.com/preloop/OGyZqdRph9qrEfDT/demo/debug.mp4?fit=max&auto=format&n=OGyZqdRph9qrEfDT&q=85&s=16d6d4c310723b62714738bb06cb2f5e" alt="Screen recording of a local run failing, a fix applied in another terminal pane, and the workflow re-run without a push" aria-label="Screen recording of a local run failing, a fix applied in another terminal pane, and the workflow re-run without a push" data-path="demo/debug.mp4" />

The first job downloads and prepares the official image, so it takes longer than later jobs. Follow the run with:

```sh theme={null}
preloop status
preloop logs -f --job <job-key>
```

<Note>
  `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.
</Note>

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](/control-plane/guides/debugging) covers the verdicts you can issue.

## Next steps

* [Connect a GitHub App](/control-plane/github/app) so pushes and pull requests start runs and publish check runs.
* [Configuration](/control-plane/configuration) covers the config file, secrets, and where state is stored.
* [Install](/control-plane/install#run-as-a-background-service) runs the engine as a service that survives reboots.
* [CLI reference](/control-plane/reference/cli) lists every command and flag.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.