gbox

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