turbo-agent-sandbox

Turbo-Agent 的沙盒组件管理库：为智能体提供代码沙盒、浏览器沙盒、VNC 接管和登录态持久化的统一抽象。

• 基础沙盒：基于 OpenSandbox
• 安全运行时：默认强制 gVisor（runsc）
• 持久化粒度：(session_type_id, anchor_id) 唯一标定一个物理沙盒
• 浏览器沙盒：浏览器指纹 + 登录态整份持久化、运行环境代理注入、VNC/noVNC 接入
• 内置工具：自动注册 13 个 builtin tool（5 个 shell/artifact + 8 个浏览器交互）
• 浏览器镜像：基于 OpenSandbox desktop，含 google-chrome-stable、xdotool、中文输入/字体和 Word 文档编辑外部依赖

不兼容旧 chromium profile（2026-05-23 用户裁决）：浏览器镜像已统一收敛到 google-chrome-stable，不再向下兼容 chromium 时代导出的 browser-profile zip。 旧 archive 首次挂到新镜像启动如果出现 profile 损坏，sandbox 不做静默迁移—— 让它自然 fail，触发用户重新登录流程，重登后生成的新 archive 即可正常使用。

安装

uv add turbo-agent-sandbox

可选 extras：

uv add 'turbo-agent-sandbox[docker]'   # 启用 docker SDK（preflight 检测用）
uv add 'turbo-agent-sandbox[vnc]'      # 启用 websockify 内嵌反代支持

快速开始（30 秒）

import asyncio
from turbo_agent_sandbox import (
    SandboxApplicationService,
    SandboxAcquirePayload,
    SandboxCommandPayload,
)


async def main() -> None:
    # 无参构造即可：内部自动装配 InMemorySessionRunRegistry，不需要 Redis。
    service = SandboxApplicationService()

    # 拉起一个代码沙盒（按 session_type_id + anchor_id 复用 / 隔离）。
    await service.acquire(SandboxAcquirePayload(
        session_type_id="sandbox.execution",
        anchor_id="hello-workset",
        kind="code",
    ))

    # 在沙盒里跑一条命令。
    result = await service.run_command(SandboxCommandPayload(
        session_type_id="sandbox.execution",
        anchor_id="hello-workset",
        kind="code",
        command="uname -a && echo hello",
    ))
    print(result["stdout"])

    # 销毁沙盒（force=True 直接清空 refcount 强制回收）。
    await service.destroy(
        session_type_id="sandbox.execution",
        anchor_id="hello-workset",
        kind="code",
        force=True,
    )


asyncio.run(main())

运行前请先在 OpenSandbox Server 所在 Docker daemon 配置 gVisor（runsc）。完整步骤见 docs/external/preflight-gvisor.md。

外部开发者文档

按消费方视角组织：

历史与内部文档

• DEVELOPMENT_STATUS_AND_INTEGRATION.md —— 模块内部状态、改造进展、未结题事项；面向 sandbox 模块维护者，不建议外部消费方阅读。
• sandbox.md —— 初版设计草稿，已不代表当前实现。

许可与反馈

模块迭代仍处于早期，公开 API 在 1.0 之前可能调整。问题与反馈请提到 turbo-agent 主仓库 issue tracker。