Introduction

Anbox and Waydroid have revolutionized Android development and testing on Linux, offering near-native performance for running Android applications in a containerized environment. While highly efficient for most use cases, one common challenge arises when advanced debugging or physical device interaction is required: direct USB passthrough. Unlike traditional virtual machines that offer straightforward USB device attachment, the containerized nature of Anbox/Waydroid (leveraging LXC, Binder, and Ashmem) complicates this process. This deep dive will explore how to achieve robust ADB over USB passthrough, enabling sophisticated debugging workflows for physical Android devices directly from your Anbox or Waydroid instance, focusing on the powerful usbip utility.

Understanding the Landscape: Anbox, Waydroid, and USB

Anbox and Waydroid are not hypervisors in the traditional sense. Instead, they provide a full Android system in a container by sharing the host Linux kernel. This approach offers significant performance benefits but also means that hardware access, particularly for USB devices, isn’t as direct as in KVM or VirtualBox. The Android environment inside Anbox/Waydroid operates on a network interface (often a bridge, e.g., anbox0 or waydroid0), making ADB over network a common and usually sufficient debugging method for standard app development.

ADB over Network: The Simpler Path (and its limitations)

For most application debugging, ADB over TCP/IP is the go-to solution. Once your Anbox or Waydroid instance is running, you can connect to it via its IP address:

adb connect <WAYDROID_IP>:5555

You can find the IP address typically by checking the network interface assigned to Waydroid (e.g., ip addr show waydroid0 on the host or in Waydroid’s settings). While convenient, this method only allows debugging of the virtualized Android instance itself. It does not provide a mechanism to debug a physical Android device connected to your host machine from within the Anbox/Waydroid environment. Scenarios like flashing custom ROMs, low-level kernel debugging, or interacting with devices that only expose certain functionalities via USB (e.g., fastboot mode, special diagnostic tools) necessitate true USB passthrough.

Prerequisites for USB Passthrough with usbip

To successfully implement USB passthrough using usbip, ensure you have the following:

• A running Anbox or Waydroid instance on a Linux host.
• Root access on your host machine.
• The usbip utilities installed on your host. On Debian/Ubuntu-based systems, install with:sudo apt updatesudo apt install usbip
• Kernel modules usbip_host, usbip_core, and vhci-hcd available and loadable on your host.
• Network connectivity between your host and the Anbox/Waydroid container.

Method: Deep Dive into USB Passthrough with usbip

usbip is a powerful tool that allows you to share USB devices over a network. It effectively creates a virtual USB device on a client machine (your Anbox/Waydroid instance) that mirrors a physical USB device connected to a server machine (your Linux host). This is precisely what we need to get our physical Android device recognized within the virtualized Android environment.

Step 1: Prepare the Host Machine (USBIP Server)

First, we need to make sure the necessary kernel modules are loaded and the usbip daemon is running.

Load Kernel Modules:

Ensure the host module for usbip is loaded:

sudo modprobe usbip_host

Start the usbipd Daemon:

The usbipd daemon runs in the background, making devices available for export.

sudo usbipd -D

This command detaches the daemon, running it in the background. You can verify it’s running with ps aux | grep usbipd.

Identify Your Android Device:

Connect your physical Android device to your host machine via USB. Then, list the available USB devices and identify its bus ID:

usbip list --local

The output will show a list of devices. Look for your Android device (e.g., a Google, Samsung, or specific OEM device). Note down its `BUSID`, which will look something like 1-1.2.

Example output snippet:

- busid 1-1.2 (04e8:6860)  <-- This is likely your Android device (Samsung in this case)

Bind and Export the Device:

Once you have the BUSID, bind it to the usbip_host driver and export it:

sudo usbip bind -b <BUSID>

Replace <BUSID> with the actual ID you identified (e.g., 1-1.2). After binding, you can verify it’s exported:

usbip list --exported

You should see your device listed as exported.

Step 2: Prepare the Anbox/Waydroid Instance (USBIP Client)

Now, we need to configure the Anbox/Waydroid container to act as a usbip client.

Load Kernel Modules within the Container:

You’ll need to load the client-side usbip modules. This step can be tricky as directly loading modules inside a Waydroid/Anbox container might require additional permissions or capabilities that are not enabled by default. Often, these modules need to be available and loadable on the host system, and the container needs to be configured to allow module loading or have these capabilities. For Waydroid, you might need to run the following on your host if the container can’t load them:

sudo modprobe usbip_coresudo modprobe vhci-hcd

If these modules are not present or loadable within the container, you might need to ensure your host’s kernel has usbip support compiled or as modules, and Waydroid’s LXC profile allows for module loading or devices access. In many cases, Waydroid/Anbox leverages the host kernel, so loading them on the host is sufficient.

Identify Host IP:

Determine the IP address of your host machine from the perspective of the Anbox/Waydroid container. This is typically the IP address of the bridge interface (e.g., anbox0 or waydroid0).

On the host machine, run:

ip addr show waydroid0

Look for the inet address. Let’s assume it’s 192.168.250.1.

Attach the Remote USB Device:

Now, from within the Anbox/Waydroid environment (you might need to use adb shell into the container first, or run this from a terminal app inside Android if you have one), attach the exported USB device from the host:

usbip attach -h <HOST_IP> -b <BUSID>

Replace <HOST_IP> with your host’s IP (e.g., 192.168.250.1) and <BUSID> with the same bus ID you used earlier (e.g., 1-1.2).

After successful attachment, you should see output similar to:

new usb device attached to usbip port <PORT_NUMBER>

Verify Device Recognition:

Inside the Anbox/Waydroid container, you can now check if the USB device is recognized:

lsusb

Your physical Android device should now appear in the list! At this point, you can start the ADB server within the container (if not already running) and expect your physical device to be recognized:

adb start-serveradb devices

Your physical Android device should appear in the adb devices list from within the Waydroid/Anbox container, allowing for direct debugging.

Troubleshooting Common Issues

• usbipd not running or accessible:

  Ensure sudo usbipd -D was run successfully and no firewall is blocking TCP port 3240 (the default usbip port) between the host and the container.

• Android Mobile Specs & Compare Directory

  Are you researching mobile hardware properties, processor SoCs, GPU chipsets, or RAM configurations? Access our complete specs catalog to compare up to 5 devices side-by-side!

  Compare Devices Specs →