文档 | 中文文档

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

OpenSandbox 现已入选 CNCF Landscape。

特性

• 多语言 SDK：提供 Python、Java/Kotlin、JavaScript/TypeScript、C#/.NET 和 Go 语言的沙箱 SDK。
• 沙箱协议：定义了沙箱生命周期管理 API 和沙箱执行 API，方便用户扩展自定义的沙箱运行时。
• 沙箱运行时：内置支持 Docker 和 高性能 Kubernetes 运行时 的生命周期管理功能，既可本地运行，也可进行大规模分布式调度。
• 沙箱环境：内置命令行、文件系统和代码解释器实现。示例涵盖编码代理（如 Claude Code）、浏览器自动化（Chrome、Playwright）以及桌面环境（VNC、VS Code）。
• 网络策略：统一的 Ingress 网关，支持多种路由策略，并为每个沙箱提供 出口控制。
• 强隔离性：支持 gVisor、Kata Containers 和 Firecracker microVM 等安全容器运行时，以增强沙箱工作负载与宿主机之间的隔离。详细信息请参阅 安全容器运行时指南。

SDK

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

CLI

OpenSandbox 还提供了 osb 命令行工具，用于常见的沙箱工作流：创建沙箱、运行命令、移动文件、查看诊断信息以及管理运行时出口策略。

安装：

pip install opensandbox-cli
# 或
uv tool install opensandbox-cli

快速入门：

osb config init
osb config set connection.domain localhost:8080
osb config set connection.protocol http
osb sandbox create --image python:3.12 --timeout 30m -o json
osb command run <sandbox-id> -o raw -- python -c "print(1 + 1)"

完整命令参考请参阅 CLI README。

MCP

OpenSandbox 的 MCP 服务器向支持 MCP 的客户端（如 Claude Code 和 Cursor）暴露了沙箱创建、命令执行和文本文件操作等功能。

安装并运行：

pip install opensandbox-mcp
opensandbox-mcp --domain localhost:8080 --protocol http

最小化 stdio 配置：

{
  "mcpServers": {
    "opensandbox": {
      "command": "opensandbox-mcp",
      "args": ["--domain", "localhost:8080", "--protocol", "http"]
    }
  }
}

客户端特定的设置请参阅 MCP README。

入门指南

要求：

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

安装并配置沙箱服务器

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

uvx opensandbox-server

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

创建代码解释器并执行命令/代码

安装代码解释器 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. 创建一个沙箱
    sandbox = await Sandbox.create(
        "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. 执行一个 shell 命令
        execution = await sandbox.commands.run("echo 'Hello OpenSandbox!'")
        print(execution.logs.stdout[0].text)

        # 3. 写入一个文件
        await sandbox.files.write_files([
            WriteEntry(path="/tmp/hello.txt", data="Hello World", mode=644)
        ])

        # 4. 读取一个文件
        content = await sandbox.files.read_file("/tmp/hello.txt")
        print(f"Content: {content}") # Content: Hello World

        # 5. 创建一个代码解释器
        interpreter = await CodeInterpreter.create(sandbox)

        # 6. 执行 Python 代码（单次运行，直接指定语言）
        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. 清理沙箱
    await sandbox.kill()

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

更多示例

OpenSandbox 提供了涵盖 SDK 使用、代理集成、浏览器自动化以及训练工作负载的示例。所有示例代码都位于 examples/ 目录中。

🎯 基本示例

• code-interpreter - 沙箱中的端到端代码解释器 SDK 工作流程。
• aio-sandbox - 使用 OpenSandbox SDK 的一体化沙箱设置。
• agent-sandbox - 示例集成，用于在 Kubernetes 上运行 OpenSandbox 工作负载，并与 kubernetes-sigs/agent-sandbox 集成。
• 卷 — Docker PVC / 命名卷、Docker OSSFS、Kubernetes PVC：持久化和共享存储模式。

🤖 编码代理集成

• 编码 CLI — Claude Code、Gemini CLI、OpenAI Codex CLI、Qwen Code、Kimi CLI：在 OpenSandbox 中运行各个供应商的 CLI。
• langgraph - LangGraph 状态机工作流，用于创建/运行带有回退重试功能的沙箱任务。
• google-adk - Google ADK 代理，使用 OpenSandbox 工具来读写文件和执行命令。
• openclaw - 在沙箱内启动 OpenClaw 网关。

🌐 浏览器和桌面环境

• chrome - Chromium 沙箱，配备 VNC 和 DevTools 访问权限，用于自动化和调试。
• playwright - Playwright + Chromium 无头爬取和测试示例。
• desktop - 沙箱中的完整桌面环境，支持 VNC 访问。
• vscode - 在沙箱内运行 code-server (VS Code Web)，用于远程开发。

🧠 机器学习和训练

• rl-training - 在沙箱中进行 DQN CartPole 训练，支持检查点保存和摘要输出。

更多详情，请参阅 examples 以及每个示例目录中的 README 文件。

项目结构

目录	描述
sdks/	多语言 SDK（Python、Java/Kotlin、TypeScript/JavaScript、C#/.NET）
specs/	OpenAPI 规范和生命周期规范
server/	Python FastAPI 沙箱生命周期服务器
cli/	OpenSandbox 命令行界面
kubernetes/	Kubernetes 部署及示例
components/execd/	沙箱执行守护进程（命令和文件操作）
components/ingress/	沙箱流量入口代理
components/egress/	沙箱网络出口控制
sandboxes/	运行时沙箱实现
examples/	集成示例和用例
oseps/	OpenSandbox 改进建议
docs/	架构和设计文档
tests/	跨组件端到端测试
scripts/	开发和维护脚本

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

文档

• docs/architecture.md – 整体架构与设计哲学
• oseps/README.md – OpenSandbox 增强提案
• SDK
  • 沙箱基础 SDK（Java/Kotlin SDK、Python SDK、JavaScript/TypeScript SDK、C#/.NET SDK）、Go SDK – 包含沙箱生命周期管理、命令执行、文件操作等功能
  • 代码解释器 SDK（Java/Kotlin SDK、Python SDK、JavaScript/TypeScript SDK、C#/.NET SDK）– 代码解释器
• cli/README.md – OpenSandbox CLI 安装及命令参考
• sdks/mcp/sandbox/python/README.md – MCP 服务器安装与客户端配置
• specs/README.md – 沙箱生命周期 API 和沙箱执行 API 的 OpenAPI 定义
• server/README.md – 沙箱服务器启动与配置；支持 Docker 和 Kubernetes 运行时

许可证

本项目采用 Apache 2.0 许可证 开源。

路线图 [2026.03]

SDK

• 沙箱客户端连接池 – 客户端侧的沙箱连接池管理，提供预置的沙箱环境，可在 X 毫秒内获取运行环境。已在 Kotlin SandboxPool 中实现，并在 Kotlin SDK README 中记录。相关 PR：#301、#393、#617。
• Go SDK – Go 客户端 SDK，用于沙箱生命周期管理、命令执行和文件操作。详见 Go SDK README。相关 PR：#597、#683、#707。

沙箱运行时

• 持久化存储卷 – 可挂载的沙箱持久化存储卷。详见 提案 0003、Docker PVC / 命名卷、Docker OSSFS 以及 Kubernetes PVC。相关 PR：#166、#233、#424、#515、#563。
• 本地轻量级沙箱 – 适用于直接在个人电脑上运行 AI 工具的轻量级沙箱。
• 安全容器 – 用于在容器内运行 AI 代理的安全沙箱。详见 安全容器运行时指南。相关 PR：#177、#249、#417。

部署

• 指南 – 自托管 Kubernetes 集群的部署指南。详见 Kubernetes README 以及 kubernetes/charts/ 中的 Helm Chart 文档。相关 PR：#232、#302、#342。

联系与讨论

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

星标历史

OpenSandbox 快速上手指南

OpenSandbox 是一个面向 AI 应用的通用沙箱平台，支持 Docker 和 Kubernetes 运行时，适用于代码执行、Agent 评估、浏览器自动化及强化学习训练等场景。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows (WSL2 推荐)
• 容器运行时：必须安装 Docker (用于本地执行)
• 编程语言：推荐安装 Python 3.10+ (用于运行示例和本地服务)
• 包管理工具：推荐安装 uv 或 pip 以加速依赖安装

安装步骤

1. 初始化并启动 Sandbox 服务器

使用 uv (推荐) 或 pip 快速初始化配置并启动本地服务器。以下命令将生成一个基于 Docker 的示例配置文件并启动服务：

# 初始化配置 (生成 ~/.sandbox.toml)
uvx opensandbox-server init-config ~/.sandbox.toml --example docker

# 启动服务器
uvx opensandbox-server

提示：若未安装 uv，可使用 pip install uv 或直接使用 pip install opensandbox-server。

2. 安装客户端 SDK

根据您的需求选择对应的语言 SDK。以下是 Python 环境的安装命令：

# 安装核心 SDK
pip install opensandbox

# 安装代码解释器专用 SDK (用于执行代码示例)
pip install opensandbox-code-interpreter

其他语言安装参考：

• Node.js: npm install @alibaba-group/opensandbox
• Go: go get github.com/alibaba/OpenSandbox/sdks/sandbox/go
• .NET: dotnet add package Alibaba.OpenSandbox

基本使用

以下是一个完整的 Python 示例，演示如何创建一个沙箱、执行 Shell 命令、读写文件以及运行 Python 代码。

创建文件 main.py 并填入以下内容：

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. 创建沙箱
    # 使用官方提供的 code-interpreter 镜像
    sandbox = await Sandbox.create(
        "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. 执行 Shell 命令
        execution = await sandbox.commands.run("echo 'Hello OpenSandbox!'")
        print(execution.logs.stdout[0].text)

        # 3. 写入文件
        await sandbox.files.write_files([
            WriteEntry(path="/tmp/hello.txt", data="Hello World", mode=644)
        ])

        # 4. 读取文件
        content = await sandbox.files.read_file("/tmp/hello.txt")
        print(f"File Content: {content}")

        # 5. 创建代码解释器
        interpreter = await CodeInterpreter.create(sandbox)

        # 6. 执行 Python 代码
        result = await interpreter.codes.run(
              """
                  import sys
                  print(sys.version)
                  result = 2 + 2
                  result
              """,
              language=SupportedLanguage.PYTHON,
        )

        print(f"Code Result: {result.result[0].text}") 
        print(f"Stdout Logs: {result.logs.stdout[0].text}")

    # 7. 清理沙箱资源
    await sandbox.kill()

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

运行脚本：

python main.py

预期输出： 您将看到 Shell 命令的回显、文件内容 "Hello World"，以及 Python 代码的执行结果（版本号及计算结果 4）。

---

进阶：使用命令行工具 (CLI)

如果您不想编写代码，也可以使用 osb 命令行工具直接操作沙箱：

# 安装 CLI
pip install opensandbox-cli

# 配置连接信息
osb config init
osb config set connection.domain localhost:8080
osb config set connection.protocol http

# 创建沙箱并执行命令
SANDBOX_ID=$(osb sandbox create --image python:3.12 --timeout 30m -o json | jq -r '.id')
osb command run $SANDBOX_ID -o raw -- python -c "print(1 + 1)"