/crabbox-quickstart

name: crabbox-quickstart
description: "First contact with Crabbox: run your repository's tests inside a disposable Docker or Podman container on your own machine, no account and no cloud spend, then stop the box. Use when someone asks what Crabbox is or how to try it, wants a throwaway sandbox for a repo with no crabbox.yaml yet, or is about to run crabbox init here; hand off to the crabbox skill for config that already exists, leased remote machines, jobs, secrets, or artifacts."
license: MIT

Crabbox Quickstart

Crabbox runs your repository's commands on a disposable box — a container on your own machine, or a remote machine you lease. It syncs your working tree, runs one command, streams the output back, and exits with that command's code.

The loop

lease -> sync -> run -> read output -> stop

• **Lease** a box from a provider. `--provider local-container` uses Docker or

Podman on your own machine: no account, no login, no spend.

• **Sync** your current checkout onto it. Crabbox builds the file list from

Git, so the directory must be a repository.

• **Run** one command there. Its exit code becomes Crabbox's exit code.
• **Read** the streamed output, and optionally timing and test-result files.
• **Stop** the box. A one-shot `run` does this for you; a warm box does not.

Install and check

crabbox --version                  # already installed? skip the install
brew install openclaw/tap/crabbox  # or github.com/openclaw/crabbox/releases
crabbox doctor --provider local-container

`doctor` with a provider is the readiness check that matters: it names the container runtime, the leases you already hold, and the `image=` your commands will run inside.

First run, no account needed

With Docker or Podman running, this works in any Git repository with no config file, no login, and no cloud spend:

git init                                  # only if not already a repository
crabbox run --provider local-container -- uname -a

Crabbox provisioned a container, synced the dirty checkout, ran the command there, streamed its output, propagated its exit code, and deleted the lease. Budget 30-45 seconds once the base image is local, nearly all of it container startup; the very first run adds a one-time image pull.

The box is bare

Read this before swapping `uname -a` for real work. The default image is plain Ubuntu with `git`, `curl`, `tar`, `python3`, `rsync`, and passwordless `sudo`. No node, npm, make, gcc, go, cargo, or java. A command needing a runtime fails before your code does — usually exit 127 and `make: not found`, or for npm a preflight that stops the run first. Install what you need once, on a warm box:

crabbox warmup --provider local-container          # prints the <slug>
crabbox run --provider local-container --id <slug> -- \
  sudo apt-get install -y make

Commands after `--` are literal argv. For `&&`, pipes, or redirects, add `--shell` before `--` and pass the shell source as one quoted argument. Making the setup permanent is a `.crabbox.yaml` job — that is the `crabbox` skill, not this page.

Warm a box and reuse it

One-shot runs pay for container startup every time, and throw away whatever you installed. Keep one box and send several commands to it instead:

crabbox warmup --provider local-container
crabbox run --provider local-container --id <slug> -- ./run-tests.sh
crabbox status --provider local-container --id <slug>

`warmup` prints both a `cbx_...` lease id and a friendly slug; either works as `--id`. A cold run measured 33-45 seconds, the same run warm about 4 seconds. Above and below, `./run-tests.sh` stands for your own test command.

What actually gets synced

Your dirty working tree filtered by Git, not a committed ref, so untracked-but-not-ignored files do get uploaded — minus a built-in exclude list: `node_modules`, `dist`, `target`, `.venv`, `__pycache__`, and other dependency and build output. That never travels; rebuild it in the box. `crabbox sync-plan` prints the file count, total bytes, and the largest files and directories without starting a container. Exclude anything else surprising in `.crabboxignore`.

Errors you will meet first

Exit 2 is a missing `--provider`, 6 a directory that is not a Git repository, 7 a runtime Crabbox cannot reach, 4 an `--id` naming no live lease. Your own command's code passes through verbatim too, so the number alone never says which failed — read the message, then rerun the `doctor` command above.

When your command itself fails, Crabbox exits with its code, prints a failure digest with `next:` commands, and drops a bundle in `.crabbox/captures/`. Sync excludes it; add `.crabbox/` to `.gitignore`.

Environment and secrets

Nothing from your shell crosses into the box automatically; forwarding is an allowlist by name, set with `--allow-env` or `env.allow` in the repo config. Never put a token on a command line; the `crabbox` skill covers the rest.

Evidence from a run

Evidence flags attach to any `run` and cost no extra time:

crabbox run --provider local-container --results-auto -- ./run-tests.sh

If your command writes a JUnit XML report, `--results-auto` finds it without being told the path and summarizes it in one line:

test results files=1 tests=3 failures=1 errors=0 skipped=1

If nothing writes a JUnit file the flag is a silent no-op.

Stop what you started

Boxes from `warmup` outlive the command; so do runs given `--keep`. Stop them:

crabbox stop --provider local-container <slug>
crabbox list --provider local-container

An empty `list` means no leases remain on that provider. Local containers kept by `warmup` or `--keep` require explicit `stop`; they do not expire on their own.

When you outgrow this page

Stop here and load the full `crabbox` skill as soon as the task involves any of:

• a repository that already has `crabbox.yaml` or `.crabbox.yaml`, including

one `crabbox init --dete