Features

Prebaked Runner Images

GitHub Edit page

Prebaked Runner Images

A prebaked image is a provider machine image (AWS AMI, Hetzner snapshot, and so on) with the stable parts of a runner already installed, so a lease boots ready instead of installing tooling on every warmup.

Read this when you are:

  • deciding what belongs in a provider image versus a warm lease or a repo cache;
  • speeding up crabbox warmup and crabbox run for desktop or browser QA;
  • planning to bake or promote a Crabbox runner image.

The guiding rule: prebaked images store machine capabilities, not scenario state. Tools, browsers, and OS patches go in the image. Checkouts, dependency caches, credentials, and login state stay out.

For the exact AWS bake, smoke, promotion, rollback, and cleanup commands, follow the Image bake runbook. This page covers the underlying model.

#Where images live

Provider-owned image storage is always the source of truth for image bytes:

  • AWS — AMIs and their backing EBS snapshots live in the AWS account.

    • crabbox image create builds a candidate AMI from a lease, and crabbox image promote records the selected AMI as the default for matching brokered AWS leases. Promotion is scoped by target, architecture, and region, so a macOS AMI never replaces the Linux or Windows default.

  • Azure / GCP — managed images and disk snapshots live in the cloud project.

    • crabbox image create can capture them and crabbox image delete can remove them (--provider azure|gcp).

  • Hetzner — snapshots live in the Hetzner project. Crabbox can already boot a

    • configured image (via config or CRABBOX_HETZNER_IMAGE), but the create/promote lifecycle commands are not implemented for Hetzner. Manage Hetzner snapshots with Hetzner tooling, then point Crabbox at the result.

  • Delegated runners (for example Blacksmith) — images are owned by the

    • provider's runner infrastructure, not by Crabbox.

The coordinator stores only the current provider image identifier, promotion metadata, and enough tags to explain provenance. Do not store image bytes in git, release artifacts, or coordinator durable state.

#What to bake

Bake stable machine capabilities:

  • current OS security updates and base packages;
  • core access tooling: SSH, Git, rsync, curl, jq, and the readiness helpers;
  • desktop and browser capabilities for --desktop --browser leases (Xvfb, a

    • slim XFCE, x11vnc, Chrome or Chromium);

  • capture tools such as ffmpeg, ffprobe, scrot, and xdotool;
  • language and build toolchains the image targets: Node 24 with corepack/pnpm,

    • build-essential, Python, and common native-addon headers;

  • Docker Engine and supporting plugins where the platform runs headless Docker;
  • empty shared cache directories such as /var/cache/crabbox/pnpm.

Do not bake scenario state:

  • secrets, tokens, or provider credentials;
  • browser profiles, cookies, OAuth state, or chat/login sessions;
  • repository checkouts, node_modules, built dist/, or PR artifacts;
  • one-off operator notes or debugging files.

Anything that varies per repository, per lockfile, or per run does not belong in a shared image.

#Runtime caches belong outside the image

Dependency state changes far more often than machine capabilities, so it lives outside the image:

  • a warm lease can keep /var/cache/crabbox/pnpm and browser profiles for a

    • short-lived operator session;

  • GitHub Actions should cache candidate pnpm stores by lockfile and platform;
  • product-specific runtime bundles and evidence belong in the workflow

    • workspace, for example under .artifacts/;

  • long-lived reusable volumes should be keyed by repo, lockfile, runtime version,

    • platform, and image id before Crabbox mounts them into leases.

This split keeps one image reusable across many repositories while still letting slow QA lanes skip repeated dependency work when they deliberately reuse a warm lease or a keyed external cache.

#Operator flow

The Image bake runbook has the precise commands and guard scripts. At a high level, an AWS bake is:

  1. Warm a fresh source lease with the capabilities the image must provide:

``bash crabbox warmup --provider aws --class standard --desktop --browser \ --ttl 2h --idle-timeout 30m ``

  1. Verify the machine capability contract on that lease (tools, browser,

    2. directories) over crabbox run --no-sync --shell.

  2. Create a candidate AMI from the lease's canonical cbx_... id:

``bash crabbox image create --id <cbx_id> --name my-org-linux-desktop-YYYYMMDD-HHMM \ --wait --json ``

  1. Boot the candidate explicitly through an image override and smoke it:

``bash CRABBOX_AWS_AMI=ami-1234567890abcdef0 \ crabbox warmup --provider aws --class standard --desktop --browser \ --ttl 30m --idle-timeout 10m ``

  1. Promote the candidate once the smoke passes:

``bash crabbox image promote ami-1234567890abcdef0 --json ``

  1. Run a normal brokered lease (no override) plus the relevant QA lane to confirm

    2. the promoted image is selected and healthy.

  2. Keep the previous known-good AMI until the new image has real QA proof.

A successful bake is not just "the browser exists." A useful image measurably reduces crabbox warmup and crabbox run time in your timing evidence while keeping credentials, login state, and repository artifacts out of the image.

#Image commands

All image commands require coordinator admin auth and can create paid provider-side artifacts.

  • crabbox image create --id <cbx_id> --name <name> [--wait] — capture a

    • provider image from a lease (--no-reboot defaults to true on AWS).

  • crabbox image promote <ami-id> [--target linux|macos|windows] [--region <r>]

    • — set the default brokered AWS image; supports --fast-snapshot-restore with --fsr-az <az>.

  • crabbox image fsr-status <ami-id|snapshot-id> — AWS Fast Snapshot Restore

    • status.

  • crabbox image delete <image-id> [--provider aws|azure|gcp] — remove a

    • provider image.

See the image command reference for full flags.