🌉 BridgeLink

BridgeLink is a production-ready CLI tool that exposes your local Android devices remotely via the NativeBridge platform, making them accessible from anywhere with secure tunneling powered by bore.

---

✨ Features

• 🚀 One-Command Setup - Install and configure in seconds
• 📱 Multi-Device Support - Manage multiple Android devices simultaneously
• 📡 WiFi Connection Support - Connect devices wirelessly via WiFi (no USB cable needed!)
• 🔐 Secure Tunneling - API key-based authentication via NativeBridge
• 🌍 Remote Access - Access devices from anywhere in the world
• 🤖 Auto-Installation - Automatically installs bore tunnel and ADB
• 💻 Cross-Platform - Works on macOS, Linux, and Windows
• 🔄 Background Management - Tunnels run in the background as daemons
• 🔍 Automatic Health Monitoring - Auto-detects and deactivates disconnected devices (1s polling - fast!)
• 🔄 Auto-Activation - Devices automatically reconnect when plugged back in (1s polling - fast!)
• 📊 Device Tracking - Track device state and connection URLs in real-time
• ✅ Input Validation - Validates device serials via ADB before backend calls
• 🎯 Smart Activation - Intelligently reactivates existing devices
• 🛡️ Platform-Aware Detection - Different health checks for physical devices vs emulators
• 🔌 USB & WiFi Support - Seamlessly handles both USB and wireless connections

---

📦 Installation

Choose your preferred installation method:

Option 1: Homebrew (macOS) - Recommended for Mac users

# Add the BridgeLink tap
brew tap AutoFlowLabs/tap

# Install BridgeLink
brew install bridgelink

# Run setup to install required tools (ADB, bore)
bridgelink setup

---

Option 2: pip (Linux, Windows, macOS)

Method A: Virtual Environment (Recommended)

<details> <summary><b>macOS / Linux</b></summary>

# Create virtual environment
python3 -m venv bridgelink-env

# Activate virtual environment
source bridgelink-env/bin/activate

# Install BridgeLink
pip install bridgelink

# Run setup
bridgelink setup

</details> <details> <summary><b>Windows (Command Prompt)</b></summary>

# Create virtual environment
python -m venv bridgelink-env

# Activate virtual environment
bridgelink-env\Scripts\activate.bat

# Install BridgeLink
pip install bridgelink

# Run setup
bridgelink setup

</details> <details> <summary><b>Windows (PowerShell)</b></summary>

# Create virtual environment
python -m venv bridgelink-env

# Activate virtual environment
bridgelink-env\Scripts\Activate.ps1

# If you get an execution policy error, run:
# Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Install BridgeLink
pip install bridgelink

# Run setup
bridgelink setup

</details>

Note: Remember to activate the virtual environment each time you open a new terminal session before using BridgeLink.

Method B: Global Installation

If you prefer to install globally (not recommended due to potential dependency conflicts):

# Linux/macOS
pip install bridgelink
# Or with sudo if permission denied:
sudo pip install bridgelink

# Windows (run terminal as Administrator)
pip install bridgelink

After installation, run setup:

bridgelink setup

This automatically installs required tools:

• bore - Tunnel binary for your platform (macOS, Linux, Windows)
• ADB - Android Debug Bridge from Google

---

🚀 Quick Start

After installation, follow these steps:

1. Set API Key

Get your API key from NativeBridge Dashboard:

macOS / Linux:

export NB_API_KEY='Nb-kNGB.your-api-key-here'

Windows (Command Prompt):

set NB_API_KEY=Nb-kNGB.your-api-key-here

Windows (PowerShell):

$env:NB_API_KEY="Nb-kNGB.your-api-key-here"

2. Connect Your Device

Option A: USB Connection (Default) Connect your Android device via USB and enable USB debugging.

Option B: WiFi Connection (Wireless)

1. Connect your Android device via USB first
2. Ensure both device and computer are on the same WiFi network
3. Use the --wifi flag when adding the device (see below)

3. Add Device

USB Connection:

bridgelink devices add <device-serial>

WiFi Connection:

bridgelink devices add <device-serial> --wifi

After WiFi setup completes, you can disconnect the USB cable. The device will remain accessible via WiFi!

4. Access Remotely

Option A: Via ADB Command Line

adb connect bridgelink.nativebridge.io:15750

Option B: Via NativeBridge Dashboard Visit the BridgeLink Dashboard to:

• 📊 View all your registered devices
• 🎮 Start remote device sessions
• 🖥️ Control devices directly from your browser
• 📈 Monitor device status in real-time

Dashboard URL: https://nativebridge.io/dashboard/bridgelink (Development: https://trust-me-bro.nativebridge.io/dashboard/bridgelink)

---

📋 Commands

Device Management

# Add device(s)
bridgelink devices add <serial>                    # USB connection
bridgelink devices add <serial> --wifi             # WiFi connection (USB required initially)
bridgelink devices add <serial1> <serial2>         # Multiple devices
bridgelink devices add <serial> --auto-activate    # Enable auto-activation
bridgelink devices add <serial> --wifi --auto-activate  # WiFi + auto-activation

# Activate existing device
bridgelink devices activate <serial>               # Works with both USB and WiFi devices

# List all devices
bridgelink devices list

# Deactivate device (keeps registration)
bridgelink devices deactivate <serial>
bridgelink devices deactivate                      # Deactivate ALL active devices (with confirmation)
bridgelink devices deactivate --all                # Deactivate ALL active devices

# Remove device completely
bridgelink devices remove <serial>

# Auto-activation management
bridgelink devices set-auto-activate <serial> on   # Enable auto-activation
bridgelink devices set-auto-activate <serial> off  # Disable auto-activation

Daemon Management

# Check tunnel status
bridgelink daemon status

# View tunnel logs
bridgelink daemon logs <serial>

# Stop tunnel(s)
bridgelink daemon stop <serial>            # Stop specific tunnel
bridgelink daemon stop                     # Stop ALL tunnels (with confirmation)
bridgelink daemon stop --all               # Stop ALL tunnels

# Clean up dead tunnels
bridgelink daemon cleanup

Setup & Installation

# Run interactive setup (installs bore, ADB, configures API key)
bridgelink setup

# Install both bore and ADB (non-interactive)
bridgelink install

# Install only bore
bridgelink install --bore-only

# Install only ADB
bridgelink install --adb-only

---

📡 WiFi Connection (Wireless ADB)

BridgeLink supports wireless ADB connections via WiFi, allowing you to use your devices without USB cables!

How It Works

1. Initial Setup (USB Required):

   • Connect device via USB
   • Run: bridgelink devices add <serial> --wifi
   • BridgeLink will:
     • Enable TCP/IP mode on the device (port 5555)
     • Get the device's WiFi IP address
     • Connect via WiFi (adb connect <ip>:5555)
     • Create tunnel using WiFi connection

2. After Setup:

   • Disconnect the USB cable
   • Device remains connected via WiFi
   • Tunnel continues working wirelessly
   • Access remotely via BridgeLink URL

Requirements

• Device and computer must be on the same WiFi network
• WiFi must be enabled on the Android device
• USB connection required only for initial setup

Example Usage

# Initial setup (USB connected)
bridgelink devices add 1d752b81 --wifi

# Output:
# 📡 Setting up WiFi connection...
#    Step 1/3: Enabling TCP/IP mode on device...
#    ✓ TCP/IP mode enabled on port 5555
#    Step 2/3: Getting device IP address...
#    ✓ Device IP address: 192.168.1.15
#    Step 3/3: Connecting to device via WiFi...
#    ✓ Connected via WiFi: 192.168.1.15:5555
#
# 💡 You can now disconnect the USB cable!

# Now disconnect USB - device stays connected via WiFi!
# Tunnel URL: bridgelink.nativebridge.io:15750

Multiple WiFi Devices

You can connect multiple devices via WiFi simultaneously:

# Add first device via WiFi
bridgelink devices add device1_serial --wifi

# Add second device via WiFi
bridgelink devices add device2_serial --wifi

# List all devices
bridgelink devices list
# Shows both devices with WiFi connections (IP:5555 format)

WiFi + Auto-Activation

Combine WiFi with auto-activation for ultimate convenience:

bridgelink devices add <serial> --wifi --auto-activate

Now your device will:

• ✅ Connect wirelessly via WiFi
• ✅ Auto-deactivate when disconnected from WiFi
• ✅ Auto-activate when reconnected to WiFi
• ✅ No USB cable needed after initial setup

Limitations & Notes

• Reboot: If you restart the device, it will reset to USB mode. You'll need to run the WiFi setup again (USB cable + --wifi flag).
• Network: Device and computer must remain on the same WiFi network
• Battery: WiFi ADB consumes more battery than USB ADB
• Performance: WiFi connection may have slightly higher latency than USB

Troubleshooting WiFi

Device not connecting?

# Check device IP manually
adb shell ip route | grep src

# Try manual connection
adb connect <device-ip>:5555

# Verify connection
adb devices

Connection lost?

• Ensure device hasn't gone to sleep (keep screen on during setup)
• Check both