使用说明

项目简介

Gru Sandbox 是一个自托管的沙箱环境，专为 MCP (Model Context Protocol) 和 AI Agent 设计。它提供了一个安全和隔离的环境，用于运行 AI Agent 和 MCP 任务，核心功能是通过容器技术管理和隔离不同的计算环境（Boxes），并对外提供符合 MCP 协议的服务接口，使得 LLM 客户端能够安全地执行代码、访问资源和利用工具。

主要功能点

资源管理 (Boxes): 通过 Docker 或 Kubernetes 技术，在隔离的容器（Boxes）中运行代码，支持容器的创建、删除、启动、停止和状态查看。
工具注册与执行: 内置了 'run-python' 和 'run-bash' 工具，允许 LLM 客户端在沙箱环境中执行 Python 和 Bash 代码。
Prompt 模板: 提供 'run-python' Prompt 模板，引导用户如何使用 Python 代码执行工具。
MCP 协议支持: 实现了 MCP Server 规范，通过 JSON-RPC 协议与客户端通信，支持资源、工具和 Prompt 的发现和调用。
灵活的环境配置: 支持 Docker 和 Kubernetes 两种部署模式，可以根据需求选择合适的运行环境。
自动资源回收: 具备 Box 自动回收机制，定期清理不活跃的容器，节省资源。

安装步骤

系统要求:
- macOS 10.15 或更高版本
- Docker Desktop for Mac (或已安装 Docker 环境，如 Linux 或 Windows 系统)
- Homebrew (macOS)

安装 gbox CLI 工具: 在 macOS 终端中执行以下命令安装 'gbox' 命令行工具：

brew tap babelcloud/gru && brew install gbox

初始化环境: 执行 'gbox setup' 初始化 Gru Sandbox 环境。
导出 MCP 配置: 执行 'gbox mcp export --merge-to <客户端名称>' 命令导出 MCP 服务器配置，并合并到指定的 MCP 客户端（如 'claude' 或 'cursor'）的配置文件中。例如，要配置 Claude Desktop 客户端，执行：
```
gbox mcp export --merge-to claude
```
或配置 Cursor 客户端：
```
gbox mcp export --merge-to cursor
```
重启 MCP 客户端: 重启您配置的 MCP 客户端（如 Claude Desktop 或 Cursor），使配置生效。

服务器配置

MCP 客户端需要配置 MCP 服务器的连接信息才能正常工作。'gbox mcp export --merge-to <客户端名称>' 命令已经自动完成了配置合并，以下是导出的 MCP 服务器配置信息示例 (JSON 格式)，通常无需手动配置，仅供参考：

{
  "serverName": "gbox-mcp-server",  // MCP 服务器名称
  "command": "gbox mcp export",     // 启动 MCP 服务器的命令 (实际此命令用于导出配置，MCP Server 以后台服务形式运行)
  "args": [],                        // 启动命令的参数，此处为空
  "transport": "stdio",              // 通信传输协议，默认为 stdio
  "capabilities": {                 // 服务器声明的功能
    "prompts": {},                   // 支持 Prompt 功能
    "resources": {},                 // 支持资源管理功能
    "tools": {},                     // 支持工具调用功能
    "logging": {}                    // 支持日志记录功能
  }
}

注意: 实际的 MCP 服务器并非通过 'gbox mcp export' 命令直接启动，而是通过 'gbox setup' 等命令在后台以服务形式运行。 'gbox mcp export' 命令的主要作用是生成并导出客户端所需的配置文件，方便客户端连接到已经运行的 MCP 服务器。

基本使用方法

使用 MCP 客户端连接: 按照 MCP 客户端（如 Claude Desktop, Cursor 等）的指引，配置并连接到 Gru Sandbox MCP Server。连接成功后，客户端应该能够发现 Gru Sandbox 提供的资源和工具。
列出 Boxes 资源: 在 MCP 客户端中，可以使用 "list-boxes" 工具列出当前可用的 Boxes 资源。每个 Box 代表一个隔离的容器环境。
执行 Python 代码: 使用 "run-python" 工具在指定的 Box 环境中执行 Python 代码。如果不指定 Box ID，系统会自动选择或创建一个合适的 Box 来运行代码。
执行 Bash 命令: 使用 "run-bash" 工具在指定的 Box 环境中执行 Bash 命令。
管理 Boxes (通过 gbox CLI): 可以使用 'gbox' 命令行工具管理 Boxes，例如：
- 'gbox box list': 列出所有 Boxes
- 'gbox box create': 创建新的 Box
- 'gbox box delete <box-id>': 删除指定的 Box
- 'gbox box exec <box-id> -- <command>': 在指定的 Box 中执行命令

详细的 'gbox' 命令用法，请参考仓库 README 文档或执行 'gbox --help' 命令查看帮助信息。

关键词