System Architecture

Waydroid employs a sophisticated architecture that combines standard Linux technologies to run a full Android system efficiently within a container.

Waydroid Diagram

1. Host System Integration

Waydroid is not a virtual machine. It runs directly on the host's kernel, using several key Linux features to create an isolated environment:

  • Linux Namespaces: Waydroid uses namespaces (PID, network, mount, UTS, IPC, user) to give the Android system its own isolated view of the system's resources. This means Android has its own process tree, network stack, and mount points, separate from the host.
  • Cgroups: Control Groups are used to manage and limit the resources (CPU, memory, I/O) available to the Android container.

2. LXC Container Runtime

Waydroid uses LXC (Linux Containers) as its container runtime. LXC is responsible for setting up the namespaces and cgroups and managing the lifecycle of the container. The configuration for the Waydroid container is dynamically generated and can be found at /var/lib/waydroid/lxc/waydroid/.

3. The Android System

Inside the container, Waydroid runs a complete Android system based on LineageOS. This is not an emulation; it is a real Android system running on the Linux kernel. The system is composed of two main images:

  • system.img: The core Android operating system.
  • vendor.img: Contains hardware-specific drivers and libraries.

These images are downloaded during the waydroid init process.

4. Hardware Abstraction and Access

Waydroid's performance comes from its ability to grant the container direct access to hardware. This is achieved by bind-mounting device nodes from the host into the container's /dev directory.

  • Graphics: The GPU is passed through by mounting the host's DRM render nodes (e.g., /dev/dri/renderD128) into the container. Waydroid then uses Wayland to display application windows on the host desktop. See the Graphics and Display page for more details.
  • Binder IPC: Binder is the main Inter-Process Communication (IPC) mechanism in Android. Waydroid uses the binder_linux kernel module on the host to create binder device nodes (/dev/binder, /dev/vndbinder, /dev/hwbinder) which are then passed into the container, allowing Android processes to communicate efficiently.
  • Networking: A dedicated network bridge (waydroid0) is created on the host. The container gets a virtual Ethernet interface connected to this bridge, and iptables or nftables rules on the host provide Network Address Translation (NAT) for internet access.

5. System Services and Integration

Waydroid runs several services on the host to manage the container and integrate it with the desktop environment.

  • Systemd Service (waydroid-container.service): This is a system-level service responsible for launching and managing the container's lifecycle. It is controlled via D-Bus.
  • D-Bus: Waydroid exposes a D-Bus service (id.waydro.Container) on the system bus. The waydroid CLI tool and other components communicate with the container manager through this service.
  • Session Services: When a user runs waydroid session start, several user-level services are launched. These include managers for applications, clipboard integration, and hardware events. These services communicate with services inside the Android container via binder.