格框

gbox是一个自托管沙盒，可供 AI 代理执行命令、浏览网页以及使用桌面/移动设备。详情请参阅“功能”部分。

该项目基于gru.ai的技术，已在超过 100,000 个 Agent 作业上进行测试。

随着 MCP 越来越流行，我们还实现了一个 MCP 服务器，以便于直接集成到 MCP 客户端，例如 Claude Desktop/Cursor。

特征

1. 终端

   • 执行任何 Linux 命令

   • 直接执行python脚本

   • 跨调用共享会话 [开发中]

2. 文件

   • 将主机文件夹挂载到沙盒中

   • 通过http链接访问沙盒文件

   • 以多模式读取文件内容

   • 写入/重写文件

   • 编辑文件[开发中]

   • 搜索文件 [开发中]

3. 浏览器

   • 打开任意 url，以多模式返回内容

   • 从任意 URL 下载 [开发中]

   • 根据提示操作浏览器

   • 人类接管[开发中]

4. HTTP 服务器

   • 按需在任意文件夹启动 http 服务 [开发中]

5. SDK

   • Python SDK：使用pip install pygbox安装。详情请参阅PyPI 。

   • Typescript SDK

6. 微胶囊钙

   • 标准 MCP 支持

   • 集成 Claude Desktop 和 Cursor

Related MCP server: Capsule server

使用 gbox 作为 SDK

Python SDK

pip install pygbox

Python SDK 文档

Typescript SDK

npm install @gru/gbox

Typescript SDK 文档

使用 gbox 作为 CLI

安装

系统要求

• macOS 10.15 或更高版本

• 适用于 Mac 的 Docker Desktop

• 自制

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

安装步骤

# Install via Homebrew
brew tap babelcloud/gru && brew install gbox

# Initialize environment
gbox setup

# Export MCP config and merge into Claude Desktop
gbox mcp export --merge-to claude
# or gbox mcp export --merge-to cursor

# Restart Claude Desktop

更新步骤

# Update gbox to the latest version
brew update && brew upgrade gbox

# Update the environment
gbox setup

# Export and merge latest MCP config into Claude Desktop
gbox mcp export --merge-to claude
# or gbox mcp export --merge-to cursor

# Restart Claude Desktop

命令行用法

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

# Cluster management
gbox cluster setup # Setup cluster environment
gbox cluster cleanup # Cleanup cluster environment

# Container management
gbox box create --image python:3.9 --env "DEBUG=true" -w /app -v /host/path:/app # Create container
gbox box list # List containers
gbox box start <box-id> # Start container
gbox box stop <box-id> # Stop container
gbox box delete <box-id> # Delete container
gbox box exec <box-id> -- python -c "print('Hello')" # Execute command
gbox box inspect <box-id> # Inspect container

# MCP configuration
gbox mcp export # Export MCP configuration
gbox mcp export --merge-to claude # Export and merge into Claude Desktop config
gbox mcp export --dry-run # Preview merge result without applying changes

卷挂载

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）

例子：

# Basic bind mount
gbox box create -v /data:/data --image python:3.9

# Read-only bind mount
gbox box create -v /data:/data:ro

# Multiple bind mounts
gbox box create \
 -v /config:/etc/myapp \
 -v /data:/var/lib/myapp:ro \
 -v /logs:/var/log/myapp:ro:rprivate \
 --image python:3.9

注意：创建容器前，主机路径必须存在。若不存在，则会自动创建容器路径。

MCP 用例

您的 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.处理本地文件

在下载文件夹中找到图像并压缩为 zip。👁 图像
https://claude.ai/share/f8c4c617-9b32-4062-a8e2-2ab33ef46f42

5.执行任意任务

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

开发 gbox

先决条件

• Go 1.21 或更高版本

• Docker 桌面

• 制作

• pnpm（通过 corepack）

• Node.js 16.13 或更高版本

建造

# Build all components
make build

# Create distribution package
make dist

运行服务

# API Server
make -C packages/api-server dev

# MCP Server
cd packages/mcp-server && pnpm dev

# MCP Inspector
cd packages/mcp-server && pnpm inspect

贡献

欢迎大家贡献代码！欢迎提交 Pull 请求。对于重大变更，请先提交一个问题，讨论您希望修改的内容。

1. 分叉存储库

2. 创建你的功能分支（ git checkout -b username/feature-name ）

3. 提交您的更改（ git commit -m 'Add some feature' ）

4. 推送到分支（ git push origin username/feature-name ）

5. 打开拉取请求

关于本地开发和调试你需要知道的事情

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

1. 使用gbox cleanup停止已安装的 gbox。它将停止 api 服务器，以便您可以在开发环境中运行 api 服务器。

2. 在项目根目录执行make api-dev 。

3. 执行./gbox box list ，这是从您的开发环境运行的命令。

如何在开发环境中将 Claude Desktop 等 MCP 客户端连接到 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. 根据需要更改图像名称（例如，为 TypeScript 图像make build-image-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文件。

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers