How mayukh4/linux-android works
1. Repository purpose
This repo is an installer/orchestration toolkit for turning one Android phone into two possible runtime targets: a Linux desktop or a Home Assistant smart-home server. It is not an app with a long-running internal service graph; the core architecture is a set of shell scripts that provision and launch software inside the Termux environment.
2. Top-level entrypoints
The architecture centers on two scripts:
- termux-linux-setup.sh for the desktop path
- setup-homeassistant.sh for the Home Assistant path
The README treats these as the primary boundaries between “install/provision” and “run/use.”
3. Desktop subsystem
The Linux desktop path installs and configures a GUI stack on Android through Termux + Termux-X11. The desktop environment is selectable at install time: XFCE4, LXQt, MATE, or KDE Plasma. This path is aimed at interactive local use, with a phone acting as the host and Termux-X11 acting as the display surface.
4. Graphics and hardware acceleration boundary
A major subsystem in the desktop setup is GPU detection and graphics backend selection. The script chooses between:
- Qualcomm/Adreno: Turnip Vulkan + Zink
- Other GPUs: fallback software-oriented rendering
The GPU configuration is persisted in ~/.config/linux-gpu.sh and is sourced during desktop startup. This is an important runtime boundary because it affects rendering performance but is isolated from the rest of the provisioning flow.
5. Desktop runtime lifecycle
The desktop path creates separate start/stop controls:
- ~/start-linux.sh
- ~/stop-linux.sh
The runtime is launched inside Termux, but the visible GUI appears only in the Termux-X11 app, which is effectively the display client. This splits control into a command-line launcher and a separate Android UI surface.
6. Desktop application stack
The installed desktop environment is bundled with a practical userland: Firefox, VLC, Python 3/pip, Git, curl/wget, SSH, PulseAudio, and optional Wine. This makes the phone behave like a lightweight workstation rather than just a graphical shell. Wine is explicitly optional and depends on the desktop being active.
7. Remote access subsystem
SSH is treated as a separate access channel to the phone. The repo configures OpenSSH in Termux so the device can be managed from another machine on the same Wi‑Fi network using port 8022. This provides a second control plane alongside the local desktop/X11 route and is useful for file transfer and development workflows.
8. Smart-home subsystem
The Home Assistant path installs Home Assistant Core inside a lightweight Ubuntu container via proot-distro. This is a distinct runtime boundary from the desktop path: instead of a GUI session, it creates a local automation server process running in a containerized userland on Android.
9. Home Assistant runtime lifecycle
Home Assistant is launched with:
- ~/start-homeassistant.sh
- ~/stop-homeassistant.sh
Startup is typically backgrounded with nohup, and termux-wake-lock is used to keep Android from suspending the process. This path is designed for 24/7 service behavior, usually while the phone is plugged in and connected to Wi‑Fi.
10. Home Assistant data flow and access
The Home Assistant server listens on port 8123 and is accessed from any browser on the same network via http://<phone-ip>:8123. Device integrations flow from the browser UI into HA Core. Local IP-based devices and cloud-backed integrations both terminate in HA, but the repo emphasizes that setup is mostly manual because Android limits auto-discovery.
11. Integration constraints
The README calls out the practical boundaries of running HA on Android:
- no Bluetooth access
- no USB Zigbee/Z-Wave dongles
- no mDNS/zeroconf auto-discovery
- no Docker/add-ons, only HA Core
These constraints define the architecture: it is a network-first, software-only Home Assistant host, not a full HA OS appliance.
12. Logging, resilience, and installer safety
The scripts are designed to be recoverable on flaky mobile hardware. Installation logs are written to ~/termux-setup.log, and the README describes a conflict-aware package installation strategy that avoids Termux package conflicts. This suggests the scripts are built to handle heterogeneous preinstalled Termux states rather than assuming a clean machine.
13. Examples and documentation
The examples/ directory is small and illustrative, with examples/hello_server.py and its README. It functions as a usage example rather than a separate subsystem, reinforcing that the repo is mostly about provisioning environments on the phone rather than shipping an application framework.
14. External dependencies that matter architecturally
The architecture depends on a few external layers:
- Android + Termux as the base runtime
- Termux-X11 for GUI display
- proot-distro for the Ubuntu-based Home Assistant container
- Wi‑Fi LAN for SSH and Home Assistant access
- optional Tuya/Home Assistant cloud APIs for devices that cannot be discovered locally
These external layers define the main boundaries for any diagram: Android host, Termux runtime, GUI/display client, containerized HA runtime, and LAN/cloud integrations.
Main entry points: termux-linux-setup.sh Linux setup · README.md README · setup-homeassistant.sh HA setup · examples/README.md Examples
Components 22
Android host
Base device and Termux runtime environment
- Android · Host operating system and device layer
- Termux · Command-line runtime used to install and launch both targets
- Wi‑Fi LAN · Local network used for SSH and Home Assistant access
- Termux-X11 · Android display surface for the Linux desktop GUI
- proot-distro · Userland container mechanism for Ubuntu and Home Assistant
Desktop path
Termux-based Linux desktop installer and launcher
- Linux setup · Provisions the Linux desktop environment in Termux
termux-linux-setup.sh - GPU config · Persisted graphics backend selection for desktop startup
- Start Linux · Starts the desktop session inside Termux
- Stop Linux · Stops the desktop session
- Desktop env · XFCE4, LXQt, MATE, or KDE Plasma desktop session
- Graphics backend · Adreno Turnip Vulkan + Zink or software fallback
- Desktop apps · Firefox, VLC, Python, Git, curl/wget, SSH, PulseAudio, optional Wine
- SSH access · OpenSSH service exposed on port 8022
Home Assistant path
Containerized Home Assistant Core runtime on Android
- HA setup · Provisions Home Assistant Core in an Ubuntu container
setup-homeassistant.sh - Ubuntu userland · Lightweight proot-based Linux environment
- HA Core · Home Assistant Core runtime
- Start HA · Starts Home Assistant in the container
- Stop HA · Stops the Home Assistant service
- Wake lock · Prevents Android suspension during long-running HA operation
Docs and examples
Usage guidance and illustrative sample code
- README · Primary architecture and usage reference
README.md - Examples · Illustrative example material
examples/README.md - Hello server · Small Python example under examples/
examples/hello_server.py
Connections 25
- Android → Termux: hosts · Android provides the base runtime for Termux
- Termux → Linux setup: runs · Desktop installation begins in Termux
- Termux → HA setup: runs · Home Assistant installation begins in Termux
- Linux setup → Desktop env: installs · Sets up one of the supported desktop environments
- Linux setup → Graphics backend: configures · Detects GPU and selects a rendering backend
- Graphics backend → GPU config: persists · Writes GPU choice into the desktop config file
- Linux setup → SSH access: enables · Configures OpenSSH for remote access
- Start Linux → GPU config: sources · Loads persisted graphics settings at startup
- Start Linux → Desktop env: launches · Starts the selected GUI session
- Desktop env → Termux-X11: renders to · GUI is shown through Termux-X11
- Desktop env → Desktop apps: bundles · Desktop session includes workstation apps
- Desktop apps → SSH access: uses · SSH is one of the included management tools
- SSH access → Wi‑Fi LAN: reachable via · Port 8022 is exposed on the local network
- Stop Linux → Desktop env: stops · Terminates the desktop session
- HA setup → proot-distro: uses · Builds the runtime on proot-distro
- proot-distro → Ubuntu userland: provides · Creates the Ubuntu userland container
- Ubuntu userland → HA Core: runs · Home Assistant Core executes inside Ubuntu
- Start HA → Wake lock: keeps awake · Prevents Android from sleeping during service operation
- Start HA → HA Core: launches · Starts the Home Assistant service
- HA Core → Wi‑Fi LAN: served on · Web UI is accessed from the local network
- Stop HA → HA Core: stops · Terminates the Home Assistant service
- README → Linux setup: documents · README explains the desktop installer
- README → HA setup: documents · README explains the Home Assistant installer
- README → Examples: references · README points to example material
- Examples → Hello server: contains · Example directory includes a sample server script