与 LobeHub 协同部署
LobeHub 是一个开源 AI Agent 与聊天工作台，支持自部署、多模型接入、异构 Agent 等能力。LobeHub 的内置云端沙箱默认由 LobeHub 以类似公有云的方式提供。自 2.2.7 版本开始，支持切换沙箱实现到自托管 OnlyBoxes，由 OnlyBoxes 提供实际的代码执行、Shell 命令、文件操作和异构 Agent 运行时能力。
版本要求
| 组件 | 最低要求 | 说明 |
|---|---|---|
| LobeHub | v2.2.7 或更新版本 | 需要支持 SANDBOX_PROVIDER=onlyboxes 与 ONLYBOXES_* 环境变量 |
| OnlyBoxes | 0.7.0 或更新版本 | 需要支持 LobeHub runtime 镜像和 LobeHub 沙箱集成能力 |
本文假设你已经拥有一个正在运行的 LobeHub 实例，并默认已拥有简单的 Linux 基础、Docker 概念基础，下文将简要介绍 OnlyBoxes 并指导您完成其与 LobeHub 的协同部署。
相关链接
- LobeHub 官网：https://lobehub.com
- LobeHub 自部署文档：https://lobehub.com/zh/docs/self-hosting/start
- LobeHub 云端沙箱环境变量：https://lobehub.com/zh/docs/self-hosting/environment-variables/cloud-sandbox
OnlyBoxes 简介
OnlyBoxes 是一个自托管代码执行沙箱平台，采用控制节点和执行节点分离的部署形态。
| 组件 | 说明 |
|---|---|
| Console | 负责认证、worker 注册、任务调度、REST / MCP 接口 |
| Worker | 负责实际执行命令、维护 terminal 会话、读写和导出会话文件 |
在 LobeHub 集成场景中，OnlyBoxes 不替代 LobeHub 的聊天、用户体系或模型配置，只提供沙箱执行层。
部署关系
| 组件 | 状态 | 职责 |
|---|---|---|
| LobeHub Server | 已部署 | 对用户暴露云端沙箱与异构 Agent，并签发 OnlyBoxes JIT token |
| OnlyBoxes Console | 尚未部署 | 校验 JIT token，管理和调度 worker |
| OnlyBoxes Worker | 尚未部署 | 承载 LobeHub runtime，执行 terminalExec 与 terminalResource |
LobeHub 服务端需要访问 OnlyBoxes Console 的 HTTP 地址。ONLYBOXES_BASE_URL 填 Console 根地址，不包含 /api/v1。
1. 启动 OnlyBoxes
先按 安装 部署 OnlyBoxes 控制节点和至少一个 worker。
curl -fsSL https://onlybox.es/install.sh | bash安装脚本会根据宿主机环境自动选择首个启动方式：
- 检测到 Docker 与 Docker Compose v2 时，Console 以
docker compose启动，工作目录默认为$PWD/onlyboxes，后续配置改onlyboxes/docker-compose.yml。 - 仅有 systemd 且
/etc/systemd/system可写时，Console 以 systemd 服务onlyboxes-console.service启动，环境变量写在 unit 文件的Environment=行。 - 两者都没有时，脚本会以前台进程的方式运行 Console 和 worker，关闭终端后进程也会退出。
macOS 上没有 systemd，且 worker 默认不支持 Docker in Docker，安装脚本在 macOS 上会以前台方式运行，无法被托管为常驻服务。因此在 macOS 上不建议用安装脚本拉起 worker 节点，推荐参考 worker-docker 或 worker-boxlite 手动部署 worker，自行决定后台守护方式（例如 launchd 或 tmux 等）。Console 同理。
2. 配置 OnlyBoxes Console
LobeHub 接入需要在 Console 上额外配置 CONSOLE_JIT_SIGNING_KEY，用于校验 LobeHub 签发的 jit token。
根据上一节脚本选择的启动方式，配置方式不同。
方式 A：Docker Compose 部署
编辑安装脚本生成的 onlyboxes/docker-compose.yml，在 console 服务的 environment 中追加：
services:
console:
environment:
CONSOLE_HASH_KEY: "<原有值无需修改>"
CONSOLE_JIT_SIGNING_KEY: "<修改为任意随机字符串>"在该目录下重启 Console：
cd onlyboxes
docker compose up -d console方式 B：systemd 部署
安装脚本会把环境变量写在 /etc/systemd/system/onlyboxes-console.service 的 Environment= 行。追加一行 CONSOLE_JIT_SIGNING_KEY：
[Service]
Environment=CONSOLE_HASH_KEY=<原有值无需修改>
Environment=CONSOLE_JIT_SIGNING_KEY=<修改为任意随机字符串>也可以改成在 unit 中通过 EnvironmentFile= 引入一份独立的环境变量文件，避免每次升级覆盖。
让 systemd 重新加载并重启 Console：
sudo systemctl daemon-reload
sudo systemctl restart onlyboxes-console
sudo systemctl status onlyboxes-console3. 调整 worker 参数
以下示例针对 worker-docker 运行时，即安装脚本默认部署的运行时。其他运行时（如 worker-boxlite）请参考对应文档调整等价变量。
LobeHub 集成需要将终端镜像切换为 coolfan1024/onlyboxes-runtime:lobehub，放宽单会话资源限制，并允许同一终端会话并发执行多个操作：
WORKER_TERMINAL_EXEC_DOCKER_IMAGE=coolfan1024/onlyboxes-runtime:lobehub
WORKER_TERMINAL_EXEC_MEMORY_MIB=2048
WORKER_TERMINAL_EXEC_CPUS=2
WORKER_TERMINAL_EXEC_MAX_PROCESSES=1024
WORKER_TERMINAL_SESSION_MAX_INFLIGHT=8
WORKER_TERMINAL_EXEC_MAX_INFLIGHT=16
WORKER_TERMINAL_RESOURCE_MAX_INFLIGHT=8
# 按 worker 宿主机容量设置正数；0 表示不限制。
WORKER_TERMINAL_MAX_ACTIVE_SESSIONS=0| 变量 | 默认值 | 推荐值 | 说明 |
|---|---|---|---|
WORKER_TERMINAL_EXEC_DOCKER_IMAGE | coolfan1024/onlyboxes-runtime:default | coolfan1024/onlyboxes-runtime:lobehub | 终端会话镜像。LobeHub 专用镜像预装 Python、Node、TypeScript、Agent 与常见文件工具 |
WORKER_TERMINAL_EXEC_MEMORY_MIB | 256 | 2048 | 单个终端会话的内存上限，单位 MiB |
WORKER_TERMINAL_EXEC_CPUS | 1.0 | 2 | 单个终端会话的 CPU 上限 |
WORKER_TERMINAL_EXEC_MAX_PROCESSES | 128 | 1024 | 单个终端会话的最大进程 / 线程数。LobeHub Agent 会并发启动 Node、Python、pnpm 等子进程，默认值容易触顶 |
WORKER_TERMINAL_SESSION_MAX_INFLIGHT | 1 | 8 | 单个会话中 terminalExec 与 terminalResource 合计允许的并发操作数 |
WORKER_TERMINAL_EXEC_MAX_INFLIGHT | 4 | 16 | 整个 worker 同时执行的 terminalExec 操作数 |
WORKER_TERMINAL_RESOURCE_MAX_INFLIGHT | 4 | 8 | 整个 worker 同时执行的 terminalResource 操作数 |
WORKER_TERMINAL_MAX_ACTIVE_SESSIONS | 0（无限制） | 按 worker 宿主机容量设置 | 当前 worker 进程管理的 terminal session 数量上限；容量满时已有 session 仍可用，新建 session 返回 session_capacity_exceeded |
LobeHub 会在同一会话中并发执行命令和文件操作，保持默认上限 1 可能触发 409 session_busy。请求必须同时满足单会话和 worker 级上限。
启动 worker 前建议先手动拉取镜像，避免首个会话因拉取镜像耗时而超时：
docker pull coolfan1024/onlyboxes-runtime:lobehub4. 配置 LobeHub
在 LobeHub 服务端加入：
SANDBOX_PROVIDER=onlyboxes
ONLYBOXES_BASE_URL=https://onlyboxes.example.com
ONLYBOXES_JIT_SIGNING_KEY=<same-secret-as-CONSOLE_JIT_SIGNING_KEY>| 变量 | 默认值 | 说明 |
|---|---|---|
SANDBOX_PROVIDER | market | 设为 onlyboxes 后使用自托管 OnlyBoxes |
ONLYBOXES_BASE_URL | - | OnlyBoxes Console HTTP 根地址 |
ONLYBOXES_JIT_SIGNING_KEY | - | 必须与 OnlyBoxes CONSOLE_JIT_SIGNING_KEY 一致 |
5. 文件下载
LobeHub 文件导出使用 LobeHub 自己的对象存储配置：
- LobeHub 生成上传 URL。
- LobeHub 请求 OnlyBoxes
terminalResource读取会话文件。 - OnlyBoxes worker 将文件上传到 LobeHub 提供的 URL。
- LobeHub 返回下载地址。
通过 LobeHub 使用文件下载时，应配置 LobeHub 的 S3 / 对象存储环境变量。
6. 验证
在 LobeHub 中发起一次云端沙箱请求，确认对应的代码执行或异构 Agent 任务能够正常完成：
Run `python3 - <<'PY'
print("hello from onlyboxes")
PY`常见问题
LobeHub 提示 ONLYBOXES_BASE_URL and ONLYBOXES_JIT_SIGNING_KEY are required
LobeHub 服务端没有读到 ONLYBOXES_BASE_URL 或 ONLYBOXES_JIT_SIGNING_KEY。确认变量设置在 LobeHub 服务端进程或容器上。
OnlyBoxes 返回 401
检查两侧密钥是否一致：
- OnlyBoxes Console：
CONSOLE_JIT_SIGNING_KEY - LobeHub Server：
ONLYBOXES_JIT_SIGNING_KEY
如果设置了 ONLYBOXES_JIT_TTL_SEC，同时检查两台机器的系统时间。
命令执行成功，但文件或代码工具失败
检查 worker terminal 镜像是否为 coolfan1024/onlyboxes-runtime:lobehub，并确认启动 worker 时已设置至少 2 CPU / 2 GiB 的 terminal 资源限制。
文件导出失败
优先检查 LobeHub 的对象存储配置是否正确。其次确认 OnlyBoxes worker 所在主机能够直接访问 LobeHub 配置的对象存储 endpoint：文件上传由 worker 直接 PUT 到 LobeHub 签发的预签名 URL，如果 worker 与对象存储之间存在网络隔离、出网代理或私网域名解析问题，导出会失败。