{"id":49498043,"url":"https://github.com/openclaw/crabbox","last_synced_at":"2026-06-14T13:01:01.666Z","repository":{"id":354885928,"uuid":"1225688424","full_name":"openclaw/crabbox","owner":"openclaw","description":"Crabbox: warm a box, sync the diff, run the suite.","archived":false,"fork":false,"pushed_at":"2026-06-12T03:21:36.000Z","size":7694,"stargazers_count":607,"open_issues_count":22,"forks_count":71,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-12T05:03:21.312Z","etag":null,"topics":["remote-test-runner"],"latest_commit_sha":null,"homepage":"http://crabbox.sh","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openclaw.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":["moltbot"]}},"created_at":"2026-04-30T14:31:48.000Z","updated_at":"2026-06-12T03:21:39.000Z","dependencies_parsed_at":null,"dependency_job_id":"ec73766d-4666-4577-9de1-4fe0d851fa56","html_url":"https://github.com/openclaw/crabbox","commit_stats":null,"previous_names":["openclaw/crabbox"],"tags_count":35,"template":false,"template_full_name":null,"purl":"pkg:github/openclaw/crabbox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openclaw%2Fcrabbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openclaw%2Fcrabbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openclaw%2Fcrabbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openclaw%2Fcrabbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openclaw","download_url":"https://codeload.github.com/openclaw/crabbox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openclaw%2Fcrabbox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34322074,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["remote-test-runner"],"created_at":"2026-05-01T11:00:23.431Z","updated_at":"2026-06-14T13:01:01.656Z","avatar_url":"https://github.com/openclaw.png","language":"Go","funding_links":["https://github.com/sponsors/moltbot"],"categories":["Go"],"sub_categories":[],"readme":"# 🦀 📦 Crabbox\n\n![Crabbox banner](docs/assets/readme-banner.jpg)\n\n[![CI](https://github.com/openclaw/crabbox/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/openclaw/crabbox/actions/workflows/ci.yml)\n[![Release](https://github.com/openclaw/crabbox/actions/workflows/release.yml/badge.svg?event=push)](https://github.com/openclaw/crabbox/actions/workflows/release.yml)\n[![Latest release](https://badgen.net/github/release/openclaw/crabbox/stable)](https://github.com/openclaw/crabbox/releases/latest)\n\n**Warm a box, sync the diff, run the suite.**\n\nCrabbox is a remote software testing and execution control plane for maintainers\nand AI agents. Lease fast managed cloud capacity, point at an existing SSH host,\nor use an agent sandbox provider — then sync your dirty checkout, run commands\nremotely, stream output, collect evidence, and release. Local edit-save-run\nloop, cloud-grade compute, agent-ready observability.\n\n```sh\ncrabbox run -- pnpm test\n```\n\nBehind that one command: a Go CLI on your laptop, an optional coordinator that\nowns provider credentials and lease state, and a managed or delegated runner.\nRun the coordinator on Cloudflare Workers with a Durable Object, or as a\nNode.js service backed by PostgreSQL.\n\n## How it works\n\n```text\nyour laptop                 coordinator runtime              cloud provider\n-------------               -------------------              --------------\ncrabbox CLI    -- HTTPS --\u003e Cloudflare + Durable Object  --\u003e Hetzner / AWS / Azure / GCP\n   |                      or Node.js + PostgreSQL              |\n   |                                                           |\n   +------------- SSH + rsync to leased runner \u003c---------------+\n```\n\n- **CLI** — Go binary. Loads config, mints a per-lease SSH key, asks the broker\n  for a lease, waits for SSH, seeds remote Git, rsyncs the dirty checkout (with\n  a fingerprint skip when nothing changed), runs the command, streams output,\n  releases.\n- **Coordinator** — the same fleet control plane on either Cloudflare Workers\n  plus a Fleet Durable Object, or Node.js plus PostgreSQL and pg-boss. Owns\n  provider credentials, serializes lease state, enforces active-lease and\n  monthly spend caps, and expires stale leases. Auth is GitHub browser login, a\n  shared bearer token, or an explicitly trusted identity proxy.\n- **Runner** — a throwaway machine reachable over SSH on the primary port\n  (default `2222`) plus configured fallback ports, prepared with Crabbox's\n  sync/run prerequisites. Linux uses Ubuntu with cloud-init and `/work/crabbox`;\n  native Windows uses OpenSSH, Git for Windows, and `C:\\crabbox`. No broker\n  credentials live on the box. Project runtimes (Go, Node, Docker, services,\n  secrets) come from your repo's GitHub Actions hydration, devcontainer, Nix,\n  mise/asdf, or setup scripts — not from Crabbox.\n\nThe data plane — SSH, rsync, command execution — always runs directly from the\nCLI to the runner. The coordinator only manages leases, cost, and observability.\n\nOnly `aws`, `azure`, `gcp`, and `hetzner` can transfer provider lifecycle to the\ncoordinator, and even those run direct from the CLI when no coordinator URL is\nconfigured. Every other provider runs direct or delegated. A direct-provider mode\n(`--provider hetzner|aws|azure|gcp|digitalocean|linode|proxmox` with local\ncredentials) exists for debugging the coordinator itself or using private\ninfrastructure.\n\n### Coordinator deployment choices\n\n| Path                     | State and scheduling                                          | Best fit                                                                                                                     |\n| ------------------------ | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |\n| **Cloudflare Workers**   | Fleet Durable Object, alarms, scheduled Worker trigger        | Managed edge deployment with minimal server operations and optional Cloudflare Access.                                       |\n| **Node.js + PostgreSQL** | PostgreSQL key/value state, pg-boss alarms and reconciliation | Initial runtime for containers, a VM, or Kubernetes with one replica; requires Node.js, PostgreSQL 13+, TLS, and WebSockets. |\n| **No coordinator**       | Local claims and provider-owned state                         | Personal/direct providers where shared credentials, history, budgets, and central cleanup are unnecessary.                   |\n\nBoth coordinator runtimes expose the same API, GitHub login, portal, provider\nadapters, cost controls, cleanup behavior, and live bridges. State is not\nautomatically migrated between Durable Object storage and PostgreSQL.\nCloudflare is the established deployment; validate the newly shipped Node\nruntime against the production proof checklist before cutover. See\n[Infrastructure](docs/infrastructure.md) for deployment and ingress details.\n\nFor the full mental model, see [How Crabbox Works](docs/how-it-works.md). For\nthe doc-to-code map, see [Source Map](docs/source-map.md).\n\n## Install\n\n```sh\nbrew install openclaw/tap/crabbox\ncrabbox --version\n```\n\nNo Homebrew? Grab a [GoReleaser archive](https://github.com/openclaw/crabbox/releases)\nfor macOS, Linux, or Windows.\n\nApple Silicon Homebrew bottles and archives also include the native\n`crabbox-apple-vz-helper` used by the local Apple VZ provider.\n\nLaptop prerequisites: `git`, `ssh`, `ssh-keygen`, `rsync`, `curl`.\n\n## Quick start\n\nBroker access is deployment-specific. Use a coordinator URL from your team, use\ndirect-provider mode for a personal cloud account, or self-host the broker on\nCloudflare or Node.js/PostgreSQL with your own provider credentials and spend\ncaps. See\n[Getting started](docs/getting-started.md#choosing-an-access-path) and\n[Infrastructure](docs/infrastructure.md#self-hosted-broker-minimum-setup) for the\nsetup paths.\n\n```sh\n# log in once per machine (stores a broker token in user config)\ncrabbox login --url https://broker.example.com\n\n# verify local prerequisites and broker reachability\ncrabbox doctor\n\n# one-shot: lease, sync, run, release\ncrabbox run -- pnpm test\n\n# named repo workflow from .crabbox.yaml\ncrabbox job run full-ci\n\n# or warm a box once, then reuse it\ncrabbox warmup                                       # prints cbx_... + a slug\ncrabbox prewarm                                      # lease + Actions hydration\ncrabbox run --id blue-lobster -- pnpm test:changed\ncrabbox ssh --id blue-lobster\ncrabbox stop blue-lobster\n```\n\nEvery lease has a stable `cbx_...` ID and a friendly crustacean slug\n(`blue-lobster`, `swift-hermit`, …). Either works wherever an `--id` is\naccepted. Use `--slug \u003cname\u003e` on fresh leases when a specific reusable slug\nhelps, and `--label \u003ctext\u003e` on `run` when the history entry needs a\nhuman-readable name.\n\n## Providers\n\n`Brokered` providers can run through either coordinator runtime (or direct when\nno coordinator is configured); every other provider runs direct or delegated\nfrom the CLI.\n\n### SSH-lease providers (provision or connect a box, full lifecycle)\n\n| Provider and aliases | Runs on / mode | Notes |\n| --- | --- | --- |\n| [AWS EC2](docs/providers/aws.md) — `aws` | Linux, macOS, Windows · brokered | EC2 instances and EC2 Mac; native AMI/EBS checkpoints. |\n| [Azure](docs/providers/azure.md) — `azure` | Linux, Windows · brokered | VMs with Tailscale support; native Windows and WSL2. |\n| [Google Cloud](docs/providers/gcp.md) — `gcp` (`google`, `google-cloud`) | Linux · brokered | Compute Engine VMs with Tailscale support. |\n| [Hetzner Cloud](docs/providers/hetzner.md) — `hetzner` | Linux · brokered | VMs with desktop/browser/code and Tailscale. |\n| [DigitalOcean](docs/providers/digitalocean.md) — `digitalocean` | Linux · direct | Droplets with per-lease SSH keys and Crabbox tags. |\n| [Linode](docs/providers/linode.md) — `linode` | Linux · direct | Linode instances with metadata user-data, optional existing firewall attachment, and Crabbox tags. |\n| [Hostinger](docs/providers/hostinger.md) — `hostinger` | Linux · direct | VPS leases over public SSH; explicit purchase opt-in, stop-only release. |\n| [Parallels](docs/providers/parallels.md) — `parallels` | Linux, macOS, Windows · direct | Local or remote macOS host; checkpoint/fork/restore/snapshot. |\n| [Proxmox](docs/providers/proxmox.md) — `proxmox` | Linux · direct | Clone QEMU templates on a private Proxmox VE cluster. |\n| [XCP-ng](docs/providers/xcp-ng.md) — `xcp-ng` | Linux · direct | Self-hosted XCP-ng pool on dedicated x86_64 server hardware. |\n| [Incus](docs/providers/incus.md) — `incus` | Linux · direct | SSH leases through the official Incus Go client. |\n| [Static SSH](docs/providers/ssh.md) — `ssh` (`static`, `static-ssh`) | Linux, macOS, Windows · direct | Existing machines; no provisioning. |\n| [Local Container](docs/providers/local-container.md) — `local-container` (`docker`, `container`, `local-docker`) | Linux · direct | Local Docker-compatible runtime (Docker Desktop, OrbStack, Colima, Podman). |\n| [Apple Container](docs/providers/apple-container.md) — `apple-container` (`apple`, `applecontainer`) | Linux · direct | Apple's native `container` runtime on Apple silicon macOS. |\n| [Apple Container Machine](docs/providers/apple-machine.md) — `apple-machine` (`applemachine`) | Linux · direct | Persistent Linux development machines from Apple Container 1.0, defaulting to Alpine. |\n| [Apple VZ](docs/providers/apple-vz.md) — `apple-vz` (`applevz`) | Linux ARM64 · direct | Full Ubuntu VMs through Apple `Virtualization.framework`; no cloud account or VM daemon. |\n| [exe.dev](docs/providers/exe-dev.md) — `exe-dev` (`exe`, `exedev`) | Linux · direct | exe.dev VMs exposed as public SSH leases. |\n| [KubeVirt](docs/providers/kubevirt.md) — `kubevirt` (`kubernetes-vm`) | Linux · direct | Generic KubeVirt VMs through `kubectl`, `virtctl`, and control-plane SSH forwarding. |\n| [External](docs/providers/external.md) — `external` (`exec-provider`) | Linux · direct | Configured executable implementing the Crabbox provider protocol. |\n| [Namespace Devbox](docs/providers/namespace-devbox.md) — `namespace-devbox` (`namespace`, `namespace-devboxes`) | Linux · direct | Namespace.so Devboxes over SSH. |\n| [Namespace Compute Instance](docs/providers/namespace-instance.md) — `namespace-instance` (`namespace-compute`) | Linux · direct | Namespace Compute instances through `nsc` and SSH. |\n| [Semaphore](docs/providers/semaphore.md) — `semaphore` (`sem`) | Linux · direct | A Semaphore CI job leased as a testbox. |\n| [Sprites](docs/providers/sprites.md) — `sprites` | Linux · direct | Sprites microVMs through `sprite proxy`. |\n| [Tenki](docs/providers/tenki.md) — `tenki` | Linux · direct | Tenki sandbox VMs through `tenki sandbox ssh-proxy`. |\n| [Daytona](docs/providers/daytona.md) — `daytona` | Linux · direct | Daytona-managed dev sandbox over SSH. |\n| [Morph](docs/providers/morph.md) — `morph` | Linux · direct | Morph Cloud snapshot-backed instances over the shared SSH gateway. |\n| [RunPod](docs/providers/runpod.md) — `runpod` (`run-pod`, `runpodio`) | Linux · direct | RunPod GPU pods with public SSH. |\n| [ASCII Box](docs/providers/ascii-box.md) — `ascii-box` (`ascii`, `asciibox`) | Linux · direct | ASCII Box Ubuntu sandboxes exposed as SSH leases. |\n\nXCP-ng itself can host Linux, Windows, and BSD guests, but Crabbox's current\n`xcp-ng` adapter provisions normal leases from Linux templates only. The\nseparate XCP-ng ISO E2E harness also covers Windows x86_64/x64 installers.\nmacOS guests are out of scope on this path; use the Tart provider on Apple\nhardware for macOS VM workflows.\n\n### Delegated-run providers (sandbox/proof runners, no SSH lease)\n\n| Provider and aliases                                                                                           | Runs on      | Notes                                                                           |\n| -------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------- |\n| [Cloudflare](docs/providers/cloudflare.md) — `cloudflare` (`cf`)                                               | Linux        | Cloudflare Containers via the Worker runtime.                                   |\n| [Docker Sandbox](docs/providers/docker-sandbox.md) — `docker-sandbox`                                          | Linux        | Docker Sandboxes through the standalone `sbx` CLI.                              |\n| [E2B](docs/providers/e2b.md) — `e2b`                                                                           | Linux        | E2B Firecracker sandbox.                                                        |\n| [Freestyle](docs/providers/freestyle.md) — `freestyle`                                                         | Linux        | Freestyle VMs through the Freestyle REST API.                                   |\n| [Islo](docs/providers/islo.md) — `islo`                                                                        | Linux        | Islo sandbox.                                                                   |\n| [Modal](docs/providers/modal.md) — `modal`                                                                     | Linux        | Modal Sandbox through the local Python client.                                  |\n| [Microsoft Execution Containers](docs/providers/mxc.md) — `mxc` (`execution-container`)                        | Windows      | Policy-driven local Windows process containment.                                |\n| [OpenComputer](docs/providers/opencomputer.md) — `opencomputer` (`oc`, `open-computer`)                        | Linux        | OpenComputer Linux VMs through the OpenComputer REST API.                       |\n| [OpenSandbox](docs/providers/opensandbox.md) — `opensandbox`                                                   | Linux        | OpenSandbox delegated containers through the OpenSandbox Go SDK.                |\n| [Railway](docs/providers/railway.md) — `railway` (`rail`, `railwayapp`)                                        | Linux        | Redeploy and stream an existing Railway service.                                |\n| [Anthropic Sandbox Runtime](docs/providers/anthropic-sandbox-runtime.md) — `anthropic-sandbox-runtime` (`srt`) | macOS, Linux | Local one-shot sandboxing through Anthropic's `srt` CLI.                        |\n| [SmolVM](docs/providers/smolvm.md) — `smolvm` (`smol`, `smolmachines`, `smolfleet`)                            | Linux        | Smol Machines microVM sandboxes via the smolfleet API.                          |\n| [Tensorlake](docs/providers/tensorlake.md) — `tensorlake` (`tl`, `tensorlake-sbx`)                             | Linux        | Tensorlake Firecracker sandbox via the Tensorlake CLI.                          |\n| [Upstash Box](docs/providers/upstash-box.md) — `upstash-box` (`upstash`, `box`, `upstashbox`)                  | Linux        | Upstash Box through the Box REST API.                                           |\n| [Azure Dynamic Sessions](docs/providers/azure-dynamic-sessions.md) — `azure-dynamic-sessions`                  | Linux        | Azure Container Apps dynamic sessions.                                          |\n| [Blacksmith Testbox](docs/providers/blacksmith-testbox.md) — `blacksmith-testbox` (`blacksmith`)               | Linux        | Delegated Blacksmith CI Testbox lifecycle and execution.                        |\n| [W\u0026B Sandboxes](docs/providers/wandb.md) — `wandb` (`weights-and-biases`)                                      | Linux        | Weights \u0026 Biases Sandboxes; reuses `wandb login` credentials.                   |\n| [Windows Sandbox](docs/providers/windows-sandbox.md) — `windows-sandbox` (`wsb`, `windows-sandbox-provider`)   | Windows      | Disposable Microsoft Windows Sandbox sessions through generated `.wsb` configs. |\n\nSee [Providers](docs/providers/README.md) for the full reference, capabilities,\nand authoring guide.\n\n## Highlights\n\n- **One-shot or warm workspaces.** `crabbox run` for fire-and-forget;\n  `crabbox warmup` + `--id` for raw reusable leases, or `crabbox prewarm` when\n  the box should be hydrated before the first test command. See\n  [warmup](docs/commands/warmup.md), [prewarm](docs/commands/prewarm.md), and\n  [run](docs/commands/run.md).\n- **Named repo jobs.** `crabbox job run \u003cname\u003e` lets repos define warmup,\n  optional Actions hydration, run command, and cleanup policy in `.crabbox.yaml`.\n  See [Jobs](docs/features/jobs.md).\n- **Local-first workspace sync.** No clean-checkout requirement. Tracked and\n  nonignored files only, fingerprint skip on no-op runs, sanity checks against\n  suspicious mass deletions, optional shallow base-ref hydration for\n  changed-test workflows. See [Sync](docs/features/sync.md).\n- **Run observability.** Every coordinator-backed run gets an early `run_...`\n  handle. Use `crabbox attach \u003crun-id\u003e` while it is active,\n  `crabbox events \u003crun-id\u003e` for durable lifecycle/output events, and\n  `crabbox logs \u003crun-id\u003e` for retained output after completion. See\n  [History and logs](docs/features/history-logs.md) and\n  [Observability](docs/observability.md).\n- **GitHub Actions hydration.** `crabbox actions hydrate` runs supported setup\n  steps from the repo's workflow locally over SSH, so leased boxes get the same\n  runtimes and tooling without GitHub write access. Use `--github-runner` only\n  when setup needs full Actions semantics such as repository secrets, OIDC,\n  service containers, or unsupported `uses:` steps. See\n  [Actions hydration](docs/features/actions-hydration.md).\n- **Failure capsules.** `crabbox capsule from-actions \u003crun-url\u003e` captures a\n  failing CI run into a portable, replayable bundle; `capsule replay` reruns it.\n  See [Capsules](docs/features/capsules.md).\n- **Checkpoints.** Save VM-or-workspace state and `restore`/`fork` from it, via\n  workspace archives or provider-native snapshots/images. See\n  [Checkpoints](docs/features/checkpoints.md).\n- **Pond peer groups.** Leases that share a `--pond \u003cname\u003e` label form an\n  emergent peer group with discovery (`pond peers`), an SSH-mesh of\n  `ssh -L` forwards to members' `--expose` ports (`pond connect`), and bulk\n  `pond release`. See [Pond](docs/features/pond.md).\n- **Brokered cloud with cost guardrails.** Maintainers and agents share infra\n  without sharing provider tokens. Hetzner, AWS, Azure, and Google Cloud are\n  the managed providers; per-lease and monthly spend caps reject over-budget\n  leases. Providers fall back across compatible instance families when capacity\n  or quota rejects a request. `crabbox usage` summarizes spend by user, org,\n  provider, and type. See [Coordinator](docs/features/coordinator.md),\n  [Capacity fallback](docs/features/capacity-fallback.md), and\n  [Cost and usage](docs/features/cost-usage.md).\n- **Interactive desktop, browser, and code leases.** `--browser` provisions\n  Chrome/Chromium for headless automation, `--desktop` provisions a visible UI\n  with tunnel-only VNC takeover, and `--code` provisions code-server on managed\n  Linux. `crabbox desktop click/paste/type/key` provide first-class input\n  helpers; `desktop proof` captures metadata, screenshot, diagnostics, MP4, and\n  a contact-sheet PNG in one publishable bundle. See\n  [Interactive desktop and VNC](docs/features/interactive-desktop-vnc.md).\n- **Authenticated web portal.** Browser login opens owner-scoped and shared\n  lease/run views with run logs/events, WebVNC, code-server, and telemetry\n  charts. `crabbox webvnc`/`crabbox code` bridge a lease into the portal;\n  `crabbox share` grants a lease to a user or the owning org. See\n  [Portal](docs/features/portal.md).\n- **Agent workspace evidence.** History, logs, events, telemetry, JUnit\n  summaries, screenshots, recordings, artifacts, and PR publishing make\n  autonomous work reviewable instead of only ephemeral terminal output. See\n  [Artifacts](docs/features/artifacts.md) and\n  [Telemetry](docs/features/telemetry.md).\n- **Stable timing records.** `--timing-json` on `run`, `warmup`, `prewarm`, and\n  `actions hydrate` gives scripts one machine-readable sync/command/total\n  timing schema across providers.\n- **Hardened coordinator auth.** GitHub browser login, owner-scoped leases,\n  admin-only routes, optional GitHub team allowlists, Cloudflare Access JWT\n  verification, and service-token support keep normal use and operator\n  automation separate. See [Auth and admin](docs/features/auth-admin.md) and\n  [Security](docs/security.md).\n\n## Machine classes\n\n`beast` is the default for providers that expose class-based managed capacity.\nThe providers below fall back across ordered instance-type lists unless `--type`\npins a specific provider-native size.\n\n```text\nHetzner    standard  ccx33, cpx62, cx53\n           fast      ccx43, cpx62, cx53\n           large     ccx53, ccx43, cpx62, cx53\n           beast     ccx63, ccx53, ccx43, cpx62, cx53\n\nAWS Linux  standard  c7a/c7i/m7a/m7i.8xlarge family\n           fast      …16xlarge family\n           large     …24xlarge family\n           beast     …48xlarge family, falling back to 32x/24x/16x\n           arm64     c7g/m7g/r7g families with --arch arm64\n\nAWS Win    standard  m7i.large, m7a.large, t3.large\n           fast      m7i.xlarge, m7a.xlarge, t3.xlarge\n           large     m7i.2xlarge, m7a.2xlarge, t3.2xlarge\n           beast     m7i.4xlarge, m7a.4xlarge, m7i.2xlarge\n\nAWS WSL2   standard  m8i.large, m8i-flex.large, c8i.large, r8i.large\n           fast      m8i.xlarge, m8i-flex.xlarge, c8i.xlarge, r8i.xlarge\n           large     m8i.2xlarge, m8i-flex.2xlarge, c8i.2xlarge, r8i.2xlarge\n           beast     m8i.4xlarge, m8i-flex.4xlarge, c8i.4xlarge, r8i.4xlarge, m8i.2xlarge\n\nAWS macOS  all       mac2.metal, then mac1.metal unless --type is set\n\nAzure      standard  Standard_D32ads_v6, Standard_D32ds_v6, Standard_F32s_v2, then 16-vCPU fallbacks\n           fast      Standard_D64ads_v6, Standard_D64ds_v6, Standard_F64s_v2, then 48/32-vCPU fallbacks\n           large     Standard_D96ads_v6, Standard_D96ds_v6, then 64/48-vCPU fallbacks\n           beast     Standard_D192ds_v6, Standard_D128ds_v6, then 96/64-vCPU fallbacks\n           arm64     Standard_D*ps_v6 / D*pds_v6 Cobalt families with --arch arm64\n\nAzure Win/\nWSL2       standard  Standard_D2ads_v6, Standard_D2ds_v6, Standard_D2ads_v5, Standard_D2ds_v5, Standard_D2as_v6\n           fast      Standard_D4ads_v6, Standard_D4ds_v6, Standard_D4ads_v5, Standard_D4ds_v5, Standard_D4as_v6\n           large     Standard_D8ads_v6, Standard_D8ds_v6, Standard_D8ads_v5, Standard_D8ds_v5, Standard_D8as_v6\n           beast     Standard_D16ads_v6, Standard_D16ds_v6, Standard_D16ads_v5, Standard_D16ds_v5, Standard_D8ads_v6\n\nNamespace  standard  S\n           fast      M\n           large     L\n           beast     XL\n\nNamespace\nCompute    standard  4x8\n           fast      8x16\n           large     16x32\n           beast     32x64\n\nCloudflare standard  standard-4\n           fast      standard-4\n           large     standard-4\n           beast     standard-4\n```\n\nOverride with `--type` or `CRABBOX_SERVER_TYPE` for a specific instance. Use\n`--arch arm64` / `architecture: arm64` for Linux ARM capacity on Azure or AWS;\nexplicit ARM provider types also select ARM images when no custom image is set.\nCloudflare also accepts `lite`, `basic`, `standard-1`, `standard-2`, and\n`standard-3` as smaller explicit `--type` values; `standard-4` is the default.\nProviders without a row either use provider-native capacity settings or reject\nclass/type selection.\n\n## Configuration\n\nConfig resolves in order: flags → env → repo `.crabbox.yaml` → user\n`~/.config/crabbox/config.yaml` → defaults.\n\n```yaml\nbroker:\n  url: https://broker.example.com\n  provider: aws\n  token: ...\nclass: beast\ncapacity:\n  market: spot\n  strategy: most-available\n  fallback: on-demand-after-120s\n  hints: true\naws:\n  region: eu-west-1\n  rootGB: 400\nlease:\n  idleTimeout: 30m\n  ttl: 90m\nssh:\n  key: ~/.ssh/id_ed25519\n  user: crabbox\n  port: \"2222\"\n  # Ordered fallback ports tried after ssh.port; use [] to disable fallback.\n  fallbackPorts:\n    - \"22\"\n```\n\nSet `broker.mode: registered` to keep provisioning and cleanup in any direct\nprovider while registering lease metadata with the coordinator for inventory,\nsharing, and portal WebVNC. Kept desktop leases start the outbound WebVNC bridge\nautomatically by default; set `broker.autoWebVNC: false` to opt out. The\ncoordinator never receives provider credentials or directly calls a registered\nprovider. By default it removes only registration metadata; an explicitly\nbound outbound runtime adapter can perform a user-confirmed workspace delete.\n\nForwarded environment is intentionally narrow: `NODE_OPTIONS` and `CI`. Do not\npass secrets as command-line arguments. For live-secret smoke tests, use\n`crabbox run --env-from-profile \u003cfile\u003e --allow-env NAME` so Crabbox forwards\nonly selected names and prints redacted presence/length metadata. For stale warm\nboxes, `--full-resync` (alias `--fresh-sync`) resets the remote workdir before\nsyncing. For larger commands, use `--script \u003cfile\u003e` or `--script-stdin` so the\nremote runner executes an uploaded file instead of a giant quoted shell string.\n\nFor binary or terminal-hostile output, use `crabbox run --capture-stdout \u003cpath\u003e`\nor `--capture-stderr \u003cpath\u003e`. Add `--preflight` for a remote capability\nsnapshot, `--keep-on-failure` to SSH into the exact failed one-shot lease, or\n`--download remote=local` to copy a successful-run artifact back. Failed\nSSH-backed and Blacksmith delegated runs save local `.crabbox/captures/*.tar.gz`\nbundles by default. Captured files are not redacted by Crabbox.\n\nOptional Tailscale reachability for managed Linux leases:\n\n```yaml\ntailscale:\n  enabled: true\n  network: auto\n  tags:\n    - tag:crabbox\n  hostnameTemplate: crabbox-{slug}\n  authKeyEnv: CRABBOX_TAILSCALE_AUTH_KEY\n  exitNode: mac-studio.example.ts.net\n  exitNodeAllowLanAccess: true\n```\n\nTailscale is a network plane, not a provider. `--tailscale` joins new managed\nLinux leases to the tailnet; `--network auto|tailscale|public` chooses how SSH\nand VNC tunnel commands resolve the host. Brokered mode uses Worker OAuth\nsecrets to mint one-off keys; direct-provider mode reads the auth key from the\nconfigured env var. See [Tailscale](docs/features/tailscale.md).\n\nA few provider-specific config snippets:\n\n```yaml\n# Static macOS or Windows target (existing machine, no provisioning)\nprovider: ssh\ntarget: windows\nwindows:\n  mode: normal # or wsl2\nstatic:\n  host: win-dev.local\n  user: alice\n  port: \"22\"\n  workRoot: C:\\crabbox\n```\n\n```yaml\n# Local container (alias: docker; detects docker or podman)\nprovider: local-container\nlocalContainer:\n  runtime: docker\n  image: debian:bookworm\n  workRoot: /work/crabbox\n```\n\n```yaml\n# Delegated Blacksmith CI Testbox\nprovider: blacksmith-testbox\nblacksmith:\n  org: example-org\n  workflow: .github/workflows/ci-check-testbox.yml\n  job: test\n  ref: main\n  idleTimeout: 90m\n```\n\nKeep provider tokens in environment variables, not repo config (for example\n`CRABBOX_SEMAPHORE_TOKEN`, `CRABBOX_SPRITES_TOKEN`, `RUNPOD_API_KEY`,\n`MORPH_API_KEY`, `ASCII_BOX_API_KEY`, `E2B_API_KEY`, `DAYTONA_API_KEY`). The full env-var\nreference, per-provider sections, and per-command flags are in\n[docs/cli.md](docs/cli.md), [Configuration](docs/features/configuration.md),\nand the [provider docs](docs/providers/README.md).\n\n## Development\n\n```sh\n# Go CLI\ngo build -trimpath -o bin/crabbox ./cmd/crabbox\ngo vet ./...\ngo test -race ./...\n\n# Coordinator runtimes (Node 22+ locally; CI runs Node 24)\nnpm ci --prefix worker\nnpm test --prefix worker\nnpm run build --prefix worker\nnpm run check:node --prefix worker\nnpm run build:node --prefix worker\n\n# Repository scripts\nnode --test scripts/*.test.js\n\n# Docs\nscripts/check-docs.sh\n\n# Optional live smoke, when broker/provider credentials are available\nCRABBOX_LIVE=1 CRABBOX_LIVE_REPO=/path/to/my-app scripts/live-smoke.sh\n```\n\nCI runs the full gate (gofmt, vet, race tests, all Go modules, coverage\nthreshold, repository script tests, docs link/build check, GoReleaser snapshot, and Worker\nlint/typecheck/tests/build) on every push and PR. Tagged pushes matching `v*`\npublish Go archives via GoReleaser and bump the Homebrew formula at\n[openclaw/homebrew-tap](https://github.com/openclaw/homebrew-tap).\n\nCloudflare, Node/PostgreSQL, container, ingress, secrets, and DNS deployment live in\n[docs/infrastructure.md](docs/infrastructure.md).\n\n## Docs\n\n- **Get the model:** [How Crabbox Works](docs/how-it-works.md), [Architecture](docs/architecture.md), [Concepts](docs/concepts.md), [Orchestrator](docs/orchestrator.md)\n- **Use the CLI:** [CLI](docs/cli.md), [Commands](docs/commands/README.md), [Features](docs/features/README.md), [Configuration](docs/features/configuration.md)\n- **Choose a provider:** [Providers](docs/providers/README.md), [AWS](docs/providers/aws.md), [Azure](docs/providers/azure.md), [GCP](docs/providers/gcp.md), [Hetzner](docs/providers/hetzner.md), [DigitalOcean](docs/providers/digitalocean.md), [Linode](docs/providers/linode.md), [Hostinger](docs/providers/hostinger.md)\n- **Advanced features:** [Actions hydration](docs/features/actions-hydration.md), [Capsules](docs/features/capsules.md), [Checkpoints](docs/features/checkpoints.md), [Jobs](docs/features/jobs.md), [Pond](docs/features/pond.md)\n- **Interactive QA:** [Interactive Desktop and VNC](docs/features/interactive-desktop-vnc.md), [Artifacts](docs/features/artifacts.md), [Portal](docs/features/portal.md)\n- **Integrate infrastructure:** [Bring Your Own Infrastructure](docs/features/bring-your-own-infrastructure.md), [Portable Coordinator](docs/features/portable-coordinator.md), [External Provider](docs/providers/external.md)\n- **Operate it:** [Operations](docs/operations.md), [Observability](docs/observability.md), [Troubleshooting](docs/troubleshooting.md), [Performance](docs/performance.md)\n- **Set it up or audit it:** [Infrastructure](docs/infrastructure.md), [Security](docs/security.md), [Getting Started](docs/getting-started.md), [Source Map](docs/source-map.md)\n- **Changes:** [CHANGELOG.md](CHANGELOG.md)\n\nThe GitHub Pages site at \u003chttps://openclaw.github.io/crabbox/\u003e is generated from\nthe `docs/` Markdown:\n\n```sh\nscripts/check-docs.sh\nopen dist/docs-site/index.html\n```\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenclaw%2Fcrabbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenclaw%2Fcrabbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenclaw%2Fcrabbox/lists"}