turbo-agent-sandbox 0.1.11rc1

Turbo-Agent 沙盒组件管理：代码沙盒 / 浏览器沙盒（含指纹与登录态持久化）/ 资源调度 / VNC 接入。当前为调研打通版本。

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。

外部开发者文档

按消费方视角组织：

文档	内容
docs/external/overview.md	架构概述、与 ta-core / ta-runtime / ta-store / ta-cloud 的关系、模块边界
docs/external/concepts.md	核心概念：SandboxApplicationService / SandboxCarrier / PersistenceScope / BrowserUseSession / SandboxExecutionSession / WorkspaceMount / AccountInjection
docs/external/api-reference.md	公开 API 索引：service / manager / carrier / session 方法签名 + payload schema + builtin tool 清单
docs/external/bundles.md	Bundle 接入模式：BrowserProfileBundle / KnowledgeResourceBundle / AgentOutputsBundle / SandboxResourceOrchestrator
docs/external/scenarios.md	用户场景四例：①跑 builtin tool ②拉起 account sandbox 保存登录态 ③agent 拉起 account sandbox 恢复登录态 ④S3 文件后端集成
docs/external/vnc-proxy.md	单进程 VNC 反代教程：零配置启动 + FastAPI 反代示例 + token TTL 调优
docs/external/path-constraint.md	PathConstraint 安全规范：@tool_method(path_constraints=...) 用法
docs/external/preflight-gvisor.md	启动前 gVisor / runsc 配置步骤
docs/external/environment.md	环境变量索引（TA_SANDBOX_*）

历史与内部文档

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

许可与反馈

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