warmup.md

warmup

crabbox warmup leases a box and waits until it is ready: it provisions (or claims) a remote machine, waits for SSH plus the Crabbox bootstrap plumbing to come up, then keeps the lease so later commands can reuse it. Unlike run, warmup runs no command — it just hands you a ready box.

crabbox warmup --class beast
crabbox warmup --provider aws --class beast --market on-demand
crabbox warmup --provider aws --os ubuntu:26.04 --desktop --browser --desktop-env wayland
crabbox warmup --provider azure --class beast
crabbox warmup --provider azure --arch arm64 --class fast
crabbox warmup --browser
crabbox warmup --tailscale
crabbox warmup --slug update-flow-smoke
crabbox warmup --provider aws --lease-id cbx_abcdef123456 --slug update-flow-smoke
crabbox warmup --pond alpha --slug db
crabbox warmup --provider aws --target windows --desktop
crabbox warmup --provider azure --target windows
crabbox warmup --provider aws --target macos --desktop --market on-demand --type mac2.metal
crabbox warmup --actions-runner
crabbox warmup --provider ssh --target macos --static-host mac-studio.example.com
crabbox warmup --provider ssh --target windows --static-host win-dev.example.com --static-work-root 'C:\crabbox' --browser

Output

On success warmup prints two lines on stdout — the lease summary and the ready SSH endpoint — followed by a total-duration line:

leased cbx_0123456789ab slug=swift-crab provider=hetzner server=... type=... ip=... idle_timeout=30m expires=...
ready ssh=root@... :2222 network=public workroot=/work/crabbox
warmup complete total=42.1s

The canonical lease ID is cbx_...; the friendly slug is an auto-generated <adjective>-<noun> handle (or a normalized --slug you requested). Reuse either with later run, status, ssh, inspect, and stop commands. Scripts should prefer the canonical ID. Add --timing-json to emit a final JSON timing record (provider, lease ID, slug, total duration, exit code) on stderr.

Warmup records a local claim binding the lease to the current repo checkout. Use --reclaim to overwrite an existing claim for that lease.

Warmup requires an explicit provider selection from --provider, CRABBOX_PROVIDER, user or repository config, broker config, or an applicable recorded lease route. With no selection it exits before provider initialization and points to crabbox providers recommend.

For local-container, the default --keep=true also covers SSH readiness failure: once Docker has returned an exact container identity, Crabbox persists a scoped provisioning claim before inspecting the container or waiting for SSH. Cancellation or timeout retains that pending lease and prints exact inspect, reclaim, and cleanup commands. warmup --keep=false rolls the container and all per-lease local state back instead.

Lifetime: TTL and idle timeout

• --ttl <duration> is the maximum wall-clock lifetime. Default 90m.
• --idle-timeout <duration> releases the lease after no touch for that long. Default 30m.

Naming and grouping

--slug <slug> requests a human-chosen slug for a new lease. Crabbox normalizes it and may append a short suffix if an active lease already uses that slug.

--lease-id cbx_<12 lowercase hex> is the automation idempotency contract for providers that explicitly support fixed identities. Direct AWS and managed coordinator leases accept it. Replaying the same normalized create intent returns or joins the same lease, including after the creating process loses its response. Reusing the ID with a different provider, slug request, SSH key, machine shape, capabilities, lifetime, or other immutable create input fails with lease_id_conflict before another provider create. Slugs remain display aliases and are never used as the idempotency key.

Coordinator-backed fixed-ID creation uses a versioned PUT /v1/leases/<id> route. An older coordinator therefore rejects the request before provisioning; the CLI never falls back to slug lookup or legacy create behavior. After an ambiguous fixed create response, the CLI repeats that exact PUT to atomically confirm the same intent before it may poll lease status with GET.

A fixed lease ID is single-use. If direct AWS acquisition completed and its bound instance later disappears, replay fails closed instead of relying on EC2 client-token retention. Successful stop and missing-resource cleanup replace the live local claim with a compact terminal tombstone, so the ID remains rejected after release. Use a new operation ID for every later lease. If an AWS launch attempt was durably recorded but its instance is not yet visible, replay fails closed without resubmitting it; retry later to adopt the resource after provider inventory converges.

--pond <name> tags a new lease into a named pond (stored as a reserved provider label); crabbox list --pond <name> filters by it. When combined with --tailscale on a Tailscale-capable provider, the CLI also advertises a tag:cbx-pond-<owner>-<name> ACL tag, and cloud-init refreshes /etc/hosts.cbx plus a managed /etc/hosts block every 30 seconds so Tailscale peers in the same pond resolve each other as <slug>.cbx. See pond for the one-time ACL snippet and doctor --pond coverage. To let Crabbox install the Tailscale policy rows automatically, set both TS_API_KEY and CRABBOX_POND_ACL_BOOTSTRAP=1; TS_API_KEY alone is read-only verification for pond commands.

Capabilities

Capabilities are opt-in features requested at warm time and validated against the provider's feature set. See capabilities.

• --desktop provisions a visible UI and loopback-bound VNC for automation and operator takeover. Managed cloud Linux defaults to resize-capable TigerVNC with a slim XFCE session; local containers retain Xvfb/x11vnc. Use --desktop-env wayland for the experimental labwc/WayVNC profile on Ubuntu 26.04-compatible images, or --desktop-env gnome for a GNOME-apps profile with GNOME Panel taskbars over labwc/WayVNC (GNOME-profile app launches use Xwayland so the panel can list windows). --desktop does not imply a browser.
• --browser provisions a known browser binary and records it in /var/lib/crabbox/browser.env. It works without --desktop for headless automation; combine --desktop --browser to run a headed browser in the visible display. Managed Linux tries Google Chrome stable first, then a Chromium package fallback.
• --code provisions code-server on Linux leases and enables crabbox code --id <lease> to bridge the workspace through the authenticated portal at /portal/leases/<lease>/code/.

Reusing a lease later requires matching capability labels.

OS image

--os selects a portable Linux OS image; ubuntu:26.04 is the default. Explicit provider image flags and config values still win for exact AMIs, URNs, image families, or provider image names.

Capacity and market (AWS)

For AWS, --market spot|on-demand overrides capacity.market for this lease. Use --market on-demand when Spot capacity is blocked or a quota was approved only for the standard On-Demand quota. An explicit --type always means the exact type: Crabbox reports quota/capacity/policy failures instead of silently switching capacity.

Networking

--tailscale joins newly created managed Linux leases to the configured tailnet. --network auto|tailscale|public controls the SSH endpoint printed after readiness: auto prefers the tailnet when reachable, tailscale requires it, and public forces the provider/public host. Tailscale is a reachability layer, not a provider — static hosts should put a MagicDNS name or 100.x address in static.host instead. See Tailscale.

Provider notes

blaxel

--provider blaxel creates a Crabbox-owned Blaxel Linux sandbox and waits for the sandbox to become ready. Warmup prints the blx_<sandbox-id> lease ID and a friendly slug for later run --id, status, and stop calls. It does not prepare SSH, browser, desktop, code-server, or Actions runner surfaces.

ssh (static / bring-your-own host)

With --provider ssh, warmup claims an existing host instead of creating cloud capacity. Use --target macos, --target windows --windows-mode normal, or --target windows --windows-mode wsl2 to select the remote command/sync contract. Native Windows static hosts must already have OpenSSH Server reachable, PowerShell, Git, tar, and a writable static.workRoot. Restart sshd after installing Git so new sessions see the updated PATH.

hetzner

Managed Hetzner provisioning supports Linux only. For managed Windows, use --provider aws --target windows or --provider azure --target windows; for an existing Hetzner Windows host, use --provider ssh --target windows.

xcp-ng

--provider xcp-ng copies a configured Linux template to the selected SR with VM.copy, calls VM.provision, attaches a per-lease FAT16 CIDATA config-drive image, waits for XCP-ng guest metrics to report an IPv4 address, and then uses the normal SSH bootstrap. If xcpNg.network or xcpNg.networkUuid is set, Crabbox moves all template VIFs to that network, so single-NIC templates are the safest default. Run crabbox doctor --provider xcp-ng --json first; it is non-mutating and reports mutation=false. A template name or UUID, storage repository, API URL, username, and password must come from config or environment before warmup can create a lease. Keep the XAPI endpoint on a management network or VPN, prefer trusted certificates, and treat --xcp-ng-insecure-tls as private-lab only.

coder

--provider coder creates or reuses a Linux Coder workspace through the local coder CLI. New workspaces require --coder-template or coder.template. Crabbox connects through coder ssh --stdio, so no raw public host or provider SSH key is needed. Run crabbox doctor --provider coder first; if the local Coder CLI is not logged in, doctor reports auth=missing_login without mutating workspaces.

aws — Windows

--provider aws --target windows --windows-mode normal --desktop creates a real AWS Windows Server lease. EC2Launch user data installs OpenSSH Server, Git for Windows, TightVNC Server, a per-lease local administrator named crabbox, and a loopback VNC password retrievable through crabbox vnc --id <lease>. The OpenSSH, Git, and TightVNC downloads are SHA-256 verified before use.

--provider aws --target windows --windows-mode wsl2 still creates a Windows Server host, then enables WSL, VirtualMachinePlatform, and HypervisorPlatform, reboots as needed, updates the WSL kernel, imports an Ubuntu rootfs, and prepares the Linux-side crabbox-ready toolchain. The rootfs uses a versioned URL and pinned SHA-256 verified before import. The launch enables nested virtualization and uses C8i, M8i, or R8i instance families. Commands and sync then use the POSIX WSL contract.

azure — Windows

--provider azure --target windows creates a native Windows Server lease, uses the VM Agent Custom Script Extension to install OpenSSH Server and Git for Windows, verifies both downloads by pinned SHA-256, and configures the crabbox user for SSH/sync/run. Add --desktop to run the shared Windows desktop bootstrap over SSH, install TightVNC, configure auto-logon, and expose VNC through the normal SSH tunnel. With --windows-mode wsl2, Crabbox enables WSL2 over SSH and uses the POSIX WSL sync/run/actions contract. Azure Windows does not provision browser/code.

azure — backend and OS disk

Azure leases use managed StandardSSD_LRS OS disks by default so native disk-snapshot checkpoints can be created and forked. Use --azure-os-disk ephemeral only for stateless leases that don't need native Azure checkpoint/fork support. Use --azure-os-disk ephemeral-preview for Azure's public-preview full-caching ephemeral OS disk mode; --azure-os-disk auto resolves to managed.

--azure-backend dynamic-sessions keeps --provider azure as the family selector while routing to the azure-dynamic-sessions delegated backend.

vercel-sandbox

--provider vercel-sandbox creates a Vercel-managed Linux microVM and keeps it until explicit stop. Warmed sandboxes use vsbx_... local claims and can be reused by Crabbox slug or lease ID. The provider is delegated-run only: it supports archive sync and command execution through the SDK bridge, but not SSH, Tailscale, browser, desktop, code-server, or Actions runner hydration.

cloudflare-dynamic-workers

--provider cloudflare-dynamic-workers rejects warmup. Dynamic Workers require module source before Cloudflare can load or cache them; use crabbox doctor for loader readiness or crabbox run --script <file> to load code. The provider does not start a Linux machine and does not support Actions runner registration, SSH, desktop, browser, code-server, ports, --class, or --type.

cloudflare-sandbox

--provider cloudflare-sandbox creates a Cloudflare-managed Linux sandbox through the configured Sandbox bridge and keeps it until explicit stop. Warmed sandboxes use cfsbx_... local claims and can be reused by Crabbox slug or lease ID. The provider is delegated-run only: it supports archive sync and command execution through the bridge, but not SSH, Tailscale, browser, desktop, code-server, URL sessions, storage mounts, checkpoints, or Actions runner hydration.

aws — macOS

--provider aws --target macos --desktop launches an EC2 Mac instance on an already allocated Dedicated Host. Crabbox can discover an available host in the selected region, or pin one with CRABBOX_HOST_ID / hostId (CRABBOX_AWS_MAC_HOST_ID and aws.macHostId remain AWS compatibility aliases). Brokered host pinning requires admin authentication unless the host has a retained instance from the same owner and organization's released lease; other users rely on automatic available-host discovery. Use --market on-demand, and expect EC2 Mac host lifecycle rules to dominate cleanup and cost. Warmup never allocates a Dedicated Host implicitly; trusted operators manage host lifecycle with crabbox admin hosts offerings|quota|list|allocate|release --provider aws --target macos. The default SSH user is ec2-user; the VNC password from crabbox vnc is the per-lease macOS account password set by bootstrap.

GitHub Actions runner

--actions-runner immediately registers the warm box as an ephemeral self-hosted GitHub Actions runner for the current repository. Most projects should instead prefer crabbox actions hydrate --id <lease> after warmup, because it also dispatches the workflow and waits for the ready marker.

Flags

--provider <name>                  provider (see crabbox providers); defaults to configured selection
--profile <name>                   configuration profile
--class <name>                     machine class; default beast
--arch amd64|arm64                 CPU architecture; arm64 supports Linux on AWS/Azure/Apple Container and native Windows on Azure
--os ubuntu:26.04|ubuntu:24.04     portable Linux OS image selector
--type <provider-type>             provider server/instance type
--market spot|on-demand            capacity market (AWS)
--slug <slug>                      request a friendly slug for a new lease
--lease-id cbx_<12 lowercase hex> fixed lease ID for idempotent automation
--pond <name>                      tag this lease into a pond
--expose <port>                    declare a TCP port reachable over the SSH-mesh plane; repeatable
--cache-volume [name=]key:path     require a provider-backed cache volume; repeatable
--ttl <duration>                   maximum lease lifetime; default 90m
--idle-timeout <duration>          release after idle; default 30m
--desktop                          provision/require a visible desktop + VNC
--desktop-env xfce|wayland|gnome   Linux desktop environment
--browser                          provision/require a browser binary
--code                             provision/require code-server
--image-min-os <version>           require a minimum promoted-image OS version
--image-sdk <name=version>         require a minimum SDK version; repeatable
--image-runtime <name=version>     require a minimum runtime version; repeatable
--image-require-browser            require browser support in the promoted image
--image-require-webview2           require WebView2 support in the promoted image
--image-require-desktop            require desktop support in the promoted image
--target linux|macos|windows       target OS
--windows-mode normal|wsl2         Windows mode
--static-host <host>               static SSH host (provider=ssh)
--static-user <user>               static SSH user
--static-port <port>               static SSH port
--static-work-root <path>          static target work root
--network auto|tailscale|public    network mode for the printed SSH endpoint
--tailscale                        join new managed Linux leases to the tailnet
--tailscale-tags <a,b,c>           Tailscale tags for new managed leases
--tailscale-hostname-template <t>  Tailscale hostname template
--tailscale-auth-key-env <env>     env var holding a direct-provider Tailscale auth key
--tailscale-exit-node <name|100.x> Tailscale exit node
--tailscale-exit-node-allow-lan-access
--keep                             keep the box after warmup; default true
--actions-runner                   register the box as an ephemeral GitHub Actions runner
--reclaim                          overwrite an existing local claim for this lease
--timing-json                      print a final JSON timing record on stderr
--azure-backend vm|dynamic-sessions
--azure-os-disk managed|ephemeral|ephemeral-preview|auto

Provider-specific flags (for example --azure-backend, --e2b-template, --daytona-snapshot) are contributed by the selected provider; run crabbox warmup --provider <name> --help to see the set for a given provider, and crabbox providers to list all providers and their capabilities.

Image requirement flags currently select AWS promoted images. Crabbox verifies the full requirement set before reserving a lease or calling AWS. Explicit AMI, snapshot, and stock-image overrides cannot be verified against the promotion catalog and fail closed when combined with image requirements. The CLI sends capability-aware creates to a dedicated coordinator route, so an older coordinator returns not found instead of silently ignoring requirements. Image requirements cannot be combined with run --pool because current pool entries do not record or prove image capabilities.

SSH keys

New leases use per-lease SSH keys under the user config directory (RSA for AWS/Azure Windows, ed25519 otherwise):

<user-config>/crabbox/testboxes/<lease-id>/id_ed25519

On macOS and Linux this is typically ~/Library/Application Support/crabbox/... or ~/.config/crabbox/... respectively.