---
title: "Use exe.dev VMs as Crabbox boxes"
description: "Crabbox's built-in exe-dev provider leases an exe.dev VM, syncs your uncommitted checkout, runs your tests there and deletes the VM. Set up in minutes."
url: https://exe.dev/deploy/crabbox
category: "Developer tools"
updated: 2026-10-31
---

# Use exe.dev VMs as Crabbox boxes

Remote test boxes for you and your coding agents, on your exe.dev account.

- **Software:** Crabbox (https://crabbox.sh)
- **Source:** https://github.com/openclaw/crabbox
- **License:** MIT
- **Machine-readable:** https://exe.dev/deploy/crabbox/manifest.json

[Crabbox](https://github.com/openclaw/crabbox), from the OpenClaw project,
gives you and your coding agents a remote computer for tests: it leases a
box, syncs your working tree with uncommitted changes, runs the command,
streams the output back, and returns its exit code. It ships an `exe-dev`
provider, so each box is an ordinary exe.dev VM on your own account, created
and deleted over the same `ssh exe.dev` you already use. No API key, no
Crabbox account.

The VMs are real ones with their own kernel, Docker and `sudo`, which suits
builds and integration tests that need more than a container. In our test, a
one-shot `crabbox run` took about 20 seconds from start to deleted VM, and a
warm box answered a rerun in about 7.

## 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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```text
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](#start-from-a-prepared-vm)).
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:

```bash
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:

```bash
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](/docs/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`:

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

Then `--provider` can go:

```bash
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):

```bash
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](/deploy/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:

```bash
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:

```bash
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](https://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](https://github.com/openclaw/crabbox/blob/main/docs/providers/exe-dev.md).

## Frequently asked questions

### How does Crabbox log in to exe.dev?

With your SSH key. Crabbox runs `ssh exe.dev whoami`, `ls`, `new` and `rm` (and `cp` and `tag` for copies), then reaches each VM at the `ssh_dest` exe.dev reports. There is no API token to create, and no Crabbox account or coordinator: the exe-dev provider doesn't use one.

### What does it cost?

Crabbox is free and MIT-licensed. Its boxes are ordinary exe.dev VMs, so they share your plan's CPU and memory and count toward its VM limit while they exist; disk beyond your allowance is billed as [usage](/docs/billing/usage). One-shot runs delete their VM; warm boxes stay until you `crabbox stop` them. See [pricing](https://exe.dev/pricing).

### Is a Crabbox box a sandbox for untrusted code?

Each box is its own VM, but Crabbox itself is built for trusted repositories: its README says repository configuration can run helpers and control infrastructure, and that its access controls serve cooperative teams, not mutually hostile tenants. Captured output and failure bundles aren't scrubbed of secrets, so review them before sharing.

### Can I run Crabbox from an exe.dev VM, for an agent that lives there?

Yes, if that VM has an SSH key on your exe.dev account (`ssh-key add`). Such a key can manage all your VMs, so only put one on a VM you trust. A key scoped with `--tag` doesn't work: Crabbox tags each VM it creates with its own ownership tags, and exe.dev refuses any tag but the key's.

### Can it test macOS or Windows, or open a desktop?

Not on exe.dev: the provider runs Linux only, and rejects `--tailscale`, `--class` and `--type` (size VMs with `--exe-dev-cpus`, `--exe-dev-memory` and `--exe-dev-disk`). It offers SSH, sync and archive checkpoints, not Crabbox's managed VNC desktop, browser or code-server. Crabbox's other providers cover those.

### How is this different from exe.dev's TypeScript SDK?

The [SDK](/deploy/typescript-sandboxes) is for your own code that creates and drives VMs. Crabbox is a ready-made tool for one job: take the checkout on your computer, run a command on a clean VM, and bring back the output and exit code.


## Related

- [Run Herdr agents on a remote machine](https://exe.dev/deploy/herdr.md): An always-on SSH machine for Herdr, with agents ready and no API keys.
- [Create sandboxes from TypeScript](https://exe.dev/deploy/typescript-sandboxes.md): Full VMs as sandboxes. Create, control, and destroy them from your code.
- [Run Claude Code on a remote server](https://exe.dev/deploy/claude-code.md): A computer for Claude. A breather for your laptop.
- [Run Codex on a remote server](https://exe.dev/deploy/codex.md): A computer for Codex. An early night for your laptop.
- [Running a self-hosted GitHub Actions Runner](https://exe.dev/deploy/github-actions-runner.md): Log in easily into your CI environment
- [VS Code in your browser, with code-server](https://exe.dev/deploy/code-server.md): Your editor in a tab. Your projects right where you left them.