crabboxSAFE

Crabbox: warm a box, sync the diff, run the suite.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
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:

```sh
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:

```sh
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:

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

Warm and reuse a lease:

```sh
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:

```sh
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:

```sh
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:

```sh
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:

```sh
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

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.