Onlyboxes MCP sunucusu
Commit 26 Eki 2026Bir yapay zeka istemcisinin kendi kendine barındırılan bir sandbox içerisinde Python kodu çalıştırmasına, durum bilgisi koruyan (stateful) terminal oturumları kullanmasına ve oluşturulan görselleri okumasına olanak tanır.
Ayrıca bilinen adı Coooolfan/onlyboxes
- Yıldızlar
- 54
- Araçlar
- —
- İndirmeler, 30 gün
- —
- En son sürüm
- —
- Son commit
- 26 Eki 2026
- Lisans
- AGPL-3.0
Onlyboxes MCP nedir?
Onlyboxes bir MCP sunucusudur. Bir yapay zeka istemcisinin kendi kendine barındırılan bir sandbox içerisinde Python kodu çalıştırmasına, durum bilgisi koruyan (stateful) terminal oturumları kullanmasına ve oluşturulan görselleri okumasına olanak tanır.
Özet, projenin README dosyasından oluşturuldu
Onlyboxes MCP sunucusu hakkında
Onlyboxes, bireyler ve küçük ekipler için kod yürütme işlemlerine yönelik kendi kendine barındırılan (self-hosted) bir sandbox ortamı sağlar. Görevleri yönetmek için kontrol düzlemi (control-plane) console ve ölçeklenebilir worker düğümlerinden oluşan ayrık bir mimari kullanır. Kullanıcılar sistemi Linux üzerinde Docker ve systemd kullanarak kurabilir ve karmaşık hesaplama görevlerini gerçekleştirmek için bir yapay zeka istemcisini MCP uç noktasına bağlayabilir.
Geliştiriciler; Python kodu çalıştırmak için pythonExec, durum bilgisi koruyan terminal oturumlarını yönetmek için terminalExec ve modellerin oluşturulan görsel çıktıları görmesini sağlamak için readImage gibi özel MCP araçlarını kullanırlar. Platform, durum bilgisi koruyan konteynerlar aracılığıyla farklı hesaplar arasında kaynak izolasyonu sağlar. Sistem self-hosted olduğu için yürütme ortamı ve worker düğümleri içinde işlenen veriler üzerinde tam kontrole sahip olursunuz.
Ortamın kurulumu için bir console düğümü ve worker-docker uygulaması gibi en az bir worker düğümü gereklidir. Bir LLM sohbet istemcisini bağlamak için web panelinden bir erişim token'ı oluşturmalı ve MCP uç nokta URL'sini sağlamalısınız. Güvenlik için, HTTP ve gRPC portlarını TLS uygulamak amacıyla bir reverse proxy arkasına yerleştirmeniz önerilir.
Neler yapabilirsiniz
- 1Yürütme kaynaklarını ölçeklendirinEkipler, mimariye daha fazla worker düğümü ekleyerek hesaplama kapasitelerini artırabilirler.
Projenin README dosyasından alınmıştır. Her kullanım durumu, oradaki bir alıntı ile kontrol edilir.
Yapılandırma
WORKER_CONSOLE_GRPC_TARGETWORKER_CONSOLE_INSECUREWORKER_IDWORKER_SECRET
| Ad | Açıklama | Sunucu |
|---|---|---|
| WORKER_CONSOLE_GRPC_TARGET | — | |
| WORKER_CONSOLE_INSECURE | — | |
| WORKER_ID | — | |
| WORKER_SECRET | — |
Otomatik kontroller
Çalıştırıldı 14 Kas 2026Tam rapor →Henüz doğrulanmadı. Bir sunucunun 80 puana, ciddi bir bulgu olmamasına ve kontrol edebilmemiz için yeterli veriye ihtiyacı vardır. Kontroller nasıl çalışır · Daha fazla puan için nelerin düzeltileceği
- Kaynak deposu bağlantılı ve erişilebilircoooolfan/onlyboxes is public and reachablegithub.com/coooolfan/onlyboxes ↗Geçti
- Paket, bu depoyu kaynağı olarak gösteriyorKontrol edilmedi
- Derleme kökeni (Sigstore onayı)Kontrol edilmedi
- Açık kaynak lisansı (OSI)AGPL-3.0spdx.org/licenses/AGPL-3.0.html ↗Geçti
- Son bir yıl içinde commit veya sürüm mevcutLast commit or release 2026-10-26github.com/coooolfan/onlyboxes ↗Geçti
- OpenSSF ScorecardKontrol edilmedi
- Paket adı popüler bir pakete yakın değilKontrol edilmedi
- Pakette veya bağımlılıklarında kritik uyarı yokKontrol edilmedi
- Modele yönelik gizli talimat yok0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersGeçti
- Yıkıcı araçlar etiketlenmişKontrol edilmedi
- Uzak uç nokta MCP el sıkışmasına yanıt veriyorKontrol edilmedi
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 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
Onlyboxes MCP soruları
Onlyboxes hangi MCP araçlarını sağlar?
Python kodu çalıştırmak için pythonExec, durum bilgisi koruyan terminal oturumları için terminalExec ve modellerin okuyabileceği görseller için readImage araçlarını sunar.
Worker başlatıldıktan sonra neden çevrimdışı kalıyor?
WORKER_CONSOLE_GRPC_TARGET değişkeninin doğru console gRPC adresini gösterdiğinden emin olun ve ağ bağlantısını kontrol edin.
Bir worker, console ile aynı makineye kurulabilir mi?
Evet, bir worker console ile aynı makinede çalışabilir ancak üretim ortamı için izole hostlar kullanılması önerilir.
Onlyboxes hazır olarak TLS sunuyor mu?
Hayır, mevcut sürümde console üzerinde yerleşik bir TLS/mTLS bulunmamaktadır. Hem console HTTP hem de gRPC uç noktalarını bir reverse proxy veya gateway arkasına koyarak TLS uygulamanız gerekir.