LinuxCommandLibrary

adb-reverse

Forward ports from Android device to host

TLDR

List all reverse socket connections from emulators and devices

$ adb reverse --list
copy

Reverse a TCP port from an emulator or device to localhost
$ adb reverse tcp:[remote_port] tcp:[local_port]
copy

Remove a reverse socket connections from an emulator or device
$ adb reverse --remove tcp:[remote_port]
copy

Remove all reverse socket connections from all emulators and devices
$ adb reverse --remove-all
copy

SYNOPSIS

adb reverse [option] remote local
adb reverse --list
adb reverse --remove remote
adb reverse --remove-all

PARAMETERS

remote
    Specifies the port on the Android device. This is the port the application on the device will attempt to connect to. Typically in the format tcp:<device-port-number> (e.g., tcp:8080).

local
    Specifies the port on the host machine. The connection from the device's remote port will be redirected to this host port. Typically in the format tcp:<host-port-number> (e.g., tcp:8080).

--list
    Lists all active reverse port forwardings currently set up via adb.

--remove remote
    Removes the specific reverse port forwarding associated with the given remote (device) port.

--remove-all
    Removes all active reverse port forwardings from the device.

DESCRIPTION

The adb reverse command establishes a reverse port forwarding tunnel between an Android device (or emulator) and the host machine. Unlike adb forward, which makes a host port accessible to the device, adb reverse makes a device port accessible to the host machine. This means that an application running on the Android device can connect to a specified TCP port on the device, and that connection will be transparently redirected to a corresponding TCP port on the development host.

It's particularly useful in development scenarios where an app on the device needs to communicate with a server or service running locally on the developer's computer. For example, an app might try to connect to localhost:8080 on the device, and adb reverse can route this connection to localhost:8080 on the host, allowing the app to interact with a local backend server. The command supports TCP port mappings and can be cleared using the --remove or --remove-all options. This simplifies debugging and testing by eliminating the need to deploy local services to a publicly accessible IP address or expose them to the network.

CAVEATS

Only supports TCP port forwarding. The established tunnels are temporary and will be cleared if the adb connection is lost (e.g., device disconnects, or adb kill-server is executed). Ensure the specified ports are not already in use on both the device and host machine. Requires developer options and USB debugging enabled on the Android device.

COMMON USE CASES

adb reverse is invaluable for Android app development. Common scenarios include:
Connecting to a local backend server: An application on the device can access a server running on the developer's machine (e.g., Node.js, Python, Java backend) via localhost:<port> on the device, without needing a public IP or complex network setup.
Debugging: Facilitates communication with debugging tools or proxies running on the host.
Testing: Enables rigorous testing against local versions of APIs or services.

MANAGING MAPPINGS

It's good practice to manage your reverse port forwardings. You can view all active mappings using adb reverse --list. To clean up, use adb reverse --remove <device-port> for specific mappings or adb reverse --remove-all to clear all active reverse tunnels, especially after development sessions.

HISTORY

The adb reverse command was introduced in later versions of the Android SDK Platform-Tools, specifically to address the growing need for devices to connect back to development services running on the host machine. While adb forward existed earlier for host-to-device communication, adb reverse filled the critical gap for device-to-host connectivity, becoming an indispensable tool for mobile application developers using local backend servers, debuggers, or other host-based services.

SEE ALSO

adb(1), adb-forward(1), netstat(8), ss(8)

Copied to clipboard