openclaw/crabbox
GitHub: openclaw/crabbox
Crabbox 是一个远程软件测试与执行控制平面，让开发者和自动化流程能够在云端或委托的 runner 上按需运行仓库命令，同时保留本地开发工作流。
Stars: 1157 | Forks: 138
# 🦀 📦 Crabbox
[](https://github.com/openclaw/crabbox/actions/workflows/ci.yml)
[](https://github.com/openclaw/crabbox/actions/workflows/release.yml)
[](https://github.com/openclaw/crabbox/releases/latest)
**预热一个 box，同步 diff，运行测试套件。**
Crabbox 是一个通用的远程软件测试与执行控制平面。它适用于需要在个人笔记本电脑以外的其他地方运行仓库命令的维护者、贡献者和自动化流程：例如在托管的云资源、现有的 SSH 主机上，或委托的沙箱 provider 中。Crabbox 保留了本地“编辑-保存-运行”的工作流，但将那些昂贵或需要产出证据的工作转移到了远程 runner 上。
```
crabbox run -- pnpm test
```
在这一条命令的背后，Crabbox 会租用或选择一个 runner，同步当前工作树，远程运行命令，回流输出结果，记录证据，最后释放或取消声明目标机器。该系统由你机器上的一个 Go CLI、一个掌握 provider 凭据和租约状态的可选 coordinator，以及一个受管理或委托的 runner 组成。你可以在带有 Durable Object 的 Cloudflare Workers 上运行 coordinator，也可以将其作为由 PostgreSQL 支持的 Node.js 服务。
## Crabbox 的适用人群
Crabbox 适合那些需要可重复的远程执行，但不想把每次测试运行都变成定制 CI 任务的团队和工具：
- 需要更快或性能更强的机器来运行测试套件、构建、浏览器检查或特定平台验证的维护者；
- 想要一个与仓库设置脚本匹配的一次性环境，并且能在运行结束后释放的贡献者；
- 需要从可审计的远程 box 获取命令输出、日志、制品和运行历史的 AI agent 及其他自动化工具；
- 希望使用由 coordinator 统一管理的云凭据、支出上限、清理机制和共享使用记录，而不是在本地使用长期有效的 provider 密钥的团队。
当本地计算太慢、目标平台在其他地方、工作流需要一个干净的一次性 runner，或者审查者需要获取所运行确切命令的流式证据时，请使用 Crabbox。请勿将其用作 CI 的替代品、对抗性多租户沙箱、密钥清理器，或互不信任用户之间的隔离边界。
## 信任模型
Crabbox 是一款开发者执行工具，而不是一个对抗性的多租户平台或统一的安全沙箱。它假定本地 OS 用户、仓库配置、配置的项目工具链以及经过身份验证的 coordinator 操作者都是可信的。仓库配置属于可执行的项目自动化：它可以运行本地辅助程序、选择运行时、挂载主机资源，并控制开发基础设施。在运行 Crabbox 之前，请先审查不熟悉的仓库。
可选的 coordinator 适用于协作且互信的团队。其身份验证、所有权和共享控制机制可以防止未经授权的访问和意外的跨所有者操作，但并不提供互为对抗的租户之间的隔离。请参阅[安全策略](SECURITY.md)了解支持的边界，并参阅[操作安全](docs/security.md)获取部署指南。
在此边界内，带有凭据的 HTTP 重定向仅限于其配置的源；破坏性的 provider 恢复需要精确的本地声明或更强的 provider 端所有权元数据；制品发布仅接受所选 bundle 中的常规文件。Provider 诊断会在文档记录的客户端上隐藏配置的凭据，但捕获的输出和失败 bundle 不会被自动清理；在共享之前请先进行审查。请参阅[操作安全](docs/security.md)和[制品](docs/features/artifacts.md)。
## 工作原理
```
your laptop coordinator runtime cloud provider
------------- ------------------- --------------
crabbox CLI -- HTTPS --> Cloudflare + Durable Object --> Hetzner / AWS / Azure / GCP
| or Node.js + PostgreSQL |
| |
+------------- SSH + rsync to leased runner <---------------+
```
- **CLI** — Go 二进制程序。加载配置，生成单次租约的 SSH 密钥，向 broker 请求租约，等待 SSH 就绪，初始化远程 Git，rsync 同步带有未提交更改的 checkout（在没有任何更改时通过指纹跳过），运行命令，回流输出，释放租约。
- **Coordinator** — 运行于 Cloudflare Workers 加 Fleet Durable Object，或者 Node.js 加 PostgreSQL 和 pg-boss 之上的同一套集群控制平面。它负责管理 provider 凭据，序列化租约状态，执行活跃租约和每月支出上限，并使过期的租约失效。身份验证方式包括 GitHub 浏览器登录、共享的 bearer token，或显式受信任的身份代理。
- **Runner** — 一台可通过 SSH 在主端口（默认为 `2222`）及配置的备用端口访问的一次性机器，已准备好 Crabbox 的同步/运行前置条件。Linux 使用带有 cloud-init 的 Ubuntu 系统以及 `/work/crabbox` 目录；原生 Windows 使用 OpenSSH、Git for Windows 和 `C:\crabbox`。机器上不存储任何 broker 凭据。项目运行时（Go、Node、Docker、服务、密钥等）来自于你仓库中的 GitHub Actions 水合、devcontainer、Nix、mise/asdf 或设置脚本，而不是由 Crabbox 提供。
数据平面 — SSH、rsync、命令执行 — 始终直接从 CLI 运行到 runner 上。Coordinator 仅管理租约、成本和可观测性。只有 `aws`、`azure`、`gcp` 和 `hetzner` 能够将 provider 生命周期转移给 coordinator，而且即使如此，在未配置 coordinator URL 时，它们也会直接通过 CLI 运行。所有其他 provider 均以直接或委托方式运行。存在一种 direct-provider 模式（带有本地凭据的 `--provider hetzner|aws|azure|gcp|digitalocean|linode|proxmox`），用于调试 coordinator 本身或使用私有基础设施。
### Coordinator 部署选项
| 路径 | 状态与调度 | 最适合 |
| ------------------------ | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Cloudflare Workers** | Fleet Durable Object、定时器、计划的 Worker 触发器 | 托管的边缘部署，只需最少的服务器操作及可选的 Cloudflare Access。 |
| **Node.js + PostgreSQL** | PostgreSQL 键/值状态，pg-boss 定时器与对账 | 适用于容器、虚拟机或具有单个副本的 Kubernetes 的初始运行时；需要 Node.js、PostgreSQL 13+、TLS 和 WebSockets。 |
| **无 coordinator** | 本地声明与 provider 拥有的状态 | 个人的/直接的 provider，此类场景下不需要共享凭据、历史记录、预算和集中清理。 |
两种 coordinator 运行时都暴露相同的 API、GitHub 登录、portal、provider 适配器、成本控制、清理行为和实时桥接。状态不会在 Durable Object 存储和 PostgreSQL 之间自动迁移。Cloudflare 是成熟的部署方案；在正式切换前，请根据生产就绪检查清单验证最新发布的 Node 运行时。有关部署和流量路由的详细信息，请参阅[基础设施](docs/infrastructure.md)。
要了解完整的概念模型，请参阅 [Crabbox 的工作原理](docs/how-it-works.md)。有关文档与代码的映射，请参阅[源码映射](docs/source-map.md)。
## 安装
```
brew install openclaw/tap/crabbox
crabbox --version
```
没有 Homebrew？请获取适用于 macOS、Linux 或 Windows 的 [GoReleaser 归档](https://github.com/openclaw/crabbox/releases)。
Apple Silicon 的 Homebrew bottles 和归档文件还包含了本地 Apple VZ provider 使用的原生 `crabbox-apple-vm-helper`。
笔记本电脑前置条件：`git`、`ssh`、`ssh-keygen`、`rsync`、`curl`。
## 快速开始
Broker 的访问方式因具体部署而异。你可以使用团队提供的 coordinator URL，针对个人云账户使用 direct-provider 模式，或者在 Cloudflare 或 Node.js/PostgreSQL 上使用你自己的 provider 凭据和支出上限自托管 broker。请参阅[入门指南](docs/getting-started.md#choosing-an-access-path)和[基础设施](docs/infrastructure.md#self-hosted-broker-minimum-setup)了解设置路径。
```
# 每台机器登录一次（在用户配置中存储 broker token）
crabbox login --url https://broker.example.com
# 验证本地前置条件和 broker 可达性
crabbox doctor
# 一次性执行：lease、sync、run、release
crabbox run -- pnpm test
# 通过 .crabbox.yaml 实现 named repo workflow
crabbox job run full-ci
# 或者预热一个 box，然后复用它
crabbox warmup # prints cbx_... + a slug
crabbox prewarm # lease + Actions hydration
crabbox run --id blue-lobster -- pnpm test:changed
crabbox connect blue-lobster # open an interactive SSH session
crabbox ssh --id blue-lobster
crabbox stop blue-lobster
```
每个租约都有一个稳定的 `cbx_...` ID 和一个友好的甲壳类动物别名 (`blue-lobster`, `swift-hermit`, …)。两者在支持 `--id` 的任何地方都有效。当特定的可复用别名有帮助时，可以在新的租约上使用 `--slug `；当历史记录条目需要人类可读的名称时，可以在 `run` 命令上使用 `--label `。
## Providers
`Brokered` 的 provider 可以通过任意一种 coordinator 运行时运行（或者在未配置 coordinator 时直接运行）；所有其他 provider 均由 CLI 直接或以委托方式运行。
### SSH 租约 provider（配置或连接一个 box，完整生命周期）
| Provider 和别名 | 运行于 / 模式 | 备注 |
| --- | --- | --- |
| [AWS EC2](docs/providers/aws.md) — `aws` | Linux, macOS, Windows · brokered | EC2 实例和 EC2 Mac；原生 AMI/EBS 检查点。 |
| [Azure](docs/providers/azure.md) — `azure` | Linux, Windows · brokered | 支持 Tailscale 的 VM；原生 Windows 和 WSL2。 |
| [Google Cloud](docs/providers/gcp.md) — `gcp` (`google`, `google-cloud`) | Linux · brokered | 支持 Tailscale 的 Compute Engine VM。 |
| [Hetzner Cloud](docs/providers/hetzner.md) — `hetzner` | Linux · brokered | 带有桌面/浏览器/代码支持和 Tailscale 的 VM。 |
| [DigitalOcean](docs/providers/digitalocean.md) — `digitalocean` | Linux · direct | 带有单次租约 SSH 密钥和 Crabbox 标签的 Droplets。 |
| [Linode](docs/providers/linode.md) — `linode` | Linux · direct | 带有元数据 user-data、可选现有防火墙附加以及 Crabbox 标签的 Linode 实例。 |
| [Hostinger](docs/providers/hostinger.md) — `hostinger` | Linux · direct | 通过公共 SSH 的 VPS 租约；显式购买选择加入，仅支持停止释放。 |
| [Parallels](docs/providers/parallels.md) — `parallels` | Linux, macOS, Windows · direct | 本地或远程 macOS 主机；检查点/fork/恢复/快照。 |
| [Proxmox](docs/providers/proxmox.md) — `proxmox` | Linux · direct | 在私有 Proxmox VE 集群上克隆 QEMU 模板。 |
| [XCP-ng](docs/providers/xcp-ng.md) — `xcp-ng` | Linux · direct | 在专用 x86_64 服务器硬件上自托管的 XCP-ng 资源池。 |
| [Incus](docs/providers/incus.md) — `incus` | Linux · direct | 通过官方 Incus Go 客户端进行 SSH 租约。 |
| [Firecracker](docs/providers/firecracker.md) — `firecracker` | Linux · direct | 在带有准备好的 kernel、rootfs 和 CNI 的 Linux KVM 主机上自托管的 Firecracker microVM 租约。 |
| [Static SSH](docs/providers/ssh.md) — `ssh` (`static`, `static-ssh`) | Linux, macOS, Windows · direct | 现有机器；无需进行配置。 |
| [Local Container](docs/providers/local-container.md) — `local-container` (`docker`, `container`, `local-docker`) | Linux · direct | 本地兼容 Docker 的运行时 (Docker Desktop, OrbStack, Colima, Podman)。 |
| [Apple Container](docs/providers/apple-container.md) — `apple-container` (`apple`, `applecontainer`) | Linux · direct | Apple silicon macOS 上的原生 `container` 运行时。 |
| [Apple Container Machine](docs/providers/apple-machine.md) — `apple-machine` (`applemachine`) | Linux · direct | 来自 Apple Container 1.0 的持久 Linux 开发机，默认使用 Alpine。 |
| [Apple VZ](docs/providers/apple-vm.md) — `apple-vm` (`applevm`) | Linux ARM64 · direct | 通过 Apple `Virtualization.framework` 实现的完整 Ubuntu VM；无需云账户或 VM 守护进程。 |
| [exe.dev](docs/providers/exe-dev.md) — `exe-dev` (`exe`, `exedev`) | Linux · direct | 作为公共 SSH 租约暴露的 exe.dev VM。 |
| [KubeVirt](docs/providers/kubevirt.md) — `kubevirt` (`kubernetes-vm`) | Linux · direct | 通过 `kubectl`、`virtctl` 和控制平面 SSH 转发实现的通用 KubeVirt VM。 |
| [External](docs/providers/external.md) — `external` (`exec-provider`) | Linux · direct | 实现了 Crabbox provider 协议的可配置可执行文件。 |
| [Namespace Devbox](docs/providers/namespace-devbox.md) — `namespace-devbox` (`namespace`, `namespace-devboxes`) | Linux · direct | 通过 SSH 连接的.so Devbox。 |
| [Namespace Compute Instance](docs/providers/namespace-instance.md) — `namespace-instance` (`namespace-compute`) | Linux · direct | 通过 `nsc` 和 SSH 连接的 Namespace Compute 实例。 |
| [Semaphore](docs/providers/semaphore.md) — `semaphore` (`sem`) | Linux · direct | 作为测试盒租用的 Semaphore CI 作业。 |
| [Sprites](docs/providers/sprites.md) — `sprites` | Linux · direct | 通过 `sprite proxy` 实现的 Sprites microVM。 |
| [Tenki](docs/providers/tenki.md) — `tenki` | Linux · direct | 通过 `tenki sandbox ssh-proxy` 实现的 Tenki 沙箱 VM。 |
| [Coder](docs/providers/coder.md) — `coder` | Linux · direct | 通过 `coder ssh --stdio` 实现的 Coder 工作区；默认停止，仅在明确选择加入时删除。 |
| [Daytona](docs/providers/daytona.md) — `daytona` | Linux · direct | 通过 SSH 连接的由 Daytona 管理的开发沙箱。 |
| [Morph](docs/providers/morph.md) — `morph` | Linux · direct | 通过共享 SSH 网关连接，基于 Morph Cloud 快照的实例。 |
| [RunPod](docs/providers/runpod.md) — `runpod` (`run-pod`, `runpodio`) | Linux · direct | 带有公共 SSH 的 RunPod GPU pod。 |
| [ASCII Box](docs/providers/ascii-box.md) — `ascii-box` (`ascii`, `asciibox`) | Linux · direct | 作为 SSH 租约暴露的 ASCII Box Ubuntu 沙箱。 |
XCP-ng 本身可以托管 Linux、Windows 和 BSD 客户机，但 Crabbox 当前的 `xcp-ng` 适配器仅通过 Linux 模板配置标准租约。单独的 XCP-ng ISO E2E 测试套件还涵盖 Windows x86_64/x64 安装程序。此路径不支持 macOS 客户机；如需 macOS VM 工作流，请在 Apple 硬件上使用 Tart provider。
### 委托运行的 provider（沙箱/验证 runner，无 SSH 租约）
| Provider 和别名 | 运行于 | 备注 |
| -------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------- |
| [AWS Lambda MicroVM](docs/providers/aws-lambda-microvm.md) — `aws-lambda-microvm` | Linux ARM64 | Lambda Firecracker MicroVM，支持归档同步、保留重用以及暂停/恢复。 |
| [Cloudflare](docs/providers/cloudflare.md) — `cloudflare` (`cf`) | Linux | 通过 Worker 运行时实现的 Cloudflare Containers。 |
| [Docker Sandbox](docs/providers/docker-sandbox.md) — `docker-sandbox` | Linux | 通过独立 `sbx` CLI 实现的 Docker 沙箱。 |
| [E2B](docs/providers/e2b.md) — `e2b` | Linux | E2B Firecracker 沙箱。 |
| [Freestyle](docs/providers/freestyle.md) — `freestyle` | Linux | 通过 Freestyle REST API 实现的 Freestyle VM。 |
| [Islo](docs/providers/islo.md) — `islo` | Linux | Islo 沙箱。 |
| [Modal](docs/providers/modal.md) — `modal` | Linux | 通过本地 Python 客户端实现的 Modal Sandbox。 |
| [Microsoft Execution Containers](docs/providers/mxc.md) — `mxc` (`execution-container`) | Windows | 基于策略的本地 Windows 进程容器隔离。 |
| [OpenComputer](docs/providers/opencomputer.md) — `opencomputer` (`oc`, `open-computer`) | Linux | 通过 OpenComputer REST API 实现的 OpenComputer Linux VM。 |
| [OpenSandbox](docs/providers/opensandbox.md) — `opensandbox` | Linux | 通过 OpenSandbox Go SDK 实现的 OpenSandbox 委托容器。 |
| [Railway](docs/providers/railway.md) — `railway` (`rail`, `railwayapp`) | Linux | 重新部署并回流现有 Railway 服务的输出。 |
| [Anthropic Sandbox Runtime](docs/providers/anthropic-sandbox-runtime.md) — `anthropic-sandbox-runtime` (`srt`) | macOS, Linux | 通过 Anthropic 的 `srt` CLI 实现的本地一次性沙箱。 |
| [SmolVM](docs/providers/smolvm.md) — `smolvm` (`smol`, `smolmachines`, `smolfleet`) | Linux | 通过 smolfleet API 实现的 Smol Machines microVM 沙箱。 |
| [Tensorlake](docs/providers/tensorlake.md) — `tensorlake` (`tl`, `tensorlake-sbx`) | Linux | 通过 Tensorlake CLI 实现的 Tensorlake Firecracker 沙箱。 |
| [Upstash Box](docs/providers/upstash-box.md) — `upstash-box` (`upstash`, `box`, `upstashbox`) | Linux | 通过 Box REST API 实现的 Upstash Box。 |
| [Azure Dynamic Sessions](docs/providers/azure-dynamic-sessions.md) — `azure-dynamic-sessions` | Linux | Azure Container Apps 动态会话。 |
| [Blacksmith Testbox](docs/providers/blacksmith-testbox.md) — `blacksmith-testbox` (`blacksmith`) | Linux | 委托的 Blacksmith CI Testbox 生命周期与执行。 |
| [W&B Sandboxes](docs/providers/wandb.md) — `wandb` (`weights-and-biases`) | Linux | Weights & Biases 沙箱；重用 `wandb login` 凭据。 |
| [Windows Sandbox](docs/providers/windows-sandbox.md) — `windows-sandbox` (`wsb`, `windows-sandbox-provider`) | Windows | 通过生成的 `.wsb` 配置实现的一次性 Microsoft Windows Sandbox 会话。 |
有关完整的参考、功能支持和编写指南，请参阅 [Providers](docs/providers/README.md)。
## 核心亮点
- **一次性或预热的工作区。** 使用 `crabbox run` 进行即发即弃的操作；使用 `crabbox warmup` + `--id` 获取原始可重用租约，或者在希望在第一个测试命令运行前先完成 box 的初始化时使用 `crabbox prewarm`。请参阅 [warmup](docs/commands/warmup.md)、[prewarm](docs/commands/prewarm.md) 和 [run](docs/commands/run.md)。
- **命名的仓库作业。** `crabbox job run ` 允许仓库在 `.crabbox.yaml` 中定义预热、可选的 Actions 水合、运行命令和清理策略。请参阅 [Jobs](docs/features/jobs.md)。
- **本地优先的工作区同步。** 无需干净的 checkout。仅同步被追踪和未被忽略的文件，无操作运行时通过指纹跳过，对可疑的大量删除进行完整性检查，为已更改测试的工作流提供可选的浅层基础 ref 水合。请参阅 [Sync](docs/features/sync.md)。
- **运行时可观测性。** 每次由 coordinator 支持的运行都会在早期获得一个 `run_...` 句柄。在运行活跃时使用 `crabbox attach `，通过 `crabbox events ` 查看持久的生命周期/输出事件，并在完成后使用 `crabbox logs ` 查看保留的输出。请参阅[历史和日志](docs/features/history-logs.md)及[可观测性](docs/observability.md)。
- **GitHub Actions 水合。** `crabbox actions hydrate` 会在本地通过 SSH 运行仓库工作流中支持的设置步骤，使得租用的 box 能够在不需要 GitHub 写入权限的情况下获得相同的运行时和工具链。仅在设置需要完整的 Actions 语义（如仓库密钥、OIDC、服务容器或不支持的 `uses:` 步骤）时，才使用 `--github-runner`。请参阅 [Actions hydration](docs/features/actions-hydration.md)。
- **失败胶囊。** `crabbox capsule from-actions ` 将失败的 CI 运行捕获为可移植且可重放的 bundle；使用 `capsule replay` 重新运行它。请参阅[Capsules](docs/features/capsules.md)。
- **检查点。** 通过工作区归档或 provider 原生的快照/镜像保存 VM 或工作区状态，并从中进行 `restore`/`fork`。请参阅[检查点](docs/features/checkpoints.md)。
- **Pond 对等组。** 共享同一个 `--pond ` 标签的租约会形成一个动态的对等组，具备发现功能 (`pond peers`)、由通向成员 `--expose` 端口的 `ssh -L` 转发组成的 SSH 网络 (`pond connect`)，以及批量操作 `pond release`。请参阅[Pond](docs/features/pond.md)。
- **带有成本防护的托管云。** 维护者和 agent 可以在不共享 provider token 的情况下共享基础设施。Hetzner、AWS、Azure 和 Google Cloud 是受管理的 provider；单次租约和每月支出上限会拒绝超出预算的租约。当容量或配额拒绝请求时，provider 会在兼容的实例系列中进行回退。`crabbox usage` 按用户、组织、provider 和类型汇总支出。请参阅[Coordinator](docs/features/coordinator.md)、[容量回退](docs/features/capacity-fallback.md)和[成本与使用量](docs/features/cost-usage.md)。
- **交互式桌面、浏览器和代码租约。** `--browser` 为无头自动化配置 Chrome/Chromium，`--desktop` 配置一个带可见 UI 且仅限隧道访问的 VNC 接管，而 `--code` 在受管理的 Linux 上配置 code-server。`crabbox desktop click/paste/type/key` 提供了一流的输入辅助工具；`desktop proof` 将元数据、截图、诊断信息、MP4 和联系表 PNG 捕获到一个可发布的 bundle 中。请参阅[交互式桌面和 VNC](docs/features/interactive-desktop-vnc.md)。
- **经过身份验证的 Web portal。** 浏览器登录会打开具有所有者作用域和共享作用的租约/运行视图，查看运行日志/事件、WebVNC、code-server 和遥测图表。`crabbox webvnc`/`crabbox code` 会将租约桥接到 portal 中；`crabbox share` 将租约授予某个用户或所属组织。请参阅[Portal](docs/features/portal.md)。
- **Agent 工作区证据。** 历史记录、日志、事件、遥测数据、JUnit 摘要、截图、录像、制品以及 PR 发布功能，使得对自主工作的审查成为可能，而不再仅仅是一时的终端输出。请参阅[制品](docs/features/artifacts.md)和[遥测](docs/features/telemetry.md)。
- **稳定的时间记录。** 在 `run`、`warmup`、`prewarm` 和 `actions hydrate` 上使用 `--timing-json`，可以为脚本在各种 provider 之间提供一套统一的、机器可读的同步/命令/总耗时 schema。
- **Coordinator 访问控制。** GitHub 浏览器登录、所有者作用域的租约、仅限管理员的路径、可选的 GitHub 团队允许列表、Cloudflare Access JWT 验证以及对 service-token 的支持，将日常使用与操作者自动化区分开来。请参阅[身份验证与管理](docs/features/auth-admin.md)及[安全策略](SECURITY.md)。
## 机器类型
对于暴露基于类型的受管容量的 provider，`beast` 是默认选项。除非使用 `--type` 指定了特定的 provider 原生大小，否则以下 provider 会在已排序的实例类型列表中进行回退。
```
Hetzner standard ccx33, cpx62, cx53
fast ccx43, cpx62, cx53
large ccx53, ccx43, cpx62, cx53
beast ccx63, ccx53, ccx43, cpx62, cx53
AWS Linux standard c7a/c7i/m7a/m7i.8xlarge family
fast …16xlarge family
large …24xlarge family
beast …48xlarge family, falling back to 32x/24x/16x
arm64 c7g/m7g/r7g families with --arch arm64
AWS Win standard m7i.large, m7a.large, t3.large
fast m7i.xlarge, m7a.xlarge, t3.xlarge
large m7i.2xlarge, m7a.2xlarge, t3.2xlarge
beast m7i.4xlarge, m7a.4xlarge, m7i.2xlarge
AWS WSL2 standard m8i.large, m8i-flex.large, c8i.large, r8i.large
fast m8i.xlarge, m8i-flex.xlarge, c8i.xlarge, r8i.xlarge
large m8i.2xlarge, m8i-flex.2xlarge, c8i.2xlarge, r8i.2xlarge
beast m8i.4xlarge, m8i-flex.4xlarge, c8i.4xlarge, r8i.4xlarge, m8i.2xlarge
AWS macOS all mac2.metal, then mac1.metal unless --type is set
Azure standard Standard_D32ads_v6, Standard_D32ds_v6, Standard_F32s_v2, then 16-vCPU fallbacks
fast Standard_D64ads_v6, Standard_D64ds_v6, Standard_F64s_v2, then 48/32-vCPU fallbacks
large Standard_D96ads_v6, Standard_D96ds_v6, then 64/48-vCPU fallbacks
beast Standard_D192ds_v6, Standard_D128ds_v6, then 96/64-vCPU fallbacks
arm64 Standard_D*ps_v6 / D*pds_v6 Cobalt families with --arch arm64
Azure Win/
WSL2 standard Standard_D2ads_v6, Standard_D2ds_v6, Standard_D2ads_v5, Standard_D2ds_v5, Standard_D2as_v6
fast Standard_D4ads_v6, Standard_D4ds_v6, Standard_D4ads_v5, Standard_D4ds_v5, Standard_D4as_v6
large Standard_D8ads_v6, Standard_D8ds_v6, Standard_D8ads_v5, Standard_D8ds_v5, Standard_D8as_v6
beast Standard_D16ads_v6, Standard_D16ds_v6, Standard_D16ads_v5, Standard_D16ds_v5, Standard_D8ads_v6
Namespace standard S
fast M
large L
beast XL
Namespace
Compute standard 4x8
fast 8x16
large 16x32
beast 32x64
Cloudflare standard standard-4
fast standard-4
large standard-4
beast standard-4
```
使用 `--type` 或 `CRABBOX_SERVER_TYPE` 覆盖以指定特定实例。在 Azure 或 AWS 上使用 `--arch arm64` / `architecture: arm64` 获取 Linux ARM 容量；在未设置自定义镜像时，显式的 ARM provider 类型也会自动选择 ARM 镜像。
Cloudflare 还接受 `lite`、`basic`、`standard-1`、`standard-2` 和 `standard-3` 作为更小的显式 `--type` 值；`standard-4` 是默认值。没有行的 provider 要么使用 provider 原生的容量设置，要么会拒绝进行类/类型选择。
## 配置
配置按以下顺序解析：命令行 flags → 环境变量 → 仓库的 `.crabbox.yaml` → 用户的 `~/.config/crabbox/config.yaml` → 默认值。
```
broker:
url: https://broker.example.com
provider: aws
token: ...
class: beast
capacity:
market: spot
strategy: most-available
fallback: on-demand-after-120s
hints: true
aws:
region: eu-west-1
rootGB: 400
lease:
idleTimeout: 30m
ttl: 90m
ssh:
key: ~/.ssh/id_ed25519
user: crabbox
port: "2222"
# Ordered fallback ports tried after ssh.port; use [] to disable fallback.
fallbackPorts:
- "22"
```
设置 `broker.mode: registered` 可在任何 direct provider 中保留配置和清理机制，同时向 coordinator 注册租约元数据，以实现清单管理、共享和 portal WebVNC。保留的桌面租约默认会自动启动出站 WebVNC 桥接；设置 `.autoWebVNC: false` 以选择退出。Coordinator 绝不会接收 provider 凭据或直接调用已注册的 provider。默认情况下，它仅移除注册元数据；显式绑定的出站运行时适配器可以执行经用户确认的工作区删除操作。API 客户端可以通过 `POST /v1/leases/{id}/release` 及请求体 `{"delete":true}` 来请求执行带有相同生成防护的删除操作。
转发的环境变量被有意限制在：`NODE_OPTIONS` 和 `CI`。不要将密钥作为命令行参数传递。对于涉及真实密钥的冒烟测试，请使用 `crabbox run --env-from-profile --allow-env NAME`，这样 Crabbox 只会转发选定的名称，并打印经过涂黑的、显示存在性/长度的元数据。对于陈旧的预热 box，`--full-resync`（别名 `--fresh-sync`）会在同步前重置远程工作目录。对于较长的命令，请使用 `--script ` 或 `--script-stdin`，以便远程 runner 执行上传的文件，而不是一个巨大的带引号的 shell 字符串。对于二进制或对终端不友好的输出，请使用 `crabbox run --capture-stdout ` 或 `--capture-stderr `。添加 `--preflight` 以获取远程能力快照，使用 `--keep-on-failure` 通过 SSH 进入确切失败的一次性租约，或使用 `--download remote=local` 将成功运行的制品拷贝回来。默认情况下，失败的基于 SSH 和 Blacksmith 委托的运行会将本地的 `.crabbox/captures/*.tar.gz` bundle 保存下来。Crabbox 不会对捕获的文件进行涂黑处理。
受管 Linux 租约的可选 Tailscale 可达性配置：
```
tailscale:
enabled: true
network: auto
tags:
- tag:crabbox
hostnameTemplate: crabbox-{slug}
authKeyEnv: CRABBOX_TAILSCALE_AUTH_KEY
exitNode: mac-studio.example.ts.net
exitNodeAllowLanAccess: true
```
Tailscale 是一个网络平面，而不是 provider。`--tailscale` 将新创建的受管 Linux 租约加入到 tailnet 中；`--network auto|tailscale|public` 用于选择 SSH 和 VNC 隧道命令解析主机的方式。Brokered 模式使用 Worker OAuth 密钥来生成一次性密钥；direct-provider 模式从配置的环境变量中读取授权密钥。请参阅 [Tailscale](docs/features/tailscale.md)。
一些特定于 provider 的配置片段：
```
# Static macOS 或 Windows 目标（现有机器，无 provisioning）
provider: ssh
target: windows
windows:
mode: normal # or wsl2
static:
host: win-dev.local
user: alice
port: "22"
workRoot: C:\crabbox
```
```
# Local container（别名：docker；检测 docker 或 podman）
provider: local-container
localContainer:
runtime: docker
image: debian:bookworm
workRoot: /work/crabbox
```
```
# Delegated Blacksmith CI Testbox
provider: blacksmith-testbox
blacksmith:
org: example-org
workflow: .github/workflows/ci-check-testbox.yml
job: test
ref: main
idleTimeout: 90m
```
请将 provider 的 token 保存在环境变量中，而不是仓库配置中（例如 `CRABBOX_SEMAPHORE_TOKEN`、`CRABBOX_SPRITES_TOKEN`、`RUNPOD_API_KEY`、`MORPH_API_KEY`、`ASCII_BOX_API_KEY`、`E2B_API_KEY`、`DAYTONA_API_KEY`）。完整的环境变量参考、各个 provider 的专属部分以及各命令的 flags 请参见 [docs/cli.md](docs/cli.md)、[配置](docs/features/configuration.md)和 [provider 文档](docs/providers/README.md)。
## 开发
```
# Go CLI
go build -trimpath -o bin/crabbox ./cmd/crabbox
go vet ./...
go test -race ./...
# Coordinator 运行时（本地为 Node 22+；CI 运行 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 脚本
node --test scripts/*.test.js
# Docs
scripts/check-docs.sh
# 当 broker/provider 凭证可用时进行可选的 live smoke
CRABBOX_LIVE=1 CRABBOX_LIVE_REPO=/path/to/my-app scripts/live-smoke.sh
# Firecracker 主机就绪 smoke（只读；当缺少 Linux/KVM 资产时报告 environment_blocked）
CRABBOX_BIN=./bin/crabbox scripts/live-firecracker-smoke.sh
```
CI 会在每次推送和 PR 时运行完整的检查关卡（gofmt、vet、竞态测试、所有 Go 模块、覆盖率阈值、仓库脚本测试、文档链接/构建检查、GoReleaser 快照，以及 Worker lint/类型检查/测试/构建）。匹配 `v*` 的标签推送会通过 GoReleaser 发布 Go 归档文件，并更新 [openclaw/homebrew-tap](https://github.com/openclaw/homebrew-tap) 上的 Homebrew formula。
有关 Cloudflare、Node/PostgreSQL、容器、流量接入、密钥和 DNS 的部署信息位于 [docs/infrastructure.md](docs/infrastructure.md) 中。
## 文档
- **了解模型：** [Crabbox 的工作原理](docs/how-it-works.md)、[架构](docs/architecture.md)、[概念](docs/concepts.md)、[Orchestrator](docs/orchestrator.md)
- **使用 CLI：** [CLI](docs/cli.md)、[命令](docs/commands/README.md)、[功能](docs/features/README.md)、[配置](docs/features/configuration.md)
- **选择 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)
- **高级功能：** [Actions hydration](docs/features/actions-hydration.md)、[Capsules](docs/features/capsules.md)、[检查点](docs/features/checkpoints.md)、[Jobs](docs/features/jobs.md)、[Pond](docs/features/pond.md)
- **交互式 QA：** [交互式桌面与 VNC](docs/features/interactive-desktop-vnc.md)、[制品](docs/features/artifacts.md)、[Portal](docs/features/portal.md)
- **集成基础设施：** [自带基础设施](docs/features/bring-your-own-infrastructure.md)、[可移植 Coordinator](docs/features/portable-coordinator.md)、[外部 Provider](docs/providers/external.md)
- **运维操作：** [运维](docs/operations.md)、[可观测性](docs/observability.md)、[故障排除](docs/troubleshooting.md)、[性能](docs/performance.md)
- **设置或审计：** [基础设施](docs/infrastructure.md)、[安全策略](SECURITY.md)、[操作安全](docs/security.md)、[入门指南](docs/getting-started.md)、[源码映射](docs/source-map.md)
- **更新日志：** [CHANGELOG.md](CHANGELOG.md)
GitHub Pages 站点
标签：EVTX分析, Go, MITM代理, Ruby工具, 内存分配, 日志审计, 测试用例, 测试自动化, 程序员工具, 远程执行