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 --provider local-container --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.1sThe 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.
For Blacksmith Testbox with a configured coordinator, the lease summary appears as soon as the ready Testbox is retained. Final completion and timing follow the optional portal inventory sync, and the total includes that bookkeeping. The sync has one five-second budget (or the caller's earlier cancellation/deadline). A sync failure prints a warning on stderr but warmup still succeeds and retains the ready lease; it does not allocate again or stop the Testbox.
Warmup records a local claim binding the lease to the current repo checkout. Use --reclaim to overwrite an existing claim for that lease.
If a coordinator lease ends while provisioning, warmup reports the lease ID, terminal state, and recorded failure cause. When the coordinator retains the cause in cleanup metadata because a resource may still exist, warmup includes that diagnostic. Use crabbox inspect --id <lease> to check the retained provisioning and cleanup evidence before recovery.
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 ordinary local-container warmups without --lease-id, 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 an ordinary container and all per-lease local state back instead. Fixed-ID local-container warmups retain their durable create attempt so an interrupted operation can be safely replayed.
#Lifetime: TTL and idle timeout
--ttl <duration>is the maximum wall-clock lifetime. Default90m.--idle-timeout <duration>releases the lease after no touch for that long. Default30m.
#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, Machine0, Daytona, Incus, and local-container leases, managed coordinator leases, and explicitly capable external providers accept it. Replaying the same normalized create intent returns or joins the same live lease, including after the creating process loses its response. A managed coordinator reports fixed_lease_terminal when that same intent has already ended. Reusing the ID with a different provider, slug request, SSH key, machine or container 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.
Daytona binds the native organization before allocation and preserves that scope across credential rotation. See Daytona fixed operation IDs for API-key organization discovery and positive cleanup-witness requirements.
Concurrent fixed-ID warmup and fork commands sharing a local state directory wait for the current acquisition to finish registration and preparation. A cancelled waiter makes no provider changes. If preparation fails after a fixed lease was acquired, the CLI retains it: retry the original command or explicitly stop the ID. A failed replay never owns automatic deletion of an adopted lease.
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.
For coordinator-backed creates, recovering an uncertain response does not restart the provisioning deadline or shorten it to the recovery window. Once the same create is confirmed, readiness uses the remaining original creation budget and honors caller cancellation. Fixed-ID leases remain available for explicit recovery or stop; ordinary creates keep their token-bound cancellation cleanup.
A fixed lease ID is single-use. Direct AWS, Machine0, Daytona, Incus, and local-container acquisitions fail closed if their bound resource later disappears. 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 or local-container create attempt was durably recorded but its resource 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.
--desktopprovisions a visible UI and loopback-bound VNC for automation and operator takeover. Managed cloud Linux and new local containers default to resize-capable TigerVNC with a slim XFCE session. Use--desktop-env waylandfor the experimental labwc/WayVNC profile on Ubuntu 26.04-compatible images, or--desktop-env gnomefor a GNOME-apps profile with GNOME Panel taskbars over labwc/WayVNC (GNOME-profile app launches use Xwayland so the panel can list windows).--desktopdoes not imply a browser.--browserprovisions a known browser binary and records it in/var/lib/crabbox/browser.env. It works without--desktopfor headless automation; combine--desktop --browserto run a headed browser in the visible display. Managed Linux tries Google Chrome stable first, then a Chromium package fallback.--codeprovisionscode-serveron Linux leases and enablescrabbox 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 enables the initial OpenSSH connection on port 22. Crabbox then runs its Windows bootstrap over that connection, installing Git for Windows and TightVNC, configuring the final SSH ports and a per-lease local administrator named crabbox, and preparing a loopback VNC password retrievable through crabbox vnc --id <lease>. Crabbox's OpenSSH, Git, and TightVNC downloads are SHA-256 verified before use. An explicitly selected workload port does not remove an advertised initial bootstrap route; see Windows bootstrap.
--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). Org-member broker requests can pin a host only when the coordinator has an exact allocation record for that host, the current org, and the requested region. Historical leases do not grant pin access; other explicit host pins require admin authentication. 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.
A new warmup does not adopt an existing lease by slug or pinned host. An occupied host returns a conflict identifying its lease; inspect or explicitly stop that lease before requesting a new one. --lease-id replays only the same fixed ID and create intent. If a coordinator returns another ID, the CLI stops before bootstrap, key migration, or failure cleanup.
#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|autoProvider-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_ed25519On macOS and Linux this is typically ~/Library/Application Support/crabbox/... or ~/.config/crabbox/... respectively.