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.

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.
• 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.

Untrusted AWS

Clean trusted default-branch checkout. Installed trusted Crabbox binary. Fresh

lease per reviewed full head SHA. No instance role. No Tailscale. No hydration.

Only CI forwarded. Trusted bootstrap uploaded beside --fresh-pr.

cd <clean-trusted-default-branch-checkout>
env -u CRABBOX_AWS_INSTANCE_PROFILE \
  "$CRABBOX" config show --json | \
  jq -e '.aws.instanceProfile == ""' >/dev/null

env -u CRABBOX_AWS_INSTANCE_PROFILE \
  -u CRABBOX_TAILSCALE \
  -u CRABBOX_TAILSCALE_AUTH_KEY \
  -u CRABBOX_TAILSCALE_AUTH_KEY_ENV \
  -u CRABBOX_TAILSCALE_EXIT_NODE \
  -u CRABBOX_TAILSCALE_EXIT_NODE_ALLOW_LAN_ACCESS \
  -u CRABBOX_TAILSCALE_HOSTNAME_TEMPLATE \
  -u CRABBOX_TAILSCALE_TAGS \
  "$CRABBOX" warmup \
  --provider aws --network public --tailscale=false \
  --tailscale-exit-node= \
  --tailscale-exit-node-allow-lan-access=false \
  --keep --timing-json

"$CRABBOX" inspect --provider aws --id <cbx_id> --json | \
  jq -e '.network == "public" and .tailscale == null' >/dev/null

env -u CRABBOX_AWS_INSTANCE_PROFILE \
  CRABBOX_ENV_ALLOW=CI \
  "$CRABBOX" run \
  --provider aws --id <cbx_id> \
  --fresh-pr <owner/repo#number> \
  --no-hydrate --timing-json \
  --script <trusted-bootstrap-script> -- \
  <expected_full_head_sha> <check-command>

env -u CRABBOX_AWS_INSTANCE_PROFILE \
  "$CRABBOX" stop --provider aws <cbx_id>

The consumer-owned bootstrap proves the IMDSv2 IAM credential endpoint returns

404, verifies the full SHA, removes inherited runtime injection variables,

pins the repository toolchain, isolates HOME, installs, and tests.

Head moved? Stop. Rewarm. No reuse across revisions. No remote PR or no-role

proof unavailable? Secretless fork CI. No exceptions.

Direct AWS

Trusted direct run:

"$CRABBOX" run \
  --provider aws \
  --idle-timeout 90m --ttl 240m --timing-json \
  --shell -- \
  "<check-command>"

Focused:

"$CRABBOX" run \
  --provider aws --timing-json --shell -- \
  "<check-command>"

Stale sync: retry --full-resync once. Still bad: fresh lease. One-shot should

stop itself; after failure/interruption verify "$CRABBOX" list --provider aws.

Broker auth, not cloud keys:

"$CRABBOX" config show
"$CRABBOX" doctor
"$CRABBOX" whoami
"$CRABBOX" login --url <broker-url> --provider aws

Normal validation asking for AWS keys usually means wrong path.

Fresh PR / Container

--fresh-pr <owner/repo#123>: clean remote checkout. Add --apply-local-patch

only for intentional local fixup. Direct providers only.

Use local Docker only when the resolved configuration selects it or the user

explicitly requests a local-container lane:

"$CRABBOX" run \
  --provider local-container \
  --local-container-image <container-image> \
  --no-hydrate --fresh-pr <owner/repo#number> \
  --timing-json --shell -- \
  "<install-and-check-command>"

Report local-container; not AWS/Testbox. Keep --no-hydrate and use a

repository-local dependency cache when host-mounted caches cannot cross filesystems.

Observability

Prefer built-ins:

• --preflight: target/workspace/tool probes.
• --debug --timing-json: sync, command, total timing.
• --script <file> / --script-stdin: safe multiline direct-provider command.
• --allow-env NAME + --env-from-profile <file>: exact direct-provider env.
• CRABBOX_ENV_ALLOW=NAME,...: exact ambient env allowlist.
• --capture-stdout, --capture-stderr: direct-provider local capture.
• --capture-on-fail: test artifacts. Treat as secret-bearing until reviewed.
• --keep-on-failure: retain failed lease for debugging.
• --results-auto / --junit <path>: structured failure digest.
• CRABBOX_PHASE:<name> lines: phase timing.

Secrets: exact key only. One command. Never print. Never repo file. Never shell

history. No safe injection path? Report live auth blocked. No fake-key upgrade to

“live proof.”

Real E2E

“Test in Crabbox” means user path, not merely remote unit tests.

1. Reproduce entrypoint when feasible.
2. Patch. Narrow local test.
3. Remote install/update/onboard/CLI/service/API path.
4. Record provider, id, command, environment shape, redacted secret source,

observed result.

1. Cleanup.

Route:

• Install/package: pack tarball; install like user; matching Docker/package lane.
• Provider/auth: real provider. Scrub unrelated provider vars.
• Integration: setup, config, send/receive, and inspect redacted logs.
• Service/session/tool: real CLI or API; inspect persisted state and result.
• Parser/config: focused tests enough only when OS/package/service cannot matter.

Before/after: same Testbox when practical. Detached temp worktrees under /tmp.

Never checkout refs in synced root. For native Testbox, prepare and compare both

revisions within one synced invocation; later runs sync the local checkout again.

Full-screen CLI: real PTY. Interactive Clack: exact arrows/Enter; raw search

typing can lie.

Use the consumer's documented temporary state/config directory so proof cannot

mutate the operator's normal installation.

Desktop / Cross-OS

Static hosts:

"$CRABBOX" run --provider ssh --target macos \
  --static-host <macos-host> -- <check-command>
"$CRABBOX" run --provider ssh --target windows --windows-mode normal \
  --static-host <windows-host> -- pwsh -NoProfile -Command '<check-command>'
"$CRABBOX" run --provider ssh --target windows --windows-mode wsl2 \
  --static-host <windows-host> -- <check-command>

Windows/WSL2: prefer Azure when advertised/configured. Native Windows uses

OpenSSH + PowerShell + Git + tar. Actions hydration Linux-only.

Brokered macOS: paid EC2 Mac. First quota/no-spend preflight. No silent

substitution for Linux proof.

"$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

Human desktop: WebVNC preferred when the resolved provider supports it. Do not

change providers only to gain desktop support.

"$CRABBOX" warmup --desktop --browser --keep
"$CRABBOX" desktop launch --id <id> \
  --browser --url https://example.com --webvnc --open --take-control
"$CRABBOX" desktop doctor --id <id>
"$CRABBOX" webvnc status --id <id>
"$CRABBOX" artifacts collect --id <id> --all --output artifacts/<slug>

Before handoff, prove CLI/app from neutral ~:

"$CRABBOX" run --id <id> --shell -- \
  "cd ~ && command -v <command> && <command> --version"

Visible desktop alone proves nothing. Keep browser windowed unless capture task.

Never commit proof assets to product repo.

Failure Triage

Identify layer: wrapper, provider, hydration, sync, SSH, command.

"$CRABBOX" doctor
"$CRABBOX" status --id <id> --wait
"$CRABBOX" inspect --id <id> --json
"$CRABBOX" history --limit 20
"$CRABBOX" logs <run_id>
"$CRABBOX" results <run_id>
blacksmith testbox list --all
blacksmith testbox status --id <tbx_id>

• Provider/CLI old: follow the consumer's trusted Crabbox update path.
• Config/auth: config show, doctor, whoami.
• Sync quiet/stale: --debug --timing-json, then --full-resync once.
• Testbox capacity: no retry storm. Report the blocker; change providers only

with explicit user approval.

• Command failure: read phase, failed test, JUnit, skipped shell segment. Focused

rerun first.

• Cleanup unclear: list exact provider. Stop only owned ids.
• Consumer wrapper broken: use the installed Crabbox CLI only to isolate the

wrapper, preserving the same resolved provider.

Crabbox stop does not accept --timing-json.

Boundary

Crabbox stays generic: lease, sync, command, logs, results, timing, cleanup.

Consumer setup belongs in that repository's hydration workflow and scripts.