Skip to content

A rootless Android app that boots Alpine Linux: run containers (Podman/Docker/LXC) and GUI desktop apps.

rewrite readme

ExTv99d5a2d9c212
diff --git a/CLAUDE.md b/CLAUDE.md
index 2cb8e78..328f259 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -35,10 +35,11 @@ All components are coordinated by `build-all.sh`:
**Monitor VM boot:**
```bash
adb logcat -s PodroidQemu
-adb shell run-as com.excp.podroid.debug cat files/console.log
+adb shell run-as com.excp.podroid cat files/console.log # release build
+adb shell run-as com.excp.podroid.debug cat files/console.log # debug build
```
-**All shipped builds are `debug` builds** — there's no Google Play / release signing certificate, so `assembleRelease` is never run. Consequence: `BuildConfig.VERSION_NAME` ends in `-debug` (e.g. `1.1.7-debug`), the `applicationId` is `com.excp.podroid.debug`, and any code that compares the local version string against an upstream release tag must strip the `-debug` suffix first (see `UpdateRepository.checkForUpdate`).
+**Shipped builds are signed `release` builds** (1.1.9+). `assembleRelease` is wired up via `signingConfigs.release` in `app/build.gradle.kts`, fed by the `PODROID_RELEASE_STORE_FILE` / `_PASSWORD` / `_KEY_ALIAS` / `_KEY_PASSWORD` Gradle properties (keystore: `podroid-release.jks`). For release builds: `applicationId = com.excp.podroid`, `BuildConfig.VERSION_NAME = "1.1.9"`. Debug builds still get `applicationIdSuffix = ".debug"` and `versionNameSuffix = "-debug"` — so `com.excp.podroid.debug` / `1.1.9-debug` for `assembleDebug`. Any code comparing the local version string against an upstream release tag must strip an optional `-debug` suffix (see `UpdateRepository.checkForUpdate`).
Native binaries require 16KB page alignment (`-Wl,-z,max-page-size=16384`) — mandatory on Android 13+.
diff --git a/CREDITS.md b/CREDITS.md
index 421fefb..d4d3e89 100644
--- a/CREDITS.md
+++ b/CREDITS.md
@@ -11,7 +11,7 @@ If something you maintain is included here and we missed you, please open an iss
These projects make up the actual Linux system that runs inside Podroid.
### 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.
+Podroid ships a custom build of the upstream Linux kernel (currently 7.0.5) configured specifically for OCI-compatible containers under QEMU TCG.
- Project: https://kernel.org
- License: GNU General Public License v2.0
@@ -23,12 +23,14 @@ 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)
-### Container runtime
-The full rootless OCI stack ships pre-installed and pre-configured.
+### Container runtimes
+The full rootless OCI stack ships pre-installed and pre-configured. Docker and LXC are bundled alongside Podman for users who prefer them.
| Component | Role | Project |
| --------------- | ---------------------------------------- | ---------------------------------------------------- |
| **Podman** | Daemonless container engine | https://podman.io |
+| **Docker** | Classic daemon-based container engine | https://www.docker.com |
+| **LXC** | System containers (alternative to OCI) | https://linuxcontainers.org |
| **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 |
@@ -42,14 +44,22 @@ All maintained by the containers community; primarily Apache-2.0 / GPL-2.0 licen
- **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)
+- **doas / sudo**: privilege escalation for `wheel`-group users (OpenBSD / https://www.sudo.ws)
- **iproute2, iptables, nftables, bridge-utils**: networking utilities maintained by netfilter.org and the Linux community
+### X11 desktop stack
+The in-app X11 viewer is backed by these components running inside the VM. Podroid's Android side speaks RFB 3.8 directly (no third-party VNC client) and decodes the audio stream natively.
+
+- **TigerVNC** (`Xvnc`): combined X server + RFB server (https://tigervnc.org, GPL-2.0)
+- **PulseAudio**: audio server, exposing a null-sink monitor over `module-simple-protocol-tcp` (https://www.freedesktop.org/wiki/Software/PulseAudio/, LGPL-2.1)
+- **font-misc-misc, font-cursor-misc, ttf-dejavu**: minimum X11 fonts so apps render correctly out of the box
+
---
## Emulation
### 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.
+QEMU provides the machine emulation that makes everything else possible. Podroid currently builds against QEMU 11.0.0, cross-compiled for arm64 Android.
- Project: https://www.qemu.org
- Repository: https://gitlab.com/qemu-project/qemu
diff --git a/README.md b/README.md
index 254fbae..452744c 100644
--- a/README.md
+++ b/README.md
@@ -4,9 +4,9 @@
# Podroid
-**Linux containers on Android. No root required.**
+**Linux containers and a Linux desktop on Android. No root.**
-A real Alpine Linux VM, a real Linux kernel, and rootless Podman, all in a single APK.
+A real Alpine VM, a real Linux kernel, rootless Podman, and an in-app X11 viewer, all in one APK.
<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>
@@ -19,320 +19,115 @@ A real Alpine Linux VM, a real Linux kernel, and rootless Podman, all in a singl
<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>
+<a href="#quick-start"><strong>Quick Start</strong></a> ·
+<a href="#build"><strong>Build</strong></a>
</div>
---
-## Why Podroid
+## What it is
-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 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+.
-**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.
+## Quick start
-| | **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
-
-<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
-
-- 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
-
-</td>
-<td width="33%" valign="top">
-
-### 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
-
-- 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
-
-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*.
+1. Grab the APK from [Releases](https://github.com/ExTV/Podroid/releases/latest).
+2. Open Podroid → **Start VM** (boots in 6–30 s).
+3. Tap **Open Terminal** when status turns *Ready*.
```bash
-# Hello world
+# Containers
podman run --rm alpine echo hello
+podman run -d -p 8080:80 nginx # reachable from Android at 127.0.0.1:8080
-# Web server, accessible from Android browser at http://127.0.0.1:8080
-podman run -d -p 8080:80 nginx
-
-# Rootless interactive
-adduser -G wheel dev # then: doas su - dev
-podman run --rm -it alpine sh
+# GUI apps: tap the monitor icon in the terminal to open the X11 viewer
+apk add firefox
+firefox &
```
-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
-
-| | |
-| ------------ | ---------------------------------------------------------------- |
-| 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) |
-
----
-
-## 🏗 Architecture
+Default login: **root / podroid**.
-```
- ┌──────────────────────────────────────────────┐
- │ 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 │
- └─────────────────────────────────────────────┘
-```
+## Features
-### Boot pipeline
+- **Linux 7.0.5 kernel**, custom-built. Every container option compiled `=y`; the build fails if any get demoted.
+- **Podman, Docker and LXC pre-installed.** Rootless Podman wired up with crun + netavark + slirp4netns; `rc-service docker start` or `lxc-create …` work out of the box.
+- **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.
+- **Adaptive Material 3 UI** for phone, tablet and landscape, with dynamic color and a foreground service that keeps the VM alive.
-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.
+## Themes & fonts
-> 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))
+Open the terminal's **Quick Settings** (top sheet) for both pickers.
-### Project layout
+- **122 bundled color themes:** Dracula, Nord, Solarized, Tokyo Night, Catppuccin, Gruvbox, Monokai, the full base16 family, and more.
+- **13 bundled monospace fonts:** JetBrains Mono, Fira Code, Cascadia Code, Source Code Pro, Hack, Iosevka, Victor Mono, Monofur, Anonymous Pro, DejaVu Sans Mono, Liberation Mono, Ubuntu Mono, Terminus.
+- **Bring your own font.** The Fonts picker has a **+ Add** chip; pick any `.ttf` from the system file chooser and it's instantly available. Long-press a custom font to remove it.
+- **Bring your own theme.** The Color-themes picker has an **Import** chip that accepts a URL to a Gogh-style `.properties` file. Long-press to remove.
+- Font size, color theme, font, dark/light and haptics: all change live, no VM restart.
-```
-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)
-```
+## VM is fully configurable
-### Native components
+Everything below is editable from **Settings**:
-| 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 |
+- **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)
+- **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
-All native binaries are built with `-Wl,-z,max-page-size=16384` for compatibility with 16 KB-page Android devices (mandatory on Android 13+).
+RAM and CPU changes take effect on the next start; everything else is hot.
----
+## Diagnostics
-## 🔧 Building from source
+**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.
-### Prerequisites
+## Requirements
-- 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
+| | |
+|---|---|
+| Architecture | ARM64 only (`aarch64`) |
+| OS | Android 9.0+ (API 28), targets API 36 |
+| Storage | ~200 MB app + chosen VM disk (default 2 GB, max 64 GB) |
+| Memory | 2 GB device RAM recommended (VM defaults to 512 MB) |
-### Build pipeline
+## Build
```bash
-git clone https://github.com/ExTV/Podroid.git
-cd Podroid
-
-./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
-```
+git clone https://github.com/ExTV/Podroid.git && cd Podroid
-Or just:
-
-```bash
-./build-all.sh all # everything above, in order
-./build-all.sh deploy # build + install + launch
+./build-all.sh all # kernel + initramfs + rootfs + qemu + termux + APK
+./build-all.sh deploy # the above, plus install + launch
./build-all.sh test # boot validation: deploys APK, polls console.log for "Ready!"
```
-### Inspecting a running VM
-
-```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)
-```
-
----
-
-## 🗺 Roadmap
-
-- [x] Zero-config **Docker** and **LXC** (in addition to Podman) ✅ *1.1.7*
-- [x] `/proc/config.gz` shipped + complete container-kernel feature matrix ✅ *1.1.7*
-- [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*
-- [x] User-loadable terminal fonts (Quick Settings → font picker → `+ Add` chip → pick any `.ttf` via the system file chooser; long-press a custom font to remove) ✅ *next*
-
-Have an idea? [Open an issue](https://github.com/ExTV/Podroid/issues/new).
-
----
-
-## 🤝 Contributing
-
-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.
-
-Found a bug? Please include the contents of `console.log`:
-
-```bash
-adb shell run-as com.excp.podroid.debug cat files/console.log
-```
-
-### For AI assistants
-
-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.
+Individual stages: `kernel`, `initramfs`, `rootfs`, `qemu`, `termux`, `apk`. All container builds are Docker-cached.
----
+**Prereqs:** Docker 20.10+, Android NDK r27c, Android SDK with platform 36 + build-tools.
-## 🙏 Credits
+## Contributing
-Podroid stands on the shoulders of giants:
+Contributions of every size are welcome: bug reports, kernel-config tweaks, new themes, UI polish, X11 input fixes, anything.
-| 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 |
+- **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.
-See [CREDITS.md](CREDITS.md) for the full list of upstream projects, libraries, and contributors.
+## Credits
----
+| | |
+|---|---|
+| [QEMU](https://www.qemu.org) | Machine emulation |
+| [Termux](https://github.com/termux/termux-app) | Terminal emulator engine |
-## 📄 License
+Full list (Linux, Alpine, Podman, TigerVNC, PulseAudio, Limbo and more) in [CREDITS.md](CREDITS.md).
-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.
+## License
-<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>
+[GNU General Public License v2.0](LICENSE). QEMU, Linux, Alpine, Podman and the rest are distributed under their respective upstream licenses.
diff --git a/docs/index.html b/docs/index.html
index 0063167..51a3ac6 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -4,7 +4,7 @@
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Podroid: Linux containers on Android, no root required</title>
- <meta name="description" content="Podroid runs Podman, Docker, and LXC on Android in a real Alpine Linux VM via QEMU with a custom Linux 6.6 kernel. No root, no custom recovery, any ARM64 device." />
+ <meta name="description" content="Podroid runs Podman, Docker, and LXC on Android in a real Alpine Linux VM via QEMU with a custom Linux 7.0.5 kernel, plus an in-app X11 desktop for GUI apps. No root, no custom recovery, any ARM64 device." />
<meta property="og:title" content="Podroid: Linux containers on Android, no root required" />
<meta property="og:description" content="Spin up a real Alpine Linux VM with a full Podman runtime on any Android 9+ ARM64 device. No root, no Magisk, no AVF requirement." />
<meta property="og:type" content="website" />
@@ -551,8 +551,8 @@
<h1>Linux containers on Android.<br /><em>No root required.</em></h1>
<p class="hero-sub">
Podroid spins up a real Alpine Linux VM using QEMU and a custom&nbsp;kernel.<br />
- Run <strong>Podman</strong>, <strong>Docker</strong>, and <strong>LXC</strong> with a polished built-in terminal.<br />
- Install the APK, tap Start, run containers.
+ Run <strong>Podman</strong>, <strong>Docker</strong>, and <strong>LXC</strong> with a polished built-in terminal,<br />
+ or open the in-app <strong>X11 viewer</strong> for GUI apps. Install the APK, tap Start, go.
</p>
<div class="hero-actions">
<a href="https://github.com/ExTV/Podroid/releases" class="btn btn-primary">
@@ -588,8 +588,8 @@
<div class="feature-icon">
<svg width="18" height="18" fill="none" stroke="currentColor" stroke-width="1.8" viewBox="0 0 24 24"><circle cx="12" cy="12" r="3"/><path d="M12 1v4M12 19v4M4.22 4.22l2.83 2.83M16.95 16.95l2.83 2.83M1 12h4M19 12h4M4.22 19.78l2.83-2.83M16.95 7.05l2.83-2.83"/></svg>
</div>
- <h3>Custom Linux 6.6.87 Kernel</h3>
- <p>Compiled from scratch with netfilter, bridge, overlayfs, veth, IPVS, VXLAN, IPsec, and cgroup v2 all built-in. Docker's <code>check-config.sh</code> reports zero fixable complaints.</p>
+ <h3>Custom Linux 7.0.5 Kernel</h3>
+ <p>Compiled from scratch with netfilter, bridge, overlayfs, veth, IPVS, VXLAN, IPsec, cgroup v2, and binfmt_misc all built-in. Docker's <code>check-config.sh</code> reports zero fixable complaints.</p>
</div>
<div class="feature-card">
@@ -597,7 +597,7 @@
<svg width="18" height="18" fill="none" stroke="currentColor" stroke-width="1.8" viewBox="0 0 24 24"><rect x="2" y="3" width="20" height="14" rx="2"/><polyline points="8 21 12 17 16 21"/></svg>
</div>
<h3>Real Terminal</h3>
- <p>Termux TerminalView with xterm-256color, proper PTY, full mouse support, 114 color themes, 13 fonts, and an extra-keys bar with F1–F12, ESC, CTRL, ALT.</p>
+ <p>Termux TerminalView with xterm-256color, proper PTY, full mouse support, 122 color themes, 13 fonts (plus your own <code>.ttf</code> via the system file picker), and an extra-keys bar with F1–F12, ESC, CTRL, ALT.</p>
</div>
<div class="feature-card">
@@ -621,7 +621,31 @@
<svg width="18" height="18" fill="none" stroke="currentColor" stroke-width="1.8" viewBox="0 0 24 24"><path d="M13 2L3 14h9l-1 8 10-12h-9l1-8z"/></svg>
</div>
<h3>Persistent &amp; Fast</h3>
- <p>Overlayfs over a persistent ext4 image. Containers, packages, and configs survive reboots. ZRAM swap gives 2× effective RAM. Boots in 6–15 seconds.</p>
+ <p>Overlayfs over a persistent ext4 image. Containers, packages, and configs survive reboots. ZRAM swap gives 2× effective RAM. Boots in 6–30 seconds.</p>
+ </div>
+
+ <div class="feature-card">
+ <div class="feature-icon">
+ <svg width="18" height="18" fill="none" stroke="currentColor" stroke-width="1.8" viewBox="0 0 24 24"><rect x="2" y="3" width="20" height="14" rx="2"/><line x1="8" y1="21" x2="16" y2="21"/><line x1="12" y1="17" x2="12" y2="21"/></svg>
+ </div>
+ <h3>In-app X11 Desktop</h3>
+ <p>Tap the monitor icon in the terminal and an in-app viewer opens, talking RFB to <code>Xvnc</code> inside the VM. Touch becomes mouse, soft-keyboard becomes keyboard, and PCM audio streams from PulseAudio. Run <code>firefox</code>, <code>xterm</code>, anything from Alpine.</p>
+ </div>
+
+ <div class="feature-card">
+ <div class="feature-icon">
+ <svg width="18" height="18" fill="none" stroke="currentColor" stroke-width="1.8" viewBox="0 0 24 24"><circle cx="12" cy="12" r="10"/><line x1="12" y1="8" x2="12" y2="12"/><line x1="12" y1="16" x2="12.01" y2="16"/></svg>
+ </div>
+ <h3>One-tap Diagnostics</h3>
+ <p><strong>Settings → Export Diagnostic Log</strong> bundles app info, settings, VM state, app logcat, and the full QEMU console into a single <code>log.txt</code> and shares it via the system share sheet. No ADB needed to file a useful bug report.</p>
+ </div>
+
+ <div class="feature-card">
+ <div class="feature-icon">
+ <svg width="18" height="18" fill="none" stroke="currentColor" stroke-width="1.8" viewBox="0 0 24 24"><polyline points="22 12 18 12 15 21 9 3 6 12 2 12"/></svg>
+ </div>
+ <h3>Tuned for Software Emulation</h3>
+ <p>KVM needs root, so we leaned hard on TCG instead. Multi-thread TCG with a 512 MB translation cache, a dedicated I/O thread for the rootfs disk, ZRAM lz4 swap at half RAM, and <code>mitigations=off</code> in the guest combine for a 5–15% CPU win. Native 16 KB page alignment, so Pixel 8/9/10 are first-class.</p>
</div>
</div>
@@ -687,7 +711,7 @@
</tr>
<tr>
<td class="row-label">Custom kernel</td>
- <td class="col-podroid"><span class="check">✓ Linux 6.6.87</span></td>
+ <td class="col-podroid"><span class="check">✓ Linux 7.0.5</span></td>
<td><span class="cross">✗ host kernel</span></td>
<td><span class="check">✓</span></td>
</tr>
@@ -753,7 +777,7 @@
│ │ /sbin/init (busybox) │ │
│ │ OpenRC (PID 1) │ │
│ │ ┌──────────┐ ┌──────────────┐ │ │
- │ │ │ Podman + │ │ Linux 6.6 │ │ │
+ │ │ │ Podman + │ │ Linux 7.0.5 │ │ │
└──►│ │ Docker │ │ (custom) │ │◄───┘
boot stages │ │ + LXC │ └──────────────┘ │ libpodroid-bridge.so
│ └──────────┘ │ PTY ↔ virtio-console
@@ -772,7 +796,7 @@ qmp.sock → runtime port-forward control</div>
<div class="step-num">1</div>
<div class="step-body">
<h4>QEMU loads the kernel</h4>
- <p>Custom Linux 6.6.87 + a tiny initramfs and a 41 MB Alpine squashfs are extracted from APK assets on first launch.</p>
+ <p>Custom Linux 7.0.5 + a tiny initramfs and an Alpine squashfs are extracted from APK assets on first launch.</p>
</div>
</div>
<div class="step">
@@ -819,7 +843,7 @@ qmp.sock → runtime port-forward control</div>
</div>
<div class="qs-step">
<div class="qs-step-num">3</div>
- <p><strong>Tap Start VM.</strong> Watch the boot progress; typically ready in 6–15 seconds.</p>
+ <p><strong>Tap Start VM.</strong> Watch the boot progress; typically ready in 6–30 seconds.</p>
</div>
<div class="qs-step">
<div class="qs-step-num">4</div>
@@ -831,18 +855,20 @@ qmp.sock → runtime port-forward control</div>
</div>
</div>
- <div class="code-block"><span class="c-comment"># Podman: works out of the box</span>
-<span class="c-prompt"># </span><span class="c-cmd">podman run --rm alpine echo hello</span>
+ <div class="code-block"><span class="c-comment"># Podman: rootless, works out of the box</span>
+<span class="c-prompt"># </span><span class="c-cmd">podman run --rm alpine echo hi</span>
-<span class="c-comment"># Docker: install + start, then go</span>
-<span class="c-prompt"># </span><span class="c-cmd">apk add docker &amp;&amp; rc-service docker start</span>
+<span class="c-comment"># Docker: pre-installed, auto-started</span>
<span class="c-prompt"># </span><span class="c-cmd">docker run -d -p 8080:80 nginx</span>
-<span class="c-comment"># LXC: bridge + MASQUERADE pre-configured</span>
-<span class="c-prompt"># </span><span class="c-cmd">apk add lxc lxc-templates</span>
-<span class="c-prompt"># </span><span class="c-cmd">lxc-create -t busybox -n test &amp;&amp; lxc-start -n test</span>
+<span class="c-comment"># LXC: pre-installed, bridge ready</span>
+<span class="c-prompt"># </span><span class="c-cmd">lxc-create -t alpine -n test</span>
+<span class="c-prompt"># </span><span class="c-cmd">lxc-start -n test</span>
+
+<span class="c-comment"># GUI apps: tap the monitor icon</span>
+<span class="c-prompt"># </span><span class="c-cmd">apk add firefox &amp;&amp; firefox &amp;</span>
-<span class="c-comment"># SSH in from your laptop</span>
+<span class="c-comment"># SSH (enable in Settings)</span>
<span class="c-prompt">$ </span><span class="c-cmd">ssh root@&lt;phone-ip&gt; -p 9922</span></div>
</div>
</div>
@@ -885,10 +911,17 @@ qmp.sock → runtime port-forward control</div>
</div>
</details>
+ <details>
+ <summary>Can I run GUI apps like Firefox?</summary>
+ <div class="faq-answer">
+ Yes. Tap the monitor icon in the terminal's top bar to open the in-app X11 viewer. It speaks RFB 3.8 to <code>Xvnc</code> running inside the VM and streams audio from PulseAudio. Then just <code>apk add firefox</code> (or anything else from the Alpine repos) and launch it from the shell. Touch becomes mouse, the soft-keyboard becomes keyboard, and the picture letterboxes to your phone's aspect ratio.
+ </div>
+ </details>
+
<details>
<summary>Can I access my Android files from the VM?</summary>
<div class="faq-answer">
- Yes. The Android Downloads folder is mounted into the VM via <code>virtio-9p</code>. Files you drop in Downloads are accessible inside the guest immediately.
+ Yes. Toggle <strong>Downloads folder sharing</strong> in Settings and the Android Downloads folder is exposed to the VM via <code>virtio-9p</code>, mounted inside the guest at <code>/mnt/downloads</code>. Files you drop in Downloads on the phone show up there immediately, and anything the VM writes to <code>/mnt/downloads</code> appears back in Downloads.
</div>
</details>