我们逆向工程了 Docker Sandbox 未文档化的 MicroVM API

# 我们逆向工程了 Docker Sandbox 未文档化的微VM API 来源：https://rivet.dev/blog/2026-02-04-we-reverse-engineered-docker-sandbox-undocumented-microvm-api/ 我们逆向工程了 Docker Sandbox 未文档化的微VM API **Docker 随附了一个用于启动微VM的未文档化 API。我们对其进行了逆向工程，并构建了开源 Sandbox Agent SDK (https://sandboxagent.dev/)，以便在其中编排编码智能体。** Docker 和容器一直是我们运行后端服务的标准方式。最近，越来越多的工作负载转向沙箱以执行不可信代码，而 Docker 并不适合这种场景。随着 Docker Sandbox 的推出，Docker 悄悄提供了一个用于微VM的未文档化 API，可以驱动沙箱。这看起来很有希望成为在自有基础设施上使用微VM管理沙箱的统一方式，就像十年前 Docker 对容器所做的那样。（目前仅支持 macOS/Windows，需要嵌套虚拟化。） Docker Sandboxes (https://docs.docker.com/ai/sandboxes/)（发布文章 (https://www.docker.com/blog/docker-sandboxes-a-new-approach-for-coding-agent-safety/)）是 Docker 为安全运行 AI 编码智能体提供的解决方案。Claude Code、Codex 和 Gemini 需要运行任意代码、安装包和修改文件。微VM 让它们可以运行 `--dangerously-skip-permissions` 而不再危险。 Docker 提供了一个简单的 CLI： 乍一看，这就像一个增强版的 `docker run` 命令，但底层 **Docker 使用了完全不同的技术：微VM**。 大多数开发者在使用 `docker run` 时熟悉并喜爱的是容器。它们提供了基本的文件系统、网络和进程隔离。然而，一个常见的 **误解是认为容器对于运行不可信代码（AI 智能体、用户提交的脚本、多租户插件）已经足够安全**。 出于设计原理，**容器共享宿主机的内核**，以保证快速和轻量。但这意味着，一个被攻破的容器可能会危及宿主机安全。使用容器的安全性影响是一个更广泛的话题，但业界多数观点认为，容器对于不可信代码执行是一种不好的实践。 为了获得更好的安全性，AWS Lambda、Fly.io 和大多数沙箱提供商都使用 **微VM 来提供带独立内核的轻量级虚拟机**，以达到更强的安全性。它比完整虚拟机更轻量，但开销也更小。这被认为是隔离用户代码的黄金标准。 有许多 (https://github.com/firecracker-microvm/firecracker?tab=readme-ov-file#what-is-firecracker) 其他 (https://www.koyeb.com/blog/10-reasons-why-we-love-firecracker-microvms) 文档 (https://firecracker-microvm.github.io/) 更详细地描述了微VM 和 Firecracker，如果你想深入了解的话。 这就是为什么 **Docker 在微VM 上构建了 Sandbox** 而不是容器，同时保持与 Docker 容器的兼容性。以下是两者的对比： | | Docker 容器 | Docker Sandbox | |---|---|---| | **安全性** | 共享内核（命名空间） | 独立内核（微VM） | | **不可信代码** | 不安全 | 安全 | | **网络访问** | 直接 HTTP | 通过过滤代理 | | **卷** | 直接挂载 | 双向文件同步 | | **平台** | Linux, macOS, Windows | 仅 macOS、Windows | 这打开了容器无法安全处理的用例： - **不可信代码执行**：运行用户提交的脚本而不会危及宿主机 - **AI 编码智能体**：让 Claude/Codex 安全地使用完全权限运行 - **多租户插件**：在 SaaS 应用中隔离客户代码 - **安全的 CI/CD**：使用 VM 级别的隔离运行构建，而非容器 `docker sandbox run` 严格限制为 Docker 白名单中的智能体：Claude、Codex、Gemini、Copilot、Kiro 和 Cagent。目前不允许你运行自己的 Docker 容器。所以我顺理成章地开始探索，看能否逆向工程底层微VM API，以便在沙箱中运行我想要的任何代码。 Docker 的 sandboxd 守护进程管理所有虚拟机，并监听 `~/.docker/sandboxes/sandboxd.sock`。它提供三个端点： - `GET /vm`：列出所有 VM - `POST /vm`：创建 VM - `DELETE /vm/{vm_name}`：销毁一个 VM 我们将使用以下命令创建一个 VM： 并得到响应： VM 名称遵循 `{agent_name}-vm` 模式。`socketPath` 是每个 VM 独立的 Docker 守护进程，我们将在下一步使用。通常所有容器共享 `/var/run/docker.sock`。任何拥有套接字访问权限的人都可以看到并控制所有其他容器。Sandboxes 翻转了这一点。**每个微VM 拥有自己的 Docker 守护进程**，位于 `~/.docker/sandboxes/vm/<vm_name>/docker.sock`，以实现最大隔离。容器在微VM 内部正常运行，但与宿主机和其他 VM 完全隔离。要针对不同的守护进程，我们需要使用 `curl --unix-socket ...` 或 `docker --host unix://...` 覆盖 Unix 套接字路径。 新 VM 与宿主机完全隔离，因此我们需要手动将已构建的镜像加载到 VM 中。我们通过构建、归档并将镜像加载到 VM 中来完成此操作，如下所示： `$VM_SOCK` 是上一步中的 `socketPath`。 现在到了有趣的部分：我们终于可以运行我们的镜像，并像处理任何其他 Docker 容器一样与之交互。 #### 网络 微VM 通过位于 `host.docker.internal:3128` 的过滤代理路由出站流量。你的容器需要设置以下环境变量： 代理会对 HTTPS 进行中间人攻击（因此使用 `NODE_TLS_REJECT_UNAUTHORIZED=0`）以执行网络策略。在生产环境中，请从 VM 响应中的 `ca_cert_path` 安装 CA 证书，而不是禁用 TLS 验证。 #### 卷 工作区同步使用相同绝对路径，因此卷挂载可以直接使用： Docker Sandbox 需要在 **macOS 或 Windows** 上安装 **Docker Desktop 4.58+**。Linux 不受支持，因为 Docker Desktop 使用平台特定的虚拟化技术（macOS 上使用 Apple Virtualization.framework，Windows 上使用 Hyper-V）。 原始的微VM API 非常强大，但在此基础上构建生产级的智能体编排系统需要处理以下问题： - **会话生命周期**：创建 VM、加载镜像、启动容器以及失败时的清理 - **智能体通信**：解析流式输出、处理权限提示、管理人工介入的工作流 - **多智能体支持**：通过统一接口运行 Claude、Codex 或 OpenCode 我们构建了 Sandbox Agent SDK (https://sandboxagent.dev/) 来处理所有这些。它封装了微VM API，并提供了一个简单的接口来生成并与 AI 编码智能体进行交互： 查看在 Docker Sandbox 上部署的完整指南 (https://sandboxagent.dev/docs/deploy/docker-sandbox)。 Docker 的微VM API 为任何工作负载打开了安全隔离的大门，而不仅仅是 Docker 官方支持的少数几个智能体。无论你是构建 AI 编码助手、运行不可信用户代码，还是隔离多租户插件，`/vm` API 都为你提供了安全实现这些目标的基本组件。该 API 未文档化且可能变更，但它在 Docker Desktop 4.58+ 上今天即可使用。如果你正在用它构建什么东西，我们很乐意听听你的想法。