格框

gbox是一个开源项目，它提供了一个可自托管的沙盒，用于 MCP 集成或其他 AI 代理用例。该沙盒可以用作代理的计算机。它包含代理执行日常任务所需的所有必要工具，例如终端、浏览器和文件编辑器。详情请参阅“功能”部分。

随着 MCP 越来越流行，我们发现没有简单的方法能够让 Claude Desktop/Cursor 等 MCP 客户端在本地安全地运行任务。本项目基于gru.ai的技术，我们将其封装到系统命令和 MCP 服务器中，使其更加易于使用。

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

特征

终端
- 执行任何 Linux 命令
- 直接执行python脚本
- 跨调用共享会话 [开发中]
文件
- 将主机文件夹挂载到沙盒中
- 通过http链接访问沙盒文件
- 以多模式读取文件内容
- 写入/重写文件[开发中]
- 编辑文件[开发中]
- 搜索文件 [开发中]
浏览器
- 打开任意 url，以多模式返回内容
- 从任意 URL 下载 [开发中]
- 根据指令操作浏览器 [开发中]
- 人类接管[开发中]
HTTP 服务器
- 按需在任意文件夹启动 http 服务 [开发中]
SDK
- Python SDK：使用pip install pygbox安装。详情请参阅PyPI 。
- Typescript SDK [开发中]
微胶囊钙
- 标准 MCP 支持
- 集成 Claude Desktop 和 Cursor

用例

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

安装

系统要求

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

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

开发设置

先决条件

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 请求。对于重大变更，请先提交一个问题，讨论您希望修改的内容。

分叉存储库
创建你的功能分支（ 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 ，这是从您的开发环境运行的命令。

如何在开发环境中将 Claude Desktop 等 MCP 客户端连接到 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文件。

gbox

Integrations

格框

特征

用例

1. 生成图表

2. 生成 PDF

3.分析计算

4.处理本地文件

5.执行任意任务

安装