crabbox/docs

🦀 Crabbox Docs

Warm a box, sync the diff, run the suite.

What Crabbox is

Crabbox is a shared remote testbox system for OpenClaw maintainers and AI agents. The goal is to keep the local developer story unchanged - edit, save, run - while moving compute and tests onto owned cloud capacity.

A crabbox run command leases a Linux machine, syncs your tracked and nonignored local files, executes the command remotely, streams stdout and stderr back, and releases the machine. Behind the scenes a small Cloudflare-hosted broker owns provider credentials, lease state, cleanup, usage, and cost guardrails so individual machines and CLIs never need to.

How it fits together

your laptop                Cloudflare Worker            cloud provider
-------------              ------------------           --------------
crabbox CLI    -- HTTPS --> Fleet Durable Object  -->   Hetzner / AWS Spot
   |                         lease + cost state              |
   |                                                         |
   +------------ SSH + rsync to leased runner <--------------+

The CLI is a Go binary. The broker is a Cloudflare Worker plus a single Durable Object. Runners are vanilla Ubuntu boxes prepared by cloud-init with SSH, Git, rsync, curl, jq, and /work/crabbox. Project runtimes come from Actions hydration or repo-owned setup. Runners hold no broker credentials - they are leaf nodes.

A run, end to end

1. CLI loads config from flags, env, repo, user, defaults.
2. CLI mints a per-lease SSH key and slug, then calls POST /v1/leases on the broker.
3. Worker checks active-lease and monthly spend caps, reserves worst-case TTL cost, provisions a server, returns host / port / user / workdir / expiry / slug.
4. CLI waits for crabbox-ready, seeds remote Git when possible, rsyncs the Git file-list manifest, runs sync guardrails and sanity checks, hydrates the configured base ref.
5. CLI runs the command over SSH, streams output, sends heartbeats/touches.
6. CLI releases the lease unless --keep is set; kept leases still auto-release after idle timeout, and the broker frees reserved cost when the lease closes.

See How Crabbox Works for the full picture, including warm-machine reuse and the brokered vs direct provider paths. See Source Map when you need to trace a documented behavior back to code.

Install

brew install openclaw/tap/crabbox

Verify with crabbox --version.

Quick start

# log in once per machine - stores a bearer token in the OS keychain
crabbox login

# one-shot run on a fresh leased box
crabbox run -- pnpm test

# keep a warm box around for repeated runs; output includes an ID and slug
crabbox warmup
crabbox run --id blue-lobster -- pnpm test:changed
crabbox ssh --id blue-lobster
crabbox stop blue-lobster

crabbox doctor validates local config, network reachability, and SSH key availability before you commit to a long workflow. crabbox usage summarizes recent spend by user, org, provider, and server type.

Where to read next

Pick whichever matches your intent:

• Get the mental model: How Crabbox Works, Architecture, Orchestrator.
• Use the CLI: CLI, Commands, Features, Actions hydration.
• Operate it: Operations, Observability, Troubleshooting, Performance.
• Set it up or audit it: Infrastructure, Security, Source Map, MVP Plan.

About these docs

Markdown in this directory is the user-facing documentation source. Implementation truth stays in code; Source Map lists the files behind each documented behavior. The GitHub Pages site at https://openclaw.github.io/crabbox/ is generated from these Markdown files by scripts/build-docs-site.mjs and deployed by .github/workflows/pages.yml. Pages must be enabled on the repository or organization for the workflow to publish.

Build the docs site locally:

node scripts/build-docs-site.mjs
open dist/docs-site/index.html