DOCSEARCHbyAlgolia
Submit Docs

GBOX

repository·main·Indexed 41 days ago

https://github.com/babelcloud/gbox

GBOX provides environments for AI Agents to operate computer and mobile devices, enabling Android and desktop automation (Linux/Browser). It supports the Model Context Protocol (MCP) for integration with agents like Cursor or Claude Code. The ecosystem includes a CLI for device management, the @gbox/live-view React component for real-time Android screen mirroring via WebRTC, and specialized hooks for handling keyboard, mouse, touch, and clipboard interactions.

Tokens
44.4K
Snippets
187
Records
231
Agent score
52%

What's inside GBOX

  1. What is GBOX?

    main

    GBOX provides environments that allow AI Agents to operate both computer and mobile devices. It supports two primary scenarios:

    • Mobile Scenario: Agents can use GBOX to develop or test Android apps, or perform mobile automation by running apps on Android.
    • Desktop Scenario: Agents can perform desktop automation by operating applications such as browsers, terminals, VSCode, and more.

    Additionally, GBOX supports the Model Context Protocol (MCP), allowing you to plug GBOX into agents like Cursor or Claude Code to instantly grant them the ability to operate computer and mobile devices.

  2. Understand GBOX environments

    main

    GBOX supports two main types of environments:

    1. Android Environments

    There are three ways to access Android environments:

    • Cloud Virtual Device: Obtained via GBOX.AI. Best for testing and development.
    • Cloud Physical Device: Real Android phones hosted in the cloud via GBOX.AI. Best for production scenarios.
    • Local Physical Device: Use your own Android device with Developer Mode enabled. Best for personal use and production scenarios.

    2. Linux Desktop/Browser Environment

    Accessed via GBOX.AI. Best for testing and development of desktop automation (browser, terminal, VSCode, etc.).

  3. Configure GBOX as an MCP Server for Cursor or Claude Code

    main

    You can plug GBOX into AI Agents like Cursor or Claude Code using the Model Context Protocol (MCP). This allows the agents to operate Android environments.

    Automatic Configuration

    Use the mcp export command to automatically merge the configuration into your agent's settings.

    • For Cursor:
      gbox mcp export --merge-to cursor
    - **For Claude Code:**
  ```bash
gbox mcp export --merge-to claude-code --scope project

    Manual Configuration

    Alternatively, you can manually add the following JSON block to your MCP configuration file:

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

    Note: Currently, GBOX MCP only supports controlling Android environments. To control a local Android device, you must Register Local Device.

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

  4. Get started with GBOX CLI

    main

    Once installed, follow these steps to begin using GBOX:

    1. Login to the GBOX service:
      gbox login
    2. Connect an Android device: (Dependencies will be installed automatically if they are missing)
      gbox device-connect
    3. Configure MCP (Optional): To enable AI agents like Cursor or Claude Code to use your device:
      gbox mcp export --merge-to cursor
# OR
gbox mcp export --merge-to claude-code
    gbox login
gbox device-connect
gbox mcp export --merge-to cursor

  6. Development commands for @gbox/live-view

    main

    If you are contributing to or developing the @gbox/live-view package, use the following pnpm commands:

    • pnpm install: Install dependencies.
    • pnpm dev: Run the development server.
    • pnpm build:component: Build the component library.
    • pnpm build:static: Build the static site.
    • pnpm build: Build both the component library and the static site.
    # Install dependencies
pnpm install

# Run development server
pnpm dev

# Build component library
pnpm build:component

# Build static site
pnpm build:static

# Build both
pnpm build

  8. Migrate from @gbox/mcp-android-server to @gbox.ai/mcp-server

    main

    The package mcp-android-server is deprecated. To continue using the MCP server functionality, you must migrate to the new package and repository.

    Action required:

    1. Update your configuration to use the new package name: @gbox.ai/mcp-server.
    2. Reference the new repository for updates and source code: babelcloud/gbox-mcp-server.
    3. Install the new package via npm: npm install @gbox.ai/mcp-server.
    npm install @gbox.ai/mcp-server

  9. Install GBOX CLI and dependencies

    main

    GBOX provides environments for AI Agents to operate computer and mobile devices. You can install the CLI using several methods depending on your operating system and requirements.

    Quick Install (Recommended)

    Option 1: Install GBOX CLI only This installs just the CLI. Dependencies like ADB, frpc, and Appium will be installed automatically when needed, or you can run gbox setup later.

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

    Option 2: Install with all dependencies (one-step setup) This installs the CLI along with Node.js, npm, ADB, FRP client (frpc), and Appium server/drivers/plugins.

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

    Alternative Installation Methods

    • macOS (Homebrew):
      brew install gbox
    • Linux/Windows (npm):
      npm install -g @gbox.ai/cli
    # CLI only
curl -fsSL https://raw.githubusercontent.com/babelcloud/gbox/main/install.sh | bash

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

  11. Update the GBOX CLI

    main

    You can update the GBOX CLI using the method you originally used to install it.

    Using the install script

    • Interactive update (prompts if already installed):
      curl -fsSL https://raw.githubusercontent.com/babelcloud/gbox/main/install.sh | bash
    • Force update (without prompts):
      curl -fsSL https://raw.githubusercontent.com/babelcloud/gbox/main/install.sh | bash -s -- --update
    • Skip update (even if a newer version is 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
    # Force update without prompt
curl -fsSL https://raw.githubusercontent.com/babelcloud/gbox/main/install.sh | bash -s -- --update

  12. Configure GBOX dependencies

    main

    If you chose the 'CLI only' installation path, you can install the necessary command dependencies (ADB, Appium, etc.) at any time using the setup command.

    To install dependencies interactively:

    gbox setup

    To install dependencies non-interactively (skipping prompts):

    gbox setup -y
    gbox setup