Content
# 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](https://brew.sh)
> Note: Using gbox on other platforms, please check npm package [@gbox.ai/cli](https://www.npmjs.com/package/@gbox.ai/cli) for installation instructions. You can also login to [GBOX.AI](https://gbox.ai) to use web-based dashboard.
### Installation Steps
#### Quick Install (Recommended)
**Option 1: Install GBOX CLI only**
```bash
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:
```bash
gbox setup
```
**Option 2: Install with all dependencies (one-step setup)**
```bash
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:**
```bash
# 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):**
```bash
brew install gbox
```
**Via npm (Linux/Windows):**
```bash
npm install -g @gbox.ai/cli
```
#### Setup Dependencies
If you installed GBOX CLI only, you can install all command dependencies anytime:
```bash
gbox setup
```
Or install them interactively:
```bash
gbox setup -y
```
#### Update GBOX CLI
Keep your GBOX CLI up to date:
**Using the install script:**
```bash
# 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):**
```bash
brew upgrade gbox
```
**Using npm (Linux/Windows):**
```bash
npm update -g @gbox.ai/cli
```
#### Get Started
```bash
# 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](https://docs.gbox.ai/cli) for detailed usage.
### SDK Usage
Check [GBOX SDK Reference](https://docs.gbox.ai/sdk) for detailed usage.
## Use GBOX as a MCP Server(Login required)
Using GBOX CLI to configure MCP server to your Claude Code/Cursor:
```bash
# 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:
```json
{
"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](https://docs.gbox.ai/cli/register-local-device)
## Android MCP Use Cases
| Use Case | Demo |
|----------|------|
| Claude Code Develop/Test Android App | [](https://www.youtube.com/watch?v=IzlZFsqC4CY) |
| Claude Code Compare Prices on eCommerce Apps | [](https://www.youtube.com/watch?v=Op3ZSVg-qg8) |
## 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](https://gbox.ai) to get a cloud virtual device. Best for testing and development.
**2. Cloud Physical Device:**
Login to [GBOX.AI](https://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](https://docs.gbox.ai/cli/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](https://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
```bash
# Build for current platform
make build
# Build for all platforms
make build-all
# Create distribution package
make dist
```
### Running Services
```bash
# 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](LICENSE) file for details.
