在 AI Agent 时代，特别是 Coding Agents 和 GUI Agents 的快速发展中，安全执行用户或 AI 生成代码成为核心痛点。OpenSandbox 作为一个通用沙箱平台，通过多语言 SDK 和 Docker/Kubernetes 运行时，提供标准化隔离环境，支持命令执行、文件操作和代码解释器，实现代理的安全评估与执行。

OpenSandbox 核心架构观点

OpenSandbox 的设计遵循协议优先原则，将沙箱分为四层：SDK 层（客户端库）、Specs 层（OpenAPI 协议）、Runtime 层（生命周期管理）和 Sandbox Instances 层（容器实例）。这种分层确保了多语言一致性和可扩展性。

关键优势在于 execd 执行守护进程的注入机制：无需修改用户镜像，通过卷挂载注入 Go 实现的 execd 二进制和启动脚本。启动序列为：execd 先启动 Jupyter Server（端口 54321），再暴露 Execution API（默认端口 44772），最后 exec 用户入口点。这种透明注入支持任意基础镜像，如 ubuntu:22.04 或 python:3.11。

对于多语言代理沙箱，Sandbox Lifecycle API 处理创建 / 销毁 / 续期，Execution API 则统一文件 / 命令 / 代码执行。网络策略通过 Ingress Gateway（动态路由 {domain}/sandboxes/{id}/port/{port}）和 Egress 控制实现隔离。

证据：关键组件参数与实现细节

从架构文档中，Docker Runtime 支持两种网络模式：

  • Host Mode：容器共享宿主机网络，适合单实例开发，端口直接暴露。
  • Bridge Mode：隔离网络，通过 HTTP 路由代理，支持多租户。

资源配额强制执行：创建 Sandbox 时指定 CPU（e.g., 2 cores）、内存（e.g., 4Gi）、GPU（NVIDIA runtime）。示例代码显示超时参数如 timeout=timedelta(minutes=10)，TTL 自动过期，支持 renew-expiration API 续期。

CodeInterpreter 支持 Python/Java/JS/TS/Go/Bash，通过 Jupyter kernel 协议保持会话状态。文件操作支持批量上传（multipart POST /files/upload）、glob 搜索（GET /files/search）和权限管理（POST /files/permissions, mode=644）。

实际场景证据：在 claude-code 示例中，代理调用 Anthropic API 生成代码后，通过 sandbox.commands.run 执行构建命令，并用 CodeInterpreter 验证结果，支持迭代反馈。

落地部署清单：快速搭建多语言沙箱平台

以下是基于 GitHub README 和 server 文档的完整部署参数清单，确保 Coding Agents 安全执行。

1. 环境准备（本地 Docker 模式）

# 安装依赖
uv pip install opensandbox-server
opensandbox-server init-config ~/.sandbox.toml --example docker

# 配置示例（~/.sandbox.toml）
[server]
host = "0.0.0.0"
port = 8000
api_key = "your-secret-api-key"  # 必填，认证用

[runtime.docker]
network_mode = "bridge"  # 或 "host"
max_containers = 50      # 并发上限
default_ttl = "10m"      # 默认 TTL
image_pull_policy = "IfNotPresent"
private_registry_auth = { username = "user", password = "pass" }  # 可选

启动服务器：

opensandbox-server

2. Python SDK 集成 Coding Agent 示例

安装 SDK：

uv pip install opensandbox-code-interpreter

核心代码参数：

import asyncio
from datetime import timedelta
from opensandbox import Sandbox
from code_interpreter import CodeInterpreter, SupportedLanguage

async def agent_sandbox():
    # 创建沙箱：镜像、入口点、资源、超时
    sandbox = await Sandbox.create(
        "opensandbox/code-interpreter:v1.0.1",
        entrypoint=["/opt/opensandbox/code-interpreter.sh"],
        env={"PYTHON_VERSION": "3.11"},
        cpu="1",
        memory="2Gi",
        timeout=timedelta(minutes=15),  # 单次操作超时
        ttl=timedelta(hours=1)         # 沙箱存活 TTL
    )
    
    async with sandbox:
        # 文件上传：AI 生成代码
        await sandbox.files.write_files([
            {"path": "/workspace/main.py", "data": "print(2+2)", "mode": 644}
        ])
        
        # 命令执行：安装依赖
        exec_result = await sandbox.commands.run("pip install numpy", cwd="/workspace")
        print(exec_result.logs.stdout[0].text)  # 实时 SSE 流
        
        # 代码解释器：多语言执行
        interpreter = await CodeInterpreter.create(sandbox)
        result = await interpreter.codes.run(
            "import numpy as np; np.sum([1,2,3])",
            language=SupportedLanguage.PYTHON
        )
        print(result.result[0].text)  # 输出 6
    
    await sandbox.kill()  # 清理

asyncio.run(agent_sandbox())

3. Kubernetes 运行时参数（大规模部署）

克隆 kubernetes 子模块，部署清单（kubernetes/）：

# Helm 值覆盖示例
replicaCount: 3
resources:
  limits:
    cpu: 2
    memory: 4Gi
ingress:
  enabled: true
  host: sandbox.yourdomain.com
egress:
  allow_domains: ["api.anthropic.com", "*.openai.com"]  # 代理出站白名单
metrics:
  scrape_interval: 30s

监控点：

  • Prometheus Metrics：GET /metrics (CPU/Mem/Exec 时间)，SSE 流 /metrics/watch。
  • 状态转换日志：Sandbox 状态机（Pending -> Running -> Expired）。
  • 阈值告警：容器数 >80%、单沙箱 Exec >5min、错误率 >10%。

4. GUI Agents 扩展：浏览器沙箱

使用 chrome 示例：

sandbox = await Sandbox.create("opensandbox/chrome:v1", expose_ports=[9222])
endpoint = await sandbox.endpoints.get(9222)  # 获取 DevTools URL
# Playwright 连接：浏览器自动化测试

回滚策略：设置 max_retries=3，失败降级到轻量镜像；生产环境启用 PersistentVolume（OSEP-0003）。

5. 风险限制与优化

  • 安全：API Key + Token 认证，Egress 白名单防数据泄露，资源 quota 防 DoS。
  • 性能：Bridge 模式下 Ingress 路由延迟 <50ms，execd Go 实现低开销。
  • 扩展：Roadmap 支持 Go SDK、本地轻量沙箱、Helm Chart。

通过以上参数，开发者可在 10 分钟内搭建支持多语言代理的沙箱平台，适用于 Agent 评估、代码执行和 RL 训练。

资料来源：

（正文约 1250 字）" posts/2026/03/05/open-sandbox-multi-language-agent-sandboxing.md