Crabbox

Use the Crabbox wrapper when OpenClaw needs remote Linux proof for broad tests, CI-parity checks, secrets, hosted services, Docker/E2E/package lanes, warmed reusable boxes, sync timing, logs/results, cache inspection, or lease cleanup.

Crabbox is the transport/orchestration surface. The actual backend can be:

• brokered AWS Crabbox: direct provider, provider=aws, lease ids like cbx_..., syncDelegated=false
• Blacksmith Testbox through Crabbox: delegated provider, provider=blacksmith-testbox, ids like tbx_..., syncDelegated=true

For OpenClaw maintainer broad pnpm gates, Blacksmith Testbox through the Crabbox wrapper is acceptable and often preferred when the standing Testbox rules apply. Do not describe those runs as "AWS Crabbox"; report them as Testbox-through-Crabbox with the tbx_... id and Actions run.

Use the repo .crabbox.yaml brokered AWS path when the task specifically needs direct AWS Crabbox behavior, persistent direct-provider leases, --fresh-pr, --full-resync, environment forwarding, capture/download support, or provider comparison. Use --provider blacksmith-testbox when the task needs OpenClaw maintainer Testbox proof, prepared CI environment, broad/heavy pnpm gates, or the user asks for Testbox/Blacksmith.

First Checks

• Run from the repo root. Crabbox sync mirrors the current checkout.
• Check the wrapper and providers before remote work:

command -v crabbox
../crabbox/bin/crabbox --version
pnpm crabbox:run -- --help | sed -n '1,120p'
../crabbox/bin/crabbox desktop launch --help
../crabbox/bin/crabbox webvnc --help

• OpenClaw scripts prefer ../crabbox/bin/crabbox when present. The user PATH shim can be stale.
• Check .crabbox.yaml for direct-provider defaults. Omitting --provider means brokered AWS for normal Linux/macOS paths; the wrapper selects Azure for unqualified Windows/WSL2 runs when the local Crabbox binary advertises Azure.
• The brokered AWS default is a Linux developer image in eu-west-1; the repo config pins hot eu-west-1a/b/c placement so Fast Snapshot Restore can apply. If warmup drifts well past the minute-scale path, verify image promotion, region/AZ placement, and FSR state before blaming OpenClaw.
• For broad OpenClaw maintainer pnpm gates, prefer the repo wrapper with --provider blacksmith-testbox or the repo Testbox helpers when the standing Testbox policy applies.
• Always report the actual provider and id. cbx_... means AWS Crabbox; tbx_... means Blacksmith Testbox through Crabbox. If the output only says blacksmith testbox list, use blacksmith testbox list --all before concluding no box exists.
• If a warm direct-provider lease smells stale, retry with --full-resync (alias --fresh-sync) before replacing the lease. This resets the remote workdir, skips the fingerprint fast path, reseeds Git when possible, and uploads the checkout from scratch.
• For live/provider bugs, use the configured secret workflow before downgrading to mocks. Copy only the exact needed key into the remote process environment for that one command. Do not print it, do not sync it as a repo file, and do not leave it in remote shell history or logs. If no secret-safe injection path is available, say true live provider auth is blocked instead of silently using a fake key.
• Prefer local targeted tests for tight edit loops. Broad gates belong remote.
• Do not treat inherited shell env as operator intent. In particular, OPENCLAW_LOCAL_CHECK_MODE=throttled from the local shell is not permission to move broad pnpm check:changed, pnpm test:changed, full pnpm test, or lint/typecheck fan-out onto the laptop.
• Only use OPENCLAW_LOCAL_CHECK_MODE=throttled|full when the user explicitly asks for local proof in the current task. If Testbox is queued or capacity is constrained, report the blocker and keep only targeted local edit-loop checks running.

macOS And Windows Targets

…