Connecting Over Wifi

Connecting Over Wi-Fi — adb pair (Modern) and adb tcpip (Legacy)

Android 11 introduced a paired wireless debugging flow that replaces the legacy adb tcpip dance. The modern path encrypts and authenticates over TLS using a pairing-code-derived shared secret and uses ephemeral ports; the legacy path leaves an unauthenticated TCP listener on a well-known port. This skill covers both, plus the mDNS plumbing the host server uses to discover paired devices.

When to use this skill

• The user wants to connect a phone to ADB without a USB cable.
• The user mentions adb pair, QR-code pairing, the "Wireless debugging" toggle in Developer options, or pairing codes.
• The user copies adb tcpip 5555 && adb connect 192.168.1.100:5555 from an old blog and asks why a modern phone treats that as insecure.
• The user sees connection refused after pairing and is on a corporate Wi-Fi.
• The user sees mDNS Bonjour vs Openscreen confusion in adb mdns check.

When NOT to use this skill

• The user wants USB device basics (selector flags, RSA dialog, udev rules) — use ../connecting-to-devices/SKILL.md.
• The user wants the architecture / env-var cheat sheet — use ../../architecture/understanding-adb-architecture/SKILL.md.
• The user wants to run a test on the wirelessly connected device — use ../../tests/running-instrumented-tests-via-adb/SKILL.md.

Prerequisites

• Workstation and device on the same Wi-Fi network. Corporate networks frequently block p2p — see step 6.
• Phones / tablets: Android 11 (API 30)+. TV / Wear OS: Android 13 (API 33)+.
• Working ADB server (see ../../architecture/understanding-adb-architecture/SKILL.md).
• Wireless debugging enabled on-device: Settings → System → Developer options → Wireless debugging.

Workflow

• 1. Prefer the modern adb pair flow on Android 11+. From developer.android.com/tools/adb#wireless:

  "Android 11 (API level 30) and higher support deploying and debugging your app wirelessly from your workstation using Android Debug Bridge (adb). For example, you can deploy your debuggable app to multiple remote devices without ever needing to physically connect your device via USB."

  User flow with a pairing code:

  1. On the device, open Settings → Developer options → Wireless debugging and toggle it on.
  2. Tap Pair device with pairing code. The device shows an IP:PORT and a six-digit pairing code.
  3. On the workstation:

     adb pair 192.168.1.42:42999
     # Enter pairing code: 123456
     # Successfully paired to 192.168.1.42:42999 [guid=adb-...-RQAZWM]

  QR-code pairing is the same protocol, driven by Android Studio's "Pair Devices Using Wi-Fi" UI.

• 2. Connect to the separate debug port shown after pairing. The pairing port is one-shot; the device exposes a different IP:PORT for actual debugging:

  adb connect 192.168.1.42:39555
  adb devices
  # 192.168.1.42:39555  device

  adb disconnect [<host:port>] drops a single host or, with no argument, all TCP devices.

• 3. Use mDNS auto-discovery for hands-off connections. The ADB server can discover paired devices and auto-connect:

  adb mdns check
  # mdns daemon version [openscreen discovery 0.0.0]
  
  adb mdns services
  # List of discovered mdns services
  # adb-XXXXXXXX-RQAZWM   _adb-tls-pairing._tcp  192.168.1.42:42999
  # adb-XXXXXXXX-RQAZWM   _adb-tls-connect._tcp  192.168.1.42:39555

  Service types:

  • _adb._tcp — legacy adb tcpip.
  • _adb-tls-pairing._tcp — the ephemeral pairing port (after tapping "Pair device with pairing code").
  • _adb-tls-connect._tcp — the post-pairing debug port. By default these are auto-connected (ADB_MDNS_AUTO_CONNECT=adb-tls-connect).

• 4. Know which mDNS backend is in use. The doc says Bonjour is the default, but from ADB v34+ the default flipped to Openscreen on Linux/Windows (the public doc lags). Force a backend explicitly with the env var when reproducibility matters:

  ADB_MDNS_OPENSCREEN=1 adb start-server     # force Openscreen
  ADB_MDNS_OPENSCREEN=0 adb start-server     # force Bonjour

  See ../../architecture/understanding-adb-architecture/SKILL.md for the full env-var table (ADB_MDNS_AUTO_CONNECT, ADB_MDNS_OPENSCREEN).

• 5. Use the legacy adb tcpip path only when pairing is not available. Pre-Android-11 (and still supported on 11+ as a fallback):

  # 1. USB-attach the device, accept the RSA dialog, confirm with `adb devices`.
  adb tcpip 5555
  # 2. Unplug USB.
  adb connect 192.168.1.42:5555

  Why it is the legacy path:

  • Requires physical USB to bootstrap, defeating the "no cable" appeal.
  • 5555 is well-known and exposed without any pairing — anyone on the LAN can reach it until reboot.
  • The device drops back to USB-only on reboot (adb usb resets it manually).
  • No mDNS auto-discovery; the user must know the IP.

  The modern adb pair flow encrypts and authenticates over TLS using a pairing-code-derived shared secret, and uses ephemeral ports — much safer.

• 6. Diagnose pairing/connection failures in this order:

  "Device not connecting after pairing successfully: adb relies on mDNS to discover and automatically connect to paired devices. If your network or device configuration does not support mDNS or has disabled it, then you need to manually connect to the device using adb connect ip:port."

  1. Same Wi-Fi? Confirm both ends are on the same SSID and the same VLAN/subnet.
  2. Corporate Wi-Fi? Verbatim:

     "Secure Wi-Fi networks, such as corporate Wi-Fi networks, may block p2p connections and not let you connect over Wi-Fi. Try connecting with a cable or another (non-corp) Wi-Fi network."

  3. mDNS disabled? Run adb mdns check. If "mDNS is not running", fall back to manual adb connect <ip:port> using the connect-port from the device's Wireless debugging screen.
  4. connection refused after adb connect? Wireless debugging port closed (toggled off, device rebooted, or pairing port used instead of the connect port). Re-enable wireless debugging; re-pair if needed; copy the _adb-tls-connect._tcp port from adb mdns services.
  5. Auto-disconnect after Wi-Fi switch? Verbatim:

     "adb over Wi-Fi sometimes turns off automatically: This can happen if the device either switches Wi-Fi networks or disconnects from the network. To resolve, re-connect to the network."

• 7. Treat wireless ADB as a "trust the LAN" feature.

  • Anyone with network reach plus the pairing code can pair.
  • Once paired, only the cryptographic key gates access — but a flat office LAN means the attack surface is everyone-on-the-Wi-Fi.
  • Disable wireless debugging when not actively using it. The Settings toggle kills the listening sockets immediately.
  • Avoid wireless ADB on public / café / hotel Wi-Fi entirely.
  • The legacy adb tcpip mode is a flat unauthenticated TCP listener — prefer adb pair whenever the device supports it.