This guide explains how to register your local Android device with Gbox for local testing and development.

​
Prerequisites

Before proceeding, ensure you have:
  • An Android device with developer options enabled
  • A Mac computer
  • USB cable for device connection
  • Active internet connection

​
Step-by-Step Registration Process

​
1. Enable Developer Options on Android Device

Reference: For detailed instructions, refer to the Pixel Developer Options Guide and Samsung Developer Options Guide

​
2. Configure Device Settings

To ensure optimal performance during testing:
  • Disable Auto screen timeout
  • Disable Auto lock screen
  • Keep the device screen on during testing sessions

​
3. Connect Device to Mac

  1. Connect your Android device to your Mac using a USB cable
  2. On your Android device, allow USB debugging when prompted
  3. Ensure the device is recognized by your Mac

​
4. Install and Configure Gbox CLI

Open Terminal on your Mac and execute the following commands: 
# Install Gbox CLI
brew install gbox

# Update Gbox if already installed
brew update && brew upgrade gbox

# Login to gbox.cloud (GitHub authorization required)
gbox login

# Register local device to gbox.ai
gbox device-connect

​
5. Verify Device Connection

After successful registration, you should see your connected device in the device list:
Connected Device List

​
6. Install GboxADBKeyboard (Required)

Your device may prompt you to install GboxADBKeyboard - this is essential for Agent input operations. Please install it when prompted.

​
Troubleshooting

​
Connection Issues

  • Ensure USB debugging is enabled
  • Try different USB cables
  • Restart both device and Mac if needed

​
Performance Note

Note: Due to our servers being located in the United States, users in other locations may experience some latency during operations.

​
Next Steps

Once your device is successfully registered, you can:
  • Run automated tests
  • Execute UI actions
  • Debug applications
  • Perform device automation tasks
For more information on using your registered device, refer to the Android Basic Guide and Real Device Testing documentation.