Crabbox Agent Skill

<picture> <source media="(max-width: 600px)" srcset="docs/assets/readme-hero-mobile.svg"> <img src="docs/assets/readme-hero.svg" alt="Crabbox — warm a box, sync the diff, run the suite." width="1200"> </picture>

On-demand computers for coding agents.

Crabbox gives agents and humans a computer to run tests, builds, and UI checks while they keep editing locally. Choose a cloud box, a local VM or container, or a machine you already own.

Quick start · Commands · Any OS · Desktop and browser · Providers · Install · Docs

With your provider and project dependencies configured:

crabbox run -- pnpm test

1. Lease a box and sync your working tree, including uncommitted changes.
2. Run pnpm test there and stream the output back to your terminal.
3. Return the command's exit code and release the one-shot box.

Why Crabbox?

• More agents, less contention. Give concurrent work separate cloud boxes instead of making every test suite compete for your laptop's CPU, RAM, and ports.
• A faster edit–test loop. Keep prepared boxes warm, reuse installed dependencies, and sync changes without committing or pushing first.
• Test across operating systems. Target Linux, macOS, native Windows, or WSL2 from the same CLI. Choose the provider and image for the job.
• See and drive the result. Open a desktop with VNC or WebVNC, run a browser, edit through browser VS Code, and inspect runs in the coordinator portal.
• Share capacity with a team. The optional coordinator keeps cloud credentials centrally, tracks usage, enforces spend caps, and expires stale leases.

Capabilities vary by provider. Crabbox supplies computers and execution evidence; your agent or harness decides what to run and what the result means.

Quick start

0. Install

On macOS or Linux with Homebrew:

brew install openclaw/tap/crabbox
crabbox --version

On Linux without Homebrew, extract a release archive and keep crabbox-runtime/ beside the crabbox executable (use arch=arm64 on ARM):

v=0.81.0 arch=amd64
curl -fLO "https://github.com/openclaw/crabbox/releases/download/v$v/crabbox_${v}_linux_${arch}.tar.gz"
curl -fLO "https://github.com/openclaw/crabbox/releases/download/v$v/checksums.txt"
sha256sum -c checksums.txt --ignore-missing
mkdir -p ~/.local/share/crabbox
tar -xzf "crabbox_${v}_linux_${arch}.tar.gz" -C ~/.local/share/crabbox
export PATH="$HOME/.local/share/crabbox:$PATH"
crabbox --version

GNU tar may warn about LIBARCHIVE.xattr.com.apple.provenance headers; they are harmless. See Install for Windows and other options.

1. Try a local box

Start Docker or Podman and make sure git, ssh, ssh-keygen, and rsync are on your PATH (Debian/Ubuntu: sudo apt-get install -y git openssh-client rsync). Then enter a Git repository you trust. No cloud account or coordinator login is needed:

crabbox doctor --provider local-container
crabbox run --provider local-container -- uname -a

You should see Linux kernel information, followed by cleanup of the one-shot container. First startup includes an image pull and bootstrap. On images with apt-get, missing sshd, git, rsync, curl, sudo, or python3 triggers installation of those tools and CA certificates, so the container needs internet access. For offline or locked-down engines, pass --local-container-image with an image that already has those tools. The box has Crabbox's sync/run prerequisites; supply your project's runtime and dependencies.

2. Run a project's tests

For a Node.js repository with a package-lock.json and an npm test script:

crabbox run --provider local-container \
  --local-container-image node:22-bookworm \
  --shell 'npm ci && npm test'

Choose an image compatible with your project. For remote boxes, use a prepared image, repository setup scripts, or Actions hydration. Dependency and build directories are excluded from normal workspace sync.

3. Reuse a box while you iterate

crabbox warmup --provider local-container --slug dev-box
crabbox run --provider local-container --id dev-box -- uname -a
# Edit locally, then run again with the same --id.
# Open a shell, or release the box when finished.
crabbox connect --provider local-container --id dev-box
crabbox stop --provider local-container dev-box

Replace uname -a with your test command once the box is prepared. warmup keeps a reusable lease; prewarm also performs Actions hydration. Use the printed cbx_... ID or friendly slug to select it. Each agent can keep its own lease and working directory.

Already have a team coordinator?

Use your team's URL in place of this example:

crabbox login --url https://broker.example.com
crabbox doctor
crabbox run -- pnpm test

The repository must select a provider and prepare its remote runtime and dependencies. For your own cloud account, follow a provider guide and skip coordinator login. Cloud capacity is billed by the provider; choose machine sizes deliberately.

Getting started · Local Container

Everyday commands

Command	What it does
crabbox doctor	Check prerequisites, configuration, and provider reachability.
crabbox providers --json	Discover providers, targets, and capabilities.
crabbox run -- <cmd>	Lease, sync, run, stream output, and release.
crabbox run --shell '<script>'	Run a multi-step shell command.
crabbox warmup / crabbox prewarm	Keep a box ready; prewarm also hydrates from Actions.
crabbox run --id <box> -- <cmd>	Sync changes and run on an existing box.
crabbox connect --id <box>	Open an interactive shell.
crabbox ssh --id <box>	Print the SSH command for your own tools.
crabbox job run <name>	Run a named workflow from repository configuration.
crabbox list / crabbox stop <box>	List active boxes or release one.

Use --script <file> for longer scripts. The execution and lease commands above (run, warmup, prewarm, connect, ssh, list, and stop) and doctor accept --provider <name> to override your configured provider. Named jobs select their provider in repository configuration. --provider is a command-specific flag, not a global flag. The providers catalog does not accept --provider; use crabbox providers describe aws to inspect one provider. See Commands and the CLI reference for details.

Any OS

Run platform-specific tests without moving your local checkout. These are execution targets, not just operating systems that can install the CLI:

Target	Providers
Linux	Cloud VMs, local containers, self-hosted VMs, and delegated sandboxes; see the complete list.
macOS	anthropic-sandbox-runtime, aws, external, lume, parallels, ssh, tart.
Native Windows	aws, azure, external, hyperv, mxc, parallels, ssh, ssh-host, windows-sandbox.
WSL2	aws, azure, external, parallels, ssh.

The catalog reports supported targets; you still need the provider's credentials, hosts, images, and guest setup. For example, macOS VMs need prepared Mac hosts or images, and AWS macOS uses Dedicated Hosts. WSL2 is a Linux execution environment inside Windows; desktop/VNC needs native Windows mode instead. The catalog also lists CUA for Linux, macOS, and Windows, but its Crabbox adapter currently supports inspection only.

crabbox providers --target macos
crabbox providers --target windows/normal
crabbox providers --target windows/wsl2

Select the OS with --target linux|macos|windows and Windows execution with --windows-mode normal|wsl2. See the provider matrix for the exact target and capability combinations.

Desktop, browser and portals

Keep a visible session when a test needs a browser, a desktop, or a human handoff. For a configured coordinator-backed Linux provider with these capabilities (such as AWS, Azure, or Hetzner):

crabbox warmup --class tiny --desktop --browser --code --slug ui-box
crabbox webvnc --id ui-box --open --take-control

Keep the WebVNC process running while viewing. From another terminal, you can open the browser editor or capture the desktop:

crabbox code --id ui-box --open
crabbox screenshot --id ui-box --output desktop.png
# Release the lease when finished.
crabbox stop ui-box

Surface	What you can do
Native VNC	crabbox vnc --id <box> --open tunnels to the desktop through SSH. Managed VNC stays on the runner's loopback interface.
WebVNC	View a desktop in the browser, observe a shared session, or take control. Coordinator sessions use an authenticated portal; direct providers can use a local viewer or a registered portal bridge.
Browser capability	Request --browser for an installed browser and BROWSER / CHROME_BIN environment variables. Add --desktop for a visible session. Browser login state is yours to manage.
Desktop automation	Launch apps, take screenshots, click, type, or record on supported targets. Input and recording support varies by OS and desktop environment.
Browser VS Code	crabbox code opens code-server on a Linux lease created with --code. It requires coordinator login, an isolated Code origin configured by the operator, and a running local bridge.
Coordinator portal	Open /portal on your coordinator to inspect leases, run history, logs, events, and live WebVNC/Code views. Share access and hand desktop control between authorized viewers.

Desktop support includes managed Linux, AWS/Azure native Windows, EC2 Mac, prepared Tart/Parallels Macs, compatible external adapters, and local containers; static SSH desktops are explicitly host-managed. Check the desktop support guide before choosing a target.

For kept desktop leases registered with a coordinator, Crabbox attempts to start the bridge automatically (broker.autoWebVNC defaults to true; set it to false to opt out). Registration adds portal access while the direct provider retains lifecycle ownership. Tailscale can supply the SSH network path; it does not expose VNC publicly. Provider url-bridge capabilities are separate app-preview routes, not desktop access; discover them with crabbox providers --feature url-bridge.

Providers

84 built-in providers plus the external plugin contract: 85 catalog entries. The groups below follow the compiled catalog and link to each provider's setup and limitations. Some adapters delegate execution; service-control adapters do not run arbitrary commands. SSH, desktops, snapshots, and cleanup are not uniform.

<!-- BEGIN README PROVIDER LIST -->

Brokerable clouds

Catalog category: brokerable-cloud. Run directly or let the coordinator own credentials, shared capacity, spend caps, and expiry.

Provider	Best fit
aws	Broad Linux, Windows, WSL2, and macOS cloud coverage.
azure	Linux or Windows workloads in Azure.
gcp	Linux compute with broad machine selection.
hetzner	Cost-effective high-CPU Linux VM.

Direct clouds and development boxes

Catalog category: direct-cloud. Daytona also supports coordinator-backed SSH.

Provider	Best fit
ascii-box	Managed Linux boxes over SSH through Boat (formerly ASCII Box).
boxd	Experimental Linux microVM leases; port 8000 is publicly proxied without authentication.
coder	Coder-backed Linux workspace over SSH proxy.
daytona	Managed development sandbox with direct toolbox execution or brokered SSH.
digitalocean	Simple direct Linux VM.
exe-dev	Fast managed Linux VM exposed over SSH.
github-codespaces	Repository-backed Linux devcontainer over SSH.
hostinger	Linux VPS subscriptions; releasing a lease does not cancel billing.
linode	Straightforward direct Linux VM.
machine0	Persistent Linux VMs with live CPU/GPU sizing; stopping still incurs compute cost.
morph	Managed Linux VMs over SSH; release pauses by default rather than deleting.
namespace-devbox	Fast managed development box over SSH.
namespace-instance	Short-lived managed Linux compute over SSH.
nebius	Direct Linux VM lease with optional GPU selection.
ovh	OVHcloud Public Cloud Linux VM.
phala	Confidential Linux compute over SSH with TDX attestation enabled by default.
scaleway	Direct Linux VM on Scaleway Instances.
sealos-devbox	Sealos DevBox Linux workspace over SSHGate or NodePort.
sprites	Fast Linux microVM over provider SSH proxy.
tencentcloud	Linux SSH leases on Tencent Cloud CVM.
tenki	Managed Linux sandboxes through Tenki's SSH gateway and certificates.
vultr	Direct Linux VM on Vultr.

Delegated sandboxes

Catalog category: delegated-sandbox.

Provider	Best fit
agent-sandbox	Delegated Linux execution from a Kubernetes Agent Sandbox warm pool.
aws-lambda-microvm	Stateful ARM64 execution with a compatible Crabbox runner image.
azure-dynamic-sessions	Short delegated container sessions in Azure.
azure-sandbox	Kept Linux shell workloads in Azure Container Apps Sandbox groups with explicit file uploads.
blaxel	Managed delegated Linux sandbox execution.
cloud-run-sandbox	Delegated Cloud Run execution through a sandbox launcher or gateway.
cloudflare	Fast delegated Linux container execution.
cloudflare-dynamic-workers	Hosted Worker modules; no shell or filesystem sync.
cloudflare-sandbox	Cloudflare Sandbox Linux command execution through a bridge.
codesandbox	Managed Linux development environments through a local Node SDK bridge.
crownest	Hosted Workspace Runs with archive sync and durable evidence; no downloads yet.
cubesandbox	Self-hosted E2B-compatible MicroVM command execution.
e2b	Hosted ephemeral code sandbox.
freestyle	Hosted delegated Linux VM execution.
islo	Hosted execution with keep/pause and a provider-owned SSH helper.
modal	Hosted Python or GPU-oriented delegated workloads.
nomad	Self-hosted delegated Linux execution on an existing Nomad cluster.
opencomputer	Hosted delegated Linux VM execution.
opensandbox	Hosted delegated sandbox through an open SDK.
orgo	Linux computer execution through HTTP; no Crabbox workspace sync.
smolvm	Lightweight hosted microVM execution.
superserve	Hosted delegated Linux sandbox.
tensorlake	Hosted Firecracker-backed delegated execution.
upstash-box	Hosted short-lived delegated sandbox.
vercel-sandbox	Hosted delegated Linux microVM execution.
warpbuild	Standalone macOS sandboxes through the WarpBuild CLI.

Local virtual machines

Catalog category: local-vm.

Provider	Best fit
apple-machine	Local delegated Linux machine execution.
apple-vm	Headless Linux ARM64 VM on Apple silicon.
hyperv	Native Windows VMs on a Windows host with Hyper-V.
lume	Layered macOS development VMs from a prepared Apple silicon base.
multipass	Portable local Ubuntu VM.
parallels	macOS, Linux, or Windows VM clones and snapshots from prepared sources.
tart	macOS VM testing on Apple silicon with prepared Tart images.

Self-hosted virtualization

Catalog category: self-hosted-virtualization.

Provider	Best fit
firecracker	Linux microVMs on your own KVM host with prepared guest and network assets.
incus	Self-hosted Linux containers or VMs.
kubevirt	Kubernetes-hosted Linux VM.
proxmox	Self-hosted Linux VM fleet.
serve	Owner-only donated container capacity through a coordinator.
xcp-ng	Self-hosted Linux VM pool over XAPI.

GPU clouds

Catalog category: gpu-cloud.

Provider	Best fit
lambda	Direct GPU-backed Linux workload over SSH.
nvidia-brev	Managed NVIDIA GPU workspace over SSH.
runpod	GPU-backed Linux workload over public SSH.
vast	Direct Linux GPU lease from the Vast.ai offer market.
wandb	Delegated ML or GPU run environment.

Local sandboxes

Catalog category: local-sandbox.

Provider	Best fit
anthropic-sandbox-runtime	Policy-constrained commands on the current Linux or macOS host; no remote lease.
docker-sandbox	Local delegated sessions through the standalone sbx CLI.
mxc	Local isolated Windows command execution.
windows-sandbox	Disposable native Windows commands using Windows Sandbox on a Windows host.

Local container runtimes

Catalog category: local-runtime.

Provider	Best fit
apple-container	Local Linux containers on Apple silicon.
local-container	Local Linux tests through Docker or Podman; no cloud account needed.

CI proof runners

Catalog category: ci-proof-runner.

Provider	Best fit
blacksmith-testbox	CI reproduction with proof and reusable sessions.
semaphore	SSH debugging with the same image and secrets available to the CI job.

Bring your own SSH host

Catalog category: byo-ssh.

Provider	Best fit
ssh-host	Coordinator-managed exclusive hosts with outbound SSH relay and confirmed cleanup.
ssh	Your existing Linux, macOS, or Windows host; Crabbox never deletes the machine.

Service control

Catalog category: service-control.

Provider	Best fit
cua	Experimental read-only diagnostics and existing-sandbox inspection.
fastapi-cloud	Inspect FastAPI Cloud deployment readiness; no arbitrary commands or app stops.
railway	Inspecting or stopping an existing Railway service.
unikraft-cloud	Running a prebuilt OCI image as a cloud microVM service.

External plugins

Catalog category: external-provider.

Provider	Best fit
external	Your own provider through an executable contract; the adapter owns its safety and lifecycle semantics.

<!-- END README PROVIDER LIST -->

Machine classes

Managed providers with class-based capacity default to beast. Start with a smaller --class, such as tiny, when evaluating cloud capacity. --class selects a tier; --type pins a provider-native size and disables class fallback. See Configuration and your provider's guide.

How it works

Local checkout → Lease a box → Sync changes → Run → Stream output + exit code
                                   ↑                         |
                                   └── Reuse a warm box ──────┘
                                             or release it

The CLI sends your working tree, including nonignored uncommitted files. SSH providers use direct CLI-to-runner connections; delegated providers own their execution transport. One-shot runs release their leases; warmup and runs with --id support reuse. Explicitly stop retained boxes when finished.

The optional coordinator manages shared leases, credentials, budgets, expiry, and history. Provider adapters own provisioning and cleanup. Existing SSH hosts remain yours: Crabbox neither provisions nor deletes them.

Coordinator deployment choices

Use providers directly, deploy the coordinator on Cloudflare Workers with a Durable Object, or self-host it on Node.js with PostgreSQL. State does not migrate automatically between runtimes. Follow the deployment and proof requirements in Infrastructure.

How Crabbox works · Architecture · Vision

When a run fails

Situation	Next step
The box is unreachable	Run crabbox doctor --provider <name>.
You need to inspect the failure	Add --keep-on-failure, then use crabbox connect --id <box>.
You need a fresh workspace sync	Add --full-resync to reset the remote workdir before syncing.
You need the command's output files	Use --download remote=local, repeatable for several files.
Output needs to go straight to a file	Use --capture-stdout <path> and --capture-stderr <path>.
A local container exits before SSH is ready	Re-run with --keep and read docker logs <container> (or podman logs <container>). If the apt-get bootstrap failed, restore container network access or use --local-container-image with the tools preinstalled. Follow the printed cleanup command when finished.
A local container has no published SSH port	Check the selected container network: Crabbox needs a published SSH port, which host networking does not provide. Use the default bridge or create a bridge network and pass --local-container-network <name> (or set localContainer.network).

Failed SSH-backed and Blacksmith delegated runs save local failure bundles by default. Follow the printed failure-bundle local=… path and review the contents before sharing. See Troubleshooting and Observability.

Highlights

Named jobs keep repeatable setup and test commands in the repository. Checkpoints save, restore, or fork workspace state. Failure capsules replay failing CI runs. Artifacts, test results, and telemetry make runs inspectable. Pond peer groups connect related leases for multi-machine tests.

Configuration

crabbox init --detect
crabbox config show

Review the generated configuration and setup before running it. Settings resolve from flags, environment, repository configuration, user configuration, then defaults. User configuration defaults to ~/.config/crabbox/config.yaml on Linux, ~/Library/Application Support/crabbox/config.yaml on macOS, and %AppData%\crabbox\config.yaml on Windows. Linux also honors XDG_CONFIG_HOME. A nonempty CRABBOX_CONFIG selects only that file, skipping both user and repository config files; environment variables and flags still apply. A repository's .crabbox.yaml can select its provider and image:

provider: local-container
localContainer:
  image: node:22-bookworm
lease:
  idleTimeout: 30m

Your shell environment is not forwarded wholesale. Only CI and NODE_OPTIONS are allowed by default; configure env.allow or pass --allow-env NAME for additional variables. Keep provider credentials outside the repository and out of command-line arguments.

Configuration · Environment forwarding · Sync

Integrations

crabbox init --detect also generates a repository-local Agent Skill for compatible coding agents. To install the published skills separately:

npx skills add openclaw/crabbox --skill crabbox
npx skills add openclaw/crabbox --skill crabbox-quickstart

Use crabbox-quickstart for the first Docker/Podman run and crabbox for remote execution and repository workflows. Install the CLI separately. Zed and Herdr integrations add editor and lease controls. See the agent guide and integration catalog.

Who Crabbox is for

Coding agents running tests in parallel, maintainers with expensive builds, contributors testing another OS, and teams sharing remote capacity. Use Crabbox alongside CI for an interactive edit–run loop and reviewable execution evidence.

Trust model

Run trusted repositories. Crabbox trusts the local OS user, repository configuration, project tooling, and authenticated coordinator operators. Configuration can execute helpers, mount host resources, and control infrastructure; container socket passthrough grants access to the host engine.

The coordinator holds cloud credentials for brokered leases. Reuse and destructive operations require verified ownership bound to the exact provider, resource, and claim; names or labels alone are not proof. Ownership and inventory failures must fail closed. See Vision for the lifecycle contract.

Coordinator access controls serve cooperative teams, not mutually hostile tenants. Captured output, artifacts, and failure bundles are not scrubbed of secrets; review them before sharing. Read the Security Policy and Operational security.

Install

Homebrew (macOS or Linux) installs the complete release distribution:

brew install openclaw/tap/crabbox
crabbox --version

For macOS, Linux, and Windows, you can also download a release archive. See the Windows installation guide for Windows setup. SSH workflows need git, ssh, ssh-keygen, rsync, and curl locally; the local-container quick start also needs Docker or Podman.

<details> <summary>Runtime packs and CLI-only Go installs</summary>

Keep a release's crabbox-runtime/ directory beside its real CLI executable. Filesystem-capable packs contain amd64 and arm64 companions for Linux, macOS, and Windows; Linux companions also provide native managed execution for Linux and WSL2. Do not mix builds or copy only the CLI. Reinstall the matching archive or Homebrew package if an official release's pack is missing or incomplete; release installations do not compile replacement companions from source.

For a CLI-only source install, pin a supported release (v0.44.0 or later):

GOTOOLCHAIN=go1.27.3 go install github.com/openclaw/crabbox/cmd/crabbox@v0.81.0

The module minimum remains Go 1.26. Use the explicit patched toolchain above for source installs: versioned go install ignores the target module's toolchain suggestion. Avoid @latest while older, incompatible release tags remain visible.

go install omits companion executables and assets, including the Apple VM helper and native runtime pack. It is not the signed/notarized release distribution. Source-built CLIs retain the shell-backed supervisor route and can compile the dependency-free filesystem helper with a local Go 1.26+ compiler; that does not build the managed-command supervisor. Use Homebrew or a complete release archive for full platform capabilities, especially Apple VM support.

</details>

Docs

Documentation site · Documentation index · Changelog

I want to…	Start here
Set up a repository	Getting started · Configuration
Look up a command or feature	Commands · Features · CLI
Understand the design	Concepts · Architecture · Source map
Operate shared infrastructure	Infrastructure · Operations · Observability
Debug a run	Troubleshooting · History and logs · Performance
Extend Crabbox	Provider authoring · External provider · Repository guidelines

Development

Read Repository guidelines and the Source map. Use the Go toolchain in go.mod and the Node version in .node-version.

go build -trimpath -o bin/crabbox ./cmd/crabbox
go vet ./...
go test -race -timeout=20m ./...

npm ci --prefix worker
npm run format:check --prefix worker
npm run lint --prefix worker
npm run check --prefix worker
npm run check:node --prefix worker
npm test --prefix worker
npm run build --prefix worker
npm run build:node --prefix worker

scripts/check-docs.sh

CI also checks Go modules, coverage, repository scripts, generated files, and release snapshots; .github/workflows/ci.yml defines the full gate. See Documentation authoring for site conventions, Infrastructure for deployments, and Release engineering for the release process.

<details> <summary>Release authorization and safety</summary>

One explicit full release/publish request authorizes the normal preparation, tagging, build/signing, private draft/upload, native proof, publication, Homebrew update, independent installation smokes, and closeout without renewed chat approval at each stage. Narrow requests stay narrow. The original request supplies authorization; GitHub events alone do not. Sequential technical gates, separate trust domains, and cancellation boundaries remain mandatory. Follow Release engineering for the exact sequence.

</details>

License

MIT.