#Run your code on the right machine.

Crabbox runs your repository's commands on remote machines, existing SSH hosts, and local containers. Keep editing locally; send your working tree to a box, stream the output, and get the command's exit code back.

Quick start · Commands · Install · Providers · Documentation · Security

Inside a Git repository you trust, with Docker or Podman running:

crabbox run \
  --provider docker \
  -- uname -a

One command creates a Linux container, syncs your checkout, runs uname -a, streams the result, and removes the container. No cloud account or login needed. For remote compute, choose a provider or your team's coordinator.

#Why Crabbox?

• Test the code you are editing. Sync uncommitted changes and nonignored files without pushing a commit. Dependency and build directories are excluded; install dependencies on the box. Workspace sync
• Keep a box warm. Reuse a prepared environment through an edit–run loop, or use a one-shot run for work that should clean up afterward. Warm workspaces
• Make runs reviewable. Collect test reports and artifacts; use coordinator history, logs, and events to inspect remote work. Evidence
• Choose your infrastructure. Use local containers, your own SSH machines, cloud VMs, or delegated execution providers. Capabilities vary by provider. Provider matrix
• Share capacity with your team. An optional coordinator owns cloud credentials, tracks usage, enforces spend caps, and expires stale leases. Coordinator

#Install

Homebrew installs the complete release distribution:

brew install openclaw/tap/crabbox
crabbox --version

For macOS, Linux, and Windows, you can also download a release archive. Windows users should follow the Windows installation guide.

When a release includes a crabbox-runtime directory, keep it beside the real CLI executable. New filesystem-capable packs contain amd64 and arm64 companions for Linux, macOS, and Windows. Linux companions additionally provide native managed execution for Linux and WSL2; copying only the CLI omits those bundled capabilities. Do not mix a runtime pack with a differently built controller. An official release with a missing or incomplete pack is a broken installation: reinstall its matching archive or Homebrew package. It does not silently compile replacement companions from source. CLI-only source builds retain their existing shell-backed supervisor route.

Local prerequisites for the SSH workflow: git, ssh, ssh-keygen, rsync, and curl. The local quick start also needs a running Docker or Podman engine.

go install github.com/openclaw/crabbox/cmd/crabbox@v0.44.0

#Quick start

#1. Try a local box

Inside a Git repository you trust, with Docker or Podman running:

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

You should see the container's Linux kernel information. Crabbox returns the command's exit code and cleans up the one-shot container. First startup includes an image pull and bootstrap, so allow extra time.

The default box is bare. It includes Crabbox's sync/run prerequisites, but not your project's Node, Go, Python packages, or other build dependencies. Prepare those before replacing uname -a with your test command.

#2. Run a project's tests

For a Node.js repository with a package-lock.json and an npm test script, select an image with Node installed and install the dependencies on the box:

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

Choose a Node version compatible with your project. Crabbox does not install project runtimes for you: supply them with a prepared image, the repository's own setup scripts, a devcontainer, Nix, or mise/asdf. Crabbox can also reuse supported setup steps from GitHub Actions; full Actions semantics require the documented runner path.

#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 on the same box.
crabbox run --provider local-container --id dev-box -- uname -a

# Open a shell, or release the box when finished.
crabbox ssh --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 creates a reusable lease; prewarm additionally performs Actions hydration. A lease has both a stable cbx_... ID and a friendly slug; either works with --id.

For a complete repository setup, see Getting started and Local Container.

#Already have a team coordinator?

Use the URL supplied by your team; the address below is a placeholder:

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

This assumes the repository's provider and remote runtime/dependency setup are configured. For your own cloud account, follow a direct-provider setup guide and skip login. Cloud runs use your infrastructure and may incur charges.

#Everyday commands

Pass long commands as a file with --script <file> instead of a large quoted string. Every command has a page under Commands, and the CLI reference lists all flags and environment variables.

#When a run fails

Failed SSH-backed and Blacksmith delegated runs save local bundles to .crabbox/captures/*.tar.gz by default, falling back to the Crabbox user state directory when the project destination is unwritable. Follow the reported failure-bundle local=… path; see local capture storage. Crabbox does not scrub bundles, captured output, or artifacts; review them before sharing.

Troubleshooting · History and logs · Observability

#How it works

Your working tree
       |
       v
Select a box -> Sync changes -> Run command -> Stream output
                    ^                              |
                    |                              v
                    +------ Reuse the box, or release it

The CLI runs on your machine. For SSH providers, it sends files and runs commands directly on the runner over SSH and rsync. Delegated providers use their own execution transports.

An optional coordinator handles provider credentials, leases, budgets, history, and cleanup for supported managed providers. It is separate from the normal CLI-to-runner data path. Local containers and existing hosts work without a coordinator.

#Coordinator deployment choices

State does not automatically migrate between coordinator runtimes. For deployment requirements and the separate SSM-only private AWS workspace path, see Infrastructure and Private AWS Workspaces.

Read How Crabbox works for the full lifecycle, Architecture for internals, and Vision for scope and non-goals.

#Providers

Start with the environment you already have:

Browse the complete provider matrix →

The matrix documents operating systems, sync methods, lifecycle support, and provider limitations. Support for SSH, snapshots, desktops, and cleanup is not uniform across providers.

#Machine classes

Managed providers with class-based capacity default to beast. Choose a smaller --class deliberately when evaluating cloud capacity. --class selects a capacity tier; --type pins a provider-native instance size and disables class fallback. See Configuration and your provider's guide for sizes and pricing considerations.

#Highlights

Once the basic loop works, add the capabilities your workflow needs:

#Configuration

Generate a starting configuration from inside your repository:

crabbox init --detect
crabbox config show

Settings resolve in order: flags, environment, repository configuration, user configuration, then defaults. Run crabbox config path to locate your user configuration; its default location varies by platform. A few lines in .crabbox.yaml are usually enough to drop the flags from your everyday commands:

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

Review the generated configuration and setup before running it. Put repeatable validation flows in named jobs, then invoke them with crabbox job run <name>.

Your shell environment is not forwarded. Only CI and NODE_OPTIONS cross over by default; add names to env.allow in configuration, or pass --allow-env NAME and --env-from-profile <file> for a single run. Keep provider credentials in environment variables or user configuration, outside the repository, and never in command-line arguments.

See Configuration for the full schema, Environment forwarding for the allowlist, Sync for file selection, and CLI reference for flags and environment variables.

#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

Choose crabbox-quickstart for the first local Docker/Podman run, and crabbox for remote execution and repository workflows. Skills teach the agent; install the CLI separately. Other installation and discovery paths are in the agent integration guide.

• Zed: checked tasks, YAML support, and a separate crabbox open --editor=zed remote-project handoff.
• Herdr: lease controls and repository workflows in the action palette.

See the integration catalog for installation, current distribution status, and lifecycle boundaries.

#Who Crabbox is for

Crabbox fits maintainers with expensive test suites, contributors who need a repeatable environment, automation that needs reviewable execution evidence, and teams sharing remote capacity. Use it alongside CI for interactive tests, builds, browser checks, and platform-specific validation.

#Trust model

Crabbox is a developer execution tool, not a hostile multi-tenant sandbox, a secrets scrubber, or a replacement for CI. It trusts the local OS user, repository configuration, project tooling, and authenticated coordinator operators. Review unfamiliar repositories before running them: configuration can execute helpers, mount host resources, and control infrastructure.

Coordinator access controls support cooperative teams; they do not isolate mutually adversarial tenants. Captured output, artifacts, and failure bundles are not automatically scrubbed of secrets. Review them before sharing. Local container socket passthrough grants access to the host engine.

Read the Security Policy, Operational security, and Artifacts guide for the supported boundaries.

#Docs

Documentation site · Documentation index · Changelog

#Development

Contributions are welcome. Read Repository guidelines for architecture boundaries, coding conventions, and review expectations, and Documentation authoring for site conventions.

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

# Coordinator runtimes (Node 22+ locally; CI runs Node 24)
npm ci --prefix worker
npm test --prefix worker
npm run build --prefix worker
npm run check:node --prefix worker
npm run build:node --prefix worker

# Repository scripts
node scripts/generate-linux-readiness.mjs --check
node scripts/generate-bootstrap.mjs --check
node --test scripts/*.test.js scripts/*.test.mjs

# Docs
scripts/check-docs.sh

# Optional live smoke, when broker/provider credentials are available
CRABBOX_LIVE=1 CRABBOX_LIVE_REPO=/path/to/my-app scripts/live-smoke.sh

# Firecracker host readiness smoke (read-only; reports environment_blocked when Linux/KVM assets are missing)
CRABBOX_BIN=./bin/crabbox scripts/live-firecracker-smoke.sh

#License

MIT.