Crabbox

Use the Crabbox wrapper when OpenClaw needs remote Linux proof for broad tests, CI-parity checks, secrets, hosted services, Docker/E2E/package lanes, warmed reusable boxes, sync timing, logs/results, cache inspection, or lease cleanup.

Crabbox is the transport/orchestration surface. The actual backend can be:

• brokered AWS Crabbox: direct provider, provider=aws, lease ids like cbx_..., syncDelegated=false
• Blacksmith Testbox through Crabbox: delegated provider, provider=blacksmith-testbox, ids like tbx_..., syncDelegated=true

For OpenClaw maintainer broad pnpm gates, Blacksmith Testbox through the Crabbox wrapper is acceptable and often preferred when the standing Testbox rules apply. Do not describe those runs as "AWS Crabbox"; report them as Testbox-through-Crabbox with the tbx_... id and Actions run.

Use the repo .crabbox.yaml brokered AWS path when the task specifically needs direct AWS Crabbox behavior, persistent direct-provider leases, --fresh-pr, --full-resync, environment forwarding, capture/download support, or provider comparison. Use --provider blacksmith-testbox when the task needs OpenClaw maintainer Testbox proof, prepared CI environment, broad/heavy pnpm gates, or the user asks for Testbox/Blacksmith.

First Checks

• Run from the repo root. Crabbox sync mirrors the current checkout.
• Check the wrapper and providers before remote work:

command -v crabbox
../crabbox/bin/crabbox --version
pnpm crabbox:run -- --help | sed -n '1,120p'
../crabbox/bin/crabbox desktop launch --help
../crabbox/bin/crabbox webvnc --help

• If both PATH crabbox and ../crabbox/bin/crabbox are missing, or the sibling binary fails the version/help checks, install the sibling Crabbox CLI before reporting Crabbox as unavailable:

crabbox_root="../crabbox"
crabbox_src="$crabbox_root"
if [ -d "$crabbox_root/.git" ]; then
  :
elif [ -d "$crabbox_root/src/.git" ]; then
  crabbox_src="$crabbox_root/src"
elif [ ! -e "$crabbox_root" ]; then
  git clone https://github.com/openclaw/crabbox.git "$crabbox_root"
else
  echo "Existing $crabbox_root is not a Crabbox checkout; move it aside first." >&2
  exit 1
fi
if [ -n "$(git -C "$crabbox_src" status --short)" ]; then
  git -C "$crabbox_src" status --short
  echo "Dirty $crabbox_src checkout; resolve before updating Crabbox." >&2
  exit 1
fi
git -C "$crabbox_src" pull --ff-only
mkdir -p "$crabbox_root/bin"
crabbox_bin="$(cd "$crabbox_root" && pwd)/bin/crabbox"
go version
(cd "$crabbox_src" && go build -o "$crabbox_bin" ./cmd/crabbox)
"$crabbox_bin" --version
node scripts/crabbox-wrapper.mjs run --help | sed -n '1,80p'

• If go version is missing or the build fails, report that first actionable toolchain/build error. Do not claim Crabbox proof from a stale PATH shim.
• OpenClaw scripts prefer ../crabbox/bin/crabbox when present. The user PATH shim can be stale.
• Check .crabbox.yaml for direct-provider defaults. Omitting --provider means brokered AWS today.
• For broad OpenClaw maintainer pnpm gates, prefer the repo wrapper with --provider blacksmith-testbox or the repo Testbox helpers when the standing Testbox policy applies.
• Always report the actual provider and id. cbx_... means AWS Crabbox; tbx_... means Blacksmith Testbox through Crabbox. If the output only says blacksmith testbox list, use blacksmith testbox list --all before concluding no box exists.
• If a warm direct-provider lease smells stale, retry with --full-resync (alias --fresh-sync) before replacing the lease. This resets the remote workdir, skips the fingerprint fast path, reseeds Git when possible, and uploads the checkout from scratch.
• For live/provider bugs, use the configured secret workflow before downgrading to mocks. Copy only the exact needed key into the remote process environment for that one command. Do not print it, do not sync it as a repo file, and do

…