gbox

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.

Features

Terminal
- Execute any linux command
- Execute python scripts directly
- Share session across invokes [under-development]
File
- Read/Write/List files in sandbox
- Edit files [under-development]
- Search files [under-development]
Browser
- Provide cdp url for browser control [under-development]
- Download from any url [under-development]
- Human take over [under-development]
Computer-Using Agent for Android
- Natural language task execution via ADB client
- Physical Android devices supported only
HTTP Server
- Start http service on any folder on demand [under-development]
SDKs
- Typescript SDK Installing using npm install gbox-sdk, see Gbox SDK Reference for details.
MCP
- Standard MCP support
- Integrate Claude Desktop & Cursor

Use gbox as a CLI

Installation

System Requirements

macOS 10.15 or later
Docker Desktop for Mac
Homebrew

Note: Support for other platforms (Linux, Windows) is coming soon.

Installation Steps

# 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 Steps

# 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

Command Line Usage (Under Development)

The project provides a command-line tool gbox for managing sandbox containers:

# login and profile management for gbox.cloud
gbox login # login to gbox.cloud
gbox logout # logout from gbox.cloud

gbox profile create <profile-name> # create a new profile
gbox profile delete <profile-name> # delete a profile

# Setup local environment
gbox local setup    # Setup local environment
gbox local cleanup  # Cleanup local environment

# Container management for both local and gbox.cloud
gbox box newlinux --env "DEBUG=true"                                               # 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>  
gbox box cp <box-id> <local-path> <container-path>                                 # copy file from container to local

# only for gbox.cloud
gbox <box-id>  # open a box in browser                                             # switch to the target environment
gbox switch                                                                        # switch to gbox cloud dashboard

# 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

Computer-Using Agent on Android

📋 Prerequisites

An Android device connected via USB or ADB over TCP/IP
ADB (Android Debug Bridge) installed and configured
API key for OpenAI with access to the computer-use-preview model

🔧 Setting up ADB

ADB (Android Debug Bridge) is required for gbox to communicate with your Android device:

Install ADB:
- Windows: Download Android SDK Platform Tools and extract the ZIP file
- macOS: brew install android-platform-tools
- Linux: sudo apt install adb (Ubuntu/Debian) or sudo pacman -S android-tools (Arch)
Add ADB to your PATH:
- Windows: Add the path to the extracted platform-tools folder to your system's PATH environment variable
- macOS/Linux: Add the following to your ~/.bashrc or ~/.zshrc:
```
export PATH=$PATH:/path/to/platform-tools
```
Verify ADB installation:
```
adb version
```
Enable USB debugging on your Android device:
- Go to Settings → About phone
- Tap Build number 7 times to enable Developer options
- Go to Settings → System → Developer options (location may vary by device)
- Enable USB debugging

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.

Use Cases

1. Call an Uber

Prompt: Open Uber and book a ride to The Chinese University of Hong Kong now.

2. Use DoorDash/Foodpanda to order food delivery.

MCP Use Cases

Your AI client such as Claude Desktop can use gbox MCP to deliver better results, such as

Develop gbox

Prerequisites

Go 1.21 or later
Docker Desktop
Make
pnpm (via corepack)
Node.js 16.13 or later

Build

# Build all components
make build

# Create distribution package
make dist

Running Services

# API Server
make -C packages/api-server dev

# MCP Server
cd packages/mcp-server && pnpm dev

# MCP Inspector
cd packages/mcp-server && pnpm inspect

Contributing

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.

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

Things to Know about Dev and Debug Locally

How to run gbox in dev env instead of the system installed one

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-dev in project root.
Execute ./gbox box list, this is the command run from your dev env.

How to connect MCP client such as Claude Desktop to the MCP server in dev env

Execute make mcp-dev in project root.
Execute ./gbox mcp export --merge-to claude

How to open MCP inspect

Execute make mcp-inspect in project root.
Click the link returned in terminal.

How to build and use image in dev env

Execute make build-image-python in project root to build Python image, or make build-images to build all images.
Change the image name as needed (e.g., make build-image-typescript for TypeScript image).
You may need to delete current sandboxes to make the new image effective ./gbox box delete --all

Why MCP client still get the old MCP content?

After you change MCP configuration such as tool definitions, you need to run make build to update the dist/index.js file.
You may also need to execute ./gbox mcp export --merge-to claude

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

gbox Sandbox