Bass: Submix - Quick Start Guide

Bass: Submix is a minimal Debian host that boots into a Wayland compositor and runs LineageOS / Android inside a Waydroid LXC container. This guide is the short path from a downloaded ISO to a working install - flash, install, connect Wi-Fi, and reach the device from your PC.

This document ships with public builds (SourceForge, FossHub, and mirrors). For architecture diagrams, the full override catalog, mapper apps, and developer docs, use the project repository:

https://github.com/Bliss-Bass/bass-submix

On-device Ax86Docs (when included in the image) opens the same guides from the Documentation section.

1. Flash the ISO to USB

Recommended: Balena Etcher - select the .iso, choose your USB drive, and click Flash!

Alternatives: Rufus (Windows), or dd on Linux/macOS:

sudo dd if=Bass-Submix-*.iso of=/dev/sdX bs=4M status=progress conv=fsync

Replace /dev/sdX with the correct disk device (not a partition). Unplug other removable drives first so you do not overwrite the wrong disk.

2. Boot from USB

1. Insert the USB drive and power on the target PC.
2. Enter the firmware boot menu (often F12, F2, or Esc - varies by manufacturer).
3. Select the USB drive under UEFI (preferred over Legacy/CSM when available).
4. The GRUB menu appears (about 10 seconds). Choose one of the entries below.

You can try Live first to confirm hardware compatibility, then reboot and use Control Panel to install.

3. Install to disk (Control Panel)

1. Boot Control Panel (Network & Settings) or Install Waydroid Linux (Graphical).
2. Open the Install OS tab (default on live USB).
3. Click Refresh Drives and select the target disk.
4. Choose ext4 (recommended) and a Data Type (Folder or data.img size).
5. For a clean single-disk setup, enable Auto-Partition Entire Drive (wipes the selected disk).
6. Click Erase & Install OS and confirm.
7. Wait for Installation Complete, then reboot and remove the USB drive.

On first boot from the installed disk, Waydroid initializes automatically and Android runs the setup wizard. Complete the wizard before configuring Wi-Fi.

Default host credentials

The waydroid user has passwordless sudo. Switch to a host TTY with Alt+F2 (etc.) while the compositor runs on the primary session. Change the password after deployment on any device that faces a network.

4. Connect to Wi-Fi (after setup wizard)

Stay in the normal Android session (the installed Waydroid entry - not Control Panel).

Important: open Ethernet Config before joining Wi-Fi. Network policy does not run correctly on first boot until that app has been launched once.

Step 1 - Open Ethernet Config (required first)

1. Open Ethernet Config from the app drawer.
2. Tap Refresh next to the interface dropdown.

You do not need to change settings yet - opening the app and refreshing interfaces is enough to prime the service.

Step 2 - Join Wi-Fi in Settings

1. Open Settings → Network & Internet → Internet.
2. Select your SSID, enter the password, and wait until Android reports Connected.

Step 3 - Verify routing in Ethernet Config

1. Tap Refresh if needed, then select wlan0:
   • IPv4 address on your LAN
   • Default route: Yes (needed for browser/DNS)
   • ADB connect: adb connect <ip>:5555
2. Select eth0. If it shows 192.168.240.x with Default route: Yes while Wi-Fi is connected, the Waydroid bridge is still winning over Wi-Fi.
3. On eth0, tap Apply prefer_wifi demote, or Disable Ethernet tracking / Management only (no Internet).
4. Select wlan0 again and confirm Default route: Yes.

Optional check from ADB:

adb shell ip route show default          # expect wlan0, not eth0
adb shell cmd ethernet get-interface-enabled eth0   # expect false when demoted

If Wi-Fi does not work in Android

5. Control Panel: host Wi-Fi and passthrough

Use this when Android has no wlan0, or when you need to configure networking from the host before the full session.

1. Reboot and select Control Panel (Network & Settings) from GRUB.
2. Click Refresh hardware, then Scan Wi-Fi; connect to your SSID.
3. Under Hardware & drivers, enable Passthrough → Android on the Wi-Fi interface. Equivalently, turn off Keep host network connection (pin virtual eth0) (see note below).
4. Expand Android network (Waydroid) and enable Prefer Wi-Fi in Android (androidboot.ax86_prefer_wifi) - recommended on Wi-Fi-only hardware.
5. Reboot a normal GRUB entry (not Control Panel).
6. Return to §4: open Ethernet Config first, then confirm Wi-Fi and routing.

Host connection (virtual eth0) is on by default. While on, Wi-Fi passthrough is disabled: the host keeps its own LAN IP and stays reachable over SSH (including multi-display MD-2 boots). Android still reaches the internet through bridged eth0 (NAT). Turn it off to hand the physical Wi-Fi NIC to Android; then reach the host via Android's Wi-Fi IP on port 8022.

Host TTY equivalents:

# Keep host network (virtual eth0 sticks - default):
echo wifi_passthrough=false | sudo tee /var/lib/waydroid/passthrough-devices.conf
# Hand Wi-Fi to Android (passthrough):
echo wifi_passthrough=auto  | sudo tee /var/lib/waydroid/passthrough-devices.conf

sudo waydroid-boot-option.sh ax86_prefer_wifi 1
sudo reboot

6. Prefer Wi-Fi (routing preference)

androidboot.ax86_prefer_wifi=1 tells Android to prefer Wi-Fi for Internet instead of the Waydroid management bridge eth0 (192.168.240.x). Without it, browsers may fail DNS and ADB may show the bridge address instead of your LAN IP.

• Control Panel / waydroid-boot-option.sh persist the flag across reboots.
• Ethernet Config → Apply prefer_wifi demote fixes routing immediately after you connect Wi-Fi.

Keep it enabled on typical Wi-Fi devices. Full policy details: OVERRIDES.md and VENDOR_DEPLOYMENT.md.

7. Connect from your PC (ADB and SSH)

Default credentials: user waydroid, password waydroid (change in production).

Find the Android Wi-Fi IP in Settings → Network & Internet, the Ethernet Config status panel, or:

waydroid shell ip -4 addr show wlan0

ADB

Enable Settings → Developer options → Wireless debugging (or ADB over network on port 5555). PC and device on the same LAN:

adb kill-server 2>/dev/null || true
adb start-server
adb connect 192.168.1.x:5555
adb devices -l
adb shell getprop ro.build.display.id

SSH (host)

# Passthrough mode (host via Android Wi-Fi address):
ssh waydroid@192.168.1.x -p 8022

# Control Panel / host LAN:
ssh waydroid@192.168.1.x

Useful after SSH:

systemctl status waydroid-container waydroid-session
waydroid status

On the device keyboard (no network): log in as waydroid on a TTY, then use waydroid shell / waydroid adb.

More detail: VENDOR_DEPLOYMENT.md §2.

8. Next steps (full documentation)

Once the OS is installed and online:

9. Custom Builds & Services

Bass: Submix covers a broad range of x86 deployments out of the box. If you need a tailored image for a specific device, industry, or workflow - hardware bring-up, custom launcher/UI, kiosk or restricted modes, multi-display layouts, OTA/update infrastructure, or ongoing production support - Navotpala Tech can help.

View customization services - custom OS development, application & framework work, build/OTA hosting, and end-to-end solution delivery.

Typical engagements include:

• Bass / Submix custom builds and hardware-specific optimizations
• System apps, frameworks, and device-management integrations
• Security hardening, multi-architecture support, and fleet provisioning
• Professional support, consultation, and enterprise partnership options

Ready to talk about your use case? Start from the services page above, or open a conversation at navotpala.tech.

Links

• Project & docs: https://github.com/Bliss-Bass/bass-submix
• Customization services: https://navotpala.tech/services
• Navotpala Tech: https://navotpala.tech/