gbox is an open source project that provides a self-hostable sandbox for Agents to execute commands, read/write files, browse the web, operate iOS/Android. The sandbox can be used as a computer/phone/pad for agent. See "Features" section for details.
This project is based on the technology behind gru.ai. It has been tested over 100000 Agent jobs.
For advanced scenarios, we also kept the ability to run sandboxes in k8s cluster locally or remotely.
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.
- Terminal
- Execute any linux command
- Execute python scripts directly
- Share session across invokes [under-development]
- File
- Mount host machine folders into sandbox
- Access sandbox files through http links
- Read file content in multi-modal
- Write/re-write files
- Edit files [under-development]
- Search files [under-development]
- Browser
- Open any url, return content in multi-modal
- Download from any url [under-development]
- Operate browser by instructions [under-development]
- Human take over [under-development]
- HTTP Server
- Start http service on any folder on demand [under-development]
- SDKs
- Python SDK: Install using
pip install pygbox. See PyPI for details. - Typescript SDK
- Python SDK: Install using
- MCP
- Standard MCP support
- Integrate Claude Desktop & Cursor
pip install pygboxnpm install @gru/gbox- macOS 10.15 or later
- Docker Desktop for Mac
- Homebrew
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 DesktopThe 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
# 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 changesThe 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.9Note: The host path must exist before creating the container. The container path will be created automatically if it doesn't exist.
Your AI client such as Claude Desktop can use gbox MCP to deliver better results, such as
Generate diagrams of Tesla stock prices:
Generate PDF of latest AI news:
Analyze and compare Nvidia/Tesla market cap:
Find images in download folder and compress into zip.
Download youtube video:
- Go 1.21 or later
- Docker Desktop
- Make
- pnpm (via corepack)
- Node.js 16.13 or later
# 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 inspectWe 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.
- Fork the repository
- Create your feature branch (
git checkout -b username/feature-name) - Commit your changes (
git commit -m 'Add some feature') - Push to the branch (
git push origin username/feature-name) - Open a Pull Request
- Stop the installed gbox by
gbox cleanup. It will stop the api server so that you can run the api server in dev env. - Execute
make api-devin project root. - Execute
./gbox box list, this is the command run from your dev env.
- Execute
make mcp-devin project root. - Execute
./gbox mcp export --merge-to claude
- Execute
make mcp-inspectin project root. - Click the link returned in terminal.
- Execute
make build-image-pythonin project root to build Python image, ormake build-imagesto build all images. - Change the image name as needed (e.g.,
make build-image-typescriptfor TypeScript image). - You may need to delete current sandboxes to make the new image effective
./gbox box delete --all
- After you change MCP configuration such as tool definitions, you need to run
make buildto update thedist/index.jsfile. - You may also need to execute
./gbox mcp export --merge-to claude
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.