gbox

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

该项目基于 gru.ai 背后的技术。它已在超过 100000 个代理作业中进行了测试。

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

功能

终端
- 执行任何 Linux 命令
- 直接执行 Python 脚本
- 在调用之间共享会话 [开发中]
文件
- 将主机文件夹挂载到沙盒中
- 通过 HTTP 链接访问沙盒文件
- 多模态读取文件内容
- 写入/重写文件
- 编辑文件 [开发中]
- 搜索文件 [开发中]
浏览器
- 打开任意网址，多模态返回内容
- 从任意网址下载 [开发中]
- 通过指令操作浏览器
- 人工接管 [开发中]
Android 电脑使用代理
- 通过 ADB 客户端执行自然语言任务
- 仅支持物理 Android 设备
HTTP 服务器
- 根据需要在任何文件夹上启动 HTTP 服务 [开发中]
SDK
- Python SDK：使用 pip install pygbox 安装。详情请参见 PyPI。
- Typescript SDK
MCP
- 标准 MCP 支持
- 集成 Claude Desktop & Cursor

将 gbox 用作 SDK

Python SDK

使用gbox命令行工具

TypeScript SDK

npm install @gru/gbox

TypeScript SDK 文档

使用 gbox 作为 CLI

安装

系统要求

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>                                                          # 检查容器

# 使用Android的计算机使用代理需要OPENAI_API_KEY。
gbox cua android "打开Uber并叫车前往香港中文大学。"

# 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

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

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

Android上的电脑使用代理

📋 前提条件

通过 USB 或 ADB over TCP/IP 连接的 Android 设备
已安装并配置 ADB (Android Debug Bridge)
具有访问 computer-use-preview 模型权限的 OpenAI API 密钥

🔧 ADB 设置

gbox 需要 ADB (Android Debug Bridge) 来与您的 Android 设备通信：

安装 ADB:
- Windows: 下载 Android SDK Platform Tools 并解压 ZIP 文件
- macOS: brew install android-platform-tools
- Linux: sudo apt install adb (Ubuntu/Debian) 或 sudo pacman -S android-tools (Arch)
将ADB添加到你的PATH环境变量中:
- Windows: 将解压后的platform-tools文件夹路径添加到系统的PATH环境变量中。
- macOS/Linux: 将以下内容添加到你的_/.bashrc或/.zshrc文件中：
```
export PATH=$PATH:/path/to/platform-tools
```
验证ADB安装:
```
adb version
```
在你的Android设备上启用USB调试:
- 前往设置 → 关于手机
- 点击版本号 7 次以启用开发者选项
- 前往设置 → 系统 → 开发者选项 （位置可能因设备而异）
- 启用USB调试

通过USB连接Android设备并确认ADB已连接

adb devices -l
已连接设备列表
897X0691U       Pixel_3 device

设置OPENAI_API_KEY环境变量并体验gbox Android CUA CODE_BLOCK

此任务的视频演示可在下面的“用例”部分的第一个用例中找到。

用例

1. 叫车

提示: 打开Uber并立即预订前往香港中文大学的行程。

2. 使用DoorDash/Foodpanda订餐。

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. 分析和计算

分析和比较英伟达/特斯拉的市值： 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 Desktop
Make
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

贡献

欢迎贡献！请随时提交拉取请求。对于重大更改，请先打开一个问题来讨论您想更改的内容。

Fork 代码库
创建您的功能分支 (git checkout -b username/feature-name)
提交您的更改 (git commit -m 'Add some feature')
推送到分支 (git push origin username/feature-name)
打开一个拉取请求

本地开发和调试须知

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

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

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

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

如何打开MCP检查器

在项目根目录下执行make mcp-inspect。
点击终端返回的链接。

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

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

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

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

许可证

本项目采用Apache License 2.0许可 - 详情请见LICENSE文件。