crabbox

Files (1)

• SKILL.md

SKILL.md (first lines)

# Crabbox

Remote and clean-machine proof. Packages. Docker. Live providers. Desktop.
Cross-OS. The consumer repository owns when its validation needs a remote
environment; Crabbox availability alone is not a reason to offload local work.

Backends:

- `blacksmith-testbox`: trusted maintainer source. Prepared CI. `tbx_...`.
- `aws`: direct brokered Crabbox. Fresh PRs. Custom sync/env/capture. `cbx_...`.
- `local-container`: Docker fallback. Not remote proof.
- `ssh`: existing operator host. macOS/Windows/WSL2.

Always report provider, id, run URL, command, result. Never call Testbox “AWS
Crabbox.”

## Repository Contract

This canonical skill owns portable Crabbox policy and CLI operations only.
Consumer-specific setup belongs in that repository's `AGENTS.md`, package
scripts, hydration workflow, or another file outside the synchronized skill.

Resolve these placeholders from trusted repository instructions before running
an example:

- `<check-command>`: the repository's focused or broad validation command.
- `<install-and-check-command>`: its clean-container install plus validation.
- `<trusted-bootstrap-script>`: a maintainer-reviewed untrusted-PR bootstrap
  stored outside the untrusted checkout.
- `<container-image>` and `<owner/repo#number>`: the consumer's runtime and PR.

Never invent a missing command or copy a command from another consumer.

## Authorization and Isolation

Routine use of the configured Crabbox/Testbox environment is part of completing
the requested task; do not ask for separate approval. This includes creating,
reusing and stopping task-owned leases, temporary state, and clean checkouts or
worktrees needed for proof or a task-required Crabbox repair.

A dirty, missing or occupied checkout is a reason to use a clean task-owned
checkout or worktree, not a permission blocker. Preserve existing checkouts,
branches and unrelated edits. Keep source-trust, credential, production-access,
budget and publication boundaries; routine-use approval does not waive them.

## Route First

Source trust determines which providers are allowed. It does not select one.

- Trusted development tests/checks/builds: follow the consumer's local-first
  policy; use remote when its environment is needed or explicitly requested.
- Trusted + remote proof: inspect and preserve the resolved provider.
- Blacksmith Testbox: use when already resolved or explicitly requested.
- Direct AWS: use when AWS semantics are required or explicitly requested.
- Untrusted contributor/fork: secretless fork CI or sanitized direct AWS.
- Never untrusted code on credential-hydrated Testbox.
- Never run untrusted repo wrapper/config locally.
- No speculative warmup. Acquire when first heavy command ready. Reuse id. Stop.
- Use the consumer's smallest proven remote profile. Large/high-memory profiles
  are explicit exceptions for a named command with measured memory need or a
  controlled total-cost benefit. Record the reason before allocation; a generic
  failure, queue delay, or timeout is not a reason to upsize. Do not raise worker
  counts to compensate for a smaller machine.
- For delegated Testbox sizing, select a documented workflow through
  `--blacksmith-workflow`; direct-provider `--class`/`--type` flags do not choose
  the Testbox runner. Change profiles with a fresh lease.

Test size, expected duration, and hydration failure do not authorize a provider
override. Omit `--provider` for normal work. Add it only when the user requests
that backend or the proof specifically tests its semantics.

## Preflight

Run from repo root.

```sh
command -v crabbox
crabbox --version
crabbox config show --json | jq '{provider, profile, target}'
crabbox run --help | sed -n '1,100p'
command -v blacksmith
blacksmith --version
```

Set the checked installed binary once. A consumer may document a different
trusted wrapper, but the shared skill never assumes a sibling checkout or
repository-specific script.

```sh
export CRABBOX="$(command -v crabbox)"
test -n "$CRABBOX"
"$CRABBOX" --version
"$CRABBOX" config show --json | jq '{provider, profile, target}'
```

Read `.crabbox.yaml` and `config show`; the resolved provider can also come from
user or environment configuration. If the binary is missing, follow the
consumer's trusted install instructions. For a source build or repair, verify
the canonical upstream and use a clean task-owned checkout or worktree. Never
assume a sibling checkout is trusted or overwrite its unrelated work. Keep
task-specific builds separate from the operator's installed binary.

## Trusted Testbox

Use this section only when `config show` resolves `blacksmith-testbox` or the
user explicitly requested Testbox. These provider-neutral commands preserve the
resolved configuration; add `--provider blacksmith-testbox` only for that
explicit override.

One-shot heavy gate:

```sh
"$CRABBOX" run --timing-json -- CI=1 <check-command>
```

Several commands: warm once, save id, reuse, stop.

```sh
"$CRABBOX" warmup --keep --timing-json

From Elogic360/imClaw, MIT.

More from Elogic360/imClaw