逆向工程 Docker Sandbox 未公开 MicroVM API：gRPC 接口与隔离机制解析

Docker Desktop 4.58+ 版本引入的 Sandboxes 功能为 AI Agent 提供了基于 microVM 的隔离执行环境。Rivet 团队通过逆向工程发现了其中未公开的 API 接口，这套接口允许开发者以编程方式创建、管理和销毁隔离的虚拟机环境。本文将深入解析该 API 的设计细节、隔离机制原理以及实际工程应用中的关键参数。

API 端点与通信机制

Docker Sandbox 的控制平面通过本地 Unix Domain Socket 暴露，默认路径位于 ~/.docker/sandboxes/sandboxd.sock。与常规的 Docker REST API 不同，这套接口采用简化的 HTTP-like 协议封装在 gRPC 之上，支持三种核心操作：

• GET /vm：列出当前运行的所有 microVM 实例
• POST /vm：创建新的隔离环境
• DELETE /vm/{vm_name}：销毁指定虚拟机并回收资源

创建 VM 的请求体采用 JSON 格式，核心字段包括 agent_name（标识符）和 workspace_dir（挂载的工作目录）。成功创建后，API 返回的响应中包含 socketPath 字段，指向该 microVM 内部 Docker Daemon 的 Unix Socket。这一设计实现了 "VM 嵌套 Docker" 的架构 —— 每个隔离环境拥有独立的容器运行时，而非与宿主机共享 Docker Engine。

MicroVM 隔离架构解析

Docker 选择自研 VMM（Virtual Machine Monitor）而非采用 Firecracker 等现有方案，核心原因是跨平台需求。Firecracker 专为 Linux/KVM 云环境设计，而 Docker Sandboxes 需要原生支持 macOS（Hypervisor.framework）、Windows（Hypervisor Platform）和 Linux（KVM）三种平台。

每个 microVM 的隔离边界由以下层次构成：

内核级隔离：每个 Sandbox 拥有独立的操作系统内核，通过硬件虚拟化边界（Intel VT-x/AMD-V 或 Apple Silicon 的虚拟化扩展）与宿主机隔离。这意味着即使 Agent 在 VM 内获得 root 权限，也无法直接访问宿主机资源。

私有 Docker Daemon：这是该架构的关键差异化设计。传统的 DinD（Docker-in-Docker）方案需要特权容器和宿主机 socket 挂载，而 Docker Sandboxes 在每个 microVM 内部运行独立的 Docker Daemon。Agent 可以执行完整的 docker build、docker run 和 docker compose 操作，但这些操作被限制在 VM 边界内，不会逃逸到宿主机。

网络代理层：VM 内的出站流量统一通过 host.docker.internal:3128 代理转发，而非直接访问外部网络。这一设计允许在宿主机层面实施细粒度的网络策略控制，同时保持 VM 内部网络栈的完整性。

实际调用流程与参数

基于逆向工程结果，完整的 VM 生命周期管理流程如下：

首先通过 POST /vm 创建实例，请求示例：

{
  "agent_name": "my-sandbox",
  "workspace_dir": "/path/to/workspace"
}

响应包含 VM 元数据和内部 Docker Socket 路径。随后，开发者可通过返回的 socketPath 直接操作 VM 内的容器运行时：

# 加载镜像到 microVM 内部
docker --host unix://<socketPath> load -i my-image.tar

# 在隔离环境中运行容器
docker --host unix://<socketPath> run -d my-image

销毁时调用 DELETE /vm/{vm_name}，该操作会立即终止 VM 进程并清理相关资源，包括 VM 内部的容器、镜像和网络命名空间。由于每个 Sandbox 都是无状态的（工作目录通过挂载共享），销毁后不会留下残留状态。

安全边界与限制

这套 API 的设计体现了 "基础设施定义边界" 的安全理念。文件系统访问、网络策略和密钥注入都在 Agent 运行前由宿主机配置完成，而非依赖 Agent 自身的权限控制。这种前置边界的方式避免了 LLM 决策链中的潜在安全风险。

然而，未公开 API 存在固有的稳定性风险。Docker 官方未承诺该接口的向后兼容性，未来版本可能调整端点路径、请求格式或认证机制。此外，出站流量强制经过代理的设计虽然增强了可控性，但也意味着需要额外配置代理规则以支持特定的网络访问场景。

工程实践建议

对于希望利用该 API 构建 Agent 编排系统的开发者，建议采取以下策略：

版本锁定：明确依赖 Docker Desktop 4.58+ 版本，并在升级前验证 API 兼容性。由于接口未文档化，建议封装一层抽象层以隔离潜在的接口变更影响。

资源监控：每个 microVM 消耗独立的内存和 CPU 资源，建议设置 VM 级别的资源配额。虽然 Docker Sandboxes 实现了快速冷启动（秒级），但大量并发 VM 仍可能对宿主机造成资源压力。

网络策略：充分利用 host.docker.internal:3128 代理点实施 egress 控制。可以在宿主机运行代理服务，根据目标地址、协议类型实施细粒度的访问控制，而非允许 VM 直接访问任意外部端点。

生命周期管理：由于 VM 创建和销毁操作是同步的，建议在应用层实现异步队列和超时机制，避免因 VM 启动缓慢导致请求堆积。

总结

Docker Sandboxes 的未公开 MicroVM API 为 Agent 隔离提供了一套轻量级但完整的解决方案。通过逆向工程揭示的接口设计，我们可以看到 Docker 在跨平台 VMM、嵌套容器运行时和网络代理方面的工程权衡。这套架构的核心价值在于将 "完整开发环境" 与 "硬件级隔离" 结合，既满足了 AI Agent 对 Docker 生态的依赖，又提供了比容器更强的安全边界。

对于需要为 Agent 工作流提供隔离执行环境的团队，该 API 提供了一条可行的技术路径，但需权衡未公开接口的维护成本与官方 Sandboxes CLI 的成熟度。

参考来源

• Rivet: "We Reverse-Engineered Docker Sandbox's Undocumented MicroVM API" (2026-02-04)
• Docker: "Why MicroVMs: The Architecture Behind Docker Sandboxes" (2026-04-16)

systems