Understanding Adb Architecture

Understanding ADB Architecture — Client, Server, Daemon

ADB is one binary that wears three hats. Most "adb is being weird" reports come from misunderstanding which hat is misbehaving (the local CLI, the long-lived host server on port 5037, or the on-device adbd), or from two different adb binaries fighting over the same port. This skill grounds the mental model so the rest of the ADB skill set has a stable foundation.

When to use this skill

• The user sees * daemon not running; starting now at tcp:5037 * and assumes it is an error.
• The user sees adb server version (XX) doesn't match this client (YY); killing... after Studio updates its bundled platform-tools.
• The user wants to enable verbose ADB logging (ADB_TRACE) or set up a CI runner with a preinstalled vendor key.
• The user asks why deleting ~/.android/adbkey breaks every other paired device.
• The user is debugging port 5037 collisions, multiple adb installs, or libusb-related transport failures on Linux.

When NOT to use this skill

• The user is troubleshooting a specific connected device (USB authorization, unauthorized, no permissions) — use ../../devices/connecting-to-devices/SKILL.md.
• The user is setting up wireless / Wi-Fi ADB — use ../../devices/connecting-over-wifi/SKILL.md.
• The user is running adb shell am instrument for tests — use ../../tests/running-instrumented-tests-via-adb/SKILL.md.

Prerequisites

• Android SDK Platform-Tools installed (path resolution rules below).
• Shell access to a workstation with adb on $PATH.
• For diagnostic flows: write access to $TMPDIR (macOS/Linux) or %TEMP% (Windows).

Workflow

• 1. Internalize the three-piece model. From developer.android.com/tools/adb (Overview):

  • Client (adb CLI) — invoked from the terminal. Serializes commands and ships them to the server over a local TCP socket.
  • Server (adb-server) — host-side background process. Multiplexes commands from many clients, tracks connected transports, forwards traffic to adbd. Binds TCP port 5037 on localhost by default.
  • Daemon (adbd) — runs on the device. Spawned by init on userdebug/eng builds, and by the system on user builds. Receives commands from the host server over USB or TCP and executes them in the device's userspace.

• 2. Recognize the implicit start-server print. The first adb command on a fresh shell emits:

  * daemon not running; starting now at tcp:5037
  * daemon started successfully

  This is informational, not an error — adb auto-starts the server when none is running. Skipping over this fact wastes hours of debugging.

• 3. Use the lifecycle commands surgically:

  Command	Effect
  adb start-server	Ensures a server is running on port 5037. If a compatible server is already running, it's a no-op (idempotent). If a different process is bound to 5037 (or an older incompatible adb server), start-server fails — see the port-collision pattern below.
  adb kill-server	Terminates the local server. The next adb command respawns it.
  adb reconnect	"Kick connection from host side to force reconnect." Useful for a stuck USB transport.
  adb reconnect device	"Kick connection from device side." Asks adbd to drop and re-handshake.
  adb reconnect offline	"Reset offline/unauthorized devices to force reconnect." Targets only the misbehaving transports.
  adb -P PORT ...	Override the server port (default 5037). Same as ANDROID_ADB_SERVER_PORT.

  Stuck-transport recovery recipe:

  adb reconnect offline
  # if that fails:
  adb kill-server && adb start-server && adb devices

• 4. Resolve the binary path explicitly. adb ships in Android SDK Platform-Tools (android_sdk/platform-tools/). Check what is actually loaded:

  adb --version
  which -a adb         # find shadowed copies

  Sample adb --version output decoded:

  Android Debug Bridge version 1.0.41         # wire-protocol version (stable for years)
  Version 35.0.2-12147458                      # platform-tools release + Google build number
  Installed as /opt/homebrew/bin/adb           # the actual file the OS resolved
  Running on Darwin 24.6.0 (arm64)

  The wire-protocol number is what matters for cross-compatibility: client and server must agree, or the first command kills the older server with adb server version (XX) doesn't match this client (YY); killing....

• 5. Pick ONE canonical adb when Android Studio is involved. Studio bundles and auto-updates its own platform-tools/. If a system / Homebrew adb is also on $PATH, three failure modes appear:

  1. Version skew — first command issued by either kills the running server.
  2. Two competing servers ping-ponging port 5037.
  3. Different default backends (libusb vs. native) producing inconsistent device enumeration. Resolution rule of thumb: export PATH="$ANDROID_HOME/platform-tools:$PATH" so CLI and Studio agree, then adb kill-server once.

• 6. Know the environment variables (verbatim, from adb help):

  Variable	Purpose
  ADB_TRACE	Comma/space-separated debug categories. Tokens: all,adb,sockets,packets,rwx,usb,sync,sysdeps,transport,jdwp,services,auth,fdevent,shell,incremental.
  ADB_VENDOR_KEYS	Colon-separated paths to RSA key files/dirs. Use on CI to skip the "Allow USB debugging?" prompt.
  ANDROID_SERIAL	Default device serial (equivalent to -s). Overridden by -s.
  ANDROID_ADB_SERVER_PORT	Override the server port (default 5037). Equivalent to -P PORT.
  ADB_LOCAL_TRANSPORT_MAX_PORT	Highest odd port scanned for emulators. Default 5585 (16 emulators).
  ADB_MDNS_AUTO_CONNECT	CSV of mDNS service types eligible for auto-connect. Default: adb-tls-connect.
  ADB_MDNS_OPENSCREEN	1/0. Force the Openscreen mDNS backend. Default Openscreen on Linux/Windows from ADB v34+ — the public doc lags.
  ADB_LIBUSB	1/0. Force the libusb USB backend.
  ADB_BURST_MODE	1/0. Pipeline packets without ACK. Experimental, ADB 36.0.0+.

  Diagnostic recipe with maximum verbosity:

  ADB_TRACE=all adb devices -l 2>~/adb-trace.log

  CI runner with a preinstalled key and custom port:

  export ADB_VENDOR_KEYS=/etc/adb/ci-key
  export ANDROID_ADB_SERVER_PORT=5038
  export ADB_LOCAL_TRANSPORT_MAX_PORT=5617
  adb start-server

• 7. Find the server log when something is wrong. The server keeps a persistent log distinct from per-command ADB_TRACE output and from logcat:

  OS	Path
  macOS	$TMPDIR/adb.$UID.log (e.g. /var/folders/.../T/adb.501.log)
  Linux	$TMPDIR/adb.$UID.log (e.g. /tmp/adb.1000.log)
  Windows	%TEMP%\adb.log
  Useful flow:

  adb kill-server
  ADB_TRACE=adb,transport,auth adb start-server
  adb devices -l
  ls -lh "$TMPDIR/adb.$UID.log"

• 8. Treat ~/.android/ as load-bearing. RSA keypair: ~/.android/adbkey (private), ~/.android/adbkey.pub (public). Generated on first adb invocation. Every accepted "Allow USB debugging?" dialog appends this public key to /data/misc/adb/adb_keys on the device. Wiping the local key invalidates every device the user previously authorized — see the WRONG/RIGHT pair below.

• 9. Accept the libusb v36 regression on Linux as background context. ADB v36.0.0 (Apr 2025) shipped a rewritten libusb backend with hot-plug. ADB v36.0.2 (Sep 2025) reverted libusb as the Linux default because of instability. CI runners pinned to specific platform-tools versions need to know which side of that revert they sit on; force the backend explicitly with ADB_LIBUSB=0 or =1 if reproducibility matters.