Deploy with LobeHub

LobeHub is an open-source AI agent and chat workspace with self-hosting, multi-model access, and heterogeneous agents. Its built-in cloud sandbox is provided by LobeHub by default in a public-cloud-like form. Since version 2.2.7, the sandbox provider can be switched to self-hosted OnlyBoxes, with OnlyBoxes providing the actual code execution, shell commands, file operations, and heterogeneous agent runtime.

Version Requirements

This document assumes you already have a running LobeHub instance and basic Linux / Docker knowledge. It briefly introduces OnlyBoxes and walks through deploying it together with LobeHub.

Links

• LobeHub website: https://lobehub.com
• LobeHub self-hosting docs: https://lobehub.com/docs/self-hosting/start
• LobeHub cloud sandbox environment variables: https://lobehub.com/docs/self-hosting/environment-variables/cloud-sandbox

What Is OnlyBoxes

OnlyBoxes is a self-hosted code execution sandbox platform. It uses a split control-node and execution-node architecture.

In the LobeHub integration, OnlyBoxes does not replace LobeHub chat, users, or model settings. It only provides the sandbox execution layer.

Deployment Shape

The LobeHub server must reach the OnlyBoxes Console HTTP endpoint. Set ONLYBOXES_BASE_URL to the Console root URL, without /api/v1.

1. Start OnlyBoxes

Follow Install to deploy the OnlyBoxes Console and at least one worker.

curl -fsSL https://onlybox.es/install.sh | bash

The installer picks the first available start mode based on the host environment:

• If Docker and Docker Compose v2 are available, the Console starts via docker compose in $PWD/onlyboxes by default. Subsequent configuration goes into onlyboxes/docker-compose.yml.
• Otherwise, if systemd is present and /etc/systemd/system is writable, the Console runs as the onlyboxes-console.service systemd unit. Environment variables live on Environment= lines inside the unit file.
• If neither is available, the installer runs the Console and worker as foreground processes. They exit when the terminal closes.

macOS has no systemd, and the worker does not support Docker-in-Docker by default, so the installer can only run in the foreground on macOS and cannot be managed as a long-lived service. Using the installer to launch a worker on macOS is therefore not recommended — deploy workers manually following worker-docker or worker-boxlite and pick your own supervision mechanism (launchd, tmux, etc.). The same applies to the Console.

2. Configure OnlyBoxes Console

LobeHub integration requires an extra CONSOLE_JIT_SIGNING_KEY on the Console, used to verify the JIT tokens minted by LobeHub.

The exact steps depend on which start mode the installer chose in the previous section.

Option A: Docker Compose deployment

Edit onlyboxes/docker-compose.yml generated by the installer, and append the key to the console service environment:

services:
  console:
    environment:
      CONSOLE_HASH_KEY: "<keep-existing-value>"
      CONSOLE_JIT_SIGNING_KEY: "<generate-a-long-random-secret>"

Restart the Console from that directory:

cd onlyboxes
docker compose up -d console

Option B: systemd deployment

The installer writes environment variables as Environment= lines in /etc/systemd/system/onlyboxes-console.service. Add one more line for CONSOLE_JIT_SIGNING_KEY:

[Service]
Environment=CONSOLE_HASH_KEY=<keep-existing-value>
Environment=CONSOLE_JIT_SIGNING_KEY=<generate-a-long-random-secret>

Alternatively, switch the unit to load a separate env file via EnvironmentFile= so future upgrades do not overwrite your edits.

Reload systemd and restart the Console:

sudo systemctl daemon-reload
sudo systemctl restart onlyboxes-console
sudo systemctl status onlyboxes-console

3. Tune Worker Parameters

The example below targets the worker-docker runtime, which is what the installer deploys by default. For other runtimes (such as worker-boxlite), see the matching docs for the equivalent variables.

LobeHub integration requires switching the terminal image to coolfan1024/onlyboxes-runtime:lobehub, raising the per-session resource limits, and allowing concurrent operations in one terminal session:

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
# Set a positive value based on the worker host's resource budget; 0 means unlimited.
WORKER_TERMINAL_MAX_ACTIVE_SESSIONS=0

LobeHub runs commands and file operations concurrently in one session, so the default limit of 1 may return 409 session_busy. Requests must satisfy both the per-session and worker-wide limits.

There is no universal recommendation for WORKER_TERMINAL_MAX_ACTIVE_SESSIONS. In production, set a positive value based on the memory and CPU budget available to terminal containers; with the current recommended 2048 MiB per session, a conservative starting point is floor(available memory / 2048 MiB), leaving headroom for the host and other capabilities. 0 means unlimited and is best avoided indefinitely on production workers with a defined resource budget.

Pull the image before starting the worker so the first session is not blocked on the image download:

docker pull coolfan1024/onlyboxes-runtime:lobehub

4. Configure LobeHub

Set these on the LobeHub server:

SANDBOX_PROVIDER=onlyboxes
ONLYBOXES_BASE_URL=https://onlyboxes.example.com
ONLYBOXES_JIT_SIGNING_KEY=<same-secret-as-CONSOLE_JIT_SIGNING_KEY>

5. File Downloads

LobeHub file export uses LobeHub's own object storage configuration:

1. LobeHub creates an upload URL.
2. LobeHub asks OnlyBoxes terminalResource to read a session file.
3. The OnlyBoxes worker uploads the file to the URL provided by LobeHub.
4. LobeHub returns the download URL.

For downloads through LobeHub, configure LobeHub's S3 / object storage variables.

6. Verify

Ask LobeHub to run a cloud sandbox command and confirm the code execution or heterogeneous agent task completes successfully:

Run `python3 - <<'PY'
print("hello from onlyboxes")
PY`

Troubleshooting

LobeHub says ONLYBOXES_BASE_URL and ONLYBOXES_JIT_SIGNING_KEY are required

The LobeHub server did not read ONLYBOXES_BASE_URL or ONLYBOXES_JIT_SIGNING_KEY. Confirm the variables are set on the LobeHub server process or container.

OnlyBoxes returns 401

Check that both sides use the same secret:

• OnlyBoxes Console: CONSOLE_JIT_SIGNING_KEY
• LobeHub Server: ONLYBOXES_JIT_SIGNING_KEY

If ONLYBOXES_JIT_TTL_SEC is configured, also check the system clocks.

Commands work, but code or file tools fail

Check that the worker terminal image is coolfan1024/onlyboxes-runtime:lobehub, and confirm that the worker was started with at least 2 CPU / 2 GiB terminal resource limits.

File export fails

Check LobeHub's object storage configuration first. Then verify that the OnlyBoxes worker host can reach the object storage endpoint configured by LobeHub: the worker uploads the file directly via PUT to the presigned URL minted by LobeHub, so network isolation, egress proxies, or private DNS issues between the worker and the object storage will cause exports to fail.

Related Docs

• Install
• Console Config
• MCP Tools
• worker-docker
• worker-boxlite