A self-hostable sandbox for Agents to execute commands, surf web and use desktop/mobile.
gbox is a self-hostable sandbox for AI Agents to execute commands, surf web and use desktop/mobile. See “Features” section for details.
This project is based on the technology behind gru.ai. It has been tested over 100000 Agent jobs.
As MCP is getting more and more popular, we also implemented a MCP server to make it easy to be directly integrated into MCP client such as Claude Desktop/Cursor.
pip install pygbox. See PyPI for details.pip install pygbox
Python SDK Documentation{:target=“_blank”}
npm install @gru/gbox
Typescript SDK Documentation{:target=“_blank”}
Note: Support for other platforms (Linux, Windows) is coming soon.
## 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
The project provides a command-line tool gbox for managing sandbox containers:
## 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
## To use the Computer-Using Agent for Android, an OPENAI_API_KEY is required.
gbox cua android "Open Uber and order a ride to The Chinese University of Hong Kong."
## 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
The gbox box create command supports Docker-compatible volume mounts using the -v or --volume flag. This allows you to share files and directories between your host system and the sandbox containers.
The volume mount syntax follows this format:
-v /host/path:/container/path[:ro][:propagation]
Where:
/host/path: Path to a file or directory on your host system/container/path: Path where the file or directory will be mounted in the containerro (optional): Makes the mount read-onlypropagation (optional): Sets the mount propagation mode (private, rprivate, shared, rshared, slave, rslave)Examples:
## 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
Note: The host path must exist before creating the container. The container path will be created automatically if it doesn’t exist.
ADB (Android Debug Bridge) is required for gbox to communicate with your Android device:
Install ADB:
brew install android-platform-toolssudo apt install adb (Ubuntu/Debian) or sudo pacman -S android-tools (Arch)Add ADB to your PATH:
export PATH=$PATH:/path/to/platform-tools
Verify ADB installation:
adb version
Enable USB debugging on your Android device:
Connect Android device via USB and confirm ADB connected
adb devices -l
List of devices attached
897X0691U Pixel_3 device
Set the OPENAI_API_KEY environment variable and enjoy gbox Android CUA
export OPENAI_API_KEY=YOUR_KEY
gbox cua android "Open Uber and book a ride to The Chinese University of Hong Kong now."
The video demonstration for this task can be found in the first use case below under “Use Cases” section.
Prompt: Open Uber and book a ride to The Chinese University of Hong Kong now.
Your AI client such as Claude Desktop can use gbox MCP to deliver better results, such as
Generate diagrams of Tesla stock prices:
https://claude.ai/share/34de8ca3-4e04-441b-9e79-5875fa9fc97a
Generate PDF of latest AI news:
https://claude.ai/share/84600933-dcf2-44be-a2fd-7f49540db57a
Analyze and compare Nvidia/Tesla market cap:
https://claude.ai/share/70c335b7-9fff-4ee7-8459-e6b7462d8994
Find images in download folder and compress into zip.
https://claude.ai/share/f8c4c617-9b32-4062-a8e2-2ab33ef46f42
Download youtube video:
https://claude.ai/share/c2ab6bcb-7032-489f-87d5-cc38f72c2ca9
## 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
We welcome contributions! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
git checkout -b username/feature-name)git commit -m 'Add some feature')git push origin username/feature-name)gbox cleanup. It will stop the api server so that you can run the api server in dev env.make api-dev in project root../gbox box list, this is the command run from your dev env.make mcp-dev in project root../gbox mcp export --merge-to claudemake mcp-inspect in project root.make build-image-python in project root to build Python image, or make build-images to build all images.make build-image-typescript for TypeScript image)../gbox box delete --allmake build to update the dist/index.js file../gbox mcp export --merge-to claudeThis project is licensed under the Apache License 2.0 - see the LICENSE{:target=“_blank”} file for details.
Mcp Qdrant Memory
MCP server providing a knowledge graph implementation with semantic search capabilities powered by Qdrant vector database
Terraform Mcp Server
Terraform Registry MCP Server
Mcp 3d Printer Server
Connects MCP to major 3D printer APIs (Orca, Bambu, OctoPrint, Klipper, Duet, Repetier, Prusa, Creality). Control prints, monitor status, and perform advanced STL operations like scaling, rotation, sectional editing, and base extension. Includes slicing and visualization.
A specialized Model Context Protocol (MCP) server that enables you to search, read, delete and send emails from your Gmail account, leveraging an AI Agent to help with each operation. Optimized for Systemprompt MCP Voice client.
MCP server for creating UI flowcharts
MCP server for generating human face images with various shapes and sizes