{"slug":"crabbox","title":"crabbox","summary":"Detect and use Crabbox for repository tests and validation on remote runners. Use when crabbox.yaml or .crabbox.yaml exists, the crabbox CLI is available, or work needs remote compute, a clean or reusable environment, target-platform coverage, or auditable execution evidence.","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-08-24T16:56:35.300881Z","repo":{"url":"https://github.com/openclaw/crabbox","stars":1434,"forks":189,"license":"MIT","updatedAt":"2026-09-27T12:27:25Z"},"bodyHtml":"
\n

name: crabbox\ndescription: \"Detect and use Crabbox for repository tests and validation on remote runners. Use when crabbox.yaml or .crabbox.yaml exists, the crabbox CLI is available, or work needs remote compute, a clean or reusable environment, target-platform coverage, or auditable execution evidence.\"\nlicense: MIT

\n

Crabbox

\n

Use Crabbox when a project needs remote proof, larger cloud capacity, a fresh\nPR checkout, a reusable warmed box, GitHub Actions-style setup, durable run\nlogs/results, UI proof artifacts, or sync from a dirty local checkout.

\n

Detect Crabbox

\n\n

Source Of Truth

\n\n

Auth And Config

\n

Brokered operation needs a coordinator URL and token. First login usually needs\nan explicit broker URL:

\n
crabbox login --url <broker-url>\ncrabbox whoami\ncrabbox doctor\n
\n

After broker.url is configured, crabbox login can reuse it. Trusted operator\nautomation can store a shared token without putting it on argv:

\n
printf '%s' \"$CRABBOX_COORDINATOR_TOKEN\" |\n  crabbox login --url <broker-url> --provider aws --token-stdin\n
\n

Config precedence is flags > env > repo config > user config > defaults.\nDefault user config is ~/Library/Application Support/crabbox/config.yaml on\nmacOS, ~/.config/crabbox/config.yaml on Linux, or\n$XDG_CONFIG_HOME/crabbox/config.yaml when set. crabbox config path prints\nthe active user config path.

\n

Keep provider and broker tokens out of repo config and command arguments. Use\nenvironment variables, a credential store, coordinator-managed secrets, or a\nshort-lived token command.

\n

Choose The Remote Surface

\n\n

If remote proof is blocked, name the missing capability precisely: auth,\ncoordinator, capacity, provider support, target OS, hydration, secret access,\nartifact storage, desktop support, or a delegated-provider limitation.

\n

Common Remote Proof

\n

One-shot command:

\n
crabbox run --preflight --timing-json -- pnpm test\n
\n

Warm and reuse a lease:

\n
crabbox warmup --class beast --idle-timeout 90m\ncrabbox status --id <cbx_id-or-slug> --wait\ncrabbox run --id <cbx_id-or-slug> -- pnpm test:changed\ncrabbox run --id <cbx_id-or-slug> --full-resync -- pnpm test:changed\ncrabbox stop <cbx_id-or-slug>\n
\n

Use a repo-local job when configured:

\n
crabbox job list\ncrabbox job run --dry-run <job-name>\ncrabbox job run <job-name>\ncrabbox job run --id <cbx_id-or-slug> <job-name>\n
\n

Use a ready-pool lease when the coordinator has hydrated pool capacity:

\n
crabbox pool ready\ncrabbox run --pool <pool-key> -- pnpm test\ncrabbox run --pool <pool-key> --pool-return drain -- pnpm test:flaky\n
\n

Use GitHub Actions hydration when the repository already owns setup in CI:

\n
crabbox warmup --idle-timeout 90m\ncrabbox actions hydrate --id <cbx_id-or-slug>\ncrabbox run --id <cbx_id-or-slug> -- pnpm test\n
\n

Use --github-runner only when the workflow needs full GitHub Actions\nsemantics such as repository secrets, OIDC, service containers, job containers,\nor unsupported uses: steps:

\n
crabbox actions hydrate --github-runner --id <cbx_id-or-slug>\n
\n

Sync And Fresh Checkouts

\n

Normal sync transfers tracked files plus non-ignored untracked files, excludes\nignored dependency/build/cache output, honors .crabboxignore and\nsync.exclude, seeds the remote checkout from origin when possible, and skips\nrsync when the sync fingerprint matches.

\n

Use crabbox sync-plan before large runs. Unexpected counts usually mean\nlocal generated churn; update .crabboxignore or sync.exclude instead of\nforcing huge uploads.

\n
crabbox sync-plan\ncrabbox run --debug --timing-json -- pnpm test\ncrabbox run --full-resync -- pnpm test\n
\n

Use fresh PR checkout when local dependency churn or dirty sync would confuse\nthe result:

\n
crabbox run --fresh-pr example-org/my-app#123 --script ./scripts/e2e-smoke.sh\ncrabbox run --fresh-pr 123 --apply-local-patch -- pnpm test\n
\n

--fresh-pr accepts owner/repo#number, GitHub PR URLs, or a numeric PR from\nthe current GitHub origin. Non-GitHub hosts are rejected. Fresh PR checkout is\nan SSH-run sync feature; delegated providers reject it. Native Windows SSH\ntargets are supported.

\n

When a warm lease smells stale, prefer --full-resync (alias --fresh-sync) to\nreset the remote workdir, skip the sync fingerprint fast path, reseed Git when\npossible, and upload the checkout from scratch.

\n

Scripts, Shells, And Windows Targets

\n

Use plain argv after -- for one executable. Use --shell for multi-statement\nshell snippets, pipes, or shell expansion:

\n
crabbox run --id <lease> -- go test ./...\ncrabbox run --id <lease> --shell 'corepack enable && pnpm install --frozen-lockfile && pnpm test'\n
\n

Prefer uploaded scripts for multi-line commands. Scripts are included in failure\nbundles and avoid brittle quoted shell strings:

\n
crabbox run --script ./scripts/e2e-smoke.sh --timing-json\nprintf '%s\\n' 'echo CRABBOX_PHASE:test' 'pnpm test' | crabbox run --script-stdin\n
\n

Native Windows targets use PowerShell and tar-based manifest sync. Prefer plain\nargv for one executable such as dotnet test; use --shell for multi-statement\nPowerShell and --script <file.ps1> for longer scripts.

\n

Hyper-V Windows leases

\n

hyperv needs a Generation 2 VHDX, DHCP, and a known local administrator\npassword in trusted config or CRABBOX_HYPERV_GUEST_PASSWORD. It installs\npinned, verified OpenSSH and MinGit packages when missing, using PowerShell\nDirect. See docs/providers/hyperv.md for template and lifecycle details.

\n

For provider testing, prefer an elevated headless runner; early PowerShell\nDirect failures can show credential UI. Keep passwords out of arguments and\nlogs, and verify the lease becomes ready, runs over SSH, and releases.

\n

Secrets And Environment Forwarding

\n

Crabbox does not forward the whole local environment. Forwarding is name-based:\nonly allowlisted names that are actually set locally or in an allowed profile\ncross the boundary. Avoid allowlisting secret-shaped names unless the run is an\nexplicit live-secret smoke.

\n
crabbox run --allow-env CI,NODE_OPTIONS -- pnpm test\ncrabbox run \\\n  --env-from-profile ~/.project-live.profile \\\n  --allow-env API_TOKEN \\\n  --preflight \\\n  --script ./scripts/live-smoke.sh\n
\n

--env-from-profile parses simple export NAME=value and NAME=value lines\nwithout executing the profile. Crabbox prints redacted presence/length metadata,\nnot values. POSIX SSH leases can persist a helper for later commands on a lease\nyou control:

\n
crabbox run \\\n  --id <lease> \\\n  --env-from-profile ~/.project-live.profile \\\n  --allow-env API_TOKEN \\\n  --env-helper live \\\n  -- true\ncrabbox run --id <lease> -- ./.crabbox/env/live ./scripts/live-smoke.sh\n
\n

The generated helper and matching secret profile remain in the remote workdir\nuntil cleanup, lease reset, or --full-resync; do not persist helpers on shared\nor untrusted leases.

\n

Profiles, Presets, Proof, And Results

\n

Repo config can define profiles, presets, doctor requirements, artifact globs,\nrequired artifacts, and proof templates. Use them for stable validation lanes\ninstead of encoding project knowledge in agent prompts.

\n
crabbox run \\\n  --profile live-qa \\\n  --preset qa-live \\\n  --scenario login-regression \\\n  --emit-proof /tmp/proof.md \\\n  --stop-after success\n
\n

Use --preflight for a target capability snapshot before the command, not as\nan installer. Use --preflight-tools to tune probes:

\n
crabbox run --preflight --preflight-tools node,bun,docker -- bun test\ncrabbox run --preflight --preflight-tools default,uv -- node --test\n
\n

Attach structured results and proof artifacts when the command emits them:

\n
crabbox run --junit reports/junit.xml -- ./scripts/test-with-junit.sh\ncrabbox run --artifact-glob 'reports/**' --require-artifact reports/summary.json -- pnpm test:e2e\ncrabbox run --download reports/summary.json=.crabbox/logs/summary.json -- pnpm test:e2e\n
\n

--require-artifact fails the run if the remote command exits 0 but the proof\nfile is missing. Keep required artifacts bounded and scrubbed; do not collect\nraw datasets, secrets, credentials, signed URLs, or unredacted customer rows.

\n

Run Handles And Observability

\n

Coordinator-backed runs print a durable run_... handle before leasing starts.\nKeep that run ID in status updates and PR notes.

\n
crabbox history --limit 20\ncrabbox history --lease <cbx_id-or-slug> --limit 20\ncrabbox attach <run_id>\ncrabbox attach <run_id> --after <seq>\ncrabbox events <run_id> --after <seq> --limit 100\ncrabbox events <run_id> --json\ncrabbox logs <run_id>\ncrabbox results <run_id>\n
\n

Use --timing-json on run, warmup, and actions hydrate when a stable\nmachine-readable timing record is needed. Commands can mark subphases by\nprinting markers on stdout or stderr:

\n
echo CRABBOX_PHASE:install\npnpm install --frozen-lockfile\necho CRABBOX_PHASE:test\npnpm test\n
\n

Output events are capped previews. Use logs for retained output tails and\nresults for parsed test summaries.

\n

Desktop, WebVNC, And UI Proof

\n

Create desktop/browser leases for visual QA, headed browser automation, or UI\nproof:

\n
crabbox warmup --desktop --browser\ncrabbox warmup --provider aws --os ubuntu:26.04 --desktop --browser --desktop-env wayland\ncrabbox warmup --provider aws --os ubuntu:26.04 --desktop --browser --desktop-env gnome\n
\n

ubuntu:26.04 is the default portable Linux OS selector where the provider\ncatalog supports it. Use --os ubuntu:24.04 only when a test must stay on the\nprevious LTS. Explicit provider image flags still win over --os.

\n

For human demos, prefer WebVNC over native VNC because crabbox webvnc --open\npreloads the lease password in the browser fragment:

\n
crabbox webvnc --id <lease> --open --take-control\ncrabbox webvnc status --id <lease>\ncrabbox webvnc reset --id <lease> --open --take-control\ncrabbox vnc --id <lease> --open\n
\n

For input automation, use first-class helpers instead of hand-written\nxdotool:

\n
crabbox desktop doctor --id <lease>\ncrabbox desktop launch --id <lease> --browser --url https://example.com --webvnc --open --take-control\ncrabbox desktop click --id <lease> --x 640 --y 420\ncrabbox desktop paste --id <lease> --text \"user@example.com\"\nprintf 'user@example.com' | crabbox desktop paste --id <lease>\ncrabbox desktop type --id <lease> --text \"user+qa@example.com\"\ncrabbox desktop key --id <lease> ctrl+l\ncrabbox screenshot --id <lease> --output desktop.png\n
\n

When desktop/WebVNC hangs, trust the inline rescue output first: problem: and\nrescue: lines usually name exact next commands such as webvnc status/reset,\ndesktop doctor, or native vnc --open.

\n

Use artifacts for UI QA proof instead of committing screenshots or videos to a\nproduct repo branch:

\n
crabbox artifacts collect --id <lease> --all --output artifacts/<slug>\ncrabbox artifacts publish --dir artifacts/<slug> --pr <number>\ncrabbox artifacts list <artifact-manifest-url-or-dir>\ncrabbox artifacts pull <artifact-manifest-url-or-dir> --output /tmp/<slug>-proof\n
\n

artifacts publish uses brokered storage when configured, or explicit S3/R2 /\nCloudflare/local hosting flags. Use --dry-run before public PR comments when\nreviewing generated Markdown or storage commands.

\n

Provider Boundaries

\n

SSH-lease providers support the full sync/run surface when the target supports\nit: scripts, fresh PR checkouts, captures, downloads, Actions hydration, SSH,\nports, WebVNC, code-server, desktop, browser, cache volumes, and cleanup.

\n

Delegated-run providers own command transport. Expect them to reject SSH-run\nfeatures such as --capture-stdout, --capture-stderr, --capture-on-fail,\n--script, --script-stdin, --fresh-pr, local captures, --download,\n--full-resync, and --env-helper unless crabbox providers --json and the\nprovider docs advertise the matching capability. --keep-on-failure is still\nuseful for one-shot delegated providers that Crabbox would otherwise stop after\na failed command.

\n

Module-runtime delegated providers, such as Cloudflare Dynamic Workers, run\nsource modules rather than Linux shell commands. Use --script <file> or\n--script-stdin for module source; trailing -- <command>, SSH, rsync, ports,\nActions hydration, desktop, browser, and code-server do not apply unless the\nprovider explicitly documents them.

\n

Use --market spot|on-demand on AWS warmup or one-shot run when account\nquota or capacity testing needs a temporary market override. An explicit\n--type means exact type; Crabbox reports quota/capacity/policy failures\ninstead of silently falling back.

\n

Local And Static Targets

\n

Use local-container for fast local proof when the host has Docker or Podman.\nwarmup creates a container but does not sync; for an interactive synced\ncontainer, use run --keep --sync-only:

\n
crabbox run --provider local-container --keep --slug local-smoke --sync-only\neval \"$(crabbox ssh --provider local-container --id local-smoke)\"\n
\n

Pass --local-container-runtime docker or --local-container-runtime podman\nwhen the engine matters, and keep that flag on reused lease commands such as\nrun --id, ssh, status, and stop. crabbox ssh prints an SSH command;\nuse eval \"$(crabbox ssh ...)\" to connect. After login, cd into the workdir\nprinted by run --sync-only.

\n

Use static SSH for existing machines:

\n
crabbox run --provider ssh --target macos --static-host mac.example.com -- xcodebuild test\ncrabbox run --provider ssh --target windows --windows-mode normal --static-host win.example.com -- dotnet test\n
\n

Static hosts are host-managed: Crabbox does not provision or delete them.

\n

Useful Commands

\n
crabbox providers\ncrabbox providers --json\ncrabbox doctor\ncrabbox config path\ncrabbox config show\ncrabbox whoami\ncrabbox sync-plan\ncrabbox warmup --class beast\ncrabbox prewarm\ncrabbox status --id <lease> --wait\ncrabbox heartbeat --id <lease> --idle-timeout 90m\ncrabbox inspect --id <lease> --json\ncrabbox run --id <lease> --preflight --timing-json -- pnpm test\ncrabbox job list\ncrabbox job run --dry-run <job-name>\ncrabbox pool ready\ncrabbox history --lease <lease>\ncrabbox events <run_id> --json\ncrabbox attach <run_id>\ncrabbox logs <run_id>\ncrabbox results <run_id>\ncrabbox cache stats --id <lease>\ncrabbox cache volumes\ncrabbox ssh --id <lease>\ncrabbox connect <lease>\ncrabbox ports --id <lease> --publish 8080\ncrabbox cp --id <lease> ./coverage.xml SANDBOX:/tmp/coverage.xml\ncrabbox webvnc --id <lease> --open\ncrabbox code --id <lease> --open\ncrabbox egress start --id <lease> --profile discord --daemon\ncrabbox desktop doctor --id <lease>\ncrabbox desktop proof --id <lease> --output artifacts/<slug>-proof -- ./scripts/visual-smoke.sh\ncrabbox artifacts collect --id <lease> --all --output artifacts/<slug>\ncrabbox artifacts publish --dir artifacts/<slug> --pr <number> --dry-run\ncrabbox usage --scope org\ncrabbox pause <lease>\ncrabbox resume <lease>\ncrabbox stop <lease>\n
\n

Failure Triage

\n\n

Cleanup

\n

Brokered leases have coordinator-owned idle expiry and local lease claims.\nDefault idle timeout is 30 minutes unless config or flags set a different\nvalue. Still stop boxes you created when done:

\n
crabbox stop <cbx_id-or-slug>\n
\n

When crabbox list prints orphan=no-active-lease, treat it as an operator\nreview hint: verify the provider machine is not referenced by an active\ncoordinator lease before deleting anything, especially if keep=true is set.

\n","files":[{"path":"SKILL.md","sizeBytes":19464,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-08-30T09:02:16.679861Z","sha256":"5CA3D9729773CCDD1FB4CA1D8DC9A6734CA697CE98A408DEC32366563209E5EF","sizeBytes":7351},"review":null,"source":{"repositoryUrl":"https://github.com/openclaw/crabbox","path":"skills/crabbox","license":"MIT","commit":"2e04f7e2f43c7b21b13e81de736725da08944bca","subtreeSha":"F7A002AB604EAA49A3610FB46D3EB17791564CE9F5F56CD541720A6E61F1F93C","lastSyncedAt":"2026-09-27T19:33:28.151774Z"},"reviewedAt":"2026-08-30T09:07:53.87837Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/openclaw/crabbox/tree/main/skills/crabbox"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install openclaw-crabbox@llmmart"},{"target":"git","command":"git clone https://github.com/openclaw/crabbox.git"}]}