Preloop

Preloop

Preloop is a macOS-first local/self-hosted/managed CI platform. It reimplements the GitHub Actions control plane (aksh) and a faithful Rust runner, and executes each job in an isolated Linux microVM via smolvm (libkrun) on Apple Silicon, with Firecracker as the scale-tier executor. Workflows are drop-in GitHub Actions YAML; the unmodified official runner also works against aksh.

Source of truth for this skill: the CLI at crates/preloop-cli/src/main.rs (current subcommands only — docs under preloop/docs/ are partly aspirational; verify a command exists before using it).

Non-negotiables (trust model)

• One isolated microVM per job. No host Docker socket as a core dependency.
• No real secrets in untrusted jobs by default. Secrets are reference-based: preloop secret list returns names only, never values.
• No silent fidelity gaps. Unsupported workflow behavior must be explicit and machine-readable, never silently approximated.
• Dirty retry is not a clean verdict. After fixing a failure in a live VM, the final "fixed" call requires a clean run from a fresh VM/overlay with strict policy.

Agent core loop

preloop run -f <workflow>        # run; on failure a TTY run pauses the VM
preloop debug --json             # read the paused session as JSON (agents/scripts)
<edit source on the host>
preloop debug --verdict retry --sync --from <step>
                                 # sync host edits into the VM, re-run from that step
preloop debug --verdict continue # keep going from the paused step
preloop debug --verdict abort    # tear down, mark failed

Interactive preloop run pauses at a failed step and holds the microVM open so you can fix and retry from that step. Non-interactive runs (--detach, piped stdout, CI) never pause; pass --preserve-on-failure to keep the failed VM alive for a later preloop shell.

Command reference (current CLI)

Run workflows

preloop run [-f <path>] [--job <id>] [--event <trigger>] [--payload <file.json>]
            [--base <ref>] [--secret NAME=VALUE] [-d|--detach] [--no-debug]
            [--preserve-on-failure]

• -f — workflow file. A bare filename like ci.yml resolves inside .github/workflows/; a path is used as-is. When omitted, discovers workflows whose triggers match the current repo state/event.
• --job — single job by its YAML key; includes the needs: dependency closure.
• --event — simulate a trigger (push, pull_request, merge_group, …); --payload supplies a webhook body JSON; --base sets the base ref for pull_request/merge_group.
• --detach — submit and return without streaming events.
• --no-debug — tear down on failure instead of pausing (default when detached).

Inspect and control

preloop plan        # expanded job DAG + matrix, no execution
preloop status      # active and recent runs
preloop logs        # run logs
preloop cancel      # cancel current run

Debug a failed job

preloop shell [session-id|run-id|job-name]        # PTY into the preserved VM
preloop debug [session] --json                    # session as JSON, exit (agents)
preloop debug [session] --verdict retry [--sync] [--force]
              [--from <step>|--from-start] [--revert none|untracked|all]
preloop debug [session] --verdict continue|abort
preloop debug [session] --export [--patch-only]   # pull VM-side edits back to host

• --sync — copy host source changes into the VM before retrying. A file changed on both sides aborts unless --force.
• --from <step> — re-run from a 1-based step number or display name (must be at or before the failed step); --from-start re-runs from the first user step.
• --revert — undo the failed attempt's workspace debris: none (default), untracked, or all.
• --export — bring edits made inside the VM back to the host workspace.

Secrets and GitHub credentials

preloop secret set <NAME> [--value V | stdin] [--repo owner/repo]
preloop secret list [--repo owner/repo]           # names only, never values
preloop secret rm <NAME> [--repo owner/repo]
preloop setup github                              # GitHub App or fine-grained PAT
preloop doctor                                    # verify credential config

Serve and update

preloop serve [--listen ADDR] [--public-url URL] [--github-app-id ID]
              [--github-app-key PATH] [--github-app-installation-id ID]
              [--webhook-secret SECRET] [--save]
preloop update   # poll GitHub Releases, atomically install matching binary

serve is the self-hosting entry point: control plane + microVM runner pool in the foreground, serving the GitHub webhook and Checks endpoints. --public-url must be the URL GitHub and remote runners can actually reach. Hidden alias: engine.