A rootless Android app that boots Alpine Linux: run containers (Podman/Docker/LXC) and GUI desktop apps.
docs: rewrite README, CONTRIBUTING, CREDITS for 1.1.6
ExTv38ff5e867543
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.mdindex 9cfb646..feccecf 100644--- a/.github/ISSUE_TEMPLATE/bug_report.md+++ b/.github/ISSUE_TEMPLATE/bug_report.md@@ -22,10 +22,9 @@ What you expected to happen.What actually happened instead.## Diagnostic Log-**Required** — Attach the log export from:-`Settings → Diagnostics → Export Log`+**Required.** Attach the log export from `Settings → Diagnostics → Export Log`.-This already includes: app version, device info (model/Android), settings, and full logcat.+The export already includes: app version, device info (model / Android version), settings, and full logcat.## Reproduction SampleIf this is about the VM, include terminal output from running:diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 224fd5e..d994055 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -1,57 +1,99 @@# Contributing to Podroid-Contributions are welcome! Whether it's a bug report, feature idea, or code change — all help is appreciated.+Thanks for considering a contribution. Bug reports, feature requests, and pull requests are all welcome.-## Getting Started+Before you start, please skim [`skill.md`](skill.md). It documents the boot pipeline, every native binary, and the design quirks you need to know to make changes that don't regress.-1. Clone the repo:- ```sh- git clone https://github.com/ExTV/Podroid.git- cd Podroid- ```+## Getting started-2. Build the initramfs (requires Docker with multi-arch support):- ```sh- ./docker-build-initramfs.sh- ```+```sh+git clone https://github.com/ExTV/Podroid.git+cd Podroid+```-3. Open in Android Studio and build, or from the command line:- ```sh- ./gradlew assembleDebug- adb install -r app/build/outputs/apk/debug/app-debug.apk- ```+You will need:-You need an **arm64 Android device** running **Android 14+** to test.+- **Docker 20.10+** for the kernel, initramfs, rootfs, and QEMU build pipelines+- **Android NDK r27c** for the bridge and Termux native libraries+- **Android SDK** with platform 36 + build-tools+- An **arm64 Android device** running **Android 9.0+ (API 28)** for testing-## Reporting Bugs+## Build pipeline-Open an [issue](https://github.com/ExTV/Podroid/issues) with:-- Steps to reproduce-- What you expected vs what happened-- Device model and Android version-- Relevant logcat output (`adb logcat --pid=$(adb shell pidof com.excp.podroid.debug)`)+`build-all.sh` orchestrates every component:-## Submitting Changes+```sh+./build-all.sh kernel # custom Linux 6.6.87 (~5–10 min, Docker-cached)+./build-all.sh initramfs # kernel + minimal initramfs+./build-all.sh rootfs # Alpine 3.23 squashfs (~30 s, Docker-cached)+./build-all.sh qemu # QEMU 11 + podroid-bridge (~30 min first run)+./build-all.sh termux # libtermux.so via local NDK+./gradlew installDebug # build + install the APK+```-1. Fork the repo and create a branch (`fix/your-bug` or `feature/your-feature`)-2. Keep PRs focused — one fix or feature per PR-3. Test on a real device before submitting-4. Update the README if your change affects user-facing behavior+Or, for the common case where you only changed Kotlin / UI code:-## Project Structure+```sh+./gradlew installDebug+```-- `init-podroid` — VM init script (Alpine Linux boot, overlay setup, getty)-- `Dockerfile` / `docker-build-initramfs.sh` — initramfs build pipeline-- `app/src/main/java/com/excp/podroid/engine/` — QEMU lifecycle, QMP client, VM state-- `app/src/main/java/com/excp/podroid/service/` — Android foreground service-- `app/src/main/java/com/excp/podroid/ui/` — Jetpack Compose UI (Home, Terminal, Settings)-- `app/src/main/jniLibs/` — Pre-built QEMU and libslirp binaries+To validate a full rebuild end-to-end:-## Code Style+```sh+./build-all.sh test # deploys APK, polls console.log for "Ready!"+```-- Follow standard [Kotlin conventions](https://kotlinlang.org/docs/coding-conventions.html)-- Keep it simple — no unnecessary abstractions or premature optimization-- Match the existing style of the file you're editing+## Reporting bugs++Please open an issue using the **Bug Report** template. The most useful single thing you can attach is the diagnostic log:++`Settings → Diagnostics → Export Log`++It bundles app version, device model + Android version, settings, and full logcat in one file. If the bug is VM-side, also include the VM console:++```sh+adb shell run-as com.excp.podroid.debug cat files/console.log+```++## Submitting changes++1. Fork the repository and create a topic branch (`fix/issue-42`, `feature/whatever`).+2. Keep pull requests focused: one fix or one feature per PR.+3. Test on a real arm64 device before submitting. Emulators do not exercise the QEMU + native binary path the way real hardware does.+4. If your change is user-facing, update [`README.md`](README.md). If it changes the boot pipeline, terminal layer, or kernel options, update [`skill.md`](skill.md) and [`CLAUDE.md`](CLAUDE.md) too.+5. Match the existing code style of the file you are editing.++## Project layout++```+Podroid/+├── app/ Android application (Jetpack Compose, Hilt)+│ └── src/main/+│ ├── java/com/excp/podroid/+│ │ ├── engine/ PodroidQemu, QmpClient, VmState+│ │ ├── service/ Foreground service + boot-stage notification+│ │ ├── data/repository/ DataStore-backed settings & port forwards+│ │ └── ui/ Compose screens + theme+│ ├── jniLibs/arm64-v8a/ QEMU, podroid-bridge, libslirp, libtermux+│ └── assets/ kernel, initramfs, squashfs, fonts, themes+├── init-podroid Minimal initramfs script (~45 lines)+├── podroid-bridge.c Native PTY ↔ virtio-console relay+├── Dockerfile Kernel + initramfs + QEMU build pipeline+├── build-rootfs/ Alpine squashfs build pipeline+│ ├── Dockerfile.rootfs+│ ├── build-rootfs.sh+│ └── files/ OpenRC services baked into the squashfs+├── build-all.sh Unified build / deploy script+├── podroid_kernel.config Custom kernel Kconfig fragment+└── docs/ GitHub Pages site+```++## Code style++- Kotlin: follow the [official conventions](https://kotlinlang.org/docs/coding-conventions.html).+- Keep it simple. No premature abstractions.+- Match the surrounding file's style. Consistency beats personal preference.+- Comments explain *why*, not *what*. Self-documenting names go further than prose.## Licensediff --git a/CREDITS.md b/CREDITS.mdindex e71d337..421fefb 100644--- a/CREDITS.md+++ b/CREDITS.md@@ -1,117 +1,144 @@# Credits & Acknowledgements-Podroid is built upon the work of many talented open source developers and communities.-We are deeply grateful to everyone listed here.+Podroid stands on the shoulders of an enormous amount of open-source work. The list below covers the upstream projects whose code, designs, fonts, or themes are shipped inside the APK, along with the major Android-side dependencies. Every component remains under its own upstream license; see [LICENSE](LICENSE) for Podroid's own license (GPL v2.0).++If something you maintain is included here and we missed you, please open an issue or a pull request and we will fix it.----## Core Engine: QEMU+## Virtual machine stack-**QEMU** is the heart of Podroid. It provides the machine emulation and virtualization.+These projects make up the actual Linux system that runs inside Podroid.-- **Original Author:** Fabrice Bellard-- **Website:** https://www.qemu.org-- **Repository:** https://gitlab.com/qemu-project/qemu-- **License:** GNU General Public License v2.0 (and later)-- **Copyright:** The QEMU Project developers+### Linux kernel+Podroid ships a custom build of the upstream Linux kernel (currently 6.6.87) configured specifically for OCI-compatible containers under QEMU TCG.-Notable QEMU contributors whose work this project relies on:-- Fabrice Bellard — original author-- The QEMU community — https://www.qemu.org/contributors/+- Project: https://kernel.org+- License: GNU General Public License v2.0+- Maintainers: Linus Torvalds and the Linux kernel community----+### Alpine Linux+The guest userspace is a slightly customized Alpine Linux 3.23 root filesystem.++- Project: https://alpinelinux.org+- License: per-package (see Alpine's individual package licenses)-## Android Integration Foundation: Limbo PC Emulator+### Container runtime+The full rootless OCI stack ships pre-installed and pre-configured.-**Limbo** pioneered running QEMU on Android and solved countless platform-specific challenges-that Podroid builds upon. Much of the JNI layer, SDL integration, and Android lifecycle-management in this project is derived from Limbo's work.+| Component | Role | Project |+| --------------- | ---------------------------------------- | ---------------------------------------------------- |+| **Podman** | Daemonless container engine | https://podman.io |+| **crun** | Fast, low-memory OCI runtime | https://github.com/containers/crun |+| **netavark** | Container network configuration tool | https://github.com/containers/netavark |+| **aardvark-dns**| DNS resolver for netavark networks | https://github.com/containers/aardvark-dns |+| **fuse-overlayfs** | Rootless overlay filesystem driver | https://github.com/containers/fuse-overlayfs |+| **slirp4netns** | Rootless user-mode networking | https://github.com/rootless-containers/slirp4netns |+| **shadow-utils**| `newuidmap` / `newgidmap` for rootless | https://github.com/shadow-maint/shadow |-- **Author:** Max Kastanas (max2idea)-- **Repository:** https://github.com/limboemu/limbo-- **License:** GNU General Public License v2.0-- **Copyright:** Copyright (C) Max Kastanas 2012 and Limbo contributors+All maintained by the containers community; primarily Apache-2.0 / GPL-2.0 licensed.-Limbo contributors whose work influenced this project:-- Max Kastanas — principal developer-- All contributors at https://github.com/limboemu/limbo/graphs/contributors+### System & init+- **busybox**: multi-call binary providing the initramfs userland and `/sbin/init` (https://busybox.net, GPL-2.0)+- **OpenRC**: service manager running as PID 1 inside the VM (https://github.com/OpenRC/openrc, BSD-2-Clause)+- **Dropbear SSH**: small SSH server (https://matt.ucc.asn.au/dropbear/dropbear.html, MIT-style)+- **iproute2, iptables, nftables, bridge-utils**: networking utilities maintained by netfilter.org and the Linux community----## SDL2 (Simple DirectMedia Layer)+## Emulation-SDL2 is used as the graphics/input backend.+### QEMU+QEMU provides the machine emulation that makes everything else possible. Podroid currently builds against QEMU 11.0.0-rc2, cross-compiled for arm64 Android.-- **Author:** Sam Lantinga and SDL contributors-- **Website:** https://libsdl.org-- **License:** zlib License-- **Copyright:** Copyright (C) 1997-2024 Sam Lantinga+- Project: https://www.qemu.org+- Repository: https://gitlab.com/qemu-project/qemu+- License: GNU General Public License v2.0 (and later)+- Original author: Fabrice Bellard+- Contributors: https://www.qemu.org/contributors/----+### libslirp+SLIRP is QEMU's user-mode network stack. Podroid links it into the QEMU binary statically.-## musl libc+- Project: https://gitlab.freedesktop.org/slirp/libslirp+- License: BSD-3-Clause-musl is a lightweight C standard library used for Android compatibility shims.+### libucontext+Bionic does not implement the System V `ucontext.h` API, which QEMU coroutines depend on. Podroid links against Ariadne Conill's portable libucontext to fill the gap.-- **Author:** Rich Felker and musl contributors-- **Website:** https://musl.libc.org-- **License:** MIT License-- **Copyright:** Copyright © 2005-2020 Rich Felker, et al.+- Project: https://github.com/kaniini/libucontext+- License: ISC----+### Limbo PC Emulator+Limbo pioneered running QEMU on Android years ago and solved many of the platform-specific issues we no longer have to. Although Podroid is a fresh codebase with a different UI and pipeline, the lineage of "QEMU on Android" traces back to Max Kastanas's work.-## Android Jetpack+- Repository: https://github.com/limboemu/limbo+- License: GNU General Public License v2.0+- Author: Max Kastanas (max2idea)-Podroid uses the following AndroidX / Jetpack libraries:+----| Library | Copyright |-|---------|-----------|-| Jetpack Compose | Copyright (C) Google LLC |-| Room | Copyright (C) Google LLC |-| Navigation Compose | Copyright (C) Google LLC |-| ViewModel / Lifecycle | Copyright (C) Google LLC |-| DataStore | Copyright (C) Google LLC |-| Hilt (Dagger) | Copyright (C) Google LLC / The Dagger Authors |+## Terminal & UI-All licensed under the Apache License 2.0.-See https://source.android.com/setup/start/licenses+### Termux Terminal Emulator+The terminal layer (xterm-256color emulator, escape-sequence parsing, mouse tracking, color theme parsing) is the Termux project's `terminal-view` and `terminal-emulator` libraries, consumed via JitPack as `com.github.termux:terminal-view:0.118.1`. Podroid rebuilds `libtermux.so` locally for 16 KB page alignment.----+- Project: https://github.com/termux/termux-app+- License: GNU General Public License v3.0+- Maintainers: Fredrik Fornwall and the Termux community-## Kotlin+### Color themes+Podroid ships 122 terminal color schemes covering most of the popular ecosystem (Dracula, Nord, Solarized, Tokyo Night, Catppuccin, Gruvbox, Monokai, the base16 family, and more). The themes are sourced from the [**Gogh**](https://github.com/Gogh-Co/Gogh) project's curated collection (MIT). Individual color palette designers are credited within each `.properties` file.-The application is written in **Kotlin**.+### Bundled fonts-- **Developer:** JetBrains s.r.o.-- **Website:** https://kotlinlang.org-- **License:** Apache License 2.0+| Font | License |+| ----------------------------------------------------------------------------------- | ------------------- |+| [JetBrains Mono](https://www.jetbrains.com/mono/) | OFL-1.1 |+| [Fira Code](https://github.com/tonsky/FiraCode) | OFL-1.1 |+| [Cascadia Code](https://github.com/microsoft/cascadia-code) | OFL-1.1 |+| [Source Code Pro](https://github.com/adobe-fonts/source-code-pro) | OFL-1.1 |+| [Hack](https://github.com/source-foundry/Hack) | MIT + Bitstream |+| [Iosevka](https://github.com/be5invis/Iosevka) | OFL-1.1 |+| [Victor Mono](https://github.com/rubjo/victor-mono) | OFL-1.1 |+| [Monofur](https://www.fontsquirrel.com/fonts/monofur) | Free for personal & commercial use |+| [Anonymous Pro](https://www.marksimonson.com/fonts/view/anonymous-pro) | OFL-1.1 |+| [DejaVu Sans Mono](https://dejavu-fonts.github.io/) | DejaVu / Bitstream Vera |+| [Liberation Mono](https://github.com/liberationfonts/liberation-fonts) | OFL-1.1 |+| [Ubuntu Mono](https://design.ubuntu.com/font/) | UFL-1.0 |+| [Terminus](https://terminus-font.sourceforge.net/) | OFL-1.1 |----## Podroid--Podroid itself is developed by **excp** and contributors.+## Android application-- **Repository:** https://github.com/ExTV/Podroid-- **License:** GNU General Public License v2.0 (or later)+### Language & libraries+- **Kotlin** by JetBrains s.r.o. (https://kotlinlang.org, Apache-2.0)+- **Jetpack Compose** by Google LLC (Apache-2.0)+- **AndroidX** (Lifecycle, Navigation, DataStore, ViewModel, Activity Compose) by Google LLC (Apache-2.0)+- **Hilt / Dagger** by Google LLC and the Dagger Authors (Apache-2.0)+- **Material 3** by Google LLC (Apache-2.0)+- **kotlinx.coroutines** by JetBrains (Apache-2.0)-If you have contributed to Podroid and are not listed here, please open an issue or pull-request to have your name added.+### Build toolchain+- **Android Gradle Plugin, Android SDK, Android NDK r27c** by Google LLC+- **Gradle** by Gradle, Inc. (Apache-2.0)+- **Docker** for the cross-build pipelines used by the kernel, initramfs, rootfs, and QEMU stages----## How to Attribute+## Podroid++Podroid itself is developed by **[ExTV](https://github.com/ExTV)** and contributors.-If you distribute a modified version of Podroid, you must:+- Repository: https://github.com/ExTV/Podroid+- Website: https://extv.github.io/Podroid/+- License: GNU General Public License v2.0 (or later)-1. Retain this CREDITS.md and all upstream license notices-2. Credit the original QEMU and Limbo projects-3. Make your modifications available under GPL v2.0 or later-4. Clearly indicate that your version is modified+If you have contributed code, themes, fonts, or bug reports and would like to be listed here, please open an issue or a pull request.----## Reporting Missing Credits+## Reporting missing or incorrect attribution-If you believe your work is used in Podroid but not properly credited, please open an issue-at the project repository. We take attribution seriously.+We take attribution seriously. If you believe your work is shipped in Podroid but not properly credited, or if any information above is incorrect, please [open an issue](https://github.com/ExTV/Podroid/issues/new) and we will get it fixed quickly.diff --git a/README.md b/README.mdindex c659926..e02dc26 100644--- a/README.md+++ b/README.md@@ -1,230 +1,337 @@+<div align="center">++<img src="https://github.com/ExTV.png" width="96" height="96" alt="Podroid" style="border-radius: 24px" />+# Podroid-<p align="center">- <img src="https://img.shields.io/github/stars/ExTV/Podroid?style=for-the-badge" alt="Stars">- <img src="https://img.shields.io/github/forks/ExTV/Podroid?style=for-the-badge" alt="Forks">- <img src="https://img.shields.io/github/downloads/ExTV/Podroid/total?style=for-the-badge" alt="Downloads">-</p>+**Linux containers on Android. No root required.**-<p align="center">- <strong>Run Linux containers on your Android phone — no root required.</strong>-</p>+A real Alpine Linux VM, a real Linux kernel, and rootless Podman, all in a single APK.-<p align="center">- <a href="https://github.com/ExTV/Podroid/releases">- <img src="https://img.shields.io/github/v/release/ExTV/Podroid?include_prereleases&style=flat-square&label=Download" alt="Download">- </a>- <a href="https://github.com/ExTV/Podroid/blob/main/LICENSE">- <img src="https://img.shields.io/github/license/ExTV/Podroid?style=flat-square" alt="License">- </a>+<p>+ <a href="https://github.com/ExTV/Podroid/releases"><img src="https://img.shields.io/github/v/release/ExTV/Podroid?include_prereleases&style=flat-square&label=release&color=blue" alt="Release" /></a>+ <a href="https://github.com/ExTV/Podroid/releases"><img src="https://img.shields.io/github/downloads/ExTV/Podroid/total?style=flat-square&color=brightgreen" alt="Downloads" /></a>+ <a href="https://github.com/ExTV/Podroid/stargazers"><img src="https://img.shields.io/github/stars/ExTV/Podroid?style=flat-square&color=yellow" alt="Stars" /></a>+ <a href="LICENSE"><img src="https://img.shields.io/github/license/ExTV/Podroid?style=flat-square" alt="License" /></a>+ <img src="https://img.shields.io/badge/platform-Android%209%2B-3DDC84?style=flat-square&logo=android&logoColor=white" alt="Android 9+" />+ <img src="https://img.shields.io/badge/arch-arm64-orange?style=flat-square" alt="arm64" /></p>+<a href="https://extv.github.io/Podroid/"><strong>Website</strong></a> ·+<a href="https://github.com/ExTV/Podroid/releases/latest"><strong>Download</strong></a> ·+<a href="#-quick-start"><strong>Quick Start</strong></a> ·+<a href="#-architecture"><strong>Architecture</strong></a> ·+<a href="#-building-from-source"><strong>Build</strong></a>++</div>+----Podroid spins up a lightweight Alpine Linux 3.23 VM using QEMU 11.0.0-rc2 and a custom Linux 6.6.87 kernel. It gives you a fully working [Podman](https://podman.io) container runtime with a built-in terminal. Install the APK, tap Start, and you're running containers in seconds.+## Why Podroid++Termux gives you a Linux shell on Android, but it runs on the host kernel, and the namespaces, cgroups, and netfilter rules that real containers need are not there. Google's new Terminal app uses the Android Virtualization Framework, which is locked to recent Pixel devices and ships without a container runtime. `proot` is a chroot emulation; most Docker Hub images do not work reliably.++**Podroid runs an actual Alpine Linux VM with its own purpose-built Linux 6.6 kernel.** Every OCI image runs unmodified, every `podman` flag works, and your changes (`apk add`, `rc-update add`, custom configs) persist across reboots in a writable overlay.++| | **Podroid** | Termux + proot | Google Terminal | KVM / chroot |+| ------------------------------ | --------------- | --------------- | --------------- | ---------------------- |+| Real Linux kernel | ✅ (custom 6.6) | ❌ | ✅ (Debian) | depends |+| Rootless Podman | ✅ | ⚠️ unreliable | ❌ manual | ✅ |+| Works on stock Android 9+ | ✅ | ✅ | ❌ (Pixel only) | ❌ (root + recovery) |+| OCI images run unmodified | ✅ | ❌ | ⚠️ manual setup | ✅ |+| Persistent VM state | ✅ | n/a | ✅ | ✅ |+| Zero post-install setup | ✅ | ❌ | ❌ | ❌ |----## Features+## ✨ Features++<table>+<tr>+<td width="33%" valign="top">++### Real Linux, real Podman++- Standard Alpine 3.23 root filesystem+- **OpenRC as PID 1**: `apk add docker; rc-service docker start` just works+- Custom Linux 6.6.87 kernel with overlayfs, netfilter, bridge, FUSE, and 9p built-in+- Rootless Podman + crun + netavark + slirp4netns+- Persistent ext4 overlay survives reboots++</td>+<td width="33%" valign="top">++### Built-in terminal-### Container Runtime-- **Rootless Podman** — Full Docker-compatible container runtime with no root access required-- **Custom Kernel** — Optimized Linux 6.6.87 kernel with netfilter, bridge, and overlayfs built-in for maximum performance-- **Persistent Storage** — Packages, configurations, and images survive restarts via persistent ext4 storage and overlayfs-- **Out-of-the-box Networking** — Internet access enabled via QEMU SLIRP; proper MASQUERADE support for container networking+- xterm-256color emulator (Termux engine)+- 114 color themes · 13 curated fonts+- CSI mouse tracking: `btop`, `htop`, `mc`, `nvim`, `tmux` work out of the box+- Customizable extra-keys bar (ESC, TAB, CTRL, ALT, F1–F12, arrows, symbols)+- Auto-resize with debounced SIGWINCH so the keyboard slide never flashes the prompt-### Terminal-- **xterm-256color Emulation** — Powered by Termux TerminalView v0.118.1-- **Real PTY** — Proper job control, signal handling, and escape sequence support-- **114 Color Themes** — Dracula, Nord, Solarized, Tokyo Night, Catppuccin, Gruvbox, and more-- **13 Curated Fonts** — JetBrains Mono, Fira Code, Cascadia Code, Source Code Pro, Hack, and more-- **Full Mouse Support** — CSI mouse tracking for btop, htop, mc, vim, and other TUI apps-- **Extra Keys Bar** — ESC, TAB, CTRL, ALT (sticky), arrows, F1–F12, and common symbols-- **Auto-resize** — Optimized resize daemon with debounced SIGWINCH signals to stop cursor flashing during keyboard animations+</td>+<td width="33%" valign="top">-### Networking-- **Port Forwarding** — Expose VM services to your Android device via runtime QMP control-- **Built-in SSH** — Dropbear server running on port 9922 (configurable)+### Networking & SSH++- SLIRP user-mode networking: Internet access, no host changes+- Live port-forward editor (host ↔ guest) over QEMU QMP+- Built-in Dropbear SSH on `127.0.0.1:9922` (toggleable)+- MASQUERADE / bridge built into the kernel for full container networking+- Optional Downloads-folder share via virtio-9p++</td>+</tr>+<tr>+<td valign="top">++### Adaptive UI++- Material 3 with dynamic color+- Phone, tablet, and landscape layouts+- Animated boot-progress indicator+- Live VM controls + status from a foreground service+- In-app update checker++</td>+<td valign="top">### Performance-- **ARM64-native** — Executes directly on your device's CPU using QEMU TCG-- **Multi-core Support** — Configure 1-8 CPU cores (tcg-thread=multi)-- **Allocatable RAM** — 512MB to 4GB configurable; ZRAM swap enabled in guest for 2x effective memory-- **16KB Page Support** — Optimized for newer Android devices (Pixel 8/9/10+) with 16KB system pages-### Storage-- **2–64 GB** — Configurable persistent storage-- **Downloads Sharing** — Mount Android Downloads folder via virtio-9p with optimized msize+- QEMU TCG with `thread=multi`, 256–512 MB translation cache+- Dedicated I/O thread on virtio-blk (massive win for image pulls)+- ZRAM swap at 50 % of guest RAM (lz4) → ~2× effective memory+- `mitigations=off` in guest kernel: safe under TCG, ~5–15 % faster+- 16 KB-page-aligned native binaries (Pixel 8/9/10+ ready)++</td>+<td valign="top">++### Configurable++- 1, 2, 4, 6, 8 vCPUs · 512 MB – 4 GB RAM+- 2 GB – 64 GB persistent storage+- Editable QEMU `-cpu` / `-accel` / `-machine` flags+- Editable guest kernel command line+- Per-app font size, theme, font, haptics, extras-bar layout++</td>+</tr>+</table>----## Quick Start+## 🚀 Quick Start-1. **Download** the latest APK from [Releases](https://github.com/ExTV/Podroid/releases)-2. **Install** and open Podroid-3. **Tap Start VM** — Boot progress shows via an animated tracker and notification-4. **Wait ~10-15 seconds** for "Ready" status (as fast as 6s on high-end devices)-5. **Tap Open Terminal** to access the shell-6. **Run containers:**+1. Download the latest APK from the [Releases page](https://github.com/ExTV/Podroid/releases/latest).+2. Install and open Podroid. The first launch extracts the kernel, initramfs, and Alpine squashfs to app storage (~100 MB, one-time).+3. Tap **Start VM**. Boot completes in 6–15 seconds depending on device.+4. Tap **Open Terminal** when the indicator turns to *Ready*.-```sh+```bash# Hello worldpodman run --rm alpine echo hello-# Interactive shell-podman run --rm -it alpine sh--# Run Nginx+# Web server, accessible from Android browser at http://127.0.0.1:8080podman run -d -p 8080:80 nginx-# List running containers-podman ps -a+# Rootless interactive+adduser -G wheel dev # then: doas su - dev+podman run --rm -it alpine sh```+Default credentials: **root / podroid**. Change with `passwd`. Create a regular user with `adduser -G wheel <name>`; wheel-group members can use `doas` and `sudo`.+----## Requirements+## 📋 Requirements-| | |-|---|---|-| **Device** | ARM64 Android device (most phones from 2018+) |-| **Android** | Min SDK 28 (Android 9.0+), Target SDK 36. |-| **Storage** | ~200 MB app + VM disk size |+| | |+| ------------ | ---------------------------------------------------------------- |+| Architecture | ARM64 only (`aarch64`) |+| OS | Android 9.0+ (API 28) · target API 36 |+| Storage | ~200 MB app + chosen VM disk size (default 2 GB, max 64 GB) |+| Memory | 2 GB device RAM recommended (the VM defaults to 512 MB allocation) |----## How It Works+## 🏗 Architecture```-┌─────────────────────────────────────────────────────────────┐-│ Android App │-│ ┌─────────────┐ ┌──────────────┐ ┌────────────────┐ │-│ │ Service │ │ QEMU 11 │ │ Compose UI │ │-│ │ (WakeLock) │ │ (TCG) │ │ Terminal View │ │-│ └──────┬──────┘ └──────┬───────┘ └───────┬────────┘ │-└─────────┼────────────────┼──────────────────┼───────────────┘- │ │ │- │ ┌──────▼───────┐ ┌──────▼────────┐- │ │ Alpine 3.23 │ │ Podroid │- └────────►│ + Podman │◄──│ Bridge │- Boot │ + Kernel 6.6│ │ (virt-console)│- Stages └──────────────┘ └───────────────┘+ ┌──────────────────────────────────────────────┐+ │ Android App │+ Compose UI │ ┌──────────────┐ ┌────────────────────┐ │+ Setup ▸ Home ▸ │ │ PodroidQemu │ │ PodroidService │ │+ Terminal ▸ Settings │ │ (engine) │ │ (foreground + WL) │ │+ │ └──────┬───────┘ └─────────┬──────────┘ │+ └─────────┼────────────────────┼───────────────┘+ │ │+ spawns │ │ owns notification+ ▼ ▼+ ┌──────────────────────────────────────────────┐+ │ QEMU 11.0.0-rc2 (TCG, ARMv8 virt machine) │+ └──┬─────────────────┬─────────────────┬───────┘+ serial.sock │ terminal.sock │ ctrl.sock │ qmp.sock+ (boot) │ (hvc0) │ (hvc1) │ (control)+ ▼ ▼ ▼+ ┌─────────────────────────────────────────────┐+ │ Alpine Linux 3.23 VM │+ │ /sbin/init (busybox) ▸ /etc/inittab ▸ │+ │ OpenRC (PID 1) │+ │ │+ │ /dev/vda ext4 overlay (writable) │+ │ /dev/vdb squashfs (read-only base) │+ │ │+ │ podroid-bootstrap podroid-network │+ │ podroid-resize dropbear (optional) │+ │ podroid-ready ▸ "Ready!" marker │+ │ │+ │ Podman + crun + netavark + slirp4netns │+ └─────────────────────────────────────────────┘```-**Boot Sequence:**-1. QEMU loads custom Linux kernel + initramfs-2. Phase 1 init mounts persistent storage.img as overlayfs-3. Phase 2 configures networking, Podman, and starts the resize daemon-4. **Three-channel I/O**:- - `serial.sock`: Kernel/boot log stream for the monitor (ttyAMA0)- - `terminal.sock`: Primary shell I/O for the bridge (virtio-console hvc0)- - `ctrl.sock`: Out-of-band resize signals (virtio-console hvc1)+### Boot pipeline++1. **PodroidApplication** copies kernel, initramfs, and Alpine squashfs from APK assets into `filesDir` on first launch (size-checked, idempotent).+2. **QEMU** launches with `-M virt`, two virtio-blk drives (`/dev/vda` writable ext4, `/dev/vdb` read-only squashfs), four Unix sockets, and the user-configured RAM / CPU count.+3. **`init-podroid`** (45 lines, runs in initramfs as PID 1) mounts the squashfs as the lower layer of an overlayfs, the ext4 image as the upper, and `switch_root`s into `/sbin/init`.+4. **OpenRC** brings up the system via three custom services on the squashfs:+ - `podroid-bootstrap`: cgroup v2, devpts/shm/mqueue, sysctl, ZRAM, mount-propagation tweaks for rootless containers+ - `podroid-network`: eth0 up, `10.0.2.15/24`, `/etc/resolv.conf`+ - `podroid-ready`: emits the boot-stage markers consumed by the Android UI+5. **Android UI** sees `Ready!` on `serial.sock` → state = *Running* → the bridge connects directly to virtio-console (`/dev/hvc0`) and the terminal becomes interactive.++> Why `switch_root` and not `chroot`? `setns(CLONE_NEWNS)` inside `crun exec` resets `fs->root`, so a chroot pivot left `podman exec -it` looking at raw kernel paths and failing to open `/dev/ptmx`. `switch_root` reorganizes the kernel mount tree itself, so namespace operations land on a clean `/`. ([fix details](https://github.com/ExTV/Podroid/issues/17))++### Project layout++```+Podroid/+├── app/ Android application (Jetpack Compose, Hilt)+│ └── src/main/+│ ├── java/com/excp/podroid/+│ │ ├── engine/ PodroidQemu, QmpClient, VmState+│ │ ├── service/ PodroidService (foreground)+│ │ ├── data/repository/ DataStore-backed settings & port forwards+│ │ └── ui/ Compose screens + theme+│ ├── jniLibs/arm64-v8a/ QEMU, podroid-bridge, libslirp, libtermux+│ └── assets/ kernel, initramfs, squashfs, fonts, themes+├── init-podroid Minimal initramfs script (~45 lines)+├── podroid-bridge.c Native PTY ↔ virtio-console relay+├── Dockerfile Kernel + initramfs + QEMU build pipeline+├── build-rootfs/ Alpine squashfs build pipeline+│ ├── Dockerfile.rootfs+│ ├── build-rootfs.sh+│ └── files/ OpenRC services + helpers baked into the squashfs+├── build-all.sh Unified build / deploy script+├── podroid_kernel.config Custom kernel Kconfig fragment+└── docs/ GitHub Pages site (extv.github.io/Podroid)+```++### Native components++| Binary | Purpose |+| --------------------------- | ----------------------------------------------------------- |+| `libqemu-system-aarch64.so` | QEMU TCG engine (ELF executable shipped as a `.so`) |+| `libpodroid-bridge.so` | PTY ↔ virtio-console relay with debounced SIGWINCH |+| `libtermux.so` | Termux terminal emulator JNI (rebuilt for 16 KB pages) |+| `libslirp.so` | SLIRP user-mode networking, statically linked into QEMU |++All native binaries are built with `-Wl,-z,max-page-size=16384` for compatibility with 16 KB-page Android devices (mandatory on Android 13+).----## Building from Source+## 🔧 Building from source### Prerequisites-- Docker (for VM initramfs, kernel, and QEMU builds)-- Android NDK r27c (for bridge/Termux native builds)-- Android SDK+- Docker 20.10+ (for kernel, initramfs, rootfs, and QEMU builds)+- Android NDK r27c (for the bridge and Termux native libs)+- Android SDK with platform 36 + build-tools-### Build Steps+### Build pipeline```bash-# Clone the repositorygit clone https://github.com/ExTV/Podroid.gitcd Podroid-# 1. Build custom kernel (~10min, cached)-./build-all.sh kernel+./build-all.sh kernel # ~5–10 min, Docker-cached+./build-all.sh initramfs # kernel + minimal initramfs+./build-all.sh rootfs # Alpine squashfs (~30 s, Docker-cached)+./build-all.sh qemu # ~30 min first run, fully cached after+./build-all.sh termux # local NDK build of libtermux.so+./gradlew installDebug # build + install the APK on a connected device+```-# 2. Build VM initramfs (~5min)-./build-all.sh initramfs+Or just:-# 3. Build QEMU + bridge via Docker (~30min first time)-./build-all.sh qemu+```bash+./build-all.sh all # everything above, in order+./build-all.sh deploy # build + install + launch+./build-all.sh test # boot validation: deploys APK, polls console.log for "Ready!"+```-# 4. Build Termux JNI lib (local NDK)-./build-all.sh termux+### Inspecting a running VM-# 5. Build and install the APK-./gradlew installDebug+```bash+adb logcat -s PodroidQemu # engine logs+adb shell run-as com.excp.podroid.debug cat files/console.log # full VM serial log+ssh [email protected] -p 9922 # if SSH is enabled (password: podroid)```----## Architecture--### Project Structure--```-Podroid/-├── app/ # Android application (Compose)-│ └── src/main/-│ ├── java/ # Kotlin source (Engine, UI, Data)-│ ├── jniLibs/ # Native binaries (.so renamed ELF)-│ └── assets/ # Kernel, initramfs, fonts, themes-├── init-podroid # Two-phase VM bootstrap script-├── podroid-bridge.c # PTY ↔ virtio-console socket relay-├── build-all.sh # Unified build-everything script-├── Dockerfile # Multi-stage CI/CD build pipeline-├── podroid_kernel.config # Custom Linux kernel configuration-└── gradlew # Gradle wrapper-```+## 🗺 Roadmap-### Native Components+- [x] OpenRC as PID 1: `apk add docker; rc-service docker start` works and persists ✅ *1.1.6*+- [x] Adaptive layouts for tablets and landscape phones ✅ *1.1.6*+- [x] Issue #17: `podman exec -it` works rootful and rootless ✅ *1.1.6*+- [x] Custom Linux 6.6 kernel with all required options forced built-in ✅ *1.1.4*+- [x] virtio-console terminal channel separate from boot serial ✅ *1.1.4*+- [ ] User-loadable terminal fonts (drop a `.ttf` into a folder, picker auto-discovers)+- [ ] Optional KVM acceleration on devices that expose it-| File | Description |-|------|-------------|-| `libqemu-system-aarch64.so` | QEMU TCG engine |-| `libpodroid-bridge.so` | Stateful PTY relay with SIGWINCH debouncing |-| `libtermux.so` | Terminal emulator JNI |-| `libslirp.so` | SLIRP user-mode networking |+Have an idea? [Open an issue](https://github.com/ExTV/Podroid/issues/new).----## TODO+## 🤝 Contributing-- [x] **Better QEMU performance** — TCG optimization, and performance profiling-- [x] **Better terminal integration** — Improve TUI app support (nvim, vim, less, nano) with proper CSI escape sequence handling and resize propagation-- [ ] **User account instead of root** — Run VM processes as a non-root user for improved security-- [ ] **Docker socket compatibility** — Proper service scripts for `rc-service` and `docker` commands+Pull requests are welcome. Before opening a PR, please read [**CONTRIBUTING.md**](CONTRIBUTING.md) and skim [**skill.md**](skill.md). It documents the boot pipeline, every native binary, and the design quirks you need to know to make changes that don't regress.------## Contributing+Found a bug? Please include the contents of `console.log`:-Contributions are welcome! Please read the [skill.md](skill.md) for complete project context before submitting PRs.+```bash+adb shell run-as com.excp.podroid.debug cat files/console.log+```-### For AI Assistants+### For AI assistants-Give AI assistants full context on Podroid:+If you're using Claude Code, Cursor, Copilot, or another assistant, point it at [`skill.md`](skill.md) before making any change. It covers the full architecture, every constant, every quirk, and every common task.-```markdown-Read the skill.md file at: /path/to/Podroid/skill.md-```+----The skill file includes complete architecture, all source files, build commands, known issues, and settings.+## 🙏 Credits----+Podroid stands on the shoulders of giants:-## Credits+| Project | Role |+| -------------------------------------------------------------------- | --------------------------------------------------- |+| [QEMU](https://www.qemu.org) | Machine emulation, the heart of the VM |+| [Linux](https://kernel.org) | Custom 6.6.87 kernel |+| [Alpine Linux](https://alpinelinux.org) | Tiny, fast Linux distribution |+| [Podman](https://podman.io) · [crun](https://github.com/containers/crun) | Rootless container runtime |+| [Termux](https://github.com/termux/termux-app) | Terminal emulator engine |+| [Limbo PC Emulator](https://github.com/limboemu/limbo) | Original groundwork for QEMU on Android |-| Project | Purpose |-|---------|---------|-| [QEMU](https://www.qemu.org) | Machine emulation and virtualization |-| [Alpine Linux](https://alpinelinux.org) | Lightweight VM base |-| [Podman](https://podman.io) | Rootless container runtime |-| [Termux](https://github.com/termux/termux-app) | Terminal emulator for Android |-| [Limbo PC Emulator](https://github.com/limboemu/limbo) | QEMU on Android groundwork |+See [CREDITS.md](CREDITS.md) for the full list of upstream projects, libraries, and contributors.----## License+## 📄 License-[GNU General Public License v2.0](LICENSE)-c License v2.0](LICENSE)-2.0](LICENSE)+Podroid is released under the [GNU General Public License v2.0](LICENSE). QEMU, the Linux kernel, Alpine, and Podman are each distributed under their respective upstream licenses.+<div align="center">+<sub>Built with care by <a href="https://github.com/ExTV">@ExTV</a> · <a href="https://extv.github.io/Podroid/">extv.github.io/Podroid</a></sub>+</div>