Metadata-Version: 2.4
Name: turbo-agent-sandbox
Version: 0.1.11rc4
Summary: Turbo-Agent 沙盒组件管理：代码沙盒 / 浏览器沙盒（含指纹与登录态持久化）/ 资源调度 / VNC 接入。当前为调研打通版本。
Author-email: sherlet <wuzeilmt@gmail.com>
Requires-Python: <3.14,>=3.10
Requires-Dist: anyio>=4.12.1
Requires-Dist: loguru>=0.7.3
Requires-Dist: opensandbox>=0.1.7
Requires-Dist: pydantic-settings>=2.13.1
Requires-Dist: pydantic>=2.12.5
Requires-Dist: rich>=13.7.1
Requires-Dist: turbo-agent-core
Requires-Dist: turbo-agent-runtime
Requires-Dist: turbo-agent-store
Requires-Dist: typer>=0.15.4
Provides-Extra: docker
Requires-Dist: docker>=7.1.0; extra == 'docker'
Provides-Extra: vnc
Requires-Dist: websockify>=0.13.0; extra == 'vnc'
Description-Content-Type: text/markdown

# turbo-agent-sandbox

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

- 基础沙盒：基于 [OpenSandbox](https://github.com/alibaba/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 即可正常使用。

## 安装

```bash
uv add turbo-agent-sandbox
```

可选 extras：

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

## 快速开始（30 秒）

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

## 历史与内部文档

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

## 许可与反馈

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