Gru Sandbox

🚀 Gbox

Gbox is a powerful containerization tool designed to help developers easily manage sandbox containers. It offers a comprehensive command-line interface (CLI) for creating, starting, stopping, and deleting containers, and supports integration with MCP servers.

🚀 Quick Start

Gbox simplifies the management of sandbox containers and offers seamless integration with MCP servers. With Gbox, you can:

• Map host directories to container directories using Docker-compatible volume mounts.
• Configure and export MCP configurations for interaction with tools like Claude Desktop.
• Check and manage running containers.
• Rapidly develop and build new features.

📦 Installation

Install via System Package Manager

# For Debian/Ubuntu systems
sudo apt-get install gbox

# For CentOS/RHEL systems
sudo yum install gbox

Manual Installation

Download the latest version of gbox and follow the instructions in the official documentation.

💻 Usage Examples

Container Management

# Create a new container
gbox box create --image image_name [--env environment_variable] [-w working_directory] [-v host_path:container_path[:ro][:propagation_mode]]

# List all containers
gbox box list

# Start a specified container
gbox box start <container_id>

# Stop a specified container
gbox box stop <container_id>

# Delete a specified container
gbox box delete <container_id>

# Execute a command inside a container
gbox box exec <container_id> -- <executable> [<arguments>...]

# View detailed information about a container
gbox box inspect <container_id>

MCP Configuration

# Export MCP configuration
gbox mcp export

# Merge the configuration into Claude Desktop
gbox mcp export --merge-to claude

# Preview the merge result without applying changes
gbox mcp export --dry-run

Volume Mounts

The gbox box create command supports Docker-compatible volume mount formats:

-v /host_path:/container_path[:ro][:propagation_mode]

Basic Usage

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

Advanced Usage

# 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

Note: The host path must exist before creating the container, and the container path will be created automatically if needed.

📚 Documentation

Prerequisites for Development Environment Setup

• Go 1.21 or higher
• Docker Desktop
• Make tool
• pnpm (installed via corepack)
• Node.js 16.13 or higher

Compile the Project

# Compile all components
make build

# Create a distribution package
make dist

Run the Service

# Start the API server
npm run dev

# Test the API server
npm test

# Perform type checking
npm run type-check

Contribution Guidelines

Contributions are welcome! Please refer to the CONTRIBUTING.md file for detailed information.

Commit Specifications

• Provide a clear description for each commit.
• Include relevant test cases and documentation updates in merge requests.
• Follow the code style guide.

📄 License

This project is licensed under the MIT License.