ADB Setup & Architecture Guide

ADB can be frustrating when setting up custom configurations. Since it’s a private tool, aside from official documentation and scattered online discussions, resources are limited.

This guide explains what ADB is, how it works, and how to integrate it into different development environments, including Docker-based workflows. While there are different ways to bridge ADB (e.g. host, hybrid, or containerized), the connection process is always the same: authorize via USB, optionally switch to wireless.

---

What is ADB?

ADB (Android Debug Bridge) is a command-line tool that allows you to communicate with an Android device from your computer. It’s commonly used for:

• Debugging apps
• Installing APKs
• Transferring files
• Running shell commands on the device

---

ADB Architecture

ADB uses a client-server model with 3 main components:

• ADB Client – Runs on your machine and sends commands.
• ADB Server – A background service on your machine that manages connections (default port 5037).
• ADB Daemon (adbd) – Runs on the Android device, executing the commands it receives.

For wireless ADB, the daemon listens on port 5555. Never change port 5037 on the host, unless you have a very specific reason; it’s the expected standard.

---

Enabling ADB on Your Android Device

Before anything else, you must enable Developer access and USB Debugging:

1. Go to Settings on your Android device.
2. Navigate to About phone → Tap Build number 7 times.
3. Go back and open Developer Options.
4. Enable USB Debugging.

---

ADB Connection Process (Always the Same)

No matter which environment you’re working in, the ADB connection flow always follows these steps:

Step 1: USB Authorization

1. Connect your device via USB.
2. On your host (or container if bridged), run:

adb devices

1. Tap Allow on your device when prompted.

USB is always required the first time. Wireless debugging will not work until your device trusts the host (or the bridged container).

Why You Might Need to Reconnect via USB Later

Even after setting up wireless ADB, you might need to reconnect your device via USB again in these cases:

• You manually revoked USB debugging authorizations on your device.
• A system update resets Developer Options, disabling USB debugging and clearing trusted computers.

---

Step 2: Switch to Wireless (Optional)

Once authorized via USB, you can use ADB over Wi-Fi:

1. Ensure both your device and computer are on the same network.
2. On your machine, run:

adb tcpip 5555

1. Find your device’s IP address (Settings → About phone → Status information → IP address).
2. Connect wirelessly:

adb connect <device-ip>:5555

1. Confirm connection:

adb devices

---

Bridging ADB in Custom Environments

These aren’t separate “setups”, they are different bridging methods to access your Android device using the same ADB process.

---

Method 1: ADB on Host (Simple & Direct)

• ADB client and server both run on your host machine.
• Device is connected via USB or wireless.
• No containerization involved.

Easiest and most common setup.

---

Method 2: Host ADB Server + Docker ADB Client (Hybrid)

• ADB Server runs on your host
• ADB Client runs in Docker (for tools/scripts inside containers)

Useful when you:

• Need ADB commands inside a dev container
• Want to avoid installing full Android tools inside the host system

Learn more: Docker + Host ADB Integration

---

Method 3: ADB Server and Client Inside Docker (Isolated)

• Fully containerized ADB
• Both server and client live in the same Docker container
• Works with USB and wireless
• Best for CI/CD pipelines, isolated dev environments, or when avoiding host dependencies

Vagrant + Docker Configuration Example

docker.create_args = [
  "--device=/dev/bus/usb/:/dev/bus/usb/"
]
docker.volumes = [
  "/dev/bus/usb/:/dev/bus/usb"
]

config.vm.network "forwarded_port", guest: 5037, host: 5037

This allows:

• USB access inside the container
• Port 5037 forwarding for the ADB server

---

Raw Docker Setup (No Vagrant)

docker run --rm -it \
  --device=/dev/bus/usb/:/dev/bus/usb/ \
  -v /dev/bus/usb/:/dev/bus/usb \
  -p 5037:5037 \
  <your-docker-image>

Explanation:

Flag	Purpose
--rm	Auto-remove the container on exit
-it	Interactive terminal session
--device	Grants USB access to container
-v	Mounts the USB bus device folder
-p 5037:5037	Forwards ADB server port

---

Final Notes

Setup Method	USB Access	ADB Server Location	Wireless ADB	Best For
Host Direct	Yes	Host	Yes	Local development
Hybrid (Docker CLI)	Yes (host)	Host	Yes	Tooling in containers
Full Docker	Yes (bridged)	Inside container	Yes	CI/CD, isolation