gru-sandbox

Gru-sandbox(gbox) 是一个开源项目，为 MCP 集成或其他 AI 代理用例提供可自托管的沙箱。

随着 MCP 越来越受欢迎，我们发现没有简单的方法可以使 MCP 客户端（如 Claude Desktop/Cursor）在本地安全地执行命令。本项目基于 gru.ai 背后的技术，并将其封装成一个系统命令和 MCP 服务器，使其易于使用。

对于高级场景，我们还保留了在本地或远程 k8s 集群中运行沙箱的能力。

使用场景

您的 AI 客户端（如 Claude Desktop）可以使用 gbox MCP 来提供更好的结果，例如

1. 生成图表

生成特斯拉股票价格的图表： https://claude.ai/share/34de8ca3-4e04-441b-9e79-5875fa9fc97a

2. 生成 PDF

生成最新 AI 新闻的 PDF： https://claude.ai/share/84600933-dcf2-44be-a2fd-7f49540db57a

3. 分析和计算

分析和比较 Nvidia/Tesla 市值： https://claude.ai/share/70c335b7-9fff-4ee7-8459-e6b7462d8994

4. 处理本地文件 (即将推出)

请压缩共享文件夹中的所有照片，并确保每张照片小于 2MB。

5. 执行任意任务

下载 youtube 视频： https://claude.ai/share/c2ab6bcb-7032-489f-87d5-cc38f72c2ca9

安装

系统要求

• macOS 10.15 或更高版本
• Docker Desktop for Mac
• Homebrew

注意：对其他平台（Linux、Windows）的支持即将推出。

安装步骤

# 通过 Homebrew 安装
brew tap babelcloud/gru && brew install gbox

# 初始化环境
gbox setup

# 导出 MCP 配置并合并到 Claude Desktop
gbox mcp export --merge-to claude
# 或 gbox mcp export --merge-to cursor

# 重启 Claude Desktop

更新步骤

# 将 gbox 更新到最新版本
brew update && brew upgrade gbox

# 更新环境
gbox setup

# 导出最新的 MCP 配置并合并到 Claude Desktop
gbox mcp export --merge-to claude
# 或 gbox mcp export --merge-to cursor

# 重启 Claude Desktop

命令行用法

该项目提供了一个命令行工具 gbox，用于管理沙箱容器：

# 集群管理
gbox cluster setup    # 设置集群环境
gbox cluster cleanup  # 清理集群环境

# 容器管理
gbox box create --image python:3.9 --env "DEBUG=true" -w /app -v /host/path:/app   # 创建容器
gbox box list                                                                      # 列出容器
gbox box start <box-id>                                                            # 启动容器
gbox box stop <box-id>                                                             # 停止容器
gbox box delete <box-id>                                                           # 删除容器
gbox box exec <box-id> -- python -c "print('Hello')"                               # 执行命令
gbox box inspect <box-id>                                                          # 检查容器

# MCP 配置
gbox mcp export                          # 导出 MCP 配置
gbox mcp export --merge-to claude        # 导出并合并到 Claude Desktop 配置
gbox mcp export --dry-run                # 预览合并结果而不应用更改

卷挂载

gbox box create 命令支持使用 -v 或 --volume 标志进行 Docker 兼容的卷挂载。这允许您在主机系统和沙箱容器之间共享文件和目录。

卷挂载语法如下：

-v /host/path:/container/path[:ro][:propagation]

其中：

• /host/path: 主机系统上文件或目录的路径
• /container/path: 文件或目录将在容器中挂载的路径
• ro (可选): 使挂载只读
• propagation (可选): 设置挂载传播模式（private、rprivate、shared、rshared、slave、rslave）

示例：

# 基本绑定挂载
gbox box create -v /data:/data --image python:3.9

# 只读绑定挂载
gbox box create -v /data:/data:ro --image python:3.9

# 多个绑定挂载
gbox box create \
  -v /config:/etc/myapp \
  -v /data:/var/lib/myapp:ro \
  -v /logs:/var/log/myapp:ro:rprivate \
  --image python:3.9

注意：在创建容器之前，主机路径必须存在。如果容器路径不存在，将自动创建。

开发设置

前提条件

• Go 1.21 或更高版本
• Docker Desktop
• Make
• pnpm (通过 corepack)
• Node.js 16.13 或更高版本

构建

# 构建所有组件
make build

# 创建分发包
make dist

运行服务

# API 服务器
make -C packages/api-server dev

# MCP 服务器
cd packages/mcp-server && pnpm dev

# MCP 检查器
cd packages/mcp-server && pnpm inspect

贡献

欢迎贡献！请随时提交 Pull Request。对于重大更改，请先打开一个 issue 讨论您想要更改的内容。

1. Fork 仓库
2. 创建您的特性分支 (git checkout -b username/feature-name)
3. 提交您的更改 (git commit -m 'Add some feature')
4. 推送到分支 (git push origin username/feature-name)
5. 打开一个 Pull Request

关于本地开发和调试的注意事项

如何在开发环境而不是系统安装的环境中运行 gbox

1. 通过 gbox cleanup 停止已安装的 gbox。 这将停止 api 服务器，以便您可以在开发环境中运行 api 服务器。
2. 在项目根目录中执行 make api-dev。
3. 执行 ./gbox box list，这是从您的开发环境运行的命令。

如何将 MCP 客户端（如 Claude Desktop）连接到开发环境中的 MCP 服务器

1. 在项目根目录中执行 make mcp-dev。
2. 执行 ./gbox mcp export --merge-to claude

如何打开 MCP 检查器

1. 在项目根目录中执行 make mcp-inspect。
2. 单击终端中返回的链接。

如何在开发环境中构建和使用镜像

1. 在项目根目录中执行 make build-image-python 以构建 Python 镜像，或执行 make build-images 以构建所有镜像。
2. 根据需要更改镜像名称（例如，make build-image-typescript 用于 TypeScript 镜像）。
3. 您可能需要删除当前的沙箱才能使新镜像生效 ./gbox box delete --all

为什么 MCP 客户端仍然获取旧的 MCP 内容？

1. 在您更改 MCP 配置（例如工具定义）后，您需要运行 make build 来更新 dist/index.js 文件。
2. 您可能还需要执行 ./gbox mcp export --merge-to claude

许可证

本项目基于 Apache License 2.0 许可证 - 有关详细信息，请参阅 LICENSE 文件。