MCP server de Onlyboxes
Commit 26 oct 2026Permite que un cliente de IA ejecute código Python, utilice sesiones de terminal con estado y lea imágenes generadas en un sandbox auto-hospedado.
También conocido como Coooolfan/onlyboxes
- Stars
- 54
- Herramientas
- —
- Descargas, 30 días
- —
- Última versión
- —
- Último commit
- 26 oct 2026
- Licencia
- AGPL-3.0
¿Qué es Onlyboxes MCP?
Onlyboxes es un MCP server. Permite que un cliente de IA ejecute código Python, utilice sesiones de terminal con estado y lea imágenes generadas en un sandbox auto-hospedado.
Resumen generado a partir del README del proyecto
Acerca del MCP server de Onlyboxes
Onlyboxes permite a individuos y equipos pequeños disponer de un sandbox auto-hospedado para la ejecución de código. Utiliza una arquitectura dividida que consiste en una consola de plano de control y nodos worker escalables para gestionar las tareas. Los usuarios pueden desplegar el sistema en Linux usando Docker y systemd, conectando un cliente de IA al endpoint MCP para realizar tareas computacionales complejas.
Los desarrolladores utilizan las herramientas MCP específicas pythonExec para ejecutar código Python, terminalExec para gestionar sesiones de terminal con estado y readImage para permitir que los modelos visualicen los resultados visuales generados. La plataforma garantiza el aislamiento de recursos entre diferentes cuentas mediante contenedores con estado. Al ser un sistema auto-hospedado, mantienes el control sobre el entorno de ejecución y los datos procesados dentro de los nodos worker.
La configuración del entorno requiere un nodo de consola y al menos un nodo worker, como la implementación worker-docker. Para conectar un cliente de chat LLM, debes generar un token de acceso desde el panel web y proporcionar la URL del endpoint MCP. Por seguridad, se recomienda colocar los puertos HTTP y gRPC detrás de un proxy inverso para aplicar TLS.
Qué puedes hacer con él
- 1Escalar recursos de ejecuciónLos equipos pueden ampliar su capacidad de cómputo añadiendo más nodos worker a la arquitectura.
Escrito a partir del README del proyecto. Cada caso de uso se verifica con una cita del mismo.
Configuración
WORKER_CONSOLE_GRPC_TARGETWORKER_CONSOLE_INSECUREWORKER_IDWORKER_SECRET
| Nombre | Descripción | Tipo |
|---|---|---|
| WORKER_CONSOLE_GRPC_TARGET | — | |
| WORKER_CONSOLE_INSECURE | — | |
| WORKER_ID | — | |
| WORKER_SECRET | — |
Verificaciones automáticas
Ejecutado 14 nov 2026Informe completo →Aún no verificado. Un servidor necesita una puntuación de 80, ningún hallazgo grave y suficientes datos para que podamos revisarlo. Cómo funcionan las verificaciones · Qué corregir para obtener más puntos
- Repositorio de origen vinculado y accesiblecoooolfan/onlyboxes is public and reachablegithub.com/coooolfan/onlyboxes ↗Aprobado
- El paquete indica este repositorio como su origenNo verificado
- Procedencia de la compilación (atestación de Sigstore)No verificado
- Licencia de código abierto (OSI)AGPL-3.0spdx.org/licenses/AGPL-3.0.html ↗Aprobado
- Commit o lanzamiento en el último añoLast commit or release 2026-10-26github.com/coooolfan/onlyboxes ↗Aprobado
- OpenSSF ScorecardNo verificado
- El nombre del paquete no es similar a un paquete popularNo verificado
- No hay avisos críticos en el paquete ni en sus dependenciasNo verificado
- Sin instrucciones ocultas para el modelo0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersAprobado
- Las herramientas destructivas están etiquetadasNo verificado
- El endpoint remoto responde al handshake de MCPNo verificado
README
Ver en GitHubOnlyboxes
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 executionterminalExec: stateful terminal sessionsreadImage: 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.
workerrejects insecure console endpoints by default; plaintext is allowed only whenWORKER_CONSOLE_INSECURE=trueis 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:
- Check the environment (Linux, Docker, Docker Compose v2, systemd)
- Download and render the compose template with auto-generated credentials
- Start the console via
docker compose up -d - Create a
normalworker - Download the architecture-matched
worker-dockerrelease binary for the default latest version, or your--tagoverride - Generate and enable a systemd service for the worker
- 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)
- Docker Engine (required by
2) Start the console service
-
Create a working directory and a
docker-compose.ymlfile in it:mkdir -p onlyboxes-console && cd onlyboxes-consoleservices: 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 -
Replace at least:
CONSOLE_HASH_KEYCONSOLE_DASHBOARD_PASSWORD
-
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:8089in 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_SECRETis one-time visible).
- (Optional) Click
Open in Startup Tool with Id and Secretto 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.

- 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.
-
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.
-
Download the latest
worker-dockerbinary from GitHub Releases:https://github.com/onlyboxes/onlyboxes/releases/latest
-
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=trueonly 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 - Workers reject insecure console endpoints by default; set
6) Verify readiness
- Confirm the worker is
onlineon the dashboard Workers page. - For REST API request examples, see
docs/API.md. - If no tokens are configured,
/mcpand execution APIs return401by design. - Add the MCP endpoint
http://127.0.0.1:8089/mcpin any LLM Chat Client, set the token, and verify it works correctly.
FAQ
-
Q: Worker stays
offlineafter starting? A: Check thatWORKER_CONSOLE_GRPC_TARGETpoints 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
:8089and: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 Referencebelow 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_WORKER_CONNECTION_CONFLICT_POLICY |
REPLACE |
Duplicate Worker connection policy: REPLACE disconnects the existing connection; REJECT rejects the new connection |
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
- Authentication:
/api/v1/auth/* - Resource management:
/api/v1/accounts*,/api/v1/api-keys*,/api/v1/tokens*,/api/v1/sessions*,/api/v1/workers*,/api/v1/proxy-routes* - Command execution:
/api/v1/commands/* - 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 offlatestwhen 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>andcoolfan1024/onlyboxes:latest - Terminal runtime images:
coolfan1024/onlyboxes-runtime:<version>-default,<version>-default-cn, and<version>-lobehub; stable aliases aredefault,default-cn,lobehub, andlatest(same asdefault) - Console binary includes embedded web assets
Security and Operational Notes
- Console does not provide built-in TLS/mTLS in this release;
worker-dockerrequires explicitWORKER_CONSOLE_INSECURE=trueto connect over plaintext. - Put console HTTP (
:8089) and gRPC (:50051) behind a reverse proxy/gateway and enforce TLS on public/external links. WORKER_SECRETand access token plaintext values are returned only at creation time.- Dashboard login sessions are in-memory and are invalidated when
consolerestarts.
Links
License
Preguntas sobre Onlyboxes MCP
¿Qué herramientas MCP ofrece Onlyboxes?
Expone pythonExec para la ejecución de código Python, terminalExec para sesiones de terminal con estado y readImage para imágenes legibles por el modelo.
¿Por qué mi worker se mantiene fuera de línea después de iniciarlo?
Comprueba que WORKER_CONSOLE_GRPC_TARGET apunte a la dirección gRPC correcta de la consola y verifica la conectividad de red.
¿Se puede desplegar un worker en la misma máquina que la consola?
Sí, un worker puede ejecutarse en la misma máquina que la consola, aunque las recomendaciones de producción sugieren hosts aislados.
¿Ofrece Onlyboxes TLS de forma nativa?
No, la versión actual no incluye TLS/mTLS integrado en la consola. Coloca tanto los endpoints HTTP como los gRPC de la consola detrás de un proxy inverso o gateway para aplicar TLS allí.