DOCSEARCHbyAlgolia
Submit Docs

Crabbox Documentation

repository·main·Indexed 22 days ago

https://github.com/openclaw/crabbox

A remote software testing and execution control plane that enables developers to run commands on remote, disposable runners while maintaining a local edit-save-run workflow. Managed via the `crabbox` CLI, it supports a wide array of providers including cloud (AWS, GCP, Azure), local runtimes (Docker, Apple VM, Multipass), and delegated sandboxes (E2B, Cloudflare). It features integration surfaces for editors like Zed and Herdr, as well as support for coding-agent clients.

Tokens
425K
Snippets
1K
Records
1.7K
Agent score
74%

What's inside crabbox

  1. What is Crabbox?

    main

    Crabbox is a remote software testing and execution control plane. It allows developers to run repository commands on remote runners (managed cloud capacity, SSH hosts, or sandbox providers) instead of their local machine. This is useful for running expensive tests, platform-specific validation, or providing disposable environments for contributors and AI agents.

    Core Workflow:

    1. Lease/Select: The CLI selects a remote runner.
    2. Sync: The current working tree is synced to the runner (using rsync with fingerprint skipping).
    3. Run: The command is executed remotely.
    4. Stream: Output is streamed back to the local terminal.
    5. Release: The runner is released or unclaimed.
    crabbox run -- pnpm test

  2. Overview of Crabbox features

    main

    Crabbox is a tool for managing ephemeral and reusable workspaces (leases) across various cloud providers and local environments. Key capabilities include:

    • Workspace Management: Use crabbox run for one-shot tasks, or crabbox warmup/prewarm for reusable, hydrated workspaces.
    • Named Repo Jobs: Define workflows (warmup, run, cleanup) in a .crabbox.yaml file and execute them via crabbox job run <name>.
    • Observability: Monitor active runs with crabbox attach <run-id>, view lifecycle events with crabbox events <run-id>, or retrieve logs with crabbox logs <run-id>.
    • GitHub Actions Hydration: Use crabbox actions hydrate to run repository setup steps locally over SSH, ensuring the leased box matches the CI environment.
    • Failure Capsules: Capture failing CI runs into portable bundles using crabbox capsule from-actions <run-url>, which can be replayed with capsule replay.
    • Interactive Leases: Provision specialized environments using --browser (Chrome/Chromium), --desktop (visible UI via VNC), or --code (code-server).
    • Pond Peer Groups: Group leases using --pond <name> for discovery (pond peers) and SSH-mesh connectivity (pond connect).

  3. Overview of the Crabbox AWS Lambda MicroVM Runner

    main

    The AWS Lambda MicroVM Runner is the application image used when configuring a provider with provider: aws-lambda-microvm.

    Key Capabilities:

    • Exposes Lambda lifecycle hooks.
    • Supports bounded archive upload.
    • Provides health checks.
    • Supports streamed command execution on port 8080.

    Security Model: AWS protects every public endpoint request with a MicroVM-scoped JWE token. The runner does not accept any independent public credentials; it relies entirely on the JWE token provided by AWS.

  4. Overview of the Crabbox CLI command surface

    main

    Crabbox is managed via a single CLI tool named crabbox. Unlike some CLI tools that use a primary subcommand (like testbox), Crabbox uses top-level commands.

    Commands are categorized into several functional areas including lifecycle management (init, run, stop), observability (logs, status, events), resource management (desktop, media, artifacts), and connectivity (ssh, connect, tunnel).

    Note that some commands act as parents to subcommands (e.g., desktop launch or pond connect), which are documented within their respective parent command pages.

  5. Overview of the crabbox CLI

    main

    The crabbox CLI is used to lease remote machines (boxes), sync your local repository state to them, run commands, and stream the output. It manages the entire lifecycle of a remote execution session, including lease acquisition, file synchronization via rsync, command execution over SSH, and automatic cleanup.

    Usage Pattern:

    crabbox [global flags] <command> [args]

    Output Behavior:

    • stdout: Primary results and command output.
    • stderr: Progress, diagnostics, and errors.
    • --json: Most read commands support a --json flag for stable, scriptable output.
    • TTY: Progress lines are automatically suppressed when stdout is not a TTY.
    crabbox [global flags] <command> [args]

  6. Choose a Crabbox integration surface

    main

    Crabbox provides various integration surfaces depending on whether you want to teach a coding agent to use the CLI, run remote jobs, or use an editor as a control surface.

    Integration vs. Provider: Note that an Integration is a caller-side control surface (like an editor plugin or agent skill) that uses the crabbox CLI. A Provider is the underlying execution substrate. Integrations allow users to use Crabbox without managing provider credentials, lease ownership, or synchronization manually.

    GoalSurfaceStatus
    Teach a local coding agent when and how to use Crabboxcrabbox init Agent SkillAvailable
    Run a repo-owned one-shot harness remotelycrabbox run or a named jobCredential-free run-evidence pattern available
    Reuse repository setup on a warm leaseGitHub Actions hydrationAvailable
    Use Zed as a local Crabbox control surfaceZed extension packagePackage available
    Open a synced lease as a remote editor workspacecrabbox open --editor=zedAvailable
    Edit a Linux lease in browser VS Codecrabbox codeAvailable for coordinator-backed code-capable providers
    Control leases and jobs from HerdrHerdr pluginDirect install available

  7. Manage machine pools with `crabbox pool`

    main

    The crabbox pool command provides helpers for managing machine inventories and 'Ready Pools'. Ready pools consist of hydrated broker leases that have been prepared (via prewarm or actions hydrate) and are ready to be borrowed for execution using crabbox run --pool.

    Key Concepts

    • Ready Pools: Broker records for already hydrated leases. You register a lease after it is prepared, borrow it to make it busy, and return it to make it ready again or drain/release it.
    • Compatibility Keys: Use --compatibility-key to name provider-neutral capability and size classes (e.g., linux-16-vcpu). This allows different provider shapes (like AWS and Azure) to share a single logical pool key while maintaining separate compatibility requirements.
    • Borrowing & Heartbeats: When you pool borrow a lease, it becomes busy. To prevent an abandoned borrow from being quarantined, you must send pool heartbeat to opt-in to deadline enforcement. crabbox run --pool handles these heartbeats automatically.
    # Example workflow
crabbox pool ready example/app/main/linux
crabbox pool borrow example/app/main/linux --compatibility-key linux-16-vcpu
crabbox pool heartbeat example/app/main/linux --id cbx_... --borrow-token <token>
crabbox pool return example/app/main/linux --id cbx_... --result ready --borrow-token <token>

  8. Use the AWS Provider for managed EC2 instances

    main

    The AWS provider allows Crabbox to provision EC2 instances for various workloads. It supports Linux, native Windows, Windows under WSL2, and EC2 Mac.

    When running in direct mode (without a broker URL), Crabbox uses your local AWS credentials via the standard AWS SDK chain. When running in brokered mode, credentials are managed by the coordinator.

    Key Use Cases:

    • Managed Windows or WSL2 test machines.
    • EC2 Mac desktops (requires Dedicated Host).
    • Broad Linux capacity with Spot and On-Demand fallback.
    • Broker-owned cloud credentials and cost accounting.
    # Example: Warm up a standard Linux instance
crabbox warmup --provider aws --class standard

# Example: Run a command on a fast ARM64 instance
crabbox run --provider aws --arch arm64 --class fast -- pnpm test

# Example: Warm up a Windows WSL2 instance
crabbox warmup --provider aws --target windows --windows-mode wsl2

  9. Manage provider base images with `crabbox image`

    main

    The crabbox image command provides trusted-operator controls for managing provider base images. Use it to create runner images from active leases, promote images (AWS AMIs or Azure OS disk snapshots) as brokered defaults, inspect AWS Fast Snapshot Restore (FSR) status, and delete stale images.

    Note: These commands require a configured coordinator (broker) and admin-token authentication. Set broker.adminToken or CRABBOX_COORDINATOR_ADMIN_TOKEN locally. They are not available to standard GitHub browser-login users.

    Important: Use crabbox image for shared base images and cleanup, not for per-scenario state. For saving a specific scenario state to fork later, use crabbox checkpoint instead.

  10. Explore Crabbox feature domains

    main

    Crabbox is organized into several functional domains that allow you to manage remote execution targets (leases) and runners:

    Foundations

    Core configuration, identity, and connectivity settings including crabbox doctor checks, network plane selection (--network auto|tailscale|public), and environment variable forwarding.

    Fleet Control and Coordination

    Tools for managing the control plane, including the Coordinator (Cloudflare Durable Object or Node.js/PostgreSQL), the Browser Portal UI, authentication/routing, and telemetry/logging.

    Runners and Reachability

    Mechanisms for accessing remote runners via Tailscale, SSH, or mediated egress, as well as runner bootstrapping and image management.

    Sync, Execution, and Evidence

    Workflows for synchronizing files (via Git manifests or rsync), running jobs, managing remote workspaces (Checkpoints), and collecting evidence (logs, screenshots, artifacts, and JUnit test results).

    Integrations

    Support for editors, terminal UIs, coding-agent clients, and repository onboarding via crabbox init.

  11. Use `crabbox desktop` to drive visible desktop sessions

    main

    crabbox desktop is used to interact with a lease that has been warmed with the --desktop capability. It allows you to launch applications and terminals, send pointer/keyboard input, capture screenshots and video, and collect proof bundles.

    Each subcommand resolves the lease, touches it to keep it alive, verifies the desktop capability, and acts over SSH without syncing the repository.

    Note: Desktop helpers reject delegated providers like Blacksmith, which manage their own connectivity.

    # Example: Warm up a lease with desktop and browser capabilities
crabbox warmup --desktop --browser

# Example: Launch a browser on a specific lease
crabbox desktop launch --id swift-crab --browser --url https://example.com

  12. Vast Provider capabilities and limitations

    main

    The Vast provider supports the following features and constraints:

    • OS targets: Linux only.
    • SSH: Supported via Crabbox-managed SSH over Vast direct SSH endpoints.
    • Crabbox sync: Supported via rsync over SSH.
    • Provider-managed sync: Not supported.
    • GPU: Supported (dependent on provider catalog).
    • Coordinator: Not supported; use the CLI directly.
    • Cleanup: Supported via ownership-label and local-claim guarding.
    • Desktop / browser / code-server: Not supported in this release.
    • Tailscale: Not supported in this release.