bridgelink 0.2.1

CLI tool to expose Android devices remotely via NativeBridge

🌉 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
• 🔐 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

---

📦 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

This automatically installs all dependencies including Python and bore tunnel.

---

Option 2: APT (Debian/Ubuntu) - Recommended for Linux users

# Add the BridgeLink repository
sudo add-apt-repository ppa:autoflowlabs/bridgelink
sudo apt update

# Install BridgeLink
sudo apt install bridgelink

This automatically installs all dependencies including ADB.

---

Option 3: pip (All platforms) - For Python developers

Step 1: Create Virtual Environment (Recommended)

macOS / Linux

# Create virtual environment
python3 -m venv bridgelink-env

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

# Your prompt should now show (bridgelink-env)

Windows (Command Prompt)

# Create virtual environment
python -m venv bridgelink-env

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

# Your prompt should now show (bridgelink-env)

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

# Your prompt should now show (bridgelink-env)

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

Step 2: Install BridgeLink

pip install bridgelink

Step 3: Install Dependencies (pip only)

bridgelink install

This automatically installs:

• 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

Connect your Android device via USB and enable USB debugging.

3. Add Device

bridgelink devices add <device-serial>

4. Access Remotely

adb connect bridgelink.nativebridge.io:15750

---

📋 Commands

Device Management

# Add device(s)
bridgelink devices add <serial>
bridgelink devices add <serial1> <serial2>  # Multiple devices
bridgelink devices add <serial> --auto-activate  # Enable auto-activation

# Activate existing device
bridgelink devices activate <serial>

# 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

Installation

# Install both bore and ADB
bridgelink install

# Install only bore
bridgelink install --bore-only

# Install only ADB
bridgelink install --adb-only

---

🔍 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

1. Auto-Start: When you add the first device, a background daemon automatically starts
2. Continuous Monitoring: Checks device connectivity every 1 second (fast!)
3. Smart Detection:
   • Physical Devices: Must be in "device" state (strict)
   • Emulators: Can be in "device" or "offline" state (lenient)
4. Auto-Cleanup: When devices disconnect, automatically:
   • Stops the tunnel
   • Updates backend state to "inactive"
   • No stale connections!
5. 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

1. Auto-Start: When you enable auto-activation for a device, the connection monitor starts
2. Continuous Watching: Checks for newly connected devices every 1 second (fast!)
3. 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
4. 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

---

🔧 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: [e-mail]
• 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