2026 - 03 - 13 15:24:18

深入拆解 OpenSandbox：AI Agent 时代的通用沙盒运行时

为什么 AI Agent 需要沙盒？

Claude Code、Gemini CLI、Codex CLI，越来越多的 AI 编程助手正在从“生成代码”走向“执行代码”。但一个绕不开的问题随之而来：这些 AI 生成的代码到底该在哪里跑？

直接在宿主机执行风险太大。恶意代码注入、rm -rf / 式的灾难、资源耗尽导致的系统挂起，任何一个都是不可接受的。而市面上的云端沙盒服务往往存在厂商锁定、按分钟计费、与特定 AI 框架深度耦合等问题，灵活性有限。

阿里在 2026 年 3 月以 Apache 2.0 协议开源了 OpenSandbox，定位为一个通用的 AI Agent 沙盒平台。它的目标很明确：让任意 AI 应用都能安全地执行代码、操作文件、运行命令，同时支持 Docker 本地开发和 Kubernetes 生产调度两种模式。

下面从架构设计、核心组件、安全模型和竞品对比等维度做一次完整拆解。

1. 四层分离架构

OpenSandbox 的整体设计遵循一个核心原则：关注点分离。整个系统被拆分为四个独立且可演进的层次：

SDK 层：面向开发者的客户端库，目前覆盖 Python、Java/Kotlin、TypeScript、C#/.NET 四种语言。SDK 封装了沙盒生命周期管理和代码执行两大 API，对外暴露 Sandbox、Filesystem、Commands、CodeInterpreter 四个核心抽象。

Specs 层：所有交互协议以 OpenAPI 规范的形式定义在 specs/ 目录下，包含生命周期 API 和执行 API 两大部分。

Runtime 层：基于 FastAPI 的服务端实现，负责沙盒生命周期编排。通过工厂模式根据配置动态选择 Docker 或 Kubernetes 运行时。

Sandbox 实例层：每个运行中的沙盒容器，内部注入 Go 编写的执行守护进程 execd，它承担实际的文件操作、命令执行和代码运行。

这种分层的价值在于各层可以独立演进。如果想支持一门新语言的 SDK，只需遵循 OpenAPI 规范实现即可；如果想接入新的运行时，只需在 Runtime 层实现接口，SDK 和 execd 完全不用改动。

2. Protocol-First：协议先于实现

OpenSandbox 最值得关注的设计决策之一是协议优先，先在规范层定义所有交互契约，再基于规范实现代码。

这不是“写了文档然后放着没人看”的表面功夫，它带来了几个很实在的工程收益：

多语言 SDK 天然一致。四种语言的 SDK 都是基于同一份 OpenAPI 规范实现的，接口行为完全一致。
可插拔的运行时。只要第三方实现了规范定义的接口，就能成为一个合法的沙盒运行时。
文档即契约。Swagger UI 从规范自动生成，/docs 端点开箱即用。

这种思路与 gRPC/Protobuf 先定义 IDL 再生成代码的方式非常相似。对于需要支撑多语言生态的基础设施项目来说，协议优先几乎是最优解。

3. 双运行时：Docker 与 Kubernetes

服务端通过工厂模式动态选择运行时，核心逻辑非常直接：

# server/src/services/factory.py
def create_sandbox_service() -> SandboxService:
    config = get_config()
    if config.runtime == "kubernetes":
        return KubernetesSandboxService(config)
    return DockerSandboxService(config)

Docker 运行时：本地开发首选

Docker 运行时的核心流程是：拉取用户指定镜像、将 execd 注入容器、覆盖 entrypoint，先启动 execd 再执行用户进程，并通过 TTL 实现自动清理。

三条命令即可启动：

pip install opensandbox-server
opensandbox-server init-config ~/.sandbox.toml --example docker
opensandbox-server

Kubernetes 运行时：面向大规模生产

K8s 运行时不只是把 Docker 简单换成 Pod。OpenSandbox 为此专门实现了一个 Kubernetes Operator，提供两个自定义资源：

Pool CRD：维护预热容器池，控制最小/最大缓冲数量。思路类似数据库连接池，请求到来时可以直接分配，避免等待容器冷启动。

BatchSandbox CRD：支持批量沙盒创建，专为 RL 训练等高吞吐场景设计。

此外，K8s 运行时还兼容 Kata Containers 和 gVisor 等安全容器运行时，进一步强化隔离。

4. execd：沙盒内的执行大脑

execd 是整个架构中最核心的组件，一个用 Go 编写的 HTTP 守护进程，在沙盒容器创建时被注入，无需修改基础镜像。它暴露了沙盒内执行相关的全部 API。

路由设计

/files         -> 文件系统操作
/directories   -> 目录操作
/code          -> 代码执行
/code/context  -> 执行上下文管理
/command       -> Shell 命令
/metrics/watch -> 实时系统监控

代码执行链路：Jupyter 内核协议复用

execd 在代码执行层面做了一个非常务实的设计选择：没有自己实现代码解释器，而是对接 Jupyter 内核协议。

SDK.run(code)
  -> POST /code
    -> execd 通过 WebSocket 连接 Jupyter Server
      -> Jupyter Server 转发到 Jupyter Kernel
        -> Kernel 执行代码，产生输出事件
          -> execd 将输出事件转为 SSE 流
            -> SDK 解析 SSE 流，返回结果

这个设计的好处有三个：

语言生态复用：直接复用 Jupyter 现成的多语言内核。
天然有状态：同一个 context_id 下变量可以跨多次执行保留。
流式输出：通过 SSE 实时推送结果，天然适配 Agent 的交互方式。

在代码组织上，execd 也分得很清楚：配置、HTTP 层、运行时调度、Jupyter 客户端和工具函数分别位于不同包中，职责边界清晰。

5. 沙盒的四种应用场景

OpenSandbox 不只是一个代码执行器，它支持四种面向不同工作负载的沙盒类型：

Coding Agent 沙盒：为编写、测试、调试代码的 Agent 优化。
GUI Agent 沙盒：提供完整的 VNC 桌面环境，允许 Agent 与图形界面交互。
代码执行沙盒：基于 Jupyter 内核的高性能代码运行时，支持有状态会话和实时输出流。
RL 训练沙盒：为强化学习提供隔离训练环境，配合 BatchSandbox 可以做大规模并行采样。

6. 安全设计：多层防护

对于一个执行任意不可信代码的平台，安全是命脉。OpenSandbox 在多个层面构建了防护体系。

认证：双层 Token 机制

生命周期 API：通过 OPEN-SANDBOX-API-KEY 进行认证。
execd 执行 API：通过 X-EXECD-ACCESS-TOKEN 进行认证，Token 在沙盒创建时动态生成，且每个沙盒独立。

这种双层认证的好处是即使攻击者拿到了单个沙盒的执行 Token，也无法创建或销毁其他沙盒。

网络：Ingress + Egress 双向控制

Ingress：统一流量入口，支持多种路由策略。
Egress：基于 nftables 的出口流量控制，可以按沙盒粒度设置外网访问白名单。

资源与运行时隔离

每个沙盒可以独立设置 CPU、内存、GPU 配额。
强制 TTL，超时自动销毁，防止僵尸容器长期占用资源。
支持 gVisor、Kata Containers 和 Firecracker 等高隔离运行时。

如果只是开发测试，标准容器隔离已经够用；多租户生产建议用 gVisor；执行完全不可信代码时，更适合 Kata 或 Firecracker。

7. 沙盒生命周期状态机

理解沙盒状态转换对 SDK 调用和调试很有帮助：

创建请求
   ↓
 Pending
   ↓
 Running
   ↓      ↓
Paused  Terminated
   ↓
Running

Pending -> Running 是 SDK 中轮询等待的阶段，通常受镜像拉取和容器启动速度影响。如果对延迟敏感，使用 K8s 运行时加上 Pool 预热容器可以显著缩短这一阶段。

另一个值得注意的能力是暂停与恢复，这对希望节省资源但又不想丢失会话状态的场景很有帮助。

8. 与竞品的差异化

特性	OpenSandbox	E2B	Modal	agent-sandbox
开源协议	Apache 2.0	部分开源	闭源 SaaS	Apache 2.0
自托管	Docker / K8s	支持	不支持	仅 K8s
多语言 SDK	4 种	Python / JS	Python	Python
批量沙盒	支持	不支持	不支持	不支持
代码解释器	Jupyter 内核	有	有	无
安全容器	gVisor / Kata / Firecracker	基础	基础	有
计费模式	免费自托管	按分钟计费	按使用量计费	免费自托管

OpenSandbox 的核心差异化可以概括为三点：

通用性：不绑定特定 AI 框架，任意 OCI 镜像都可以作为沙盒基础。
大规模批量能力：BatchSandbox 更适合 RL 训练等需要大量并行环境的场景。
完全自托管：数据不离开自己的基础设施，不存在明显的供应商锁定。

当然也有不足：目前原生 GPU 支持不够完整，冷启动延迟相比某些专门做沙盒的产品还有差距，持久化存储也仍在 Roadmap 中。

9. 工程实践建议

本地开发：Docker 运行时即可

pip install opensandbox-server
opensandbox-server init-config ~/.sandbox.toml --example docker
opensandbox-server

生产环境：K8s + Pool 预热

如果沙盒请求量大且对延迟敏感，用 Pool CRD 预热一批容器，将分配延迟从十几秒压缩到亚秒级。

长时间任务：后台命令模式

execd 的 /command 接口支持后台执行模式，返回命令 ID，再通过日志接口轮询输出，适合构建、训练等耗时任务。

有状态代码执行：善用 Context

在同一个 context_id 下多次调用 /code，变量和导入模块会在执行间保持。这对 Agent 的迭代式工作流非常关键。

安全加固：按场景选择隔离级别

开发测试：标准 Docker 容器 + TTL + 网络策略
多租户生产：gVisor RuntimeClass
执行不可信代码：Kata Containers 或 Firecracker

10. 几个值得学习的工程思想

回顾整个架构，有几点设计思想很值得借鉴：

协议优先：规范先于实现，用 OpenAPI 约束所有交互行为，自然得到多语言一致性和可扩展性。

彻底的关注点分离：SDK、Server、execd 三者各司其职，可以独立部署和升级。

务实的技术复用：代码执行层没有重新造轮子，而是建立在 Jupyter 内核协议之上。

分级扩展：Docker 适合本地和小规模场景，K8s Operator + 资源池应对大规模生产，两者共享同一套 API。

对于正在构建 AI Agent 基础设施，或者关注 Agent 安全执行问题的工程师来说，OpenSandbox 提供了一个非常值得研究的参考实现。