crabbox skill

Crabbox

Prefer bounded local proof on a qualified, available host. Expensive or platform-specific work can use remote capacity. Queued: stop owned allocation; use PR CI or a safe local scope and report uncovered requirements. Required build unavailable before publication: use the testing skill's draft/CI proof policy.

• Deliberate remote proof: follow proof policy.

• Never wait on queues or chain provider fallbacks.

Backends:

• ascii-box (boat alias): direct Boat Linux VMs. cbx_....
• 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

instructions. Never invent commands or copy another consumer's setup.

• Resolve example commands, bootstrap, container image, PR from trusted consumer

placeholder definitions.

• Consumer-specific setup stays outside portable skill. See

Authorization and Isolation

pre-approved. Preserve existing branches, checkouts, unrelated edits.

• Task-needed creation, reuse, cleanup, temporary state, clean checkouts:

authority boundaries. Isolated state; never touch operator Gateway without per-task approval.

• Source trust, credentials, production access, budget, publication remain

Route First

configuration and explicit task instructions. Use secretless CI/AWS for untrusted code. Never run untrusted wrappers/config locally or hydrate untrusted lease.

• For trusted source, preserve the provider resolved from the consumer's

total-cost benefit required, not generic failure/delay/timeout. Do not raise worker counts to compensate.

• Acquire when command ready; reuse owned ID; stop afterward.
• Smallest proven profile. Larger: recorded memory evidence or measured

profile changes require fresh leases.

• Testbox sizing: --blacksmith-workflow, never direct --class/--type;

Blacksmith can allocate smaller machines depending on service availability. For resource-sensitive tests or benchmarks, measure available CPUs, affinity/quotas, and usable RAM on the allocated machine. Size workers and workloads from those measurements. Record the requested tier and observed resources separately. Do not qualify hardware or performance from labels alone.

• Blacksmith runner labels request a tier, not guaranteed CPU or RAM.

explicit user selection or required backend semantics do.

• Size, duration, hydration failure, capacity never authorize provider overrides;

Preflight

Trusted repo root: read .crabbox.yaml, resolve installed binary, inspect provider/commands:

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

matching Crabbox distribution, or a verified runtime manifest selected with CRABBOXRUNTIMEARTIFACTS. Match the companions to the frozen source and verify that the manifest binds the exact selected controller. A development CLI without a runtime pack uses legacy SSH supervision; --version alone does not establish native supervision. Verify the selected pack before allocation; do not count CLI-only proof as native lifecycle proof. Follow the upstream runtime artifact instructions.

• Use consumer's trusted wrapper/install instructions.
• Native Linux/WSL command-lifecycle and cancellation proof requires a complete

binary + unrelated source. Never trust sibling checkout merely by name.

• Repairs: verify upstream; use clean task-owned checkout; preserve installed

Lease lifetime

Earlier deadline wins. Defaults: 30m each, 4h maximum. Owner/org overrides can allow up to 24h; use effective policy and sanitized clamp notices, not requested durations. Policy tightening also applies to live leases.

• TTL counts from creation, including hydration; idle timeout counts inactivity.

and idle for retained direct leases. Plain heartbeat, setup, sync, SSH, and desktop use do not extend total TTL; run requests bounded auto-extension only while a command executes, within policy, budget, and provider capability.

• --keep and stop: never do not prevent expiry. Request explicit bounded TTL

request one bounded extend --ttl --json; extension does not reset idle. Denied/budget/unsupported/nonadvancing/inactive outcomes require a visible skip or failure, never provider switching or infinite lease chains. Creation-fixed providers such as Daytona need enough TTL at allocation.

• Before long source-dependent work, inspect remaining total lifetime. If allowed,

on-box deadline. Keep the same local state and retry the same fixed total TTL only to reconcile; do not treat the failed extension as protection.

• Direct guest-refresh failure can leave a longer provider deadline with the old

requires the configured coordinator route; never bypass with direct credentials. Testbox retains its native job and idle limits; --ttl does not extend a delegated workflow.

• Honor trusted directLeases: deny and directLeaseAllow. A denied provider

resources whose cleanup is unconfirmed. Use exact-ID inspect/stop for recovery. Retain claims and recovery state until a blocking stop confirms completion.

• list shows live coordinator leases; list --retained adds kept terminal

Trusted Testbox

Resolved provider = Testbox (or explicitly requested): commands preserve it. Add --provider blacksmith-testbox only for explicit override:

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

assert physical checkout + expected source/patch; HEAD alone ≠ dirty-sync proof. Follow consumer's documented hydration shell contract.

• One lease, one active command. No sync/reclaim during run.
• Prefer bash -c; login profiles can change directories. In executing shell,

--no-sync for remote baseline: Blacksmith has no native bypass; released Crabbox versions can silently ignore flag. Unchanged intentional rerun ≠ exception.

• Native Testbox runs own sync, including reused --id runs. Never rely on

may reuse a lease when task, physical checkout, base, dependencies, preparation, and workflow/job/ref remain unchanged. Keep the original allocation provenance. Incompatible receipt: stop; rewarm. No stale-lease override.

• --reclaim only for deliberate checkout-path ownership transfer.
• Follow the consumer's allocation receipt for reuse. Compatible source commits