🌉 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)

macOS / Linux

# 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

Windows (Command Prompt)

# 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

Windows (PowerShell)

# 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

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)

Connect your Android device via USB first
Ensure both device and computer are on the same WiFi network
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

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
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 devices are on same WiFi network
Try reconnecting: adb connect <ip>:5555

🔍 Automatic Health Monitoring & Auto-Activation

BridgeLink includes two automatic background monitors that work together to provide a fully automated device lifecycle:

1. Health Monitor (Auto-Deactivation)

Watches for disconnections and automatically deactivates devices

Auto-Start: When you add the first device, a background daemon automatically starts
Continuous Monitoring: Checks device connectivity every 1 second (fast!)
Smart Detection:
- Physical Devices: Must be in "device" state (strict)
- Emulators: Can be in "device" or "offline" state (lenient)
Auto-Cleanup: When devices disconnect, automatically:
- Stops the tunnel
- Updates backend state to "inactive"
- No stale connections!
Auto-Stop: When all devices are deactivated, the daemon automatically stops

2. Connection Monitor (Auto-Activation) 🆕

Watches for reconnections and automatically activates devices with auto-activation enabled

Auto-Start: When you enable auto-activation for a device, the connection monitor starts
Continuous Watching: Checks for newly connected devices every 1 second (fast!)
Smart Activation: When a device reconnects:
- Checks if device has auto_activate enabled in backend
- Verifies device is currently inactive
- Automatically creates tunnel and activates device
Zero Manual Intervention: Once enabled, devices reconnect automatically when plugged back in

What This Means for You

✅ No Manual Monitoring - Everything happens automatically ✅ Lightning Fast Detection - Disconnects/reconnects detected within 1 second! ✅ Clean State - No stale tunnels or active states ✅ Zero Maintenance - Daemons manage themselves ✅ Opt-in Auto-Reconnect - Enable per device as needed

Example Flow (With Auto-Activation)

# 1. Add a device with auto-activation enabled
$ bridgelink devices add emulator-5554 --auto-activate
🔍 Starting background health monitor...
   ✅ Health monitor started
🔌 Starting auto-activation connection monitor...
   ✅ Connection monitor started
💡 Health monitoring is active - disconnected devices will be auto-deactivated
🔄 Auto-activation ENABLED - device will auto-reconnect when plugged back in

# 2. Device gets physically disconnected
#    (Health monitor automatically detects and deactivates)
#    Logs to ~/.bridgelink/monitor.log:
#    ⚠️  Device emulator-5554 is unhealthy: Device disconnected
#       Stopping tunnel...
#       Updating backend state to inactive...
#    ✅ Device emulator-5554 deactivated successfully

# 3. Device gets reconnected (USB plugged back in)
#    (Connection monitor automatically detects and activates)
#    Logs to ~/.bridgelink/connection_monitor.log:
#    🔌 Detected 1 newly connected device(s)
#    🔄 Auto-activating device: emulator-5554
#       Setting up ADB TCP mode...
#       Creating bore tunnel...
#       Tunnel URL: bridgelink.nativebridge.io:15751
#    ✅ Device emulator-5554 auto-activated successfully
#
#    ← No manual intervention needed!

Daemon Locations

Health Monitor:

PID File: ~/.bridgelink/monitor.pid
Log File: ~/.bridgelink/monitor.log
State File: ~/.bridgelink/health_monitor.json

Connection Monitor:

PID File: ~/.bridgelink/connection_monitor.pid
Log File: ~/.bridgelink/connection_monitor.log

📖 Documentation

For complete documentation, visit the GitHub repository.

Key Guides:

Security Guide - Security best practices ⚠️ READ FIRST
Auto-Activation Feature - Detailed auto-activation guide 🆕
Complete Command Reference - All commands with examples
Architecture - System architecture and data flow
Deployment Guide - Backend setup and deployment
Local Testing - Test before PyPI release
PyPI Release - Publishing guide

🌐 NativeBridge Dashboard

After registering a device with BridgeLink, you can manage it through the NativeBridge Dashboard.

Dashboard Features

Device Management:

📊 View all your BridgeLink devices in one place
✅ See device status (active/inactive)
🔗 View tunnel URLs for each device
📱 Check comprehensive device details:
- Hardware: Model, manufacturer, CPU, RAM, storage
- Display: Resolution, density (DPI)
- Software: Android version, SDK, security patch
- Connection: Tunnel URL, device type (USB/WiFi)

Remote Sessions:

🎮 Start remote device sessions directly from the browser
🖥️ Control devices remotely without ADB command line
🖱️ Click, swipe, and interact with your device
📸 Take screenshots and record sessions
🔄 Real-time device mirroring

Monitoring:

📈 Monitor device connection status
⏱️ View device uptime and availability
🔍 Track device usage and sessions

Accessing the Dashboard

Production:

https://nativebridge.io/dashboard/bridgelink

Development:

https://trust-me-bro.nativebridge.io/dashboard/bridgelink

Note: The dashboard URL is automatically shown when you add or activate a device. Look for the 🌐 icon in the CLI output!

How It Works

Register Device:
```
bridgelink devices add <device-serial>
```
Device Appears in Dashboard:
- Automatically registered in your NativeBridge account
- Visible at the dashboard URL
Start Remote Session:
- Click on your device in the dashboard
- Click "Start Session"
- Control device from your browser!

Use Cases

Web-Based Testing:

Test your app without installing ADB
Share device access with team members
Demo apps remotely in meetings

Remote Debugging:

Debug issues on physical devices from anywhere
No need for VPN or complex network setup
Instant access through secure tunnel

Device Management:

Centralized view of all your test devices
Quick access to device information
Easy activation/deactivation

🔧 Configuration

Environment Variables

Variable	Description	Default
`NB_API_KEY`	NativeBridge API key	Required
`NB_API_URL`	Backend API URL	`https://dev.api.nativebridge.io`
`BORE_SERVER`	Bore tunnel server	`bridgelink.nativebridge.io`

State Directory

BridgeLink stores configuration in ~/.bridgelink/:

tunnels.json - Tunnel state
tunnel_<serial>.log - Individual tunnel logs

🛡️ Security

✅ ADB Validation - Device serials validated before backend calls
✅ API Key Auth - Secure authentication for all operations
✅ User Isolation - Each user only sees their own devices
✅ HTTPS - Encrypted communication with backend

🤝 Support

Email: support@nativebridge.io
Issues: https://github.com/AutoFlowLabs/bridgelink/issues
Docs: https://docs.nativebridge.io/bridgelink
API Key: https://nativebridge.io/dashboard/api-keys

🙏 Acknowledgments

bore - Fast, simple TCP tunnel
ADB - Android Debug Bridge by Google
Click - Python CLI framework
FastAPI - Modern Python web framework

📄 License

MIT License - see LICENSE file for details.

Made with ❤️ by the NativeBridge team

Name		Name	Last commit message	Last commit date
Latest commit History 24 Commits
.github/workflows		.github/workflows
__pycache__		__pycache__
bridgelink		bridgelink
docs		docs
packaging		packaging
.bumpversion.cfg		.bumpversion.cfg
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
DOCUMENTATION_STRUCTURE.md		DOCUMENTATION_STRUCTURE.md
LICENSE		LICENSE
README.md		README.md
requirements.txt		requirements.txt
setup.py		setup.py

Folders and files

Latest commit

History

Repository files navigation

🌉 BridgeLink

✨ Features

📦 Installation

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

Option 2: pip (Linux, Windows, macOS)

Method A: Virtual Environment (Recommended)

Method B: Global Installation

🚀 Quick Start

1. Set API Key

2. Connect Your Device

3. Add Device

4. Access Remotely

📋 Commands

Device Management

Daemon Management

Setup & Installation

📡 WiFi Connection (Wireless ADB)

How It Works

Requirements

Example Usage

Multiple WiFi Devices

WiFi + Auto-Activation

Limitations & Notes

Troubleshooting WiFi

🔍 Automatic Health Monitoring & Auto-Activation

1. Health Monitor (Auto-Deactivation)

2. Connection Monitor (Auto-Activation) 🆕

What This Means for You

Example Flow (With Auto-Activation)

Daemon Locations

📖 Documentation

🌐 NativeBridge Dashboard

Dashboard Features

Accessing the Dashboard

How It Works

Use Cases

🔧 Configuration

Environment Variables

State Directory

🛡️ Security

🤝 Support

🙏 Acknowledgments

📄 License

About

Topics

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages