OpenSandbox

Documentation | 中文文档

OpenSandbox 是一个面向 AI 应用的通用沙箱平台，提供多语言 SDK、统一的沙箱 API 以及 Docker/Kubernetes 运行时。适用于编码智能体（Coding Agents）、图形界面智能体（GUI Agents）、智能体评估、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 Gateway 提供多种路由策略，并支持各沙箱粒度的 egress 控制。
强隔离性：支持 gVisor、Kata Containers 和 Firecracker 微虚拟机（microVM）等安全容器运行时，增强沙箱工作负载与宿主机之间的隔离性。详情请参阅安全容器运行时指南。

示例

基本沙箱操作 [Docker]

要求：

Docker（本地执行必需）
Python 3.10+（示例及本地运行时必需）

1. 安装并配置沙箱服务器

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

如果你倾向于从源码构建，仍可克隆仓库进行开发，但无需仅为了启动服务器而克隆整个仓库。同时，你需要确保宿主机已安装并运行 Docker。
git clone https://github.com/alibaba/OpenSandbox.git && cd OpenSandbox/server
cp opensandbox_server/examples/example.config.toml ~/.sandbox.toml
uv sync && uv run python -m opensandbox_server.main

2. 启动沙箱服务器

opensandbox-server

# 查看帮助
# opensandbox-server -h

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. 创建沙箱
    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())

alibaba/OpenSandbox