Boxlite 运行时

worker-boxlite 使用 boxlite 运行时作为执行后端。每次执行运行在独立的 Linux 内核中，隔离性强于 Docker 容器，但冷启动更慢。

适用场景

• 需要比共享内核容器更强的隔离性
• 工作负载需要每次执行独占内核
• 安全边界比冷启动延迟更重要

工作原理

1. Worker 通过 gRPC 连接控制节点。
2. 执行请求被转发给本地 boxlite 运行时。
3. boxlite 管理沙箱生命周期并流式返回输出。

前置条件

• 宿主机上的 KVM 环境可用
• 能够访问控制节点 gRPC 端口

启动 worker

从 GitHub Releases 页面 下载对应版本的 worker-boxlite 二进制文件，然后运行：

WORKER_CONSOLE_GRPC_TARGET=<console_grpc_target> \
WORKER_ID=<worker_id> \
WORKER_SECRET=<worker_secret> \
./onlyboxes-worker-boxlite

配置文件

Dashboard 中的 Worker 启动工具可以生成并下载可直接使用的 config.toml。设置 WORKER_CONFIG_FILE 可以显式指定配置文件；未设置时，worker 会依次查找程序文件同目录和当前工作目录下的 config.toml。

配置优先级为：环境变量 > config.toml > 内置默认值。TOML 键名由环境变量名移除 WORKER_ 前缀并转换为小写得到，例如 WORKER_TERMINAL_EXEC_BOXLITE_IMAGE 对应 terminal_exec_boxlite_image。Worker 标签使用 [labels] 表配置。

id = "wk_..."
secret = "..."
console_grpc_target = "console.internal:50051"
terminal_exec_boxlite_image = "coolfan1024/onlyboxes-runtime:default"
terminal_max_active_sessions = 0

[labels]
region = "cn"

全部可用配置请参考带注释的配置模板。

环境变量

连接

身份

Boxlite

默认终端镜像是通用执行镜像，包含 Python 3、Node.js 24、npm、Corepack、常用 shell/文件工具、轻量文档处理库，以及基于 Lightpanda 的 agent-browser。LobeHub 专用 sandbox 工具链请使用 coolfan1024/onlyboxes-runtime:lobehub。

并发上限

WORKER_TERMINAL_EXEC_MAX_INFLIGHT 和 WORKER_TERMINAL_RESOURCE_MAX_INFLIGHT 分别限制整个 worker 上对应能力的并发数，二者相互独立，没有额外的 worker 全局合计上限。WORKER_TERMINAL_SESSION_MAX_INFLIGHT 则限制单个 session_id，并将 terminalExec 与 terminalResource 合并计数。请求必须同时满足对应能力上限和 session 上限。

WORKER_TERMINAL_MAX_ACTIVE_SESSIONS 是独立的 session 数量上限。0 表示不限制；正数会统计创建中、可用、销毁中以及 Box cleanup 进行中的 session。容量已满时已有 session 仍可使用，新建 session 返回 429 session_capacity_exceeded。负数或非法值回退为 0。

例如将 terminalExec 和 terminalResource 上限都设为 10、单 session 上限设为 2 时，整个 worker 最多可同时处理 10 个 terminalExec 和 10 个 terminalResource，但任一 session 内两类操作合计不能超过 2。超出单 session 上限返回 409 session_busy，对应能力的 worker 级并发额度耗尽返回 429 no_capacity，新建 session 时 session 数量上限耗尽返回 429 session_capacity_exceeded。

终端租约

Worker 会声明仅供 Console 内部使用的 terminalLeaseRenew 能力。它接收 {"session_id":"required","lease_ttl_sec":300}，以单调方式延长已有租约，并在不执行命令的情况下返回确认后的绝对到期时间。该能力拥有独立的 max_inflight，其声明值取自 WORKER_TERMINAL_EXEC_MAX_INFLIGHT 配置。

心跳

日志

相关文档

• 架构
• Docker 运行时
• 系统进程运行时