Skip to content

prebaked-images.md

Latest commit

 

History

History
175 lines (136 loc) · 7.88 KB

prebaked-images.md

File metadata and controls

175 lines (136 loc) · 7.88 KB
Raw

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. Promotions may declare OS, SDK/runtime, browser, WebView2, and desktop capabilities. Capability-aware leases select the newest matching AMI from the scoped promotion catalog and fail before leasing when no image matches.
  • Azure — managed OS disk snapshots live in the subscription. A native crabbox checkpoint create captures the snapshot; crabbox image promote --provider azure records it as the default for matching target, architecture, VM size, OS, and location. crabbox image delete --provider azure removes Crabbox-owned snapshots.
  • GCP — machine images and disk snapshots live in the cloud project. crabbox image create can capture them and crabbox image delete --provider gcp can remove them.
  • Hetzner — snapshots live in the Hetzner project. A direct native checkpoint can create, verify, delete, and fork one; brokered Hetzner checkpoints remain workspace archives. image create and image promote remain coordinator operations and are unsupported for Hetzner. Direct image delete --provider hetzner is limited to a snapshot claimed by exactly one local hetzner-snapshot checkpoint record.
  • Delegated runners (for example Blacksmith) — images are owned by the provider's runner infrastructure, not by Crabbox.

The coordinator stores scoped provider image identifiers, promotion capability 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 (resize-capable TigerVNC, slim XFCE, 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.

The bundled Linux developer-image prep writes /var/lib/crabbox/image-ready only after the stable tool contract is present. On later boots Crabbox verifies the marker plus the base binaries and skips the otherwise redundant base-package APT transaction. Per-lease users, SSH keys, work roots, optional services, and readiness checks still run normally.

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:

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

  2. Verify the machine capability contract on that lease (tools, browser, directories) over crabbox run --no-sync --shell.

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

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

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

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

  5. Promote the candidate once the smoke passes:

    crabbox image promote ami-1234567890abcdef0 --json

    Add declarations such as --os-version 26.04 --runtime node=24.2 --browser --desktop when future leases must select by baked capabilities.

  6. Run a normal brokered lease (no override) plus the relevant QA lane. The CLI prints image selected id=... source=promoted; require the exact promoted ID in publication proof.

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

Image creation, promotion, Fast Snapshot Restore, and AWS/Azure/GCP deletion require coordinator admin auth and can create or remove paid provider-side artifacts. The direct Hetzner deletion exception is described below.

  • 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 <image-id> [--provider aws|azure] [--target linux|macos|windows] [--region <r>] — set a scoped brokered AWS AMI or Azure OS disk snapshot default. AWS supports --fast-snapshot-restore with --fsr-az <az> and capability declarations.
  • crabbox image fsr-status <ami-id|snapshot-id> — AWS Fast Snapshot Restore status.
  • crabbox image delete <image-id> [--provider aws|azure|gcp|hetzner] — remove a Crabbox-created provider image. Deletion requires stored Crabbox ownership metadata and refuses unrelated provider-native image or snapshot IDs. For Hetzner, this runs directly and requires exactly one matching local native checkpoint record; it does not provide general delete-by-ID access.

See the image command reference for full flags.

Related docs