OpenSandbox

OpenSandbox 是一个专为 AI 应用场景设计的通用沙盒平台，旨在安全地执行大模型（LLM）可能触发的高风险操作，例如：

• 执行任意命令
• 读写文件系统
• 运行用户提交的代码（Python/Java/Go/TS 等）
• 控制浏览器（如 Chrome、Playwright）
• 启动桌面环境（VNC、VS Code Web）

它通过隔离的容器环境，确保这些操作不会影响宿主机，同时提供标准化的接口供开发者集成。

核心特性

1. 多语言 SDK

支持主流开发语言，便于不同技术栈接入：

• ✅ Python
• ✅ Java / Kotlin
• ✅ JavaScript / TypeScript
• 🚧 Go SDK（规划中）

2. 统一沙箱协议

定义了两套标准 API：

• 生命周期管理 API：创建、销毁、监控沙箱实例
• 执行 API：在沙箱内运行命令、读写文件、执行代码

开发者可基于此协议实现自定义沙箱运行时。

3. 可扩展的运行时

默认支持：

• Docker：适合本地开发与测试
• Kubernetes：支持大规模分布式调度，适用于生产环境

4. 内置沙箱环境与示例

开箱即用的环境包括：

• 命令行（Command）
• 文件系统（Filesystem）
• 代码解释器（Code Interpreter）

并提供多个完整示例，覆盖：

• Coding Agent（Claude Code、Gemini、Codex 等）
• 浏览器自动化（Chrome、Playwright）
• 远程桌面（VNC、VS Code Web）

快速开始

环境要求

• Docker（必需）
• Python 3.10+（用于本地服务和示例）

1. 克隆项目

git clone https://github.com/alibaba/OpenSandbox.git
cd OpenSandbox

2. 启动沙箱服务

cd server
uv sync
cp example.config.toml ~/.sandbox.toml  # 复制配置文件
uv run python -m src.main               # 启动服务

注：uv 是新一代 Python 包管理工具，可替代 pip 和 venv，安装方式见 astral.sh/uv

3. 安装 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. 创建沙箱（基于 Docker 镜像）
    sandbox = await Sandbox.create(
        "opensandbox/code-interpreter:latest",
        entrypoint=["/opt/opensandbox/code-interpreter.sh"],
        env={"PYTHON_VERSION": "3.11"},
        timeout=timedelta(minutes=10),
    )

    async with sandbox:
        # 2. 执行 Shell 命令
        exec_result = await sandbox.commands.run("echo 'Hello OpenSandbox!'")
        print(exec_result.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}")

        # 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("Python 版本:", result.logs.stdout[0].text)  # 如: 3.11.14

    # 7. 自动清理沙箱（或手动调用 sandbox.kill()）

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

典型应用场景

所有示例代码位于 examples/ 目录，包含详细 README。

项目结构概览

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