Crabbox: Give Your Agent an On-Demand Box for Tests, Builds, and UI Checks

Install

npx skills add openclaw/crabbox --skill crabbox

Crabbox is best suited for letting a coding agent edit local code while handing tests, builds, or UI checks off to an on-demand remote machine. The most important prerequisite before getting started: you need to be able to install the CLI on your machine, and the local-container fast path additionally requires Docker or Podman to be installed and running.

Who It's For

For people who want an agent (or themselves) to run tests, builds, and UI checks on a cloud box, a local VM/container, or a machine they already have, while continuing to edit code locally.
Crabbox is a CLI that offers three kinds of boxes: cloud boxes, local VMs or containers, and your own existing machines.
The local-container fast path requires Docker or Podman installed and running on your machine; the SSH workflow requires local git, ssh, ssh-keygen, rsync, and curl. When these prerequisites aren't met, the official evidence doesn't describe any other available route.
Whether cloud boxes require an account, how they're billed, and which cloud platforms are supported are not stated in the evidence; check the official documentation yourself before use.

First Try in 3 Minutes

The recommended official main path is the local-container quick start, which requires no cloud account at any point:

Prerequisites: Docker or Podman installed and running on your machine, and the CLI installed separately (officially stated as "Install the CLI separately"; refer to the official README for the exact install commands).
Install the agent skill: run the official command in a supported agent:
```
npx skills add openclaw/crabbox --skill crabbox
```
The official team also publishes a crabbox-quickstart skill as an alternative.
Enter a Git repository you trust (the official guidance requires working in a trusted repository).
Have the agent (or run it yourself in a terminal) execute the official self-check command:
```
crabbox doctor --provider local-container
```
Success signal: doctor passes the local-container environment checks.
Then run a low-risk, read-only first task to verify the whole pipeline:
```
crabbox run --provider local-container -- uname -a
```
Success signal: Crabbox rents a disposable container box, streams the command output back to your terminal, then releases the box. This example only runs uname -a and doesn't modify your files.
The core workflow from then on is crabbox run -- <cmd>: it rents a box, syncs your working tree (including uncommitted changes), runs the command and streams output back to your terminal, returns the exit code, then releases the disposable box. Note: what gets synced is the entire working tree, including uncommitted changes—before running a real test command for the first time, make sure you understand what will be brought onto the box and executed there.

Use Cases

Case 1: Run the test suite in a clean box before committing. Scenario: you (or an agent) have finished editing code but don't want to pollute your local environment. Have the agent run crabbox run -- pnpm test (replace pnpm test with your project's own test command). Expected result: a disposable box is rented, your working tree along with uncommitted changes is synced over, test output streams back to your terminal in real time, you get a real exit code at the end, and the box is released.

Case 2: Verify the container box environment. Scenario: first-time setup, or you suspect something is wrong with the environment. Have the agent first run crabbox doctor --provider local-container for diagnostics, then run crabbox run --provider local-container -- uname -a to confirm the box can execute commands. Expected result: doctor reports whether the local-container environment is ready; run returns the box's system information, proving the full rent–sync–execute–release pipeline works. Both actions only perform checks and read system information—typical low-risk first-use steps.

Boundaries of Use

Side effects and confirmation points: every crabbox run rents a box and syncs your working tree (including uncommitted changes) to it, then executes the command you specify there—the command genuinely runs on the box, so confirm its contents before launching. The local-container path also starts containers on your machine; the boundaries of external services involved in cloud boxes are not stated in the evidence.
Runtime prerequisites: the local-container fast path needs Docker or Podman; the SSH workflow needs local git, ssh, ssh-keygen, rsync, and curl.
Client prerequisites: the skill is installed via npx skills add and works with agents that support agent skills; the evidence doesn't enumerate which specific clients are supported.
Key information not yet confirmed: how cloud boxes are provisioned and their account requirements, whether crabbox doctor or run accesses the network or which local files they read/write, and what subcommands exist beyond those shown in the documentation—the official evidence doesn't state any of these; consult the official README before use.