项目简介

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

通过 gbox，您可以：

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

安装指南

通过系统包管理器安装

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

# CentOS/RHEL 系统
sudo yum install gbox

手动安装

下载最新版本的 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 许可证 保护。