Configuration

Waydroid's behavior can be customized through its main configuration file and the underlying LXC configuration. Most users will not need to change these settings.

Main Configuration File

The primary configuration file is located at /var/lib/waydroid/waydroid.cfg. This file is in INI format and is managed by the waydroid init and waydroid upgrade commands.

Example waydroid.cfg structure:

[waydroid]
arch = x86_64
images_path = /var/lib/waydroid/images
vendor_type = MAINLINE
system_datetime = 1675873993
vendor_datetime = 1675873993
suspend_action = freeze
mount_overlays = True
auto_adb = False
binder = binder
vndbinder = vndbinder
hwbinder = hwbinder

[properties]
# You can add Android property overrides here
# e.g.:
# persist.waydroid.multi_windows = true

[waydroid] Section

  • arch: The system architecture (e.g., x86_64, arm64).
  • images_path: Path to the directory containing system.img and vendor.img.
  • vendor_type: The type of vendor image, typically MAINLINE or HALIUM_*.
  • system_datetime, vendor_datetime: Timestamps of the installed images, used for upgrades.
  • suspend_action: What to do on suspend command. Can be freeze (default) or stop.
  • mount_overlays: Whether to use OverlayFS for a writable system partition (default: True).
  • auto_adb: Whether to automatically connect ADB on session start (default: False).
  • binder, vndbinder, hwbinder: The names of the binder device nodes to use.
  • drm_device: Optionally specifies a DRM device node (e.g., /dev/dri/renderD129) to use, overriding the automatic detection.

[properties] Section

This section allows you to override Android system properties. Any key-value pair added here will be set in the container's build.prop at runtime.

Networking Configuration

Waydroid's network is configured by the script /usr/lib/waydroid/data/scripts/waydroid-net.sh. This script creates a bridge interface named waydroid0 and sets up network address translation (NAT) to allow the container to access the internet.

Key network properties:

  • Bridge Interface: waydroid0
  • Host IP on Bridge: 192.168.240.1
  • Container Network: 192.168.240.0/24

By default, this script uses iptables. You can switch to nftables by setting USE_NFTABLES=1 during installation via the Makefile.

LXC Configuration

The raw LXC configuration is generated dynamically and stored in /var/lib/waydroid/lxc/waydroid/. The main file is config.

This configuration is built from several templates located in the source at data/configs/:

  • config_base: Contains the core LXC settings, such as rootfs path, architecture, and capabilities to keep.
  • config_1, config_3, config_4: Version-specific LXC configuration options.
  • config_nodes: Dynamically generated file that defines all device nodes and mounts to be passed into the container.
  • config_session: Dynamically generated file for session-specific mounts, like the Wayland socket.

Advanced users can inspect these files to understand the low-level container setup.