Feat/sandbox

[huanghuoguoguo]

LangBot Box：沙箱执行系统

概述

本 PR 引入 LangBot Box，让 LLM Agent、MCP Server，以及后续的 Skill/工具执行都能在隔离环境中运行 Shell 命令、Python 脚本和长生命周期进程。

当前实现已经不是“代码主要都在 LangBot 主仓”那种结构了，职责现在明确拆成两层：

• LangBot 主仓：负责产品集成层，包括 sandbox_exec 工具暴露、Profile/宿主机路径策略、MCP Box-stdio 集成、状态接口，以及运行时连接管理。
• langbot-plugin-sdk：负责 Box Runtime 底座，包括协议、模型、错误类型、Session 生命周期、Backend 抽象、Docker/Podman/nsjail 执行后端，以及独立运行的 Box Server。

换句话说，这个 PR 现在本质上是一个跨仓协作的沙箱能力接入：LangBot 侧负责接入和策略，SDK 侧承载大部分可复用的运行时实现。

分支: feat/sandbox

---

功能

1. sandbox_exec 原生工具：LLM Agent 获得一个原生工具，可在隔离环境中运行 Shell 命令和 Python 脚本，用于精确计算、结构化解析、临时文件处理和代码执行。
2. MCP Server 隔离运行（Box-stdio）：stdio 模式的 MCP Server 在 Box 可用时会自动运行在沙箱中，支持依赖安装、路径重写和 stdio-over-WebSocket 桥接。
3. 可配置的安全边界：支持网络开关、CPU/内存/PID 限制、只读根文件系统、宿主机挂载白名单、危险路径阻断。
4. 可插拔执行后端：当前运行时支持 Podman、Docker 和 nsjail 三种 Backend，统一走同一套 BoxRuntime 生命周期管理。
5. 可观测性接口：LangBot 暴露 /api/v1/box/status、/api/v1/box/sessions、/api/v1/box/errors 供运维和调试使用。

---

架构

                         LangBot 主进程
                               │
         ┌─────────────────────┼─────────────────────┐
         │                     │                     │
  NativeToolLoader      RuntimeMCPSession       BoxService
  (sandbox_exec)        (MCP Box-stdio)   (策略 / Profile / 校验)
         │                     │                     │
         └─────────────────────┼─────────────────────┘
                               │
                BoxRuntimeConnector (LangBot)
                               │
                ActionRPCBoxClient (SDK)
                               │
               ┌───────────────┴────────────────┐
               │ stdio（本地开发）               │ WebSocket（Docker 部署）
               │ 子进程                          │ ws://langbot_box_runtime:5411
               ▼                                 ▼
          langbot_plugin.box.server（SDK 独立服务）
                               │
         ┌─────────────────────┼─────────────────────┐
         │                     │                     │
  BoxServerHandler       BoxRuntime            aiohttp WS Relay
  (Action RPC)      (Session / 进程管理)      (:5410, MCP attach)
                               │
                  ┌────────────┼────────────┐
                  │            │            │
             PodmanBackend DockerBackend NsjailBackend
                               │
                  容器 / nsjail 进程隔离环境

分层与职责

层	仓库	主要模块	职责
集成层	LangBot	pkg/box/service.py	Profile 应用、宿主机路径校验、输出裁剪、对外 API
连接层	LangBot	pkg/box/connector.py	选择 stdio 子进程或远程 WebSocket 连接 Box Runtime
工具接入层	LangBot	provider/tools/loaders/native.py	暴露 sandbox_exec 给模型
MCP 集成层	LangBot	provider/tools/loaders/mcp.py	将 stdio MCP Server 接入 Box Session / managed process
HTTP 可观测层	LangBot	api/http/controller/groups/box.py	暴露状态、Session、错误列表接口
协议层	SDK	langbot_plugin.box.actions / client.py	Action RPC 动作定义与客户端调用
模型层	SDK	langbot_plugin.box.models	BoxSpec、BoxProfile、BoxSessionInfo 等共享模型
运行时层	SDK	langbot_plugin.box.runtime	Session TTL、复用、managed process 生命周期
Backend 层	SDK	backend.py / nsjail_backend.py	Docker / Podman / nsjail 执行抽象
服务层	SDK	langbot_plugin.box.server	独立运行的 Box Server + MCP WebSocket Relay

---

核心设计决策

1. Runtime 底座下沉到 SDK

现在 Box 的核心不再放在 LangBot 主仓，而是下沉到 langbot-plugin-sdk/src/langbot_plugin/box/。这样做的原因是：

• Box Runtime 本身是一个可独立运行的服务，天然更适合放在共享基础设施层。
• LangBot 和 Box Runtime 复用了 SDK 里现有的 Action RPC / IO 抽象，不需要在主仓重复维护一套协议栈。
• Box 的模型、错误、客户端、后端探测、独立服务入口都更偏“运行时底座”，不应和 LangBot 产品逻辑耦合在一起。

LangBot 主仓保留的是产品语义相关能力：是否暴露工具、如何应用 Profile、哪些宿主机路径允许挂载、MCP 如何接入、HTTP 如何观测。

2. 独立进程架构

Box Runtime 作为独立进程 / 独立容器运行，通过 Action RPC 与 LangBot 主进程通信：

• 本地开发：LangBot 通过 BoxRuntimeConnector 启动 python -m langbot_plugin.box.server --port 5410 子进程，并用 stdio 建立连接。
• Docker 部署：LangBot 连接 langbot_box_runtime 容器暴露的 WebSocket 服务，运行时本身仍由 SDK 中的 langbot_plugin.box.server 提供。

这样主进程不需要直接承载底层容器操作逻辑，也更方便把 Box Runtime 单独部署、单独升级。

3. Session 复用

Session 是 Box 的核心调度单元。BoxRuntime 维护一个 session_id -> RuntimeSession 映射：

• sandbox_exec 默认以 query_id 作为 session_id
• MCP Box-stdio 以 mcp-{uuid} 形式持有独立 Session
• 同一 Session 内的多次执行会复用已有隔离环境，而不是每次重新创建容器 / nsjail 工作目录

Session 带 TTL（默认 300 秒）。回收条件是：

• last_used_at 超过 TTL
• 且当前没有运行中的 managed process

这保证了：

• sandbox_exec 可以在同一次对话里做多步有状态执行
• MCP Server 不会因为空闲 TTL 被误清理

4. Profile 体系在 LangBot 层生效

sandbox_exec 不直接把所有隔离参数完全裸露给模型，而是先通过 LangBot 的 BoxService 应用 Profile：

• 未传的字段由 Profile 默认值补齐
• 被锁定的字段会强制覆盖用户/模型传参
• timeout_sec 会被 clamp 到 profile.max_timeout_sec

当前内置 Profile 仍包括：

Profile	网络	CPU	内存	根文件系统	挂载	最大超时
default	OFF	1.0	512MB	只读	读写	120s
offline_readonly	OFF（锁定）	0.5	256MB	只读（锁定）	只读（锁定）	60s
network_basic	ON	1.0	512MB	只读	读写	120s
network_extended	ON	2.0	1024MB	可写	读写	300s

MCP Box-stdio 不走这套 Profile，而是走 MCPServerBoxConfig 独立配置，因为它的信任模型与 LLM 生成代码不同。

5. Backend 抽象与探测顺序

SDK 里的 BoxRuntime 现在统一从以下顺序探测可用 Backend：

1. PodmanBackend
2. DockerBackend
3. NsjailBackend

三者都实现同一套 BaseSandboxBackend 接口，上层 BoxService / BoxRuntimeConnector / ActionRPCBoxClient 都不感知底层具体是容器还是 nsjail。

6. MCP Box-stdio 模式

LangBot 中的 RuntimeMCPSession 在检测到 stdio MCP 且 Box 可用时，会执行下面这条链路：

1. 用 BoxService.create_session() 创建 Session
2. 根据 pyproject.toml / requirements.txt 自动安装依赖
3. 把宿主机路径改写为容器内 /workspace/...
4. 用 start_managed_process() 启动 MCP 进程
5. 通过 Box Runtime 暴露的 WebSocket Relay 连接到该进程的 stdin/stdout
6. 再由 LangBot 内部 MCP Client 完成协议初始化和工具发现

MCP 协议语义仍然在 LangBot 侧，SDK 里的 Box Runtime 只负责“把一个托管进程安全地跑起来并提供 attach 能力”。

7. Host Path 挂载

Box 把宿主机目录挂载到沙箱内固定的 /workspace：

• sandbox_exec：默认取 config.yaml 中的 box.default_host_workspace
• MCP Box-stdio：由 LangBot 从 MCP command/args 推断项目根目录，或使用 MCP 配置里的 box.host_path

Docker 部署下，langbot 和 langbot_box_runtime 会共享挂载同一宿主机目录，例如 ./data/box-workspaces:/workspaces。这样：

• LangBot 侧能做路径白名单校验
• Box Runtime 侧也能看到同一宿主机路径并据此创建实际容器挂载

---

核心接口

LangBot：BoxService

class BoxService:
    available: bool

    async def execute_sandbox_tool(
        parameters: dict,
        query: Query,
    ) -> dict

    async def execute_skill_tool(
        skill_data: dict,
        tool_def: dict,
        parameters: dict,
        query: Query,
    ) -> dict

    async def create_session(
        spec_payload: dict,
        skip_host_mount_validation: bool = False,
    ) -> dict

    async def start_managed_process(
        session_id: str,
        process_payload: dict,
    ) -> dict

    def get_managed_process_websocket_url(
        session_id: str,
    ) -> str

SDK：BoxSpec

class BoxSpec(pydantic.BaseModel):
    cmd: str = ''
    workdir: str = '/workspace'
    timeout_sec: int = 30
    network: BoxNetworkMode = OFF
    session_id: str
    env: dict[str, str] = {}
    image: str = 'python:3.11-slim'
    host_path: str | None = None
    host_path_mode: BoxHostMountMode = RW
    cpus: float = 1.0
    memory_mb: int = 512
    pids_limit: int = 128
    read_only_rootfs: bool = True

SDK：BaseSandboxBackend

class BaseSandboxBackend(ABC):
    name: str

    async def is_available() -> bool
    async def start_session(spec: BoxSpec) -> BoxSessionInfo
    async def exec(session: BoxSessionInfo, spec: BoxSpec) -> BoxExecutionResult
    async def stop_session(session: BoxSessionInfo) -> None
    async def start_managed_process(session, spec) -> asyncio.subprocess.Process
    async def cleanup_orphaned_containers(instance_id: str) -> None

---

通信方式

Action RPC

Box 复用 langbot_plugin.runtime.io 这一套 Action RPC / Connection / Handler 基础设施。当前 Box Runtime 暴露的动作包括：

Action	含义
box_health	健康检查
box_status	获取运行时状态
box_exec	在 Session 内执行命令
box_create_session	创建 Session
box_get_session	获取单个 Session
box_get_sessions	获取全部 Session
box_delete_session	删除 Session
box_start_managed_process	启动托管进程
box_get_managed_process	获取托管进程状态
box_get_backend_info	获取当前 Backend 信息
box_shutdown	优雅关闭 Runtime

传输模式

模式	场景	实现
stdio	本地开发、非 Docker	LangBot 拉起 langbot_plugin.box.server 子进程并通过 stdio 通信
WebSocket	Docker / 远程 Runtime	LangBot 连接 ws://langbot_box_runtime:5411

WebSocket Relay

Box Runtime 还会在 :5410 起一个轻量 aiohttp 服务，用于 MCP 托管进程 attach：

• GET /v1/sessions/{session_id}/managed-process/ws

该接口负责把 WebSocket 文本消息桥接到托管进程的 stdin/stdout。

---

部署方式

本地开发

无需额外服务编排。LangBot 会自动启动本地 Box Runtime 子进程。

box:
  profile: 'default'
  default_host_workspace: './data/box-workspaces/default'
  allowed_host_mount_roots:
    - './data/box-workspaces'
    - '/tmp'

宿主机需要具备至少一种可用后端：Podman、Docker 或 nsjail。

Docker Compose

services:
  langbot_box_runtime:
    image: rockchin/langbot:latest
    command: ["uv", "run", "--no-sync", "-m", "langbot_plugin.box.server"]
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./data/box-workspaces:/workspaces
    ports:
      - 5410:5410

  langbot:
    volumes:
      - ./data/box-workspaces:/workspaces

主 LangBot 进程通过 ws://langbot_box_runtime:5411 与 Runtime 通信，通过 http://langbot_box_runtime:5410 访问 managed-process relay。

---

安全模型

1. 禁止挂载路径：/etc、/proc、/sys、/dev、/root、/boot、容器运行时 socket 等路径被硬编码阻断。
2. 允许挂载根目录白名单：只有 allowed_host_mount_roots 下的路径才允许挂载到 /workspace。
3. Profile 锁定：安全关键字段可由管理员锁定，模型侧无法覆盖。
4. 资源限制：CPU、内存、PID 限制由 Backend 在容器 / nsjail 层实际执行。
5. 只读根文件系统：容器 Backend 默认开启；nsjail Backend 也固定以只读系统挂载为核心模型。
6. 输出截断：原始 stdout/stderr 各自有 1MB 上限，避免高吞吐命令把内存打满。
7. Session TTL：空闲 Session 默认 300 秒自动回收，但有运行中 managed process 时不会被回收。
8. 孤儿清理：容器 Backend 启动时会清理前一实例残留的 langbot.box=true 容器。

---

Skill / 插件如何接入

1. 通过 sandbox_exec

最简单的接入方式仍然是把 sandbox_exec 放进模型工具列表，让模型在需要时自行调用。

2. 直接调用 BoxService

适合插件、Skill 或平台内部逻辑明确需要执行固定命令的场景：

result = await ap.box_service.execute_sandbox_tool(
    parameters={'cmd': 'python3 -c "print(42)"', 'timeout_sec': 10},
    query=query,
)

3. MCP Server in Box

stdio MCP Server 在 Box 可用时自动运行在沙箱内，并支持通过 box 字段覆盖镜像、网络、挂载模式、启动超时等参数：

{
  "name": "my-mcp-server",
  "mode": "stdio",
  "command": "python",
  "args": ["server.py"],
  "box": {
    "image": "node:20",
    "network": "on",
    "host_path_mode": "ro",
    "startup_timeout_sec": 180
  }
}

---

文件结构

LangBot 主仓

src/langbot/pkg/box/
├── __init__.py
├── connector.py        # BoxRuntimeConnector，选择 stdio / ws 连接
└── service.py          # BoxService，Profile / 安全策略 / 对外 API

src/langbot/pkg/provider/tools/loaders/
├── native.py           # sandbox_exec 工具定义
└── mcp.py              # MCP Box-stdio 集成

src/langbot/pkg/api/http/controller/groups/
└── box.py              # /api/v1/box/status /sessions /errors

langbot-plugin-sdk

src/langbot_plugin/box/
├── __init__.py
├── __main__.py
├── actions.py          # Box Action RPC 动作枚举
├── backend.py          # BaseSandboxBackend + Docker / Podman Backend
├── client.py           # BoxRuntimeClient / ActionRPCBoxClient
├── errors.py           # Box 错误类型
├── models.py           # BoxSpec / BoxProfile / BoxSessionInfo 等
├── nsjail_backend.py   # nsjail Backend
├── runtime.py          # BoxRuntime，Session / managed process 生命周期
├── security.py         # 宿主机路径与安全校验
└── server.py           # 独立 Box Server + WebSocket Relay

部署与测试

LangBot/docker/docker-compose.yaml                       # Box Runtime 容器编排
LangBot/src/langbot/templates/config.yaml               # box 配置段

LangBot/tests/unit_tests/box/                           # BoxService / Connector 单测
LangBot/tests/unit_tests/provider/test_mcp_box_integration.py
LangBot/tests/integration_tests/box/                    # 端到端集成测试
langbot-plugin-sdk/tests/box/test_nsjail_backend.py     # nsjail Backend 单测

---

测试覆盖

• LangBot 单测：覆盖 BoxService、BoxRuntimeConnector、sandbox_exec 接入、MCP Box 配置与路径改写等逻辑。
• LangBot 集成测试：覆盖端到端执行、Session 持久化、超时、网络隔离、managed process 生命周期、MCP Server in Box。
• SDK 单测：覆盖 nsjail Backend 的探测、执行、Session 清理与隔离行为。

---

Q&A

Q: Profile 是全局的吗？模型能覆盖哪些参数？

是全局配置，来源于 config.yaml 的 box.profile。未锁定字段可被模型覆盖；锁定字段始终回退到 Profile 值。

Q: MCP Server 为什么不走 Profile？

因为 MCP Server 是管理员显式配置的可信进程，需求和 LLM 生成代码不同。它默认需要更高可用性，比如联网安装依赖，所以走 MCPServerBoxConfig 独立配置。

Q: Session TTL 会不会把 MCP Server 提前清掉？

不会。只要 Session 上还有运行中的 managed process，TTL 回收逻辑就会跳过它。

Q: 现在没有 Docker / Podman 怎么办？

Runtime 会按 Podman -> Docker -> nsjail 的顺序探测可用 Backend。三者都没有时，BoxService.available = False，sandbox_exec 不会暴露给模型，stdio MCP 也会回退到宿主机直接运行。

Q: nsjail 现在是什么状态？

已经接入当前代码路径，不再只是规划。它是 BoxRuntime 的正式候选 Backend 之一，只是在实际部署中是否命中它，取决于宿主机上是否安装并可用。

Q: 如何接入新的 Backend？

实现 BaseSandboxBackend 接口并加入 BoxRuntime.backends 探测列表即可。LangBot 集成层、Action RPC 协议、工具定义都不需要改。

[codecov]

Codecov Report

❌ Patch coverage is 60.97712% with 631 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/langbot/pkg/provider/tools/loaders/mcp.py	47.30%	127 Missing ⚠️
src/langbot/pkg/box/backend.py	35.35%	117 Missing ⚠️
src/langbot/pkg/box/server.py	40.90%	104 Missing ⚠️
src/langbot/pkg/box/runtime.py	77.59%	54 Missing ⚠️
src/langbot/pkg/box/connector.py	48.38%	48 Missing ⚠️
src/langbot/pkg/box/service.py	83.78%	36 Missing ⚠️
src/langbot/pkg/box/client.py	67.41%	29 Missing ⚠️
src/langbot/pkg/utils/managed_runtime.py	39.02%	25 Missing ⚠️
src/langbot/pkg/provider/tools/loaders/native.py	40.54%	22 Missing ⚠️
src/langbot/pkg/pipeline/process/handler.py	11.11%	16 Missing ⚠️
... and 9 more

📢 Thoughts on this report? Let us know!