Onlyboxes

简体中文

Onlyboxes is a self-hosted code execution sandbox platform for individuals and small teams.

It uses a control-plane (console) and execution-plane (worker) architecture, and exposes both REST APIs and MCP tools.

Key Features

• Self-hosted all components: control node (console) + worker nodes (worker)
• Separated control and execution planes:
  • Workers support horizontal scaling
  • Workers support multi-language heterogeneous implementations
  • Workers support multiple runtimes
• Full account system: resource isolation (stateful containers, sessions) between accounts
• MCP tools:
  • pythonExec: Python code execution
  • terminalExec: stateful terminal sessions
  • readImage: model-readable images
• REST API: all MCP tools also available via HTTP + async task API

[!WARNING]

In the current release, console (gRPC + HTTP) does not provide built-in TLS/mTLS.

worker rejects insecure console endpoints by default; plaintext is allowed only when WORKER_CONSOLE_INSECURE=true is explicitly set.

Put both console HTTP (:8089) and gRPC (:50051) endpoints behind your reverse proxy/gateway and enforce TLS for external traffic.

Architecture

One-Click Installer (Linux)

For a single-machine deployment of console + worker-docker, run:

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

The installer will:

1. Check the environment (Linux, Docker, Docker Compose v2, systemd)
2. Download and render the compose template with auto-generated credentials
3. Start the console via docker compose up -d
4. Create a normal worker
5. Download the architecture-matched worker-docker release binary for the default latest version, or your --tag override
6. Generate and enable a systemd service for the worker
7. Poll until the worker comes online and print a result summary

Available options:

| Flag | Default | Description | | --- | --- | --- | | --tag | latest published release | Optional release version override | | --workdir | $PWD/onlyboxes | Working directory | | --yes / -y | false | Non-interactive mode, skip confirmations | | --console-http-port | 8089 | Console HTTP port (host side) | | --console-grpc-port | 50051 | Console gRPC port (host side) | | --service-name | onlyboxes-worker-docker | systemd service name |

Requirements: Linux, systemd, Docker Engine, Docker Compose v2, Python 3.

Quick Start (Manual)

1) Prerequisites

• Control node:
  • Docker Engine (binaries are also available in releases — no Docker needed if deploying via binary)
• Worker node:
  • Docker Engine (required by worker-docker)

2) Start the console service

1. Create a working directory and a docker-compose.yml file in it:

   mkdir -p onlyboxes-console && cd onlyboxes-console
   

   services:
     console:
       image: coolfan1024/onlyboxes:latest
       container_name: onlyboxes-console
       restart: unless-stopped
       environment:
         CONSOLE_HASH_KEY: "replace-with-long-random-key"
         CONSOLE_ENABLE_REGISTRATION: "true"
         CONSOLE_DASHBOARD_USERNAME: "admin"     # only for first run
         CONSOLE_DASHBOARD_PASSWORD: "change-me" # only for first run
       ports:
         - "8089:8089"
         - "50051:50051"
       volumes:
         - ./db:/app/db
   

2. Replace at least:

   • CONSOLE_HASH_KEY
   • CONSOLE_DASHBOARD_PASSWORD

3. Start console:

   docker compose up -d
   

Default endpoints:

• Console Web UI / HTTP REST API / MCP endpoint: http://127.0.0.1:8089
• gRPC: 127.0.0.1:50051

3) Sign in and create an access token

• Open http://127.0.0.1:8089 in your browser.
• Sign in with the initialized admin account.
• Go to the token management page and create an access token.
• Save the plaintext token immediately (it is returned only once).

4) Create a worker

• Go to Workers page and create a worker.
• Copy and securely store the startup command from the creation dialog (WORKER_SECRET is one-time visible).
• (Optional) Click Open in Startup Tool with Id and Secret to open the startup command builder with the worker id and secret pre-filled.
  • On the opened page, you can edit all available options. The generated startup command appears at the bottom of the page — copy and save it.

5) Run worker

[!WARNING] Workers support different runtimes and environments. The current release only provides worker-docker. This section uses the Docker runtime as an example.

1. Log in to the machine where the worker will be deployed.

   • Ensure Docker Engine is installed.
   • Ensure the worker can reach the console gRPC endpoint.

2. Download the latest worker-docker binary from GitHub Releases:

   • https://github.com/onlyboxes/onlyboxes/releases/latest

3. Use the startup command values from the dashboard, and replace the executable path on the last line with your downloaded binary.

   • Workers reject insecure console endpoints by default; set WORKER_CONSOLE_INSECURE=true only to allow plaintext connections.

   # Example
   WORKER_CONSOLE_INSECURE=true \
   WORKER_CONSOLE_GRPC_TARGET=127.0.0.1:50051 \
   WORKER_ID=<worker_id> \
   WORKER_SECRET=<worker_secret> \
   /path/to/onlyboxes-worker-docker
   

6) Verify readiness

• Confirm the worker is online on the dashboard Workers page.
• For REST API request examples, see docs/API.md.
• If no tokens are configured, /mcp and execution APIs return 401 by design.
• Add the MCP endpoint http://127.0.0.1:8089/mcp in any LLM Chat Client, set the token, and verify it works correctly.

FAQ

• Q: Worker stays offline after starting? A: Check that WORKER_CONSOLE_GRPC_TARGET points to the correct console gRPC address and verify network connectivity.

• Q: Can a worker be deployed on the same machine as the console? A: Yes.

• Q: Can a worker run inside Docker? A: In theory, yes. However, it is not recommended because the worker needs access to the host Docker daemon. You would need to handle Docker-in-Docker yourself.

Production Checklist

• Replace all default credentials.
• Use a reverse proxy to enforce TLS for :8089 and :50051.
• Persist and back up the SQLite data directory (CONSOLE_DB_PATH).
• Run workers on isolated hosts to avoid sharing the Docker daemon with the console.
• Read the Configuration Reference below for all available options and adjust as needed.

Configuration Reference

Console (console)

| Environment Variable | Default | Notes | | --- | --- | --- | | CONSOLE_HTTP_ADDR | :8089 | Dashboard + REST API listen address | | CONSOLE_GRPC_ADDR | :50051 | Worker registry gRPC listen address | | CONSOLE_HASH_KEY | (required) | HMAC key for hashing worker secrets and access tokens | | CONSOLE_DB_PATH | ./db/onlyboxes-console.db | SQLite database path | | CONSOLE_DB_BUSY_TIMEOUT_MS | 5000 | SQLite busy timeout | | CONSOLE_TASK_RETENTION_DAYS | 30 | Retention for completed task records | | CONSOLE_ENABLE_REGISTRATION | false | Allow admin to register non-admin accounts | | CONSOLE_DASHBOARD_USERNAME | (empty) | Used only for first admin initialization | | CONSOLE_DASHBOARD_PASSWORD | (empty) | Used only for first admin initialization |

Worker (worker-docker)

| Environment Variable | Default | Notes | | --- | --- | --- | | WORKER_ID | (required) | Issued by POST /api/v1/workers | | WORKER_SECRET | (required) | Issued once by POST /api/v1/workers | | WORKER_CONSOLE_GRPC_TARGET | 127.0.0.1:50051 | Console gRPC target | | WORKER_CONSOLE_INSECURE | false | false enforces TLS endpoint; set true only to allow plaintext console gRPC | | WORKER_HEARTBEAT_INTERVAL_SEC | 5 | Worker heartbeat interval | | WORKER_HEARTBEAT_JITTER_PCT | 20 | Heartbeat jitter percent | | WORKER_PYTHON_EXEC_DOCKER_IMAGE | ghcr.io/astral-sh/uv:python3.12-bookworm-slim | Runtime image for pythonExec | | WORKER_TERMINAL_EXEC_DOCKER_IMAGE | coolfan1024/onlyboxes-runtime:default | Runtime image for terminalExec | | WORKER_TERMINAL_OUTPUT_LIMIT_BYTES | 1048576 | Per-stream output limit |

API Surfaces

• Dashboard auth: /api/v1/console/*
• Worker management (admin): /api/v1/workers*
• Command execution: /api/v1/commands/echo, /api/v1/commands/terminal
• Task execution: /api/v1/tasks*
• MCP (Streamable HTTP): POST /mcp

Development

Local dev orchestration

scripts/dev.sh runs console / web / website in a tmux session. Every subcommand returns immediately, and logs land in scripts/.dev/<svc>.log.

scripts/dev.sh start              # start all three
scripts/dev.sh start console web  # console + web only
scripts/dev.sh status             # session, port listeners, window state
scripts/dev.sh logs console       # last 200 log lines
scripts/dev.sh creds              # console admin credentials
scripts/dev.sh stop               # stop everything

Web dev URL defaults to http://127.0.0.1:5178 and proxies /api/* and /mcp to http://127.0.0.1:8089.

Workers are not orchestrated — their startup arguments vary per implementation, so start them manually. Full usage: scripts/README.md.

Useful docs

• Unified API reference: docs/API.md
• Console internals: console/README.md
• Worker internals: worker/worker-docker/README.md
• API/proto guide: api/README/proto.md
• Web app guide: web/README.md

Release & Images

• GitHub workflow: .github/workflows/package-release.yml — run it manually from the Actions tab, pick the branch and enter the version (e.g. 0.7.2); the tag is created from that branch. Turn off latest when patching an older line so the newest release keeps the label
• Website-only deploy: .github/workflows/deploy-website.yml — manual, independent of a release
• Console Docker image: coolfan1024/onlyboxes:<version> and coolfan1024/onlyboxes:latest
• Terminal runtime images: coolfan1024/onlyboxes-runtime:<version>-default, <version>-default-cn, and <version>-lobehub; stable aliases are default, default-cn, lobehub, and latest (same as default)
• Console binary includes embedded web assets

Security and Operational Notes

• Console does not provide built-in TLS/mTLS in this release; worker-docker requires explicit WORKER_CONSOLE_INSECURE=true to connect over plaintext.
• Put console HTTP (:8089) and gRPC (:50051) behind a reverse proxy/gateway and enforce TLS on public/external links.
• WORKER_SECRET and access token plaintext values are returned only at creation time.
• Dashboard login sessions are in-memory and are invalidated when console restarts.

Links

• linux.do
• boxlite.ai

License

GNU AGPL v3.0