### Setup GBOX Dependencies Source: https://github.com/babelcloud/gbox/blob/main/README.md Installs all necessary dependencies for GBOX. Can be run interactively or non-interactively. ```bash gbox setup # Or non-interactively gbox setup -y ``` -------------------------------- ### Quick Install GBOX CLI Source: https://github.com/babelcloud/gbox/blob/main/README.md Installs the GBOX CLI. Dependencies like ADB and Appium are installed automatically when needed or can be set up later with 'gbox setup'. ```bash curl -fsSL https://raw.githubusercontent.com/babelcloud/gbox/main/install.sh | bash ``` -------------------------------- ### Install GBOX CLI with all dependencies Source: https://github.com/babelcloud/gbox/blob/main/README.md Installs the GBOX CLI along with Node.js, npm, ADB, FRP client, and Appium. This is a one-step setup for all required components. ```bash curl -fsSL https://raw.githubusercontent.com/babelcloud/gbox/main/install.sh | bash -s -- --with-deps ``` -------------------------------- ### Install @gbox/live-view Source: https://github.com/babelcloud/gbox/blob/main/packages/live-view/README.md Install the live-view package using npm or pnpm. ```bash npm install @gbox/live-view # or pnpm add @gbox/live-view ``` -------------------------------- ### Get Started with GBOX Source: https://github.com/babelcloud/gbox/blob/main/README.md Initial commands to log in to GBOX, connect an Android device, and export MCP configurations for IDEs. ```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 ``` -------------------------------- ### Install GBOX CLI using NPM Source: https://github.com/babelcloud/gbox/blob/main/packages/cli-npm/README.md Use this command to install the GBOX CLI on Linux systems via NPM. ```bash npm install -g @gbox.ai/cli ``` -------------------------------- ### Install GBOX CLI using Homebrew Source: https://github.com/babelcloud/gbox/blob/main/packages/cli-npm/README.md Use this command to install the GBOX CLI on macOS systems via Homebrew. ```bash brew install gbox ``` -------------------------------- ### Development Commands Source: https://github.com/babelcloud/gbox/blob/main/packages/live-view/README.md Common commands for developing the component, including installing dependencies, running the dev server, and building. ```bash # 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 ``` -------------------------------- ### Build gbox for Current Platform Source: https://github.com/babelcloud/gbox/blob/main/README.md Use this command to build the gbox project for the platform you are currently working on. Ensure Go 1.21+ and Make are installed. ```bash # Build for current platform make build ``` -------------------------------- ### Non-Interactive GBOX CLI Installation Source: https://github.com/babelcloud/gbox/blob/main/README.md Installs the GBOX CLI without prompts. Use '--with-deps' to include all dependencies. ```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 ``` -------------------------------- ### Start Port Forward Source: https://github.com/babelcloud/gbox/blob/main/packages/cli/internal/server/static/adb-expose.html Initiates a port forward connection. It sends a POST request to the /api/adb-expose/start endpoint with the box ID and local port. Handles success and error responses, updating the UI accordingly. ```javascript function startForward(boxId, localPort, remotePort) { const button = document.getElementById('expose-button'); button.disabled = true; button.textContent = 'Exposing...'; fetch('/api/adb-expose/start', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ box_id: boxId, local_port: localPort, remote_port: remotePort }) }) .then(res => res.json()) .then(data => { if (data.success) { loadBoxesAndForwards(); // Reload both boxes and forwards button.textContent = 'Exposed'; // Optionally disable the button after successful exposure or provide a way to remove it } else { alert('Failed to start port forward: ' + (data.error || 'Unknown error')); // Restore button state on failure button.disabled = false; button.textContent = 'Expose'; } }) .catch(err => { console.error('Failed to start port forward:', err); alert('Failed to start port forward: ' + err.message); // Restore button state on error button.disabled = false; button.textContent = 'Expose'; }); } ``` -------------------------------- ### Run MCP Server Locally Source: https://github.com/babelcloud/gbox/blob/main/README.md Starts the MCP Server service locally. Navigate to the 'packages/mcp-server' directory and use pnpm to run the development server. Requires Node.js 16.13+ and pnpm. ```bash # MCP Server cd packages/mcp-server && pnpm dev ``` -------------------------------- ### Update GBOX CLI using install script Source: https://github.com/babelcloud/gbox/blob/main/README.md Updates the GBOX CLI using the installation script. Supports interactive updates, forced updates, and skipping updates. ```bash # Interactive update 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 ``` -------------------------------- ### Run MCP Inspector Locally Source: https://github.com/babelcloud/gbox/blob/main/README.md Starts the MCP Inspector service locally. Navigate to the 'packages/mcp-server' directory and use pnpm to run the inspector. Requires Node.js 16.13+ and pnpm. ```bash # MCP Inspector cd packages/mcp-server && pnpm inspect ``` -------------------------------- ### React Component Usage Example with Specialized Hooks Source: https://github.com/babelcloud/gbox/blob/main/packages/live-view/src/hooks/README.md Demonstrates integrating multiple specialized hooks into a React component to manage various user interactions on a video element. Ensure all necessary hooks and client/enabled/isConnected variables are defined. ```typescript import { useClipboardHandler, useControlHandler, useKeyboardHandler, useWheelHandler, useMouseHandler, useClickHandler, useTouchHandler } from '../hooks'; function MyComponent() { const clipboardHandler = useClipboardHandler({ client, enabled, isConnected, onError }); const controlHandler = useControlHandler({ client, enabled, isConnected }); const keyboardHandler = useKeyboardHandler({ client, enabled, keyboardCaptureEnabled, isConnected, onClipboardPaste: clipboardHandler.handleClipboardPaste, onClipboardCopy: clipboardHandler.handleClipboardCopy, }); const wheelHandler = useWheelHandler({ client, enabled, isConnected }); const mouseHandler = useMouseHandler({ client, enabled, isConnected }); const clickHandler = useClickHandler({ client, enabled, isConnected }); const touchHandler = useTouchHandler({ client, enabled, isConnected }); return ( ); } ``` -------------------------------- ### Start ADB Port Forwarding Source: https://github.com/babelcloud/gbox/blob/main/packages/cli/internal/server/static/adb-expose.html Initiates a new ADB port forwarding session. It sends a POST request with the box ID, local port, and remote port (defaulting to 5555). The button is disabled during the request, and inputs are cleared upon success. ```javascript function addForward() { const boxId = document.getElementById('boxId').value.trim(); const localPort = parseInt(document.getElementById('localPort').value); const button = document.getElementById('startButton'); // Button should be disabled if form is invalid, but double-check if (!boxId || !localPort || localPort < 1 || localPort > 65535) { return; // Do nothing if form is invalid } // Disable button immediately to prevent duplicate clicks button.disabled = true; button.textContent = 'Exposing...'; fetch('/api/adb-expose/start', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ box_id: boxId, local_ports: [localPort], remote_ports: [5555] }) }) .then(res => res.json()) .then(data => { if (data.success) { loadBoxesAndForwards(); // Reload both boxes and forwards // Clear inputs document.getElementById('boxId').value = ''; document.getElementById('localPort').value = '5555'; // Reset button state after successful operation button.disabled = true; // Keep disabled since form is now empty button.textContent = 'Expose'; // Reset text to ``` -------------------------------- ### useTouchHandler Hook Source: https://github.com/babelcloud/gbox/blob/main/packages/live-view/src/hooks/README.md Handles touch events including touch start, end, and move. Requires client, enabled, and isConnected. ```typescript const { handleTouchStart, handleTouchEnd, handleTouchMove } = useTouchHandler({ client, enabled: true, isConnected: true, }); ``` -------------------------------- ### Publishing to GitHub Packages Source: https://github.com/babelcloud/gbox/blob/main/packages/live-view/README.md Steps to log in to the GitHub Packages registry and publish the package. ```bash # Login to GitHub registry npm login --registry=https://npm.pkg.github.com # Publish npm publish ``` -------------------------------- ### Authenticate with GBOX CLI Source: https://github.com/babelcloud/gbox/blob/main/packages/cli-npm/README.md Run this command to log in and authenticate your GBOX CLI with the service. ```bash gbox login ``` -------------------------------- ### Build gbox for All Platforms Source: https://github.com/babelcloud/gbox/blob/main/README.md This command builds the gbox project for all supported platforms. It's useful for creating cross-platform compatible builds. Requires Make. ```bash # Build for all platforms make build-all ``` -------------------------------- ### Initial Load and Event Listeners Source: https://github.com/babelcloud/gbox/blob/main/packages/cli/internal/server/static/adb-expose.html Sets up the initial state of the page by loading boxes and forwards. It also adds event listeners to input fields to dynamically update button states and sets up an interval to refresh forwards periodically. ```javascript // Initial load loadBoxesAndForwards(); // Add event listeners for form changes document.getElementById('boxId').addEventListener('change', updateButtonState); document.getElementById('localPort').addEventListener('input', updateButtonState); // Refresh forwards every 5 seconds (boxes don't need frequent refresh) setInterval(loadForwards, 5000); ``` -------------------------------- ### Create gbox Distribution Package Source: https://github.com/babelcloud/gbox/blob/main/README.md Use this command to create a distribution package for the gbox project. This is typically the final step before deployment. Requires Make. ```bash # Create distribution package make dist ``` -------------------------------- ### Initialize Server Info Loading Source: https://github.com/babelcloud/gbox/blob/main/packages/cli/internal/server/static/index.html Ensures that the server information is loaded once the DOM is fully loaded. It also sets up an interval to periodically update the server's uptime. ```javascript // Load server info when page loads document.addEventListener('DOMContentLoaded', function() { console.log('DOM loaded, starting to load server info...'); loadServerInfo(); }); // Update uptime every 5 seconds setInterval(async () => { try { const response = await fetch('/api/server/info'); if (response.ok) { const info = await response.json(); document.getElementById('uptime').textContent = info.uptime || 'Unknown'; } } catch (error) { console.error('Failed to update uptime:', error); } }, 5000); ``` -------------------------------- ### Update GBOX CLI via npm (Linux/Windows) Source: https://github.com/babelcloud/gbox/blob/main/README.md Updates the GBOX CLI globally on Linux or Windows using npm. ```bash npm update -g @gbox.ai/cli ``` -------------------------------- ### Load Server Information Source: https://github.com/babelcloud/gbox/blob/main/packages/cli/internal/server/static/index.html Fetches and displays server version, build ID, port, and uptime from the /api/server/info endpoint. Handles errors by updating the UI to indicate a failure. ```javascript async function loadServerInfo() { try { console.log('Loading server info...'); const response = await fetch('/api/server/info'); console.log('Response status:', response.status); if (!response.ok) { throw new Error('HTTP ' + response.status + ': ' + response.statusText); } const info = await response.json(); console.log('Server info:', info); document.getElementById('version').textContent = info.version || 'Unknown'; // Format build ID to be more readable let buildIdText = 'Unknown'; if (info.build_id) { // Extract just the date part for display const buildId = info.build_id; if (buildId.includes('T')) { // Format: 2025-09-11T16:51:14+08:00-unknown -> 2025-09-11 16:51 const dateTime = buildId.split('T')[0] + ' ' + buildId.split('T')[1].split('+')[0].substring(0, 5); buildIdText = dateTime; } else { buildIdText = buildId.substring(0, 16) + '...'; } } document.getElementById('buildId').textContent = buildIdText; document.getElementById('port').textContent = info.port || 'Unknown'; document.getElementById('uptime').textContent = info.uptime || 'Unknown'; console.log('Server info loaded successfully'); } catch (error) { console.error('Failed to load server info:', error); document.getElementById('version').textContent = 'Error'; document.getElementById('buildId').textContent = 'Error'; document.getElementById('port').textContent = 'Error'; document.getElementById('uptime').textContent = 'Error'; // Update status indicator to show error const statusIndicator = document.querySelector('.status-indicator'); const statusHeader = document.querySelector('.status-header'); if (statusIndicator) statusIndicator.style.background = '#ef4444'; if (statusHeader) statusHeader.textContent = 'Server Error'; } } ``` -------------------------------- ### Load Android Boxes and Active Forwards Source: https://github.com/babelcloud/gbox/blob/main/packages/cli/internal/server/static/adb-expose.html Fetches available Android boxes and active ADB forwards to filter out already exposed boxes. Populates a select dropdown with available boxes, showing their name, device type, and status. Skips boxes that are already exposed. ```javascript function loadBoxes() { // Load both boxes and active forwards to filter out already exposed boxes Promise.all([ fetch('/api/boxes?type=android').then(res => res.json()), fetch('/api/adb-expose/list').then(res => res.json()) ]) .then(([boxesData, forwardsData]) => { const select = document.getElementById('boxId'); select.innerHTML = ''; // Get list of already exposed box IDs const exposedBoxIds = new Set(); if (forwardsData.forwards && forwardsData.forwards.length > 0) { forwardsData.forwards.forEach(forward => { exposedBoxIds.add(forward.box_id); }); } if (boxesData.boxes && boxesData.boxes.length > 0) { boxesData.boxes.forEach(box => { // Skip boxes that are already exposed if (exposedBoxIds.has(box.id)) { return; } const option = document.createElement('option'); option.value = box.id; // Show name as primary, device type as secondary, and status const displayName = box.name && box.name !== box.id ? box.name : box.id; const deviceType = box.deviceType || 'virtual'; // virtual or physical const secondaryInfo = box.name && box.name !== box.id ? deviceType : deviceType; option.textContent = `${displayName} (${secondaryInfo}) - ${box.status}`; select.appendChild(option); }); // If no available boxes after filtering if (select.children.length === 1) { select.innerHTML = ''; } } else { select.innerHTML = ''; } updateButtonState(); // Update button state after loading boxes }) .catch(err => { console.error('Failed to load boxes:', err); document.getElementById('boxId').innerHTML = ''; updateButtonState(); // Update button state even on error }); } ``` -------------------------------- ### Load Active ADB Port Forwards Source: https://github.com/babelcloud/gbox/blob/main/packages/cli/internal/server/static/adb-expose.html Fetches and displays a list of active ADB port forwards. If forwards exist, it populates a table with Box ID, Port, and an action button to stop the forward. If no forwards are active, it hides the container. ```javascript function loadForwards() { fetch('/api/adb-expose/list') .then(res => res.json()) .then(data => { const forwardsListContainer = document.querySelector('.forwards-list'); if (data.forwards && data.forwards.length > 0) { // Show the container and populate with table forwardsListContainer.style.display = 'block'; const list = document.getElementById('forwardsList'); const tableHTML = '
| Box ID | ' + 'Port | ' + 'Action | ' + '
|---|---|---|
| ' + forward.box_id + ' | ' + '' + localPort + ' | ' + '' + '' + ' | ' + '