crabbox

Files (1)

• SKILL.md

SKILL.md (first lines)

# Crabbox

Use the Crabbox wrapper when Quiet Core bot 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.

Crabbox is the transport/orchestration surface. The actual backend can be:

- brokered AWS Crabbox: direct provider, `provider=aws`, lease ids like
  `cbx_...`, `syncDelegated=false`
- Blacksmith Testbox through Crabbox: delegated provider,
  `provider=blacksmith-testbox`, ids like `tbx_...`, `syncDelegated=true`

For Quiet Core bot maintainer broad `pnpm` gates, Blacksmith Testbox through the
Crabbox wrapper is acceptable and often preferred when the standing Testbox
rules apply. Do not describe those runs as "AWS Crabbox"; report them as
Testbox-through-Crabbox with the `tbx_...` id and Actions run.

Use the repo `.crabbox.yaml` brokered AWS path when the task specifically needs
direct AWS Crabbox behavior, persistent direct-provider leases, `--fresh-pr`,
`--full-resync`, environment forwarding, capture/download support, or provider
comparison. Use `--provider blacksmith-testbox` when the task needs Quiet Core bot
maintainer Testbox proof, prepared CI environment, broad/heavy pnpm gates, or
the user asks for Testbox/Blacksmith.

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

- Quiet Core bot scripts prefer `../crabbox/bin/crabbox` when present. The user PATH
  shim can be stale.
- Check `.crabbox.yaml` for direct-provider defaults. Omitting `--provider`
  means brokered AWS for normal Linux/macOS paths; the wrapper selects Azure
  for unqualified Windows/WSL2 runs when the local Crabbox binary advertises
  Azure.
- The brokered AWS default is a Linux developer image in `eu-west-1`; the repo
  config pins hot `eu-west-1a/b/c` placement so Fast Snapshot Restore can apply.
  If warmup drifts well past the minute-scale path, verify image promotion,
  region/AZ placement, and FSR state before blaming Quiet Core bot.
- For broad Quiet Core bot maintainer `pnpm` gates, prefer the repo wrapper with
  `--provider blacksmith-testbox` or the repo Testbox helpers when the standing
  Testbox policy applies.
- Cold Testbox acquisition and hydration often take tens of seconds. When broad
  remote proof is likely, immediately start
  `node scripts/crabbox-wrapper.mjs warmup --provider blacksmith-testbox --keep --timing-json`
  in a background command session while inspecting, editing, and running
  focused local tests. Poll later, reuse the returned `tbx_...` with
  `--provider blacksmith-testbox --id <tbx_id>`, and stop it before handoff.
  Do not warm speculatively when remote proof is unlikely.
- Always report the actual provider and id. `cbx_...` means AWS Crabbox;
  `tbx_...` means Blacksmith Testbox through Crabbox. If the output only says
  `blacksmith testbox list`, use `blacksmith testbox list --all` before
  concluding no box exists.
- If a warm direct-provider lease smells stale, retry with `--full-resync`
  (alias `--fresh-sync`) before replacing the lease. This resets the remote
  workdir, skips the fingerprint fast path, reseeds Git when possible, and
  uploads the checkout from scratch.
- For live/provider bugs, use the configured secret workflow before downgrading
  to mocks. Copy only the exact needed key into the remote process environment
  for that one command. Do not print it, do not sync it as a repo file, and do
  not leave it in remote shell history or logs. If no secret-safe injection path
  is available, say true live provider auth is blocked instead of silently using
  a fake key.
- Prefer local targeted tests for tight edit loops. Broad gates belong remote.
- Do not treat inherited shell env as operator intent. In particular,
  `QUIET_CORE_LOCAL_CHECK_MODE=throttled` from the local shell is not permission
  to move broad `pnpm check:changed`, `pnpm test:changed`, full `pnpm test`, or
  lint/typecheck fan-out onto the laptop.
- Only use `QUIET_CORE_LOCAL_CHECK_MODE=throttled|full` when the user explicitly
  asks for local proof in the current task. If Testbox is queued or capacity is
  constrained, report the blocker and keep only targeted local edit-loop checks
  running.

## macOS And Windows Targets

Use these only when the task needs an existing non-Linux host. Quiet Core bot broad
Linux validation uses the repo Crabbox config unless a provider is explicitly
requested.

Native brokered Windows is available for Windows-specific proof. Prefer Azure
for Windows/WSL2 when the subscription has quota or credits and the local
Crabbox binary advertises Azure. Keep broad Linux gates on Linux/Testbox unless
the bug is Windows-specific, and only force AWS when the operator asks for the
older AWS developer image/cache path or Azure is unavailable:

```sh
pnpm crabbox:warmup -- \
  --target windows \
  --windows-mode wsl2 \
  --timing-json
```

The hydrate workflow assumes Docker should already be baked into Linux images
and only installs it as a fallback. Do not add per-run Docker installs to proof
commands unless the image probe shows Docker is actually missing.

When the user explicitly asks for brokered macOS runners, use Crabbox AWS
macOS only after confirming the deployed coordinator supports EC2 Mac host
lifecycle/image routes and the operator has AWS EC2 Mac Dedicated Host quota
and IAM. Prefer `CRABBOX_HOST_ID` for a known Crabbox-managed Dedicated Host,
or run the no-spend preflight first:

```sh
crabbox admin hosts quota --provider aws --target macos --region eu-west-1 --type mac2.metal --json
crabbox admin hosts allocate --provider aws --target macos --region eu-west-1 --type mac2.metal --dry-run --json
CRABBOX_MACOS_TYPES=all scripts/macos-host-region-preflight.sh
```

Do not silently substitute AWS macOS for normal Quiet Core bot Linux proof. Report
paid-host blockers as quota, IAM, coordinator deployment, or host availability

From liuda1999/Quiet-Core-bot, MIT.

More from liuda1999/Quiet-Core-bot