Crabbox – On‑demand computers for coding agents

What it does

Crabbox is a command‑line tool that lets you lease a temporary computer, copy your current source tree (including uncommitted changes), run a command there, stream the output back, and then release the machine. It works with many back‑ends – local Docker/Podman containers, cloud VMs, macOS/Windows hosts, or any SSH‑accessible box – so agents or developers can run tests, builds, or UI checks without tying up their own laptop.

Why it matters for AI/ML workflows

• Parallel agents – Large language‑model agents that generate code can each get their own isolated box, avoiding contention on a single workstation.
• Fast edit‑test loop – Warm‑up boxes keep dependencies installed, so repeated runs are quicker – useful for iterative prompt‑to‑code cycles.
• Cross‑platform validation – Run the same test suite on Linux, macOS, Windows, or WSL2 from a single CLI, ensuring generated code works everywhere.
• Human‑in‑the‑loop UI – With VNC/WebVNC or a browser‑based VS Code instance you can watch a UI test or manually intervene, then let the agent continue.

Core concepts

Concept	Explanation
Provider	A plug‑in that knows how to start, stop, and communicate with a particular kind of machine (Docker, AWS, Azure, SSH host, etc.). Crabbox ships with 80+ built‑in providers and an external plugin interface.
Lease / Box	A short‑lived computer instance. You request a lease (crabbox run …), use it, and it is automatically released unless you keep it warm.
Warm‑up / Pre‑warm	Keep a lease alive across multiple runs, optionally hydrating it with GitHub Actions artifacts.
Sync	Before a run, Crabbox copies the repository (including uncommitted changes) into the box, respecting a configurable workspace‑sync rule that skips large build directories.
Coordinator (optional)	A central service that can store cloud credentials, enforce spend caps, and provide a web portal to view active leases, logs, and VNC sessions.
Desktop / Browser capabilities	Some providers expose a graphical desktop (VNC/WebVNC) or an installed browser, allowing UI tests or manual debugging.

Typical workflow (CLI snippets)

# 1️⃣ Lease a box, copy your repo, run the test suite, then release
crabbox run -- pnpm test

# 2️⃣ Keep a box warm for rapid iteration
crabbox warmup --slug dev-box
crabbox run --id dev-box -- npm test
crabbox connect --id dev-box   # open a shell
crabbox stop dev-box           # release when done

# 3️⃣ Run a UI test with a visible desktop
crabbox warmup --class tiny --desktop --browser --slug ui-box
crabbox webvnc --id ui-box --open --take-control
crabbox run --id ui-box -- "npm run e2e"
crabbox stop ui-box

Getting started

1. Install – binary distribution or cargo install crabbox (Rust‑based). Docker/Podman must be running for the local-container provider.
2. Choose a provider – e.g., local-container for quick local testing, or aws for a cloud macOS VM.
3. Run crabbox doctor – checks that the provider’s credentials and prerequisites are reachable.
4. Run your first command – crabbox run -- uname -a.

Provider ecosystem (high‑level)

• Brokerable clouds – AWS, Azure, GCP, Hetzner (coordinator can manage credentials).
• Direct clouds – DigitalOcean, Linode, VULTR, GitHub Codespaces, etc.
• Delegated sandboxes – Cloud‑run, Cloudflare, E2B, Modal, etc., for short‑lived container‑style execution.
• Local & self‑hosted – Docker, Podman, Multipass, Hyper‑V, Proxmox, Firecracker, etc.
• GPU‑enabled – Lambda, RunPod, Vast, WandB for ML workloads.
• Desktop‑capable – Providers that expose VNC or WebVNC (AWS, Azure, Parallels, etc.).

Who should use it?

• LLM‑based coding agents that need isolated, reproducible environments for each generated snippet.
• Developers who want to offload heavy test suites to the cloud while keeping a fast local edit loop.
• CI/CD pipelines that need a consistent, provider‑agnostic way to spin up a machine, run a job, and collect evidence.
• Teams that want a shared “broker” to enforce spend limits and give teammates visual access to running UI tests.

---

All information above is taken directly from the project's README; no external assumptions are added.