Skip to content
Back to search

crabbox

Crabbox: warm a box, sync the diff, run the suite.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/openclaw/crabbox with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/openclaw/crabbox'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/openclaw--crabbox/badge.svg)](/listings/openclaw--crabbox)

HTML

<a href="/listings/openclaw--crabbox"><img src="/api/listings/openclaw--crabbox/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Try a local box

[Install Crabbox](#install), start Docker or Podman, and 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. The default 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](docs/features/actions-hydration.md). Dependency and build directories are excluded from normal [workspace sync](docs/features/sync.md).

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](#providers) and skip coordinator login. Cloud capacity is billed by the provider; choose [machine sizes](#machine-classes) deliberately.

[Getting started](docs/getting-started.md) · [Local Container](docs/providers/local-container.md)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 650 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <picture>
  2. <source media="(max-width: 600px)" srcset="docs/assets/readme-hero-mobile.svg">
  3. <img src="docs/assets/readme-hero.svg" alt="Crabbox — warm a box, sync the diff, run the suite." width="1200">
  4. </picture>
  5. # On-demand computers for coding agents.
  6. Crabbox gives agents and humans a computer to run tests, builds, and UI checks
  7. while they keep editing locally. Choose a cloud box, a local VM or container,
  8. or a machine you already own.
  9. [![CI](https://github.com/openclaw/crabbox/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/openclaw/crabbox/actions/workflows/ci.yml)
  10. [![Release verification](https://github.com/openclaw/crabbox/actions/workflows/release-assets.yml/badge.svg)](https://github.com/openclaw/crabbox/actions/workflows/release-assets.yml)
  11. [![Latest release](https://badgen.net/github/release/openclaw/crabbox/stable)](https://github.com/openclaw/crabbox/releases/latest)
  12. [![MIT license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
  13. **[Quick start](#quick-start)** · [Commands](#everyday-commands) · [Any OS](#any-os) ·
  14. [Desktop and browser](#desktop-browser-and-portals) · [Providers](#providers) ·
  15. [Install](#install) · [Docs](https://crabbox.sh/)
  16. With your provider and project dependencies configured:
  17. ```sh
  18. crabbox run -- pnpm test
  19. ```
  20. 1. Lease a box and sync your working tree, including uncommitted changes.
  21. 2. Run `pnpm test` there and stream the output back to your terminal.
  22. 3. Return the command's exit code and release the one-shot box.
  23. ## Why Crabbox?
  24. - **More agents, less contention.** Give concurrent work separate cloud boxes
  25. instead of making every test suite compete for your laptop's CPU, RAM, and ports.
  26. - **A faster edit–test loop.** Keep prepared boxes warm, reuse installed
  27. dependencies, and sync changes without committing or pushing first.
  28. - **Test across operating systems.** Target Linux, macOS, native Windows, or
  29. WSL2 from the same CLI. Choose the provider and image for the job.
  30. - **See and drive the result.** Open a desktop with VNC or WebVNC, run a browser,
  31. edit through browser VS Code, and inspect runs in the coordinator portal.
  32. - **Share capacity with a team.** The optional coordinator keeps cloud credentials
  33. centrally, tracks usage, enforces spend caps, and expires stale leases.
  34. Capabilities vary by provider. Crabbox supplies computers and execution evidence;
  35. your agent or harness decides what to run and what the result means.
  36. ## Quick start
  37. ### 0. Install
  38. On macOS or Linux with Homebrew:
  39. ```sh
  40. brew install openclaw/tap/crabbox
  41. crabbox --version
  42. ```
  43. On Linux without Homebrew, extract a release archive and keep `crabbox-runtime/`
  44. beside the `crabbox` executable (use `arch=arm64` on ARM):
  45. ```sh
  46. v=0.81.0 arch=amd64
  47. curl -fLO "https://github.com/openclaw/crabbox/releases/download/v$v/crabbox_${v}_linux_${arch}.tar.gz"
  48. curl -fLO "https://github.com/openclaw/crabbox/releases/download/v$v/checksums.txt"
  49. sha256sum -c checksums.txt --ignore-missing
  50. mkdir -p ~/.local/share/crabbox
  51. tar -xzf "crabbox_${v}_linux_${arch}.tar.gz" -C ~/.local/share/crabbox
  52. export PATH="$HOME/.local/share/crabbox:$PATH"
  53. crabbox --version
  54. ```
  55. GNU tar may warn about `LIBARCHIVE.xattr.com.apple.provenance` headers; they are
  56. harmless. See [Install](#install) for Windows and other options.
  57. ### 1. Try a local box
  58. Start Docker or Podman and make sure `git`, `ssh`, `ssh-keygen`, and `rsync` are
  59. on your `PATH` (Debian/Ubuntu: `sudo apt-get install -y git openssh-client rsync`).
  60. Then enter a **Git repository you trust**. No cloud account or coordinator login
  61. is needed:
  62. ```sh
  63. crabbox doctor --provider local-container
  64. crabbox run --provider local-container -- uname -a
  65. ```
  66. You should see Linux kernel information, followed by cleanup of the one-shot
  67. container. First startup includes an image pull and bootstrap. On images with
  68. `apt-get`, missing `sshd`, `git`, `rsync`, `curl`, `sudo`, or `python3` triggers
  69. installation of those tools and CA certificates, so the container needs internet access.
  70. For offline or locked-down engines, pass `--local-container-image` with an image
  71. that already has those tools. The box has Crabbox's sync/run prerequisites;
  72. supply your project's runtime and dependencies.
  73. ### 2. Run a project's tests
  74. For a Node.js repository with a `package-lock.json` and an `npm test` script:
  75. ```sh
  76. crabbox run --provider local-container \
  77. --local-container-image node:22-bookworm \
  78. --shell 'npm ci && npm test'
  79. ```
  80. Choose an image compatible with your project. For remote boxes, use a prepared
  81. image, repository setup scripts, or [Actions hydration](docs/features/actions-hydration.md).
  82. Dependency and build directories are excluded from normal [workspace sync](docs/features/sync.md).
  83. ### 3. Reuse a box while you iterate
  84. ```sh
  85. crabbox warmup --provider local-container --slug dev-box
  86. crabbox run --provider local-container --id dev-box -- uname -a
  87. # Edit locally, then run again with the same --id.
  88. # Open a shell, or release the box when finished.
  89. crabbox connect --provider local-container --id dev-box
  90. crabbox stop --provider local-container dev-box
  91. ```
  92. Replace `uname -a` with your test command once the box is prepared. `warmup`
  93. keeps a reusable lease; `prewarm` also performs Actions hydration. Use the
  94. printed `cbx_...` ID or friendly slug to select it. Each agent can keep its own
  95. lease and working directory.
  96. ### Already have a team coordinator?
  97. Use your team's URL in place of this example:
  98. ```sh
  99. crabbox login --url https://broker.example.com
  100. crabbox doctor
  101. crabbox run -- pnpm test
  102. ```
  103. The repository must select a provider and prepare its remote runtime and
  104. dependencies. For your own cloud account, follow a [provider guide](#providers)
  105. and skip coordinator login. Cloud capacity is billed by the provider; choose
  106. [machine sizes](#machine-classes) deliberately.
  107. [Getting started](docs/getting-started.md) · [Local Container](docs/providers/local-container.md)
  108. ## Everyday commands
  109. | Command | What it does |
  110. | --- | --- |
  111. | `crabbox doctor` | Check prerequisites, configuration, and provider reachability. |
  112. | `crabbox providers --json` | Discover providers, targets, and capabilities. |
  113. | `crabbox run -- <cmd>` | Lease, sync, run, stream output, and release. |
  114. | `crabbox run --shell '<script>'` | Run a multi-step shell command. |
  115. | `crabbox warmup` / `crabbox prewarm` | Keep a box ready; `prewarm` also hydrates from Actions. |
  116. | `crabbox run --id <box> -- <cmd>` | Sync changes and run on an existing box. |
  117. | `crabbox connect --id <box>` | Open an interactive shell. |
  118. | `crabbox ssh --id <box>` | Print the SSH command for your own tools. |
  119. | `crabbox job run <name>` | Run a named workflow from repository configuration. |
  120. | `crabbox list` / `crabbox stop <box>` | List active boxes or release one. |
  121. Use `--script <file>` for longer scripts. The execution and lease commands above
  122. (`run`, `warmup`, `prewarm`, `connect`, `ssh`, `list`, and `stop`) and
  123. `doctor` accept `--provider <name>` to override your configured provider.
  124. Named jobs select their provider in repository configuration. `--provider`
  125. is a command-specific flag, not a global flag. The `providers` catalog
  126. does not accept `--provider`; use `crabbox providers describe aws` to inspect
  127. one provider. See [Commands](docs/commands/README.md) and the
  128. [CLI reference](docs/cli.md) for details.
  129. ## Any OS
  130. Run platform-specific tests without moving your local checkout. These are
  131. execution targets, not just operating systems that can install the CLI:
  132. | Target | Providers |
  133. | --- | --- |
  134. | Linux | Cloud VMs, local containers, self-hosted VMs, and delegated sandboxes; see the [complete list](#providers). |
  135. | macOS | [anthropic-sandbox-runtime](docs/providers/anthropic-sandbox-runtime.md), [aws](docs/providers/aws.md), [external](docs/providers/external.md), [lume](docs/providers/lume.md), [parallels](docs/providers/parallels.md), [ssh](docs/providers/ssh.md), [tart](docs/providers/tart.md). |
  136. | Native Windows | [aws](docs/providers/aws.md), [azure](docs/providers/azure.md), [external](docs/providers/external.md), [hyperv](docs/providers/hyperv.md), [mxc](docs/providers/mxc.md), [parallels](docs/providers/parallels.md), [ssh](docs/providers/ssh.md), [ssh-host](docs/providers/ssh-host.md), [windows-sandbox](docs/providers/windows-sandbox.md). |
  137. | WSL2 | [aws](docs/providers/aws.md), [azure](docs/providers/azure.md), [external](docs/providers/external.md), [parallels](docs/providers/parallels.md), [ssh](docs/providers/ssh.md). |
  138. The catalog reports supported targets; you still need the provider's credentials,
  139. hosts, images, and guest setup. For example, macOS VMs need prepared Mac hosts or
  140. images, and AWS macOS uses Dedicated Hosts. WSL2 is a Linux execution environment
  141. inside Windows; desktop/VNC needs native Windows mode instead.
  142. The catalog also lists [CUA](docs/providers/cua.md) for Linux, macOS, and Windows,
  143. but its Crabbox adapter currently supports inspection only.
  144. ```sh
  145. crabbox providers --target macos
  146. crabbox providers --target windows/normal
  147. crabbox providers --target windows/wsl2
  148. ```
  149. Select the OS with `--target linux|macos|windows` and Windows execution with
  150. `--windows-mode normal|wsl2`. See the [provider matrix](docs/providers/README.md)
  151. for the exact target and capability combinations.
  152. ## Desktop, browser and portals
  153. Keep a visible session when a test needs a browser, a desktop, or a human handoff.
  154. For a configured coordinator-backed Linux provider with these capabilities
  155. (such as AWS, Azure, or Hetzner):
  156. ```sh
  157. crabbox warmup --class tiny --desktop --browser --code --slug ui-box
  158. crabbox webvnc --id ui-box --open --take-control
  159. ```
  160. Keep the WebVNC process running while viewing. From another terminal, you can
  161. open the browser editor or capture the desktop:
  162. ```sh
  163. crabbox code --id ui-box --open
  164. crabbox screenshot --id ui-box --output desktop.png
  165. # Release the lease when finished.
  166. crabbox stop ui-box
  167. ```
  168. | Surface | What you can do |
  169. | --- | --- |
  170. | [Native VNC](docs/commands/vnc.md) | `crabbox vnc --id <box> --open` tunnels to the desktop through SSH. Managed VNC stays on the runner's loopback interface. |
  171. | [WebVNC](docs/commands/webvnc.md) | 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. |
  172. | [Browser capability](docs/features/capabilities.md#browser) | 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. |
  173. | [Desktop automation](docs/commands/desktop.md) | Launch apps, take screenshots, click, type, or record on supported targets. Input and recording support varies by OS and desktop environment. |
  174. | [Browser VS Code](docs/commands/code.md) | `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. |
  175. | [Coordinator portal](docs/features/portal.md) | 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. |
  176. Desktop support includes managed Linux, AWS/Azure native Windows, EC2 Mac,
  177. prepared Tart/Parallels Macs, compatible `external` adapters, and local containers;
  178. static SSH desktops are explicitly host-managed. Check the
  179. [desktop support guide](docs/features/interactive-desktop-vnc.md) before choosing a target.
  180. For kept desktop leases registered with a coordinator, Crabbox attempts to start the bridge automatically
  181. (`broker.autoWebVNC` defaults to `true`; set it to `false` to opt out).
  182. Registration adds portal access while the direct provider retains lifecycle
  183. ownership. [Tailscale](docs/features/tailscale.md)
  184. can supply the SSH network path; it does not expose VNC publicly.
  185. Provider `url-bridge` capabilities are separate app-preview routes, not desktop
  186. access; discover them with `crabbox providers --feature url-bridge`.
  187. ## Providers
  188. **84 built-in providers plus the `external` plugin contract: 85 catalog entries.**
  189. The groups below follow the compiled catalog and link to each provider's setup
  190. and limitations. Some adapters delegate execution; service-control adapters do
  191. not run arbitrary commands. SSH, desktops, snapshots, and cleanup are not uniform.
  192. <!-- BEGIN README PROVIDER LIST -->
  193. ### Brokerable clouds
  194. Catalog category: `brokerable-cloud`. Run directly or let the coordinator own
  195. credentials, shared capacity, spend caps, and expiry.
  196. | Provider | Best fit |
  197. | --- | --- |
  198. | [aws](docs/providers/aws.md) | Broad Linux, Windows, WSL2, and macOS cloud coverage. |
  199. | [azure](docs/providers/azure.md) | Linux or Windows workloads in Azure. |
  200. | [gcp](docs/providers/gcp.md) | Linux compute with broad machine selection. |
  201. | [hetzner](docs/providers/hetzner.md) | Cost-effective high-CPU Linux VM. |
  202. ### Direct clouds and development boxes
  203. Catalog category: `direct-cloud`. Daytona also supports coordinator-backed SSH.
  204. | Provider | Best fit |
  205. | --- | --- |
  206. | [ascii-box](docs/providers/ascii-box.md) | Managed Linux boxes over SSH through Boat (formerly ASCII Box). |
  207. | [boxd](docs/providers/boxd.md) | Experimental Linux microVM leases; port 8000 is publicly proxied without authentication. |
  208. | [coder](docs/providers/coder.md) | Coder-backed Linux workspace over SSH proxy. |
  209. | [daytona](docs/providers/daytona.md) | Managed development sandbox with direct toolbox execution or brokered SSH. |
  210. | [digitalocean](docs/providers/digitalocean.md) | Simple direct Linux VM. |
  211. | [exe-dev](docs/providers/exe-dev.md) | Fast managed Linux VM exposed over SSH. |
  212. | [github-codespaces](docs/providers/github-codespaces.md) | Repository-backed Linux devcontainer over SSH. |
  213. | [hostinger](docs/providers/hostinger.md) | Linux VPS subscriptions; releasing a lease does not cancel billing. |
  214. | [linode](docs/providers/linode.md) | Straightforward direct Linux VM. |
  215. | [machine0](docs/providers/machine0.md) | Persistent Linux VMs with live CPU/GPU sizing; stopping still incurs compute cost. |
  216. | [morph](docs/providers/morph.md) | Managed Linux VMs over SSH; release pauses by default rather than deleting. |
  217. | [namespace-devbox](docs/providers/namespace-devbox.md) | Fast managed development box over SSH. |
  218. | [namespace-instance](docs/providers/namespace-instance.md) | Short-lived managed Linux compute over SSH. |
  219. | [nebius](docs/providers/nebius.md) | Direct Linux VM lease with optional GPU selection. |
  220. | [ovh](docs/providers/ovh.md) | OVHcloud Public Cloud Linux VM. |
  221. | [phala](docs/providers/phala.md) | Confidential Linux compute over SSH with TDX attestation enabled by default. |
  222. | [scaleway](docs/providers/scaleway.md) | Direct Linux VM on Scaleway Instances. |
  223. | [sealos-devbox](docs/providers/sealos-devbox.md) | Sealos DevBox Linux workspace over SSHGate or NodePort. |
  224. | [sprites](docs/providers/sprites.md) | Fast Linux microVM over provider SSH proxy. |
  225. | [tencentcloud](docs/providers/tencentcloud.md) | Linux SSH leases on Tencent Cloud CVM. |
  226. | [tenki](docs/providers/tenki.md) | Managed Linux sandboxes through Tenki's SSH gateway and certificates. |
  227. | [vultr](docs/providers/vultr.md) | Direct Linux VM on Vultr. |
  228. ### Delegated sandboxes
  229. Catalog category: `delegated-sandbox`.
  230. | Provider | Best fit |
  231. | --- | --- |
  232. | [agent-sandbox](docs/providers/agent-sandbox.md) | Delegated Linux execution from a Kubernetes Agent Sandbox warm pool. |
  233. | [aws-lambda-microvm](docs/providers/aws-lambda-microvm.md) | Stateful ARM64 execution with a compatible Crabbox runner image. |
  234. | [azure-dynamic-sessions](docs/providers/azure-dynamic-sessions.md) | Short delegated container sessions in Azure. |
  235. | [azure-sandbox](docs/providers/azure-sandbox.md) | Kept Linux shell workloads in Azure Container Apps Sandbox groups with explicit file uploads. |
  236. | [blaxel](docs/providers/blaxel.md) | Managed delegated Linux sandbox execution. |
  237. | [cloud-run-sandbox](docs/providers/cloud-run-sandbox.md) | Delegated Cloud Run execution through a sandbox launcher or gateway. |
  238. | [cloudflare](docs/providers/cloudflare.md) | Fast delegated Linux container execution. |
  239. | [cloudflare-dynamic-workers](docs/providers/cloudflare-dynamic-workers.md) | Hosted Worker modules; no shell or filesystem sync. |
  240. | [cloudflare-sandbox](docs/providers/cloudflare-sandbox.md) | Cloudflare Sandbox Linux command execution through a bridge. |
  241. | [codesandbox](docs/providers/codesandbox.md) | Managed Linux development environments through a local Node SDK bridge. |
  242. | [crownest](docs/providers/crownest.md) | Hosted Workspace Runs with archive sync and durable evidence; no downloads yet. |
  243. | [cubesandbox](docs/providers/cubesandbox.md) | Self-hosted E2B-compatible MicroVM command execution. |
  244. | [e2b](docs/providers/e2b.md) | Hosted ephemeral code sandbox. |
  245. | [freestyle](docs/providers/freestyle.md) | Hosted delegated Linux VM execution. |
  246. | [islo](docs/providers/islo.md) | Hosted execution with keep/pause and a provider-owned SSH helper. |
  247. | [modal](docs/providers/modal.md) | Hosted Python or GPU-oriented delegated workloads. |
  248. | [nomad](docs/providers/nomad.md) | Self-hosted delegated Linux execution on an existing Nomad cluster. |
  249. | [opencomputer](docs/providers/opencomputer.md) | Hosted delegated Linux VM execution. |
  250. | [opensandbox](docs/providers/opensandbox.md) | Hosted delegated sandbox through an open SDK. |
  251. | [orgo](docs/providers/orgo.md) | Linux computer execution through HTTP; no Crabbox workspace sync. |
  252. | [smolvm](docs/providers/smolvm.md) | Lightweight hosted microVM execution. |
  253. | [superserve](docs/providers/superserve.md) | Hosted delegated Linux sandbox. |
  254. | [tensorlake](docs/providers/tensorlake.md) | Hosted Firecracker-backed delegated execution. |
  255. | [upstash-box](docs/providers/upstash-box.md) | Hosted short-lived delegated sandbox. |
  256. | [vercel-sandbox](docs/providers/vercel-sandbox.md) | Hosted delegated Linux microVM execution. |
  257. | [warpbuild](docs/providers/warpbuild.md) | Standalone macOS sandboxes through the WarpBuild CLI. |
  258. ### Local virtual machines
  259. Catalog category: `local-vm`.
  260. | Provider | Best fit |
  261. | --- | --- |
  262. | [apple-machine](docs/providers/apple-machine.md) | Local delegated Linux machine execution. |
  263. | [apple-vm](docs/providers/apple-vm.md) | Headless Linux ARM64 VM on Apple silicon. |
  264. | [hyperv](docs/providers/hyperv.md) | Native Windows VMs on a Windows host with Hyper-V. |
  265. | [lume](docs/providers/lume.md) | Layered macOS development VMs from a prepared Apple silicon base. |
  266. | [multipass](docs/providers/multipass.md) | Portable local Ubuntu VM. |
  267. | [parallels](docs/providers/parallels.md) | macOS, Linux, or Windows VM clones and snapshots from prepared sources. |
  268. | [tart](docs/providers/tart.md) | macOS VM testing on Apple silicon with prepared Tart images. |
  269. ### Self-hosted virtualization
  270. Catalog category: `self-hosted-virtualization`.
  271. | Provider | Best fit |
  272. | --- | --- |
  273. | [firecracker](docs/providers/firecracker.md) | Linux microVMs on your own KVM host with prepared guest and network assets. |
  274. | [incus](docs/providers/incus.md) | Self-hosted Linux containers or VMs. |
  275. | [kubevirt](docs/providers/kubevirt.md) | Kubernetes-hosted Linux VM. |
  276. | [proxmox](docs/providers/proxmox.md) | Self-hosted Linux VM fleet. |
  277. | [serve](docs/providers/serve.md) | Owner-only donated container capacity through a coordinator. |
  278. | [xcp-ng](docs/providers/xcp-ng.md) | Self-hosted Linux VM pool over XAPI. |
  279. ### GPU clouds
  280. Catalog category: `gpu-cloud`.
  281. | Provider | Best fit |
  282. | --- | --- |
  283. | [lambda](docs/providers/lambda.md) | Direct GPU-backed Linux workload over SSH. |
  284. | [nvidia-brev](docs/providers/nvidia-brev.md) | Managed NVIDIA GPU workspace over SSH. |
  285. | [runpod](docs/providers/runpod.md) | GPU-backed Linux workload over public SSH. |
  286. | [vast](docs/providers/vast.md) | Direct Linux GPU lease from the Vast.ai offer market. |
  287. | [wandb](docs/providers/wandb.md) | Delegated ML or GPU run environment. |
  288. ### Local sandboxes
  289. Catalog category: `local-sandbox`.
  290. | Provider | Best fit |
  291. | --- | --- |
  292. | [anthropic-sandbox-runtime](docs/providers/anthropic-sandbox-runtime.md) | Policy-constrained commands on the current Linux or macOS host; no remote lease. |
  293. | [docker-sandbox](docs/providers/docker-sandbox.md) | Local delegated sessions through the standalone `sbx` CLI. |
  294. | [mxc](docs/providers/mxc.md) | Local isolated Windows command execution. |
  295. | [windows-sandbox](docs/providers/windows-sandbox.md) | Disposable native Windows commands using Windows Sandbox on a Windows host. |
  296. ### Local container runtimes
  297. Catalog category: `local-runtime`.
  298. | Provider | Best fit |
  299. | --- | --- |
  300. | [apple-container](docs/providers/apple-container.md) | Local Linux containers on Apple silicon. |
  301. | [local-container](docs/providers/local-container.md) | Local Linux tests through Docker or Podman; no cloud account needed. |
  302. ### CI proof runners
  303. Catalog category: `ci-proof-runner`.
  304. | Provider | Best fit |
  305. | --- | --- |
  306. | [blacksmith-testbox](docs/providers/blacksmith-testbox.md) | CI reproduction with proof and reusable sessions. |
  307. | [semaphore](docs/providers/semaphore.md) | SSH debugging with the same image and secrets available to the CI job. |
  308. ### Bring your own SSH host
  309. Catalog category: `byo-ssh`.
  310. | Provider | Best fit |
  311. | --- | --- |
  312. | [ssh-host](docs/providers/ssh-host.md) | Coordinator-managed exclusive hosts with outbound SSH relay and confirmed cleanup. |
  313. | [ssh](docs/providers/ssh.md) | Your existing Linux, macOS, or Windows host; Crabbox never deletes the machine. |
  314. ### Service control
  315. Catalog category: `service-control`.
  316. | Provider | Best fit |
  317. | --- | --- |
  318. | [cua](docs/providers/cua.md) | Experimental read-only diagnostics and existing-sandbox inspection. |
  319. | [fastapi-cloud](docs/providers/fastapi-cloud.md) | Inspect FastAPI Cloud deployment readiness; no arbitrary commands or app stops. |
  320. | [railway](docs/providers/railway.md) | Inspecting or stopping an existing Railway service. |
  321. | [unikraft-cloud](docs/providers/unikraft-cloud.md) | Running a prebuilt OCI image as a cloud microVM service. |
  322. ### External plugins
  323. Catalog category: `external-provider`.
  324. | Provider | Best fit |
  325. | --- | --- |
  326. | [external](docs/providers/external.md) | Your own provider through an executable contract; the adapter owns its safety and lifecycle semantics. |
  327. <!-- END README PROVIDER LIST -->
  328. ### Machine classes
  329. Managed providers with class-based capacity default to `beast`. Start with a
  330. smaller `--class`, such as `tiny`, when evaluating cloud capacity. `--class`
  331. selects a tier; `--type` pins a provider-native size and disables class fallback.
  332. See [Configuration](docs/features/configuration.md) and your provider's guide.
  333. ## How it works
  334. ```text
  335. Local checkout → Lease a box → Sync changes → Run → Stream output + exit code
  336. ↑ |
  337. └── Reuse a warm box ──────┘
  338. or release it
  339. ```
  340. The CLI sends your working tree, including nonignored uncommitted files. SSH
  341. providers use direct CLI-to-runner connections; delegated providers own their
  342. execution transport. One-shot runs release their leases; `warmup` and runs with
  343. `--id` support reuse. Explicitly stop retained boxes when finished.
  344. The optional coordinator manages shared leases, credentials, budgets, expiry,
  345. and history. Provider adapters own provisioning and cleanup. Existing SSH hosts
  346. remain yours: Crabbox neither provisions nor deletes them.
  347. ### Coordinator deployment choices
  348. Use providers directly, deploy the coordinator on Cloudflare Workers with a
  349. Durable Object, or self-host it on Node.js with PostgreSQL. State does not
  350. migrate automatically between runtimes. Follow the deployment and proof
  351. requirements in [Infrastructure](docs/infrastructure.md).
  352. [How Crabbox works](docs/how-it-works.md) · [Architecture](docs/architecture.md) · [Vision](VISION.md)
  353. ## When a run fails
  354. | Situation | Next step |
  355. | --- | --- |
  356. | The box is unreachable | Run `crabbox doctor --provider <name>`. |
  357. | You need to inspect the failure | Add `--keep-on-failure`, then use `crabbox connect --id <box>`. |
  358. | You need a fresh workspace sync | Add `--full-resync` to reset the remote workdir before syncing. |
  359. | You need the command's output files | Use `--download remote=local`, repeatable for several files. |
  360. | Output needs to go straight to a file | Use `--capture-stdout <path>` and `--capture-stderr <path>`. |
  361. | 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. |
  362. | 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`). |
  363. Failed SSH-backed and Blacksmith delegated runs save local failure bundles by
  364. default. Follow the printed `failure-bundle local=…` path and review the contents
  365. before sharing. See [Troubleshooting](docs/troubleshooting.md) and
  366. [Observability](docs/observability.md).
  367. ## Highlights
  368. [Named jobs](docs/features/jobs.md) keep repeatable setup and test commands in the
  369. repository. [Checkpoints](docs/features/checkpoints.md) save, restore, or fork
  370. workspace state. [Failure capsules](docs/features/capsules.md) replay failing CI
  371. runs. [Artifacts](docs/features/artifacts.md), [test results](docs/features/test-results.md),
  372. and [telemetry](docs/features/telemetry.md) make runs inspectable.
  373. [Pond peer groups](docs/features/pond.md) connect related leases for multi-machine tests.
  374. ## Configuration
  375. ```sh
  376. crabbox init --detect
  377. crabbox config show
  378. ```
  379. Review the generated configuration and setup before running it. Settings resolve
  380. from flags, environment, repository configuration, user configuration, then defaults.
  381. User configuration defaults to `~/.config/crabbox/config.yaml` on Linux,
  382. `~/Library/Application Support/crabbox/config.yaml` on macOS, and
  383. `%AppData%\crabbox\config.yaml` on Windows. Linux also honors `XDG_CONFIG_HOME`.
  384. A nonempty `CRABBOX_CONFIG` selects only that file, skipping both user and repository
  385. config files; environment variables and flags still apply.
  386. A repository's `.crabbox.yaml` can select its provider and image:
  387. ```yaml
  388. provider: local-container
  389. localContainer:
  390. image: node:22-bookworm
  391. lease:
  392. idleTimeout: 30m
  393. ```
  394. Your shell environment is not forwarded wholesale. Only `CI` and `NODE_OPTIONS`
  395. are allowed by default; configure `env.allow` or pass `--allow-env NAME` for
  396. additional variables. Keep provider credentials outside the repository and out
  397. of command-line arguments.
  398. [Configuration](docs/features/configuration.md) · [Environment forwarding](docs/features/env-forwarding.md) · [Sync](docs/features/sync.md)
  399. ## Integrations
  400. `crabbox init --detect` also generates a repository-local Agent Skill for
  401. compatible coding agents. To install the published skills separately:
  402. ```sh
  403. npx skills add openclaw/crabbox --skill crabbox
  404. npx skills add openclaw/crabbox --skill crabbox-quickstart
  405. ```
  406. Use `crabbox-quickstart` for the first Docker/Podman run and `crabbox` for remote
  407. execution and repository workflows. **Install the CLI separately.**
  408. [Zed](integrations/zed/README.md) and [Herdr](plugins/herdr/README.md) integrations
  409. add editor and lease controls. See the [agent guide](docs/integrations/agents.md)
  410. and [integration catalog](docs/integrations/README.md).
  411. ## Who Crabbox is for
  412. Coding agents running tests in parallel, maintainers with expensive builds,
  413. contributors testing another OS, and teams sharing remote capacity. Use Crabbox
  414. alongside CI for an interactive edit–run loop and reviewable execution evidence.
  415. ## Trust model
  416. Run **trusted repositories**. Crabbox trusts the local OS user, repository
  417. configuration, project tooling, and authenticated coordinator operators.
  418. Configuration can execute helpers, mount host resources, and control infrastructure;
  419. container socket passthrough grants access to the host engine.
  420. The coordinator holds cloud credentials for brokered leases. Reuse and destructive
  421. operations require verified ownership bound to the exact provider, resource, and
  422. claim; names or labels alone are not proof. Ownership and inventory failures
  423. must fail closed. See [Vision](VISION.md) for the lifecycle contract.
  424. Coordinator access controls serve cooperative teams, not mutually hostile tenants.
  425. Captured output, artifacts, and failure bundles are not scrubbed of secrets;
  426. review them before sharing. Read the [Security Policy](SECURITY.md) and
  427. [Operational security](docs/security.md).
  428. ## Install
  429. Homebrew (macOS or Linux) installs the complete release distribution:
  430. ```sh
  431. brew install openclaw/tap/crabbox
  432. crabbox --version
  433. ```
  434. For macOS, Linux, and Windows, you can also download a
  435. [release archive](https://github.com/openclaw/crabbox/releases/latest).
  436. See the [Windows installation guide](docs/windows-install.md) for Windows setup.
  437. SSH workflows need `git`, `ssh`, `ssh-keygen`, `rsync`, and `curl` locally;
  438. the local-container quick start also needs Docker or Podman.
  439. <details>
  440. <summary>Runtime packs and CLI-only Go installs</summary>
  441. Keep a release's `crabbox-runtime/` directory beside its real CLI executable.
  442. Filesystem-capable packs contain amd64 and arm64 companions for Linux, macOS,
  443. and Windows; Linux companions also provide native managed execution for Linux
  444. and WSL2. Do not mix builds or copy only the CLI. Reinstall the matching archive
  445. or Homebrew package if an official release's pack is missing or incomplete;
  446. release installations do not compile replacement companions from source.
  447. For a CLI-only source install, pin a supported release (v0.44.0 or later):
  448. ```sh
  449. GOTOOLCHAIN=go1.27.3 go install github.com/openclaw/crabbox/cmd/crabbox@v0.81.0
  450. ```
  451. The module minimum remains Go 1.26. Use the explicit patched toolchain above
  452. for source installs: versioned `go install` ignores the target module's toolchain
  453. suggestion. Avoid `@latest` while older,
  454. incompatible release tags remain visible.
  455. `go install` omits companion executables and assets, including the Apple VM
  456. helper and native runtime pack. It is not the signed/notarized release
  457. distribution. Source-built CLIs retain the shell-backed supervisor route and
  458. can compile the dependency-free filesystem helper with a local Go 1.26+ compiler;
  459. that does not build the managed-command supervisor. Use Homebrew or a complete
  460. release archive for full platform capabilities, especially Apple VM support.
  461. </details>
  462. ## Docs
  463. **[Documentation site](https://crabbox.sh/)** · [Documentation index](docs/README.md) · [Changelog](CHANGELOG.md)
  464. | I want to… | Start here |
  465. | --- | --- |
  466. | Set up a repository | [Getting started](docs/getting-started.md) · [Configuration](docs/features/configuration.md) |
  467. | Look up a command or feature | [Commands](docs/commands/README.md) · [Features](docs/features/README.md) · [CLI](docs/cli.md) |
  468. | Understand the design | [Concepts](docs/concepts.md) · [Architecture](docs/architecture.md) · [Source map](docs/source-map.md) |
  469. | Operate shared infrastructure | [Infrastructure](docs/infrastructure.md) · [Operations](docs/operations.md) · [Observability](docs/observability.md) |
  470. | Debug a run | [Troubleshooting](docs/troubleshooting.md) · [History and logs](docs/features/history-logs.md) · [Performance](docs/performance.md) |
  471. | Extend Crabbox | [Provider authoring](docs/features/provider-authoring.md) · [External provider](docs/providers/external.md) · [Repository guidelines](AGENTS.md) |
  472. ## Development
  473. Read [Repository guidelines](AGENTS.md) and the [Source map](docs/source-map.md).
  474. Use the Go toolchain in `go.mod` and the Node version in `.node-version`.
  475. ```sh
  476. go build -trimpath -o bin/crabbox ./cmd/crabbox
  477. go vet ./...
  478. go test -race -timeout=20m ./...
  479. npm ci --prefix worker
  480. npm run format:check --prefix worker
  481. npm run lint --prefix worker
  482. npm run check --prefix worker
  483. npm run check:node --prefix worker
  484. npm test --prefix worker
  485. npm run build --prefix worker
  486. npm run build:node --prefix worker
  487. scripts/check-docs.sh
  488. ```
  489. CI also checks Go modules, coverage, repository scripts, generated files, and
  490. release snapshots; [.github/workflows/ci.yml](.github/workflows/ci.yml) defines
  491. the full gate. See [Documentation authoring](docs/README.md#about-these-docs)
  492. for site conventions, [Infrastructure](docs/infrastructure.md) for deployments,
  493. and [Release engineering](docs/RELEASING.md) for the release process.
  494. <details>
  495. <summary>Release authorization and safety</summary>
  496. One explicit full release/publish request authorizes the normal preparation,
  497. tagging, build/signing, private draft/upload, native proof, publication, Homebrew
  498. update, independent installation smokes, and closeout without renewed chat
  499. approval at each stage. Narrow requests stay narrow. The original request supplies
  500. authorization; GitHub events alone do not. Sequential technical gates, separate
  501. trust domains, and cancellation boundaries remain mandatory. Follow
  502. [Release engineering](docs/RELEASING.md) for the exact sequence.
  503. </details>
  504. ## License
  505. [MIT](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.