OpenSandbox

---

中文 | English

OpenSandbox 是一个面向 AI 应用的通用沙箱平台，提供多语言 SDK、统一的沙箱 API，以及 Docker/Kubernetes 运行时，适用于 Coding Agent、GUI Agent、Agent 评测、AI 代码执行和强化学习训练等场景。

OpenSandbox 已进入 CNCF Landscape。

核心特性

• 多语言 SDK：提供 Python、Java/Kotlin、JavaScript/TypeScript、C#/.NET、Go 的沙箱 SDK。
• 沙箱协议：定义了沙箱生命周期管理 API 和沙箱执行 API。你可以通过这些沙箱协议扩展自己的沙箱运行时。
• 沙箱运行时：沙箱全生命周期管理，支持 Docker 和自研高性能 Kubernetes 运行时，实现本地运行、企业级大规模分布式沙箱调度。
• 沙箱环境：内置 Command、Filesystem、Code Interpreter 实现。并提供 Coding Agent（Claude Code 等）、浏览器自动化（Chrome、Playwright）和桌面环境（VNC、VS Code）等示例。
• 网络策略：提供统一的 Ingress Gateway 实现，并支持多种路由策略；提供单实例级别的沙箱出口网络限制。
• 强隔离安全：支持 gVisor、Kata Containers 和 Firecracker 微虚拟机等安全容器运行时，为沙箱工作负载与宿主机之间提供增强的安全隔离。详见 安全容器运行时指南。

SDKs

Python:

pip install opensandbox

Java/Kotlin (Gradle Kotlin DSL):

dependencies {
    implementation("com.alibaba.opensandbox:sandbox:{latest_version}")
}

Java/Kotlin (Maven):

<dependency>
    <groupId>com.alibaba.opensandbox</groupId>
    <artifactId>sandbox</artifactId>
    <version>{latest_version}</version>
</dependency>

JavaScript/TypeScript:

npm install @alibaba-group/opensandbox

C#/.NET:

dotnet add package Alibaba.OpenSandbox

Go:

go get github.com/alibaba/OpenSandbox/sdks/sandbox/go

快速开始

环境要求：

• Docker（本地运行必需）
• Python 3.10+（示例和本地运行所需）

安装并配置 Sandbox Server

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

uvx opensandbox-server

# 查看帮助
# uvx opensandbox-server -h

创建 Code Interpreter 并执行命令/代码

安装 Code Interpreter SDK

uv pip install opensandbox-code-interpreter

创建沙箱并执行命令

import asyncio
from datetime import timedelta

from code_interpreter import CodeInterpreter, SupportedLanguage
from opensandbox import Sandbox
from opensandbox.models import WriteEntry

async def main() -> None:
    # 1. Create a sandbox
    sandbox = await Sandbox.create(
        "sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-interpreter:v1.0.2",
        entrypoint=["/opt/opensandbox/code-interpreter.sh"],
        env={"PYTHON_VERSION": "3.11"},
        timeout=timedelta(minutes=10),
    )

    async with sandbox:

        # 2. Execute a shell command
        execution = await sandbox.commands.run("echo 'Hello OpenSandbox!'")
        print(execution.logs.stdout[0].text)

        # 3. Write a file
        await sandbox.files.write_files([
            WriteEntry(path="/tmp/hello.txt", data="Hello World", mode=644)
        ])

        # 4. Read a file
        content = await sandbox.files.read_file("/tmp/hello.txt")
        print(f"Content: {content}") # Content: Hello World

        # 5. Create a code interpreter
        interpreter = await CodeInterpreter.create(sandbox)

        # 6. 执行 Python 代码（单次执行：直接传 language）
        result = await interpreter.codes.run(
              """
                  import sys
                  print(sys.version)
                  result = 2 + 2
                  result
              """,
              language=SupportedLanguage.PYTHON,
        )

        print(result.result[0].text) # 4
        print(result.logs.stdout[0].text) # 3.11.14

    # 7. Cleanup the sandbox
    await sandbox.kill()

if __name__ == "__main__":
    asyncio.run(main())

更多示例

OpenSandbox 提供了丰富的示例来演示不同场景下的沙箱使用方式。所有示例代码位于 examples/ 目录下。

🎯 基础示例

• code-interpreter - Code Interpreter SDK 的端到端沙箱流程示例。
• aio-sandbox - 使用 OpenSandbox SDK 与 agent-sandbox 的一体化沙箱示例。
• agent-sandbox - 通过 kubernetes-sigs/agent-sandbox 在 Kubernetes 上运行 OpenSandbox。
• 卷存储 — Docker PVC / 命名卷、Docker OSSFS、Kubernetes PVC：持久化与共享存储用法。

🤖 Coding Agent 集成

• Coding CLI — Claude Code、Gemini CLI、OpenAI Codex CLI、Qwen Code、Kimi CLI：在 OpenSandbox 中运行各厂商 CLI。
• langgraph - 基于 LangGraph 状态机编排沙箱任务与回退重试。
• google-adk - 使用 Google ADK 通过 OpenSandbox 工具读写文件并执行命令。
• openclaw - 在沙箱中启动 OpenClaw Gateway。

🌐 浏览器与桌面环境

• chrome - 带 VNC 与 DevTools 的无头 Chromium，用于自动化/调试。
• playwright - Playwright + Chromium 无头抓取与测试示例。
• desktop - 通过 VNC 访问的完整桌面环境沙箱。
• vscode - 在沙箱中运行 code-server（VS Code Web）进行远程开发。

🧠 机器学习与训练

• rl-training - 在沙箱中运行 DQN CartPole 训练，输出 checkpoint 与训练汇总。

更多详细信息请参考 examples 和各示例目录下的 README 文件。

项目结构

目录	说明
sdks/	多语言 SDK（Python、Java/Kotlin、TypeScript/JavaScript、C#/.NET）
specs/	OpenAPI 与生命周期规范
server/	Python FastAPI 沙箱生命周期服务，并集成多种运行时实现
kubernetes/	Kubernetes 部署与示例
components/execd/	沙箱执行守护进程，负责命令和文件操作
components/ingress/	沙箱流量入口代理
components/egress/	沙箱网络 Egress 访问控制
sandboxes/	沙箱运行时实现与镜像（如 code-interpreter）
examples/	集成示例和使用案例
oseps/	OpenSandbox Enhancement Proposals
docs/	架构和设计文档
tests/	跨组件端到端测试
scripts/	开发和维护脚本

详细架构请参阅 docs/architecture.md。

文档

• docs/architecture.md – 整体架构 & 设计理念
• oseps/README.md – OpenSandbox 增强提案 (OSEPs)
• SDK
  • Sandbox 基础 SDK（Java\Kotlin SDK、Python SDK、JavaScript/TypeScript SDK、C#/.NET SDK）- 包含沙箱生命周期、命令执行、文件操作
  • Code Interpreter SDK（Java\Kotlin SDK 、Python SDK、JavaScript/TypeScript SDK、C#/.NET SDK）- 代码解释器
• specs/README.md - 包含沙箱生命周期 API 和沙箱执行 API 的 OpenAPI 定义
• server/README.md - 包含沙箱 Server 的启动和配置，支持 Docker 与 Kubernetes Runtime

许可证

本项目采用 Apache 2.0 License 开源。

你可以在遵守许可条款的前提下，将 OpenSandbox 用于个人或商业项目。

路线图 [2026.03]

SDK

• 沙箱客户端连接池 - 客户端沙箱连接池管理，提供预配置的沙箱实例，以毫秒级速度获取沙箱环境。
• Go SDK - Go 客户端 SDK，用于沙箱生命周期管理、命令执行和文件操作。

Sandbox Runtime

• 持久化存储 - 沙箱的持久化存储挂载（参见 Proposal 0003）。
• 本地轻量级沙箱 - 为运行在 PC 上的 AI 工具提供轻量级沙箱。
• 安全容器 - 为在容器内运行的 AI Agent 提供安全沙箱。

Deployment

• 部署指南 - 自托管 Kubernetes 集群的部署指南。

联系与讨论

• Issue：通过 GitHub Issues 提交 bug、功能请求或设计讨论
• 钉钉群：加入 OpenSandbox 技术交流群

欢迎一起把 OpenSandbox 打造成 AI 场景下的通用沙箱基础设施。

Star History

---

此页内容来自仓库源文件：docs/README_zh.md