Boxlite Runtime

worker-boxlite uses the boxlite runtime as its execution backend. Each execution runs inside an independent Linux kernel, providing stronger isolation than Docker containers at the cost of slower cold starts.

When to use

• You need stronger isolation than shared-kernel containers
• Your workload requires a dedicated kernel per execution
• Security boundary is more important than cold-start latency

How it works

1. The worker connects to the control node over gRPC.
2. Execution requests are forwarded to the local boxlite runtime.
3. boxlite manages the sandbox lifecycle and streams output back.

Prerequisites

• KVM available on the host
• Network access to the control node gRPC endpoint

Starting the worker

Download the matching version of the worker-boxlite binary from the GitHub releases page, then run:

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

Configuration file

The Worker Startup Tool in the dashboard can generate and download a ready-to-use config.toml. Set WORKER_CONFIG_FILE to use a specific file. If it is not set, the worker looks for config.toml next to the worker binary and then in the current working directory.

Environment variables take precedence over config.toml, which takes precedence over built-in defaults. TOML keys use the environment variable name without the WORKER_ prefix and in lowercase; for example, WORKER_TERMINAL_EXEC_BOXLITE_IMAGE becomes terminal_exec_boxlite_image. Use a [labels] table for 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 = "us"

See the annotated configuration template for all available keys.

Environment variables

Connection

Identity

Boxlite

The default terminal image is a general execution image with Python 3, Node.js 24, npm, Corepack, common shell/file utilities, lightweight document helpers, and agent-browser with Lightpanda. Use coolfan1024/onlyboxes-runtime:lobehub for LobeHub-specific sandbox tooling.

Concurrency

WORKER_TERMINAL_EXEC_MAX_INFLIGHT and WORKER_TERMINAL_RESOURCE_MAX_INFLIGHT independently limit their respective capabilities across the worker; there is no additional aggregate worker-wide limit. WORKER_TERMINAL_SESSION_MAX_INFLIGHT applies to one session_id and counts terminalExec and terminalResource together. A request must satisfy both its capability limit and the session limit.

WORKER_TERMINAL_MAX_ACTIVE_SESSIONS is a separate session-count limit. 0 leaves the count unlimited; a positive value counts sessions that are being created, ready, being destroyed, or undergoing Box cleanup. Existing sessions remain usable when the limit is full, while a new session returns 429 session_capacity_exceeded. Negative or invalid values fall back to 0.

For example, with both capability limits set to 10 and the per-session limit set to 2, the worker can process up to 10 terminalExec and 10 terminalResource operations at once, while any one session can run at most two operations in total. Exceeding the per-session limit returns 409 session_busy; exhausting a capability's worker-wide concurrency returns 429 no_capacity; exhausting the session-count limit while creating a session returns 429 session_capacity_exceeded.

Terminal lease

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

Heartbeat

Logging

Related docs

• Architecture
• Docker Runtime
• System Process Runtime