Remote Debugging Setup for Android Devices

Step-by-step instructions for connecting and debugging remote Android devices, along with the required helper scripts included in this repository.

Background

Remote debugging is essential when the device you need to test isn’t physically available. For example, I worked on an Android app that communicates with a smart firmware device via Bluetooth. Since the device wasn’t local, I used a remote Android phone to connect, test, and debug the app. This setup allowed reliable testing and automation without shipping hardware or depending on paid services.

Available Solutions and Limitations

• Tunneling services (Ngrok, Serveo, Cloudflare Tunnel) - easy setup but free tiers have limited duration, randomized URLs, and bandwidth restrictions.
• VPN / private networks - secure but complex to set up and often unreliable in free versions.
• SSH reverse tunnels on public servers - forward ports remotely, but free servers may limit uptime and connections.

Architecture

• Transport - Reverse SSH Tunneling (Autossh) for persistent connectivity.
• Bridge - ADB-over-TCP/IP on Android 11+ via Termux.
• Visuals - Real-time screen streaming via scrcpy over the secure tunnel.

Server Setup

To allow remote connections from Android devices, a server with a public IP is required. The basic setup includes:

1. SSH Key Setup

• Generate an SSH key pair on your local machine.
• Copy the public key to the server’s ~/.ssh/authorized_keys using ssh-copy-id or manually append.

2. Firewall Configuration

• Open the port you plan to forward (default: 5555).
• Ensure the firewall does not block other necessary traffic.

3. SSH Configuration (Optional)

• Enable GatewayPorts in sshd_config if needed for remote port forwarding.
• Restart the SSH service after making changes.

This allows remote devices to establish secure, persistent connections to the server.

Android Device Setup

Follow these steps to set up the Android device for remote debugging:

1. Install Termux

Download the APK from F-Droid. Use the F-Droid build of Termux. The Play Store version is deprecated and lacks the necessary package updates for android-tools.

2. Set Up Termux Environment

Open Termux and run:

pkg upgrade && pkg update
pkg install openssl-tool openssh android-tools git autossh netcat-openbsd

Grant storage permission to Termux for file transfers.

3. Enable Developer Options on Android

• Open Settings → About Phone.

• Tap Build Number 7 times to enable Developer Options.

• Go to Settings → System → Developer Options (location may vary by device).

• Enable the following:

  • Stay awake - keeps screen on while charging.
  • Wireless Debugging (Android 11+) - allows ADB over Wi-Fi.

• For Android 11+:

  • Tap Pair device with pairing code. Keep the screen open for pairing.

• For Android <11:

  • Connect via USB to a PC and run adb tcpip 5555 on the PC.
  • Disconnect USB and connect via Termux: adb connect localhost:5555.

4. Prepare Remote Debugging Script

• Copy the helper script (remote-adb.sh) to the device via SD card, file explorer, or scp.
• Open the script and set your server details and ports. Note: the values in the script are placeholders—replace them with your actual server username, host/IP, remote port, and local device port.

5. Run Script

Make it executable and run in Termux:

chmod +x remote-adb.sh
./remote-adb.sh

(Optional) To automatically restart the script if it stops, you can wrap it in a loop:

while true; do
  echo "Starting remote debugging..."
  git pull
  ./remote-adb.sh
  echo "Stopped, restarting in 5 seconds..."
  sleep 5
done

Notes

• Use split-screen mode if pairing and Termux need to run simultaneously.
• Run adb shell input keyevent 82 to unlock the device if necessary.

Laptop/PC Connection

1. Install scrcpy to view and control the remote device screen:

• Download and instructions: https://github.com/Genymobile/scrcpy

2. Prepare and run the script

• Open the adb-connect.sh script and set your server details and ports.
• Run the script:

./adb-connect.sh

To automatically pull updates and refresh the connection, use the -r flag:

./adb-connect.sh -r

This ensures the server script and connection are always up to date.

About the Author

Mobile app developer by profession, with a strong interest in exploring different languages, stacks, and automation tools. Open to feedback and discussions.