/crabbox

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

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 confus