GBOX

GBOX provides environments for AI Agents to operate computer and mobile devices.

*Mobile Scenario:*

Your agents can use GBOX to develop/test android apps, or run apps on the Android to complete various tasks(mobile automation).

*Desktop Scenario:*

Your agents can use GBOX to operate desktop apps such as browser, terminal, VSCode, etc(desktop automation).

*MCP:*

You can also plug GBOX MCP to any Agent you like, such as Cursor, Claude Code. These agents will instantly get the ability to operate computer and mobile devices.

Installation

System Requirements

• MacOS
  • Version: 10.15 or later
  • Homebrew

> Note: Using gbox on other platforms, please check npm package @gbox.ai/cli for installation instructions. You can also login to GBOX.AI to use web-based dashboard.

Installation Steps

Quick Install (Recommended)

Option 1: Install GBOX CLI only

curl -fsSL https://raw.githubusercontent.com/babelcloud/gbox/main/install.sh | bash

This installs just the GBOX CLI. Additional dependencies (like ADB, frpc, Appium) will be automatically installed when needed, or you can install them later using:

gbox setup

Option 2: Install with all dependencies (one-step setup)

curl -fsSL https://raw.githubusercontent.com/babelcloud/gbox/main/install.sh | bash -s -- --with-deps

This installs everything at once:

• GBOX CLI
• Node.js and npm (if not present)
• Android Debug Bridge (ADB)
• FRP client (frpc)
• Appium server, drivers and plugins

Non-Interactive Mode:

# CLI only
curl -fsSL https://raw.githubusercontent.com/babelcloud/gbox/main/install.sh | bash -s -- -y

# With all dependencies
curl -fsSL https://raw.githubusercontent.com/babelcloud/gbox/main/install.sh | bash -s -- -y --with-deps

Alternative Installation Methods

Via Homebrew (macOS):

brew install gbox

Via npm (Linux/Windows):

npm install -g @gbox.ai/cli

Setup Dependencies

If you installed GBOX CLI only, you can install all command dependencies anytime:

gbox setup

Or install them interactively:

gbox setup -y

Update GBOX CLI

Keep your GBOX CLI up to date:

Using the install script:

# Interactive update (will prompt if already installed)
curl -fsSL https://raw.githubusercontent.com/babelcloud/gbox/main/install.sh | bash

# Force update without prompt
curl -fsSL https://raw.githubusercontent.com/babelcloud/gbox/main/install.sh | bash -s -- --update

# Skip update even if newer version available
curl -fsSL https://raw.githubusercontent.com/babelcloud/gbox/main/install.sh | bash -s -- --update=false

Using Homebrew (macOS):

brew upgrade gbox

Using npm (Linux/Windows):

npm update -g @gbox.ai/cli

Get Started

# Login to gbox.ai
gbox login

# Connect your Android device (dependencies will be installed automatically if missing)
gbox device-connect

# Export MCP config and merge into Claude Code/Cursor
gbox mcp export --merge-to claude-code
gbox mcp export --merge-to cursor

Command Line Usage

Check GBOX CLI Reference for detailed usage.

SDK Usage

Check GBOX SDK Reference for detailed usage.

Use GBOX as a MCP Server(Login required)

Using GBOX CLI to configure MCP server to your Claude Code/Cursor:

# Export MCP config for Cursor
gbox mcp export --merge-to cursor

# Export MCP config for Claude Code
gbox mcp export --merge-to claude-code --scope project

Or copy paste the following content into your Claude Code/Cursor MCP config:

{
  "mcpServers": {
    "gbox-android": {
      "command": "npx",
      "args": [
        "-y",
        "@gbox.ai/mcp-server@latest"
      ]
    }
  }
}

> Note:

> - Currently, GBOX MCP can only control Android environments.

> - If you need Cursor/Claude Code to control your local Android device, please check Register Local Device

Android MCP Use Cases

Environments

Currently, GBOX supports the following environments:

• Android
• Linux Desktop/Browser

Android Environment

There are three types of Android environments, you can choose based on your needs:

1. Cloud Virtual Device:

Login to GBOX.AI to get a cloud virtual device. Best for testing and development.

2. Cloud Physical Device:

Login to GBOX.AI to get a cloud physical device. Cloud physical device is a real Android phone that you can use for production scenarios.

3. Local Physical Device:

Use your own physical device Register Local Device. Your local device can be any Android device that have Developer Mode enabled. Best for production scenarios and personal use.

Linux Desktop/Browser Environment

Login to GBOX.AI to get a Linux desktop/browser environment. Best for testing and development.

Develop gbox

Prerequisites

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

Build

# Build for current platform
make build

# Build for all platforms
make build-all

# Create distribution package
make dist

Running Services

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

1. Fork the repository

2. Create your feature branch (`git checkout -b username/feature-name`)

3. Commit your changes (`git commit -m 'Add some feature'`)

4. Push to the branch (`git push origin username/feature-name`)

5. Open a Pull Request

Things to Know about Dev and Debug Locally

License

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