Gru Sandbox

🚀 gbox - 强大的容器化工具

gbox 是一款功能强大的容器化工具，旨在助力开发者轻松管理 sandbox 容器。它提供了一套完整的命令行界面（CLI），可用于创建、启动、停止和删除容器，还支持与 MCP 服务器集成，为容器管理带来极大便利。

🚀 快速开始

gbox 提供了丰富的功能，通过它您可以：

• 利用 Docker 兼容的卷 mounts，轻松将主机目录与容器目录进行映射。
• 灵活配置和导出 MCP 配置，以便与 Claude Desktop 等工具进行交互。
• 便捷地检查和管理正在运行的容器。
• 快速开发和构建新的功能。

✨ 主要特性

• 完整的命令行界面：提供创建、启动、停止和删除容器等操作的命令。
• MCP 服务器集成：支持与 MCP 服务器集成，方便配置和导出 MCP 配置。
• Docker 兼容卷挂载：可将主机目录与容器目录进行映射。
• 功能开发便捷：有助于快速开发和构建新功能。

📦 安装指南

通过系统包管理器安装

# Debian/Ubuntu 系统
sudo apt-get install gbox

# CentOS/RHEL 系统
sudo yum install gbox

手动安装

下载最新版本的 gbox 并按照 官方文档 中的说明进行安装。

💻 使用示例

基础用法

容器管理

# 创建新容器
gbox box create --image 镜像名称 [--env 环境变量] [-w 工作目录] [-v 主机路径:容器路径[:只读][:传播模式]]

# 列出所有容器
gbox box list

# 启动指定容器
gbox box start <容器ID>

# 停止指定容器
gbox box stop <容器ID>

# 删除指定容器
gbox box delete <容器ID>

# 在容器内执行命令
gbox box exec <容器ID> -- <可执行文件> [<参数>...]

# 查看容器详细信息
gbox box inspect <容器ID>

MCP 配置

# 导出 MCP 配置
gbox mcp export

# 将配置合并到 Claude Desktop 中
gbox mcp export --merge-to claude

# 预览合并结果而不实际应用更改
gbox mcp export --dry-run

高级用法

体积挂载

gbox box create 命令支持 Docker 兼容的卷挂载格式：

-v /主机路径:/容器路径[:只读][:传播模式]

示例

# 基本绑定挂载
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

⚠️ 重要提示

主机路径必须在创建容器之前存在，容器路径将在需要时自动创建。

📚 详细文档

开发环境搭建

先决条件

• Go 1.21 或更高版本
• Docker Desktop
• Make 工具
• pnpm（通过 corepack 安装）
• Node.js 16.13 或更高版本

编译项目

# 编译所有组件
make build

# 创建发行版包
make dist

运行服务

# 启动 API 服务器
npm run dev

# 测试 API 服务器
npm test

# 执行类型检查
npm run type-check

贡献指南

欢迎任何贡献！请参考 CONTRIBUTING.md 文件获取详细信息。

提交规范

• 为每个提交提供清晰的描述。
• 在合并请求中包含相关的测试用例和文档更新。
• 遵循代码风格指南。

📄 许可证

本项目受 MIT 许可证 保护。