E2B Bridge 运行时

worker-bridge-e2b 将 OnlyBoxes 控制节点连接到远程 E2B 沙箱。worker 在本地管理 session 与任务分发，由 E2B 提供实际执行环境。

适用场景

• 希望使用托管的远程沙箱，不在 worker 主机上运行 Docker 或 KVM
• 需要为 Python 与终端任务准备不同的 E2B 模板
• 可以接受远程执行带来的网络延迟和外部服务依赖

工作原理

1. Worker 通过 gRPC 连接 OnlyBoxes 控制节点。
2. Worker 通过 E2B Control API 创建、续期和销毁沙箱。
3. 命令执行和文件读取通过沙箱内的 envd 完成。
4. pythonExec 每次请求使用一个新沙箱；terminalExec 会话在租约到期前复用同一沙箱。

前置条件

• E2B API Key
• 提供 Python 和 uv 的 E2B Python 模板
• 提供 /bin/bash 和 python3 的 E2B 终端模板
• 能够访问 OnlyBoxes 控制节点与 E2B 端点

启动 worker

从 GitHub Releases 页面 下载与系统架构匹配的 worker-bridge-e2b 二进制，然后运行：

WORKER_CONSOLE_GRPC_TARGET=<console_grpc_target> \
WORKER_ID=<worker_id> \
WORKER_SECRET=<worker_secret> \
WORKER_E2B_API_KEY=<e2b_api_key> \
WORKER_E2B_PYTHON_TEMPLATE=<python_template_id_or_alias> \
WORKER_E2B_TERMINAL_TEMPLATE=<terminal_template_id_or_alias> \
./onlyboxes-worker-bridge-e2b

worker 默认要求 TLS。只有在可信的明文开发链路中才应设置 WORKER_CONSOLE_INSECURE=true。

配置文件

设置 WORKER_CONFIG_FILE 可以显式指定 config.toml；未设置时，worker 会依次查找程序文件同目录和当前工作目录下的 config.toml。

配置优先级为：WORKER_* 环境变量、E2B 兼容环境变量别名、config.toml、内置默认值。

id = "wk_..."
secret = "..."
console_grpc_target = "console.internal:50051"
e2b_api_key = "..."
e2b_python_template = "python-template"
e2b_terminal_template = "terminal-template"
terminal_max_active_sessions = 0

[labels]
region = "cn"

全部配置项见带注释的配置模板。

环境变量

连接与身份

E2B

终端

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

WORKER_TERMINAL_MAX_ACTIVE_SESSIONS 与单 session 和 capability 并发上限相互独立。0 表示不限制；正数会统计创建中、可用、销毁中以及 E2B cleanup 进行中的 session。容量已满时已有 session 仍可使用，新建 session 返回 429 session_capacity_exceeded。该限制只作用于当前 worker 进程，不是同一 E2B API Key 下所有 worker 的全局配额；负数或非法值回退为 0。

终端命令共享沙箱文件系统，但每次调用都在独立的 /bin/bash -l -c 进程中执行，不会在调用之间保留当前目录、shell 变量或进程环境。

能力并发

心跳与日志

相关文档

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