A rootless Android app that boots Alpine Linux: run containers (Podman/Docker/LXC) and GUI desktop apps.
docs(readme): new hero logo, four phone screenshots, AVF blurb accuracy pass
ExTvf11e13cef245
diff --git a/README.md b/README.mdindex b1abdc7..d197e66 100644--- a/README.md+++ b/README.md@@ -1,6 +1,6 @@<div align="center">-<img src="https://github.com/ExTV.png" width="96" height="96" alt="Podroid" style="border-radius: 24px" />+<img src="docs/logo.png" alt="Podroid logo" width="140" /># Podroid@@ -20,7 +20,8 @@ A real Alpine VM, a real Linux kernel, rootless Podman, and an in-app X11 viewer<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="#build"><strong>Build</strong></a>+<a href="#build"><strong>Build</strong></a> ·+<a href="CONTRIBUTING.md"><strong>Contributing</strong></a></div>@@ -28,7 +29,11 @@ A real Alpine VM, a real Linux kernel, rootless Podman, and an in-app X11 viewer## What it is-Podroid boots a standard Alpine 3.23 VM under QEMU, with a custom Linux **7.0.5** kernel that has every option real containers need (overlayfs, netfilter, bridge, FUSE, binfmt_misc, …) compiled in. You get rootless Podman, Docker and LXC out of the box, plus an in-app X11 desktop for GUI apps, without root, without ADB tricks, on stock Android 9+.+- Boots a standard **Alpine 3.23** VM under QEMU on stock Android 9+.+- Custom **Linux 7.0.5** kernel: every container option (overlayfs, netfilter, bridge, FUSE, binfmt_misc) compiled `=y`. Build fails if any get demoted.+- Rootless **Podman, Docker and LXC** pre-installed and pre-wired.+- In-app **X11 viewer** (Xvnc + PulseAudio) with touch→mouse and audio.+- No root. No ADB tricks. No userland tarballs.## Quick start@@ -39,7 +44,7 @@ Podroid boots a standard Alpine 3.23 VM under QEMU, with a custom Linux **7.0.5*```bash# Containerspodman run --rm alpine echo hello-podman run -d -p 8080:80 nginx # reachable from Android at 127.0.0.1:8080+podman run -d -p 8080:80 nginx # reachable from Android at 127.0.0.1:8080# GUI apps: tap the monitor icon in the terminal to open the X11 viewerapk add firefox@@ -48,6 +53,25 @@ firefox &Default login: **root / podroid**.+## Screenshots++<div align="center">+ <table>+ <tr>+ <td align="center"><img src="docs/screenshots/01-home-idle.png" alt="Home screen with the VM stopped" width="240" /></td>+ <td align="center"><img src="docs/screenshots/02-home-running.png" alt="Home screen with the VM running and network info visible" width="240" /></td>+ <td align="center"><img src="docs/screenshots/03-terminal-fastfetch.png" alt="Built-in terminal with fastfetch showing the Podroid logo and Alpine system info" width="240" /></td>+ <td align="center"><img src="docs/screenshots/04-quick-settings.png" alt="Terminal Quick Settings sheet showing font size, theme, font, extra-keys and haptics toggles" width="240" /></td>+ </tr>+ <tr>+ <td align="center"><sub>Idle: VM stopped</sub></td>+ <td align="center"><sub>Running: IP, SSH, uptime</sub></td>+ <td align="center"><sub><code>fastfetch</code> with the Podroid logo inline</sub></td>+ <td align="center"><sub>Quick Settings: theme & font</sub></td>+ </tr>+ </table>+</div>+## Features- **Linux 7.0.5 kernel**, custom-built. Every container option compiled `=y`; the build fails if any get demoted.@@ -55,7 +79,7 @@ Default login: **root / podroid**.- **OpenRC as PID 1.** `apk add` whatever you want, `rc-service ... start`, and it persists across reboots.- **In-app X11 viewer** (Xvnc + PulseAudio) with touch→mouse, soft-keyboard input, and PCM audio over loopback.- **Built-in terminal** powered by the Termux engine: xterm-256color, mouse tracking, debounced resize, customizable extra-keys row.-- **Persistent ext4 overlay** on a read-only Alpine squashfs. Your installs and configs survive every reboot.+- **Persistent ext4 overlay** on a read-only Alpine squashfs. Installs and configs survive every reboot.- **Adaptive Material 3 UI** for phone, tablet and landscape, with dynamic color and a foreground service that keeps the VM alive.## Themes & fonts@@ -75,24 +99,24 @@ Everything below is editable from **Settings**:- **Memory:** 512 MB · 1 GB · 2 GB · 4 GB- **CPU cores:** 1 · 2 · 4 · 6 · 8- **Persistent storage:** 2 GB to 64 GB (chosen at first setup; reset to change)-- **Downloads folder sharing** (virtio-9p): toggle on/off; mounted inside the VM at `/mnt/downloads`-- **SSH** (Dropbear on `127.0.0.1:9922`): toggle on/off-- **Port forwards:** add/remove host ↔ guest TCP/UDP rules live, no VM restart (sent to QEMU over QMP)+- **Downloads folder sharing:** toggle on/off; mounted inside the VM at `/mnt/downloads` (virtio-9p on QEMU, AVF `SharedPath` where the backend supports it)+- **SSH** (Dropbear on host port `9922`): toggle on/off; reachable from the LAN as `ssh root@<phone-ip> -p 9922` once the VM is Ready+- **Port forwards:** add/remove host ↔ guest TCP/UDP rules live, no VM restart- **Advanced QEMU args:** full `-cpu` / `-accel` / RNG / device line, editable- **Advanced kernel cmdline:** extras appended to the boot cmdline- **Full App Reset:** wipe the persistent storage image and start over-RAM and CPU changes take effect on the next start; everything else is hot.+RAM, CPU and backend changes take effect on the next start; everything else is hot.## Diagnostics-**Settings → Export Diagnostic Log** bundles app info, current settings, VM state, app logcat and the full QEMU console output into a single `log.txt` and shares it via the standard Android share sheet. Attach this to bug reports; it's almost always enough to diagnose a boot or container issue without ADB.+**Settings → Export Diagnostic Log** bundles app info, current settings, VM state, app logcat and the full guest console (QEMU serial or AVF console, whichever backend is active) into a single `log.txt` and shares it via the standard Android share sheet. Attach this to bug reports; it's almost always enough to diagnose a boot or container issue without ADB.**Settings → About → AVF (pKVM) diagnostic** runs a six-line probe of the Android Virtualization Framework on your device — feature flag, permissions, system service reachability — and a smoke-start of a minimal VM to confirm the path actually works end-to-end. Tap it before opening an issue about KVM not engaging.## Hardware acceleration (KVM / pKVM)-By default Podroid emulates the guest CPU in software (QEMU TCG). On the small set of Android devices that ship Google's **pKVM** (Pixel 8/9/10, a few others), Podroid can run the same VM under the **Android Virtualization Framework** (AVF) for near-native CPU performance — boot times drop from ~15 s to under 3 s, and CPU-bound container workloads run at host speed.+By default Podroid emulates the guest CPU in software (QEMU TCG). On phones that ship Google's **pKVM**, Podroid can run the same VM under the **Android Virtualization Framework** (AVF) for near-native CPU performance: boot times drop from ~15 s to under 3 s, and CPU-bound container workloads run at host speed.This requires three things, all under your control:@@ -104,9 +128,9 @@ adb shell getprop ro.boot.hypervisor.vm.supportedadb shell getprop ro.boot.hypervisor.protected_vm.supported```-If the first line returns `feature:android.software.virtualization_framework` and the two getprop lines return `1`, your device is supported. If any are empty, it's not — Podroid will silently fall back to QEMU/TCG and nothing else in this section applies.+If the first line returns `feature:android.software.virtualization_framework` and the two getprop lines return `1`, your device is eligible. If any are empty, it's not, and Podroid will silently fall back to QEMU/TCG; nothing else in this section applies.-Confirmed support: Pixel 8/8 Pro, Pixel 9/9 Pro/Pro XL, Pixel 10/10 Pro/Pro XL, Pixel Fold, Pixel Tablet.+Eligibility alone isn't enough: some phones expose pKVM but the AVF guest kernel can't find its console device and panics on boot. Always run **Settings → About → AVF (pKVM) diagnostic** first. If the smoke test fails, leave the backend on Auto (which falls back to QEMU) or force **QEMU (TCG)** explicitly.### 2. Grant the two AVF permissions via ADB@@ -117,7 +141,7 @@ adb shell pm grant com.excp.podroid android.permission.MANAGE_VIRTUAL_MACHINEadb shell pm grant com.excp.podroid android.permission.USE_CUSTOM_VIRTUAL_MACHINE```-The grants persist across reboots and in-place app updates. They survive `adb install -r` but **not** `adb install -d` followed by a full uninstall+reinstall.+The grants persist across reboots and in-place app updates. They survive `adb install -r` but **not** a full uninstall + reinstall.### 3. Verify and select the backend in-app@@ -131,8 +155,8 @@ SUCCESS: AVF accepted our config, VM started + stopped cleanly.Then **Settings → Advanced → Backend** picks how Podroid chooses at startup:- **Auto** (default) — use AVF if the feature + permissions are both present, otherwise QEMU. The right choice for everyone.-- **AVF (KVM)** — force AVF. Useful for debugging; the VM will error explicitly if AVF rejects your config rather than silently falling back.-- **QEMU (TCG)** — force software emulation even on a pKVM device. Useful for reproducing user reports or testing the slow path.+- **AVF (KVM):** force AVF. Useful for debugging; the VM errors explicitly if AVF rejects your config rather than silently falling back.+- **QEMU (TCG):** force software emulation even on a pKVM device. Useful for reproducing reports against the slow path.Changing the backend requires a VM stop + restart (same as RAM/CPU changes).@@ -142,10 +166,10 @@ If your phone has the feature but you haven't run the `pm grant` commands yet, t### "QEMU crashed (SIGKILL)" / VM dies when I switch to another app-On Android 12+ the system aggressively reaps **phantom processes** — any native subprocess (here, QEMU + the bridge) spawned by an app that isn't visible as a standard Android process. Even with our foreground service keeping the app alive, the phantom children do not inherit that importance and get killed when the parent app goes to the background or under memory pressure.+On Android 12+ the system aggressively reaps **phantom processes**: native subprocesses (here, QEMU + the bridge) spawned by an app that isn't visible as a standard Android process. Even with our foreground service keeping the app alive, the phantom children do not inherit that importance and get killed when the app goes to the background or under memory pressure.Symptoms:-- VM was running, you switched to another app for a minute, came back to "VM stopped" or `Error(QEMU crashed (SIGKILL))`.+- VM was running, you switched apps for a minute, came back to "VM stopped" or `Error(QEMU crashed (SIGKILL))`.- Diagnostic log shows `QEMU exited: 137` and `Process PhantomProcessRecord {... libqemu-system-aarch64.so/...} died`.Disable the phantom-process killer with **one** of the following.@@ -197,7 +221,7 @@ Contributions of every size are welcome: bug reports, kernel-config tweaks, new- **Pull requests:** read [CONTRIBUTING.md](CONTRIBUTING.md) first. Keep changes scoped, run `./build-all.sh test` before pushing, and explain *why* in the PR description.- **Bug reports:** [open an issue](https://github.com/ExTV/Podroid/issues/new) with your device + Android version, a short repro, and the diagnostic log (**Settings → Export Diagnostic Log** in the app).-- **Diving into the engine:** [`skill.md`](skill.md) is the deep map: boot pipeline, every native binary, every quirk, every common task. AI assistants should read it before touching anything.+- **Diving into the engine:** [`skill.md`](skill.md) is the deep map: boot pipeline, every native binary, every quirk. AI assistants should read it before touching anything.## Creditsdiff --git a/docs/logo.png b/docs/logo.pngnew file mode 100644index 0000000..47b95c1Binary files /dev/null and b/docs/logo.png differdiff --git a/docs/screenshots/01-home-idle.png b/docs/screenshots/01-home-idle.pngnew file mode 100644index 0000000..3b72f9fBinary files /dev/null and b/docs/screenshots/01-home-idle.png differdiff --git a/docs/screenshots/02-home-running.png b/docs/screenshots/02-home-running.pngnew file mode 100644index 0000000..304b283Binary files /dev/null and b/docs/screenshots/02-home-running.png differdiff --git a/docs/screenshots/03-terminal-fastfetch.png b/docs/screenshots/03-terminal-fastfetch.pngnew file mode 100644index 0000000..56ec3dfBinary files /dev/null and b/docs/screenshots/03-terminal-fastfetch.png differdiff --git a/docs/screenshots/04-quick-settings.png b/docs/screenshots/04-quick-settings.pngnew file mode 100644index 0000000..6d409f6Binary files /dev/null and b/docs/screenshots/04-quick-settings.png differ