Use exe.dev VMs as Crabbox boxes

Before you start#

On your computer, ssh exe.dev whoami must print your account. VM creation needs an active plan. Crabbox also needs git, ssh, ssh-keygen, rsync and curl locally.

Install Crabbox#

On your computer, on macOS:

brew install openclaw/tap/crabbox

On Linux (x86-64; use linux_arm64 on ARM), unpack the release archive and keep its crabbox-runtime/ directory next to the crabbox binary:

curl -fsSLO https://github.com/openclaw/crabbox/releases/download/v0.80.0/crabbox_0.80.0_linux_amd64.tar.gz
mkdir -p ~/.local/share/crabbox
tar xzf crabbox_0.80.0_linux_amd64.tar.gz -C ~/.local/share/crabbox
export PATH="$HOME/.local/share/crabbox:$PATH"   # add this line to your shell profile too

Check it can reach exe.dev:

crabbox --version
crabbox doctor --provider exe-dev

The last line of doctor should say provider provider=exe-dev ... control_plane=ready inventory=ready.

Run your tests on a fresh VM#

In a Git repository you trust, on your computer:

crabbox run --provider exe-dev -- go test ./...

Replace go test ./... with your project's test command; use --shell 'npm ci && npm test' for more than one step. Crabbox creates a VM named crabbox-<slug>-<id> (2 vCPU, 4 GB memory and 10 GB disk unless you say otherwise), copies your files to /var/tmp/crabbox/ on it, runs the command, and deletes the VM. The output ends like this:

sync candidate: 3 files, 236 B dirty_delta=1 files, 94 B
...
ok  	example.com/demo	0.001s
command complete in 10.936s total=15.943s
...
lease cleanup stopped=true policy=auto lease=cbx_30798f1e4c67 slug=pearl-crayfish-ae053f03

dirty_delta is the uncommitted change that came along. Crabbox exits with the command's exit code, so scripts and agents can rely on it. When a run fails, it saves the output in a local failure bundle under .crabbox/captures/; add --keep-on-failure to keep the VM for a look.

The box starts from exe.dev's default image (Ubuntu 24.04 with Go, Python, uv, Docker and an old Node.js). Install whatever else your tests need in the command, or start from a prepared VM (below). Only CI and NODE_OPTIONS are forwarded from your environment; pass others with --allow-env NAME.

Keep a box warm while you iterate#

A one-shot run pays for a new VM and a cold build cache every time. Keep one instead:

crabbox warmup --provider exe-dev --slug dev-box
crabbox run --provider exe-dev --id dev-box -- go test ./...
# edit, then run again: only the changes are synced
crabbox connect --provider exe-dev --id dev-box   # a shell on the box

When you're done:

crabbox stop --provider exe-dev dev-box

Warning

Crabbox doesn't delete warm exe.dev boxes by itself: its idle timeout and crabbox cleanup don't apply to this provider. Check crabbox list --provider exe-dev and stop what you no longer need.

A warm box is a normal exe.dev VM, so the rest of exe.dev works on it. A dev server it runs on port 3000 is at https://crabbox-<slug>-<id>.exe.xyz:3000/ (the name is in Crabbox's leased ... server= line), private to you through the HTTPS proxy.

Make exe.dev the repository's default#

crabbox init --detect finds your test command and writes .crabbox.yaml, a job named detected, a GitHub Actions workflow for Crabbox's Actions hydration, and an agent skill. Add the provider to the top of .crabbox.yaml:

provider: exe-dev
exeDev:
  disk: 25GB      # optional; also cpus and memory

Then --provider can go:

crabbox job run detected
crabbox run -- go test ./...

Let your coding agent use it#

crabbox init --detect already wrote a skill to .agents/skills/crabbox/SKILL.md. To install Crabbox's published skill instead, for Claude Code, Codex and other agents (the skills tool needs Node.js 22.20 or later):

npx skills add openclaw/crabbox --skill crabbox

The skill tells the agent to warm a box early, run checks with crabbox run --id, and stop the box when it's finished. Each agent can keep its own box, so parallel agents don't fight over your laptop's CPU and ports. Herdr has a Crabbox plugin for the same lease controls.

Start from a prepared VM#

Install your toolchain and warm caches once on a VM of your own, then have Crabbox copy it with ssh exe.dev cp instead of starting from the default image. On your computer:

ssh exe.dev new --name=my-crabbox-base
ssh my-crabbox-base.exe.xyz   # install tools, warm caches, then exit

Then lease copies of it:

crabbox warmup --provider exe-dev --exe-dev-from my-crabbox-base --exe-dev-disk 25GB --slug test-copy
crabbox run --provider exe-dev --id test-copy -- go test ./...
crabbox stop --provider exe-dev test-copy

--exe-dev-disk must be at least the base's disk (25 GB for a new VM), or exe.dev answers --disk cannot be smaller than source. The copy gets the base's files, not its running processes, and the base is never changed. In our test, a copy of a box that had already built the project ran go test in 1.2 seconds, against 10 on a fresh VM. Only copy bases you trust: everything on their disk, credentials included, comes along.

Troubleshooting#

• Permission denied (publickey) or Please complete registration: ssh exe.dev whoami doesn't work yet. Fix that first; Crabbox uses the same SSH setup.
• Choose a plan to start creating VMs: pick a plan at exe.dev/billing/update.
• --class is not supported for provider=exe-dev: size VMs with --exe-dev-cpus, --exe-dev-memory and --exe-dev-disk.
• A box you didn't stop: crabbox list --provider exe-dev shows Crabbox's leases; ssh exe.dev ls shows every VM. Stop leases with crabbox stop --provider exe-dev <slug>. Crabbox only deletes VMs that carry its ownership tags and match its local claim.
• Anything else: crabbox doctor --provider exe-dev, and the provider's guide.