沙箱配置

Box 由 LangBot 主进程配置，Box Runtime 负责实际执行。常规部署只需要选择后端、设置工作目录和安全预设。Docker、nsjail 和 E2B 提供沙箱环境；Host 后端则直接在 Box Runtime 所在机器上执行命令。

推荐配置

box:
  enabled: true
  backend: 'local'        # 自动从 Docker / Nsjail 里选可用的
  local:
    profile: 'default'
    host_root: './data/box'
    skills_root: 'skills'
  docker:
    cpu_limit_enabled: true

• enabled：沙箱总开关。设为 false 时，沙箱内置工具、Skill 添加/编辑、stdio MCP 托管等依赖 Box 的能力都不可用。
• backend：见下文「后端选择」。
• local.profile：安全预设，控制网络、挂载和资源限制。
• local.host_root：主机上的沙箱工作目录，会映射为沙箱内的 /workspace。
• local.skills_root：Skill 包目录；相对路径解析到 host_root 下，默认 host_root/skills。
• docker.cpu_limit_enabled：是否为 Docker 沙箱容器启用 CPU 限制；设为 false 时不传 docker run --cpus，内存和 PID 限制仍然保留。

后端选择

Box 可以跑在本机容器、云端沙箱，也可以直接使用 Box Runtime 主机进程。box.backend 选择走哪一种：

local 是「自动选择」的简写，不是和 docker/nsjail 平级的第四种后端。它只会尝试 Docker 和 Nsjail，永远不会自动选择 host。本机后端使用 box.local.* 中的工作区配置；云端后端使用 box.e2b.*。

安全预设

box.local.profile 控制 Docker / Nsjail 本机沙箱后端的网络、挂载和资源限制：

优先使用最小权限：不需要网络就用 default 或 offline_readonly；只把必要目录加入 allowed_mount_roots。

本机工作区配置（box.local.*）

Docker、Nsjail 和 Host 共用工作区路径配置；隔离与资源配置仅在对应沙箱后端能够实施时生效：

Host 后端（可信本地开发）

Host 是依赖最少的本地选项，不需要安装 Docker 或 Nsjail。它必须显式选择：

box:
  enabled: true
  backend: 'host'
  local:
    host_root: './data/box'
    skills_root: 'skills'

WebUI、Agent 工具和调用方式不变：仍然使用相同的会话作用域、exec/read/write/edit/glob/grep、Skills 和 stdio MCP。区别只在执行层：

• /workspace、workdir 和 Skill 挂载路径会转换为 Box Runtime 主机上的实际路径。
• 子进程只继承最小的 PATH、语言和终端环境，再叠加请求中显式传入的变量；LangBot / Box 控制密钥不会自动进入子进程环境。这能减少意外泄露，但不构成文件系统隔离。
• exec 和托管进程在独立进程组中启动；超时、取消、停止、删除会话和 Runtime 关闭都会终止对应进程树。
• 空闲回收、托管进程保活和 persistent 规则与其他后端一致。
• 状态接口会返回 unsafe_direct_execution: true，便于运维侧识别当前没有沙箱隔离。

Host MVP 支持带 sh 的 POSIX 系统（Linux / macOS）。Windows 请先使用 WSL；原生 Windows 进程后端尚未支持。

外部 WebSocket Box Runtime 使用 Host 时，必须在 LangBot 与 Box Runtime 两侧设置相同的强随机 LANGBOT_BOX_CONTROL_TOKEN。本地自动管理的 stdio Box Runtime 不需要额外配置该令牌。启用了托管沙箱 admission 的 Cloud 环境仍会按隔离能力和指定后端进行校验，Host 不会绕过这些检查。

Box 沙箱内存配置

box.default_memory_mb 控制每个 stdio 模式 MCP 服务进程的 nsjail cgroup 内存上限。

Host 后端不提供 cgroup 内存隔离，因此该值不能限制 Host 上的 MCP 进程。

可通过 config.yaml 或环境变量 BOX__DEFAULT_MEMORY_MB 设置。

为什么需要调整：

• Node.js 类 MCP（npx/bunx 启动）：V8 引擎 + WebAssembly 模块初始化需要较多内存，建议 ≥ 1536 MB
• Python 类 MCP（uvx 启动）：通常 512 MB 已足够，但用默认值也没问题
• 内存不足时进程会被强制终止（return_code=137），在日志里表现为「Box managed process exited unexpectedly」

单个 MCP 服务覆盖： 在 MCP 配置的 box.memory_mb 字段单独设置，优先级高于全局默认值。

Docker 后端配置（box.docker.*）

云端后端配置（box.e2b.*）

设为 backend: 'e2b' 后配置：

E2B 不需要本机 Docker 或 Nsjail，每次执行都走远程沙箱。

Docker Compose 部署

Docker Compose 部署时，沙箱配置写在 langbot 服务上。LangBot 启动后会通过 INIT RPC 把配置下发给 langbot_box。

services:
  langbot_box:
    image: rockchin/langbot:latest
    container_name: langbot_box
    profiles: ["box", "all"]
    volumes:
      - ${LANGBOT_BOX_ROOT:-${PWD}/data/box}:${LANGBOT_BOX_ROOT:-${PWD}/data/box}
      - /var/run/docker.sock:/var/run/docker.sock
    command: ["uv", "run", "--no-sync", "-m", "langbot_plugin.cli.__init__", "box"]

  langbot:
    image: rockchin/langbot:latest
    volumes:
      - ./data:/app/data
    environment:
      - BOX__LOCAL__HOST_ROOT=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
      - BOX__LOCAL__SKILLS_ROOT=skills
      - BOX__LOCAL__ALLOWED_MOUNT_ROOTS=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
      - BOX__DOCKER__CPU_LIMIT_ENABLED=${LANGBOT_BOX_DOCKER_CPU_LIMIT_ENABLED:-true}

如需 LangBot 连接外部 Box Runtime（例如远程主机），用 box.runtime.endpoint 指定 URL：

box:
  runtime:
    endpoint: 'ws://192.168.1.10:5410'

环境变量