---

name: crabbox description: "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." license: MIT

Crabbox

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

Detect Crabbox

• Treat repo-root crabbox.yaml or .crabbox.yaml as an intentional signal to use this skill for validation work. .crabbox.yml is not a supported config filename.
• If neither config exists, command -v crabbox still identifies an installed CLI. Run crabbox doctor before depending on it for remote work.
• Inspect config before executing it. Detection does not imply permission to expose secrets, bypass command approval, or start paid infrastructure.

Source Of Truth

• Run Crabbox from the repository root; sync mirrors the current checkout.
• Treat repo-local crabbox.yaml or .crabbox.yaml as executable project automation. Review it before remote runs, especially provider, actions, jobs, profiles, env.allow, artifacts, and cleanup policy.
• Verify the installed binary before relying on examples: command -v crabbox && crabbox --version && crabbox --help | sed -n '1,120p'.
• Use crabbox providers or crabbox providers --json for the current provider/capability matrix; provider docs can lag the compiled binary.
• Use crabbox doctor for live readiness checks and crabbox config show to inspect merged config without printing secrets.
• Prefer local targeted tests for tight edit loops. Move to Crabbox for broad suites, package-heavy checks, Docker/E2E/live-provider proof, cross-OS proof, UI proof, or commands that bog down the local machine.

Auth And Config

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

crabbox login --url <broker-url>
crabbox whoami
crabbox doctor

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

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

Config precedence is flags > env > repo config > user config > defaults. Default user config is ~/Library/Application Support/crabbox/config.yaml on macOS, ~/.config/crabbox/config.yaml on Linux, or $XDG_CONFIG_HOME/crabbox/config.yaml when set. crabbox config path prints the active user config path.

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

Choose The Remote Surface

• crabbox run -- <command>: one command on a fresh or reused box.
• crabbox warmup: create a reusable lease and run commands later with --id.
• crabbox prewarm: warm a reusable lease and hydrate it from configured GitHub Actions.
• crabbox job run <name>: use a repo-local named flow that expands to warmup, optional hydration, run, and stop.
• crabbox run --pool <key>: borrow a hydrated broker ready-pool lease, run, then return/drain/release it according to --pool-return.
• crabbox run --fresh-pr ...: ignore local sync and check out a GitHub PR on the remote; add --apply-local-patch to test local uncommitted changes on top of that PR.
• crabbox run --provider ssh: use an existing macOS, Linux, or Windows host.
• crabbox warmup --desktop --browser: provision a visible desktop/browser for UI testing, WebVNC, screenshots, and artifacts.

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

Common Remote Proof

One-shot command:

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

Warm and reuse a lease:

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

Use a repo-local job when configured:

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

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

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

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

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

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

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

Sync And Fresh Checkouts

Use --no-sync only with a provider that supports skipping local file transfer. Blacksmith Testbox rejects it: native Testbox runs sync even with an existing --id. Do not use that path to inspect a remote baseline without uploading local edits. Blacksmith also rejects nonblank prewarm --probe-command probes and jobs with noSync: true before lease acquisition. Put probes in its native workflow instead.

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

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

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

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

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

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

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

Scripts, Shells, And Windows Targets

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

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

Use --script for standalone multi-line commands, included in failure bundles. On POSIX SSH leases, it runs a content-hashed copy under .crabbox/scripts/. The remote workdir is $PWD; $0, dirname "$0", and Python's __file__ refer to the uploaded copy, not the original script directory. Resolve synced assets from $PWD, or run a repository script in place when it needs adjacent files: crabbox run -- ./scripts/check.sh.

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

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

Hyper-V Windows leases

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

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

Secrets And Environment Forwarding

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

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

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

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

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

Profiles, Presets, Proof, And Results

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

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

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

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

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

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

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

Run Handles And Observability

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

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

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

echo CRABBOX_PHASE:install
pnpm install --frozen-lockfile
echo CRABBOX_PHASE:test
pnpm test

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