crabbox

Files (2)

• SKILL.md
• operations.md · references/

SKILL.md (first lines)

# Crabbox

- Deliberate remote proof: follow [proof policy](../openclaw-testing/SKILL.md#proof-policy).
  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.
- Never wait on queues or chain provider fallbacks.

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

- Resolve example commands, bootstrap, container image, PR from trusted consumer
  instructions. Never invent commands or copy another consumer's setup.
- Consumer-specific setup stays outside portable skill. See
  [placeholder definitions](references/operations.md#repository-contract).

## Authorization and Isolation

- Task-needed creation, reuse, cleanup, temporary state, clean checkouts:
  pre-approved. Preserve existing branches, checkouts, unrelated edits.
- Source trust, credentials, production access, budget, publication remain
  authority boundaries. Isolated state; never touch operator Gateway without
  per-task approval.

## Route First

- Preserve resolved provider: Testbox for trusted source; direct AWS when its
  semantics required; secretless CI/AWS for untrusted code. Never run untrusted
  wrappers/config locally or hydrate untrusted lease.
- Acquire when command ready; reuse owned ID; stop afterward.
- Smallest proven profile. Larger: recorded memory evidence or measured
  total-cost benefit required, not generic failure/delay/timeout. Do not raise
  worker counts to compensate.
- Testbox sizing: `--blacksmith-workflow`, never direct `--class`/`--type`;
  profile changes require fresh leases.
- Blacksmith runner labels request a tier, not guaranteed CPU or RAM.
  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.
- Size, duration, hydration failure, capacity never authorize provider overrides;
  explicit user selection or required backend semantics do.

## Preflight

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

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

- Use consumer's trusted wrapper/install instructions.
- Repairs: verify upstream; use clean task-owned checkout; preserve installed
  binary + unrelated source. Never trust sibling checkout merely by name.

## Lease lifetime

- TTL counts from creation, including hydration; idle timeout counts inactivity.
  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.
- `--keep` and `stop: never` do not prevent expiry. Request explicit bounded TTL
  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.
- Before long source-dependent work, inspect remaining total lifetime. If allowed,
  request one bounded `extend <id> --ttl <desired-total> --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.
- Direct guest-refresh failure can leave a longer provider deadline with the old
  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.
- Honor trusted `directLeases: deny` and `directLeaseAllow`. A denied provider
  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.
- `list` shows live coordinator leases; `list --retained` adds kept terminal
  resources whose cleanup is unconfirmed. Use exact-ID inspect/stop for recovery.
  Retain claims and recovery state until a blocking stop confirms completion.

## Trusted Testbox

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

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

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

```sh
"$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.
- Prefer `bash -c`; login profiles can change directories. In executing shell,
  assert physical checkout + expected source/patch; HEAD alone ≠ dirty-sync proof.
  Follow consumer's documented hydration shell contract.

From ngpestelos-mirrors/openclaw, MIT.