Introduction

Waydroid provides a lightweight and performant way to run a full Android system in a Linux container (LXC) on your desktop. It’s a fantastic tool for developers, testers, and power users who need Android apps or a full Android environment without the overhead of traditional virtual machines. While Waydroid excels at running apps, integrating it seamlessly with external hardware, especially USB devices for debugging purposes, can pose a unique challenge.

This article provides an expert-level, step-by-step guide on how to effectively “pass through” a physical USB Android device to your Waydroid container for ADB (Android Debug Bridge) debugging. We’ll explore why direct USB device passthrough to an LXC container isn’t always straightforward and present the most practical and reliable method for achieving ADB connectivity from within Waydroid to an external physical device.

Prerequisites

• A Linux host system with Waydroid installed and running.
• ADB tools installed on your Linux host (sudo apt install adb or equivalent).
• A physical Android device with Developer Options enabled and USB Debugging turned on.
• Basic familiarity with the Linux command line and networking concepts.

Understanding the Waydroid Container Environment

Waydroid leverages Linux Containers (LXC), which provide a level of isolation between the host system and the containerized Android environment. Unlike full virtualization solutions (e.g., KVM/QEMU, VirtualBox) that emulate hardware and allow for direct USB device passthrough at a virtual machine level, LXC containers share the host kernel. This means they are more lightweight but also more tightly integrated with the host’s system, albeit within their own namespaces for processes, network, and filesystems.

This isolation, while beneficial for security and resource management, typically means that USB devices connected to the host are not automatically available inside the Waydroid container’s /dev/bus/usb directory. Attempts to directly pass through raw USB device nodes (`/dev/bus/usb/xxx/yyy`) to an LXC container using `lxc.cgroup.devices.allow` rules can be complex, often brittle, and don’t elegantly handle hot-plugging or dynamic device enumeration, especially when the goal is specifically for ADB functionality.

Why Direct USB Device Passthrough to LXC is Tricky for ADB

ADB operates on a client-server model. The `adbd` daemon runs on the Android device (the server), and `adb` clients (like your development machine) connect to it. While ADB primarily communicates over USB when a device is physically connected, it can also operate over TCP/IP.

For Waydroid to connect to a physical Android device via ADB, Waydroid needs to act as an ADB client. Since direct USB device node passthrough is cumbersome and unreliable for dynamic devices in LXC, and ADB has a robust TCP/IP mode, leveraging the network is the most effective and stable