E2B Bridge Runtime

worker-bridge-e2b connects an OnlyBoxes control node to remote E2B sandboxes. The worker manages sessions and task dispatch locally, while E2B provides the execution environment.

When to use

• You want managed remote sandboxes without running Docker or KVM on the worker host
• You need E2B templates tailored to different Python and terminal workloads
• You accept the network latency and external service dependency of a remote execution backend

How it works

1. The worker connects to the OnlyBoxes control node over gRPC.
2. It creates, extends, and destroys sandboxes through the E2B Control API.
3. It executes commands and reads files through envd inside each sandbox.
4. pythonExec uses a new sandbox per request; terminal sessions reuse a sandbox until their lease expires.

Prerequisites

• An E2B API key
• An E2B Python template with Python and uv
• An E2B terminal template with /bin/bash and python3
• Network access to the OnlyBoxes control node and E2B endpoints

Starting the worker

Download the matching worker-bridge-e2b binary from the GitHub releases page, then run:

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

Workers require TLS by default. Set WORKER_CONSOLE_INSECURE=true only for a trusted plaintext development connection.

Configuration file

Set WORKER_CONFIG_FILE to use a specific config.toml. Otherwise, the worker looks next to its binary and then in the current working directory.

Configuration precedence is: WORKER_* environment variable, E2B-compatible environment variable alias, config.toml, then built-in default.

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 = "us"

See the annotated configuration template for all available keys.

Environment variables

Connection and identity

E2B

Terminal

The Worker advertises terminalLeaseRenew as an internal Console-only capability. It accepts {"session_id":"required","lease_ttl_sec":300}, extends an existing lease monotonically, synchronizes the E2B sandbox timeout, and returns the confirmed absolute expiry without executing a command. Its independent max_inflight declaration uses the configured WORKER_TERMINAL_EXEC_MAX_INFLIGHT value.

WORKER_TERMINAL_MAX_ACTIVE_SESSIONS is independent of the per-session and capability concurrency limits. 0 leaves the count unlimited; a positive value counts sessions that are being created, ready, being destroyed, or undergoing E2B cleanup. Existing sessions remain usable when the limit is full, while a new session returns 429 session_capacity_exceeded. The limit applies only to this worker process, not to all workers sharing an E2B API key; negative or invalid values fall back to 0.

Terminal commands share the sandbox filesystem but run in separate /bin/bash -l -c processes. They do not preserve the current directory, shell variables, or process environment between calls.

Capability concurrency

Heartbeat and logging

Related docs

• Architecture
• Docker Runtime
• Boxlite Runtime
• System Process Runtime