Onlyboxes MCP

Onlybox

简体中文

Onlyboxes是一个面向个人和小型团队的自托管代码执行沙盒平台。

它使用控制平面(console)执行平面(worker)架构，并公开了REST API和MCP工具。

主要特点

• 自托管所有组件：控制节点(console)+工作节点(worker)
• 分离的控制和执行平面：

- 工人支持 水平扩展 - 员工支持多语言 异质的 实现 - 工人支持 多个运行时

• 完整帐户系统：帐户之间的资源隔离（有状态容器、会话）
• MCP工具：

- pythonExec：Python代码执行 - terminalExec：有状态终端会话 - readImage：模型可读图像

• REST API：所有MCP工具也可通过HTTP+异步任务API获得

\[！警告\] 在当前版本中，控制台（gRPC+HTTP）不提供内置的TLS/mTLS。 worker 默认情况下拒绝不安全的控制台端点；仅当满足以下条件时才允许使用明文 WORKER_CONSOLE_INSECURE=true 已明确设置。 将两个控制台都设置为HTTP(:8089)和gRPC(:50051)反向代理/网关后面的端点，并对外部流量实施TLS。

建筑

Architecture Architecture

一键安装程序（Linux）

对于单机部署 console + worker-docker，运行：

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

安装程序将：

1. 检查环境（Linux、Docker、Docker Compose v2、systemd）
2. 下载并呈现带有自动生成凭据的撰写模板
3. 通过以下方式启动控制台 docker compose up -d
4. 创建一个 normal 工人
5. 下载匹配的架构 worker-docker 发布默认最新版本的二进制文件，或 --tag 以（权力）否决
6. 为worker生成并启用systemd服务
7. 轮询，直到员工上线并打印结果摘要

可用选项：

要求：Linux、systemd、Docker引擎、Docker Compose v2、Python 3。

快速启动（手动）

1） 先决条件

• 控制节点：

- Docker引擎（二进制文件也有发布版本——如果通过二进制文件部署，则不需要Docker）

• 工作节点：

- Docker引擎（需要 worker-docker)

2） 启动控制台服务

1. 下载 docker-compose.yml 文件：

   mkdir -p onlyboxes-console && cd onlyboxes-console
   wget https://raw.githubusercontent.com/Coooolfan/onlyboxes/refs/heads/main/docker/docker-compose.yml

1. 编辑 docker-compose.yml 并至少替换：

- CONSOLE_HASH_KEY - CONSOLE_DASHBOARD_PASSWORD

1. 启动控制台：

   docker compose up -d

默认端点：

• 控制台Web UI/HTTP REST API/MCP端点： http://127.0.0.1:8089
• gRPC： 127.0.0.1:50051

3） 登录并创建访问令牌

• 打开 http://127.0.0.1:8089 在您的浏览器中。
• 使用初始化的管理员帐户登录。

Console login page

• 转到令牌管理页面并创建访问令牌。

Token created dialog (one-time plaintext token)

• 立即保存明文令牌（它只返回一次）。

4） 创建一个worker

• 转到Workers页面并创建worker。

Workers page

• 从创建对话框复制并安全存储启动命令(WORKER_SECRET 一次性可见）。

Worker created dialog (startup command and one-time secret)

• （可选）单击 Open in Startup Tool with Id and Secret 打开预先填充了workerid和secret的启动命令生成器。

- 在打开的页面上，您可以编辑所有可用选项。生成的启动命令显示在页面底部——复制并保存。 Startup command builder

5） 跑步工人

\[！警告\] Workers支持不同的运行时和环境。当前版本仅提供 worker-docker本节以Docker运行时为例。

1. 登录到将部署工作人员的计算机。

- 确保Docker引擎已安装。 - 确保worker可以访问控制台gRPC终结点。

1. 下载最新版 worker-docker GitHub发布的二进制文件：

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

1. 使用仪表板中的启动命令值，并将最后一行的可执行路径替换为下载的二进制文件。

- 默认情况下，Workers拒绝不安全的控制台端点；集 WORKER_CONSOLE_INSECURE=true 仅允许明文连接。

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

6） 验证准备就绪

• 确认工人 online 在仪表板的Workers页面上。
• 有关REST API请求示例，请参阅 README/API.md.
• 如果没有配置令牌， /mcp 执行API返回 401 通过设计。
• 添加MCP端点 http://127.0.0.1:8089/mcp 在任何LLM聊天客户端中，设置令牌，并验证其是否正常工作。

claude-code-demo

常见问题

• Q： 工人留下来 offline 开始后？

A： 检查一下 WORKER_CONSOLE_GRPC_TARGET 指向正确的控制台gRPC地址并验证网络连接。

• Q： 工作人员可以与控制台部署在同一台机器上吗？

A： 是的。

• Q： worker可以在Docker内部运行吗？

A： 理论上，是的。但是，不建议这样做，因为worker需要访问主机Docker守护进程。你需要自己在Docker中处理Docker。

生产清单

• 替换所有默认凭据。
• 使用反向代理强制TLS :8089 和 :50051.
• 持久化并备份SQLite数据目录(CONSOLE_DB_PATH).
• 在隔离的主机上运行workers，以避免与控制台共享Docker守护进程。
• 阅读 Configuration Reference 下面列出了所有可用选项，并根据需要进行调整。

配置参考

控制台(console)

工人(worker-docker)

API表面

• 仪表板身份验证： /api/v1/console/*
• 工人管理（管理员）： /api/v1/workers*
• 命令执行： /api/v1/commands/echo, /api/v1/commands/terminal
• 任务执行： /api/v1/tasks*
• MCP（流式HTTP）： POST /mcp

发展

从源运行后端

cd console
CONSOLE_HASH_KEY=$(openssl rand -hex 32) go run ./cmd/console

运行web开发服务器

yarn --cwd web install
yarn --cwd web dev

Web开发URL默认为 http://127.0.0.1:5178 和代理 /api/* 到 http://127.0.0.1:8089.

有用的文档

• API统一参考： README/API.md
• 控制台内部： console/README/overview.md
• 工人内部： worker/worker-docker/README/overview.md
• API/原型指南： api/README/proto.md
• Web应用指南： web/README.md

发布与图片

• GitHub工作流程： .github/workflows/package-release.yml
• 控制台Docker镜像： coolfan1024/onlyboxes: 和 coolfan1024/onlyboxes:latest
• 控制台二进制文件包括嵌入式web资产

安全和操作说明

• Console在此版本中不提供内置的TLS/mTLS； worker-docker 需要明确 WORKER_CONSOLE_INSECURE=true 通过明文连接。
• 放置控制台HTTP(:8089)和gRPC(:50051)在反向代理/网关后面，并在公共/外部链路上实施TLS。
• WORKER_SECRET 并且仅在创建时返回访问令牌明文值。
• 仪表板登录会话在内存中，并且在以下情况下无效 console 重新启动。

链接

• linux.do
• boxlite.ai

许可证

GNU AGPL v3.0