crabbox

# Crabbox Use Crabbox 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. Default backend: `blacksmith-testbox`. The separate `blacksmith-testbox` skill has been removed; this skill owns both the normal Crabbox path and the direct Blacksmith fallback playbook. ## First Checks - Run from the repo root. Crabbox sync mirrors the current checkout. - Check the wrapper and providers before remote work: ```sh 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 repo defaults, but override provider explicitly. Even if config still says AWS, maintainer validation should normally pass `--provider blacksmith-testbox`. - Prefer local targeted tests for tight edit loops. Broad gates belong remote. ## macOS And Windows Targets Use these only when the task needs an existing non-Linux host. OpenClaw broad validation still defaults to `blacksmith-testbox`. Crabbox supports static SSH targets: ```sh ../crabbox/bin/crabbox run --provider ssh --target macos --static-host mac-studio.local -- xcodebuild test ../crabbox/bin/crabbox run --provider ssh --target windows --windows-mode normal --static-host win-dev.local -- pwsh -NoProfile -Command "dotnet test" ../crabbox/bin/crabbox run --provider ssh --target windows --windows-mode wsl2 --static-host win-dev.local -- pnpm test ``` - `target=macos` and `target=windows --windows-mode wsl2` use the POSIX SSH, bash, Git, rsync, and tar contract. - Native Windows uses OpenSSH, PowerShell, Git, and tar; sync is manifest tar archive transfer into `static.workRoot`. - `crabbox actions hydrate/register` are Linux-only today; use plain `crabbox run` loops for static macOS and Windows hosts. - Live proof needs a reachable, operator-managed SSH host. Without one, verify with `../crabbox/bin/crabbox run --help`, config/flag tests, and the Crabbox Go test suite. ## Default Blacksmith Backend Use this for `pnpm check`, `pnpm check:changed`, `pnpm test`, `pnpm test:changed`, Docker/E2E/live/package gates, or anything likely to fan out across many Vitest projects. Changed gate: ```sh pnpm crabbox:run -- --provider blacksmith-testbox \ --blacksmith-org openclaw \ --blacksmith-workflow .github/workflows/ci-check-testbox.yml \ --blacksmith-job check \ --blacksmith-ref main \ --idle-timeout 90m \ --ttl 240m \ --timing-json \ --shell -- \ "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test:changed" ``` Full suite: ```sh pnpm crabbox:run -- --provider blacksmith-testbox \ --blacksmith-org openclaw \ --blacksmith-workflow .github/workflows/ci-check-testbox.yml \ --blacksmith-job check \ --blacksmith-ref main \ --idle-timeout 90m \ --ttl 240m \ --timing-json \ --shell -- \ "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test" ``` Focused rerun: ```sh pnpm crabbox:run -- --provider blacksmith-testbox \ --blacksmith-org openclaw \ --blacksmith-workflow .github/workflows/ci-check-testbox.yml \ --blacksmith-job check \ --blacksmith-ref main \ --idle-timeout 90m \ --ttl 240m \ --timing-json \ --shell -- \ "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test <path-or-filter>" ``` Read the JSON summary. Useful fields: - `provider`: should be `blacksmith-testbox` - `leaseId`: `tbx_...` - `syncDelegated`: should be `true` - `commandMs` / `totalMs` - `exitCode` Crabbox should stop one-shot Blacksmith Testboxes automatically after the run. Verify cleanup when a run fails, is interrupted, or the command output is unclear: ```sh blacksmith testbox list ``` ## Reuse And Keepalive For most Blacksmith-backed Crabbox calls, one-shot is enough. Use reuse only when you need multiple manual commands on the same hydrated box. If Crabbox returns a reusable id or you intentionally keep a lease: ```sh pnpm crabbox:run -- --provider blacksmith-testbox --id <tbx_id> --no-sync --timing-json --shell -- "pnpm test <path>" ``` Stop boxes you created before handoff: ```sh pnpm crabbox:stop -- <id-or-slug> blacksmith testbox stop --id <tbx_id> ``` ## Interactive Desktop And WebVNC Prefer WebVNC for human inspection because the browser portal can preload the lease VNC password and avoids a native VNC client's copy/paste/password dance. Use native `crabbox vnc` only when WebVNC is unavailable, the browser portal is broken, or the user explicitly wants a local VNC client. Common desktop flow: ```sh ../crabbox/bin/crabbox warmup --provider hetzner --desktop --browser --class standard --idle-timeout 60m --ttl 240m ../crabbox/bin/crabbox desktop launch --provider hetzner --id <cbx_id-or-slug> --browser --url https://example.com --webvnc --open ``` Useful WebVNC commands: ```sh ../crabbox/bin/crabbox webvnc --provider hetzner --id <cbx_id-or-slug> --open ../crabbox/bin/crabbox webvnc --provider hetzner --id <cbx_id-or-slug> --daemon --open ../crabbox/bin/crabbox webvnc --provider hetzner --id <cbx_id-or-slug> --status ../crabbox/bin/crabbox webvnc --provider hetzner --id <cbx_id-or-slug> --stop ../crabbox/bin/crabbox screenshot --provider hetzner --id <cbx_id-or-slug> --output desktop.png ``` `desktop launch --webvnc --open` is usually the nicest one-shot: it starts the browser/app inside the visible session, bridges the lease into the authenticated WebVNC portal, and opens the portal. Keep browsers windowed for human QA; use `--fullscreen` only for capture/video workflows. ## If Crabbox Fails Keep the fallback narrow. First decide whether the failure is Crabbox itself, Blacksmith/Testbox, repo hydration, sync, or the test command. Fast checks: ```sh command -v crabbox ../crabbox/bin/crabbox --version crabbox run --provider blacksmith-testbox --help | sed -n '1,140p' command -v blacksmith blacksmith --version blacksmith testbox list ``` Common Crabbox-only failures: - Provider missing or old CLI: use `../crabbox/bin/crabbox` from the sibling repo, or update/install Crabbox before retrying. - Bad local config: pass `--provider blacksmith-testbox` plus explicit `--blacksmith-*` flags instead of relying on `.crabbox.yaml`. - Slug/claim confusion: use the raw `tbx_...` id, or run one-shot without `--id`. - Sync/timing bug: add `--debug --timing-json`; capture the final JSON and the printed Actions URL. - Cleanup uncertainty: run `blacksmith testbox list` and stop only boxes you created. If Crabbox cannot dispatch, sync, attach, or stop but Blacksmith itself works, use direct Blacksmith from the repo root: ```sh blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90 blacksmith testbox run --id <tbx_id> "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test:changed" blacksmith testbox stop --id <tbx_id> ``` Direct full suite: ```sh blacksmith testbox run --id <tbx_id> "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test" ``` Auth fallback, only when `blacksmith` says auth is missing: ```sh blacksmith auth login --non-interactive --organization openclaw ``` Raw Blacksmith footguns: - Run from repo root. The CLI syncs the current directory. - Save the returned `tbx_...` id in the session. - Reuse that id for focused reruns; stop it before handoff. - Raw commit SHAs are not reliable `warmup --ref` refs; use a branch or tag. - Treat `blacksmith testbox list` as cleanup diagnostics, not a shared reusable queue. Blacksmith queue/outage mode: ```sh blacksmith --version blacksmith testbox list --all blacksmith testbox status --id <tbx_id> ``` If the CLI can list/status boxes but new warmups stay `queued` with no IP or Actions run URL after a couple of minutes, treat it as Blacksmith provider, org-limit, billing, or queue pressure. Stop the queued ids you created and do not warm more boxes into the same stalled queue. Check the Blacksmith dashboard, billing, and org limits out-of-band, then use Owned Cloud Fallback below for maintainer proof. Escalate to owned AWS/Hetzner only when Blacksmith is down, quota-limited, missing the needed environment, or owned capacity is the explicit goal. Use the Owned Cloud Fallback section below. ## Blacksmith Backend Notes Crabbox Blacksmith backend delegates setup to: - org: `openclaw` - workflow: `.github/workflows/ci-check-testbox.yml` - job: `check` - ref: `main` unless testing a branch/tag intentionally The hydration workflow owns checkout, Node/pnpm setup, dependency install, secrets, ready marker, and keepalive. Crabbox owns dispatch, sync, SSH command execution, timing, logs/results, and cleanup. Minimal direct Blacksmith fallback, from repo root: ```sh blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90 blacksmith testbox run --id <tbx_id> "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test:changed" blacksmith testbox stop --id <tbx_id> ``` Use direct Blacksmith only when Crabbox is the broken layer and Blacksmith itself still works. Prefer direct `blacksmith testbox list` for cleanup diagnostics, not as a reusable work queue. Important Blacksmith footguns: - Always run from repo root. The CLI syncs the current directory. - Raw commit SHAs are not reliable `warmup --ref` refs; use a branch or tag. - If `blacksmith testbox list --all` works but warmups stay `queued`, this is not a Crabbox bug. Stop the queued ids and switch to owned AWS/Hetzner instead of retrying. - If auth is missing and browser auth is acceptable: ```sh blacksmith auth login --non-interactive --organization openclaw ``` ## Owned Cloud Fallback Use AWS/Hetzner only when Blacksmith is down, quota-limited, missing the needed environment, or owned capacity is explicitly the goal. When AWS capacity is under pressure, do not start with `class=beast`. `beast` begins at 48xlarge instances and can burn 192 vCPU quota per request. OpenClaw's owned-cloud default is `standard`; escalate to `fast`, then `large`, and only use `beast` when the work is explicitly CPU-bound and the smaller class already failed the goal. Keep capacity hints enabled so brokered AWS leases print selected region/market, quota pressure, Spot fallback, and high-pressure class warnings. The OpenClaw repo config sets `capacity.hints: true`; use `CRABBOX_CAPACITY_HINTS=0` only when debugging hint rendering itself. Use `beast` only for exceptional lanes: - full-suite or all-plugin Docker matrices where wall time is dominated by CPU, not dependency install or network; - release/blocker validation where a maintainer explicitly asks for the largest owned AWS class; - performance profiling where the point is to compare high-core behavior. Do not use `beast` for `pnpm check:changed`, focused tests, docs-only work, ordinary lint/typecheck, small E2E repros, or Blacksmith outage triage. Those should use `standard` first and `fast` only when the extra cores materially help. Preferred AWS pressure-relief flow: ```sh CRABBOX_CAPACITY_REGIONS=eu-west-1,eu-west-2,eu-central-1,us-east-1,us-west-2 \ pnpm crabbox:warmup -- --provider aws --class standard --market on-demand --idle-timeout 90m pnpm crabbox:hydrate -- --id <cbx_id-or-slug> pnpm crabbox:run -- --id <cbx_id-or-slug> --timing-json --shell -- "env NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed" pnpm crabbox:stop -- <cbx_id-or-slug> ``` Use `--market spot` only when testing Spot behavior or saving cost matters more than launch reliability. Use `--market on-demand` when diagnosing quota/capacity because it removes Spot market churn from the failure. ```sh CRABBOX_CAPACITY_REGIONS=eu-west-1,eu-west-2,eu-central-1,us-east-1,us-west-2 \ pnpm crabbox:warmup -- --provider aws --class fast --market on-demand --idle-timeout 90m pnpm crabbox:hydrate -- --id <cbx_id-or-slug> pnpm crabbox:run -- --id <cbx_id-or-slug> --timing-json --shell -- "env NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test:changed" pnpm crabbox:stop -- <cbx_id-or-slug> ``` Install/auth for owned Crabbox if needed: ```sh brew install openclaw/tap/crabbox printf '%s' "$CRABBOX_COORDINATOR_TOKEN" | crabbox login --url https://crabbox.openclaw.ai --provider aws --token-stdin ``` macOS config lives at: ```text ~/Library/Application Support/crabbox/config.yaml ``` It should include `broker.url`, `broker.token`, and usually `provider: aws` for owned-cloud lanes. Do not let that config override the OpenClaw default when Blacksmith proof is requested; pass `--provider blacksmith-testbox`. ### Interactive Desktop / WebVNC For human desktop demos, prefer `webvnc` over native `vnc` and keep the remote desktop visible/windowed. Do not fullscreen the remote browser or hide the XFCE panel/window chrome unless the explicit goal is video/capture output. After launch, verify a screenshot shows the desktop panel plus browser title bar. If Chrome is fullscreen, toggle it back with: ```sh crabbox run --id <lease> --shell -- 'DISPLAY=:99 xdotool search --onlyvisible --class google-chrome windowactivate key F11' ``` ## Diagnostics ```sh crabbox status --id <id-or-slug> --wait crabbox inspect --id <id-or-slug> --json crabbox sync-plan crabbox history --lease <id-or-slug> crabbox logs <run_id> crabbox results <run_id> crabbox cache stats --id <id-or-slug> crabbox ssh --id <id-or-slug> blacksmith testbox list ``` Use `--debug` on `run` when measuring sync timing. Use `--timing-json` on warmup, hydrate, and run when comparing backends. Use `--market spot|on-demand` only on AWS warmup/one-shot runs. ## Failure Triage