Crabbox

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.

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.

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:

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

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

"$CRABBOX" warmup --keep --timing-json
"$CRABBOX" run --id <tbx_id> --timing-json -- <check-command>
"$CRABBOX" stop <tbx_id>

Rules:

• One lease, one active command. No sync/reclaim during run.
• Compound payloads: prefer bash -c, not bash -lc. Bash syntax support does not require login startup; login profiles can change directories. Before validation, assert the exact physical checkout and expected source/patch inside the shell that runs it. A matching HEAD alone cannot prove dirty sync.
• Native Testbox runs own sync, including reused --id runs. Never rely on --no-sync to preserve a remote baseline: Blacksmith has no native bypass, and released Crabbox versions can silently ignore the flag. An unchanged intentional rerun is not a Testbox exception.
• --reclaim only deliberate checkout-path ownership transfer.
• Base/head change: stop. Rewarm. No stale-lease override.
• Raw SHA unreliable for warmup --ref; use branch/tag.
• blacksmith testbox list hides states. Use list --all or status --id <tbx_id>.
• Testbox status/stop: --id. No status --json.
• Delegated provider rejects --fresh-pr, --full-resync, --script*, --env-helper, capture/download flags.

Blacksmith directory downloads

Blacksmith CLI 0.4.60 (verified 2026-09-19) needs a trailing / on the remote directory argument to enable recursive SCP; otherwise it fails with not a regular file. A local trailing slash does not help, and SCP may add / in the error text even when the caller omitted it.

mkdir -p ./downloads
blacksmith testbox download --id <tbx_id> screenshots/ ./downloads/

Use an explicit destination: this writes ./downloads/screenshots/; omitting it can duplicate the basename (screenshots/screenshots/). Reuse the task-owned lease and existing key path (--ssh-private-key when needed). Verify the downloaded tree and hashes; recheck this workaround after CLI upgrades.