Skip to content

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

Rewrite README for v1.0.4

ExTv25a99eff0eec
diff --git a/README.md b/README.md
index 52c8d35..e313b07 100644
--- a/README.md
+++ b/README.md
@@ -1,20 +1,8 @@
-# Podroid — Rootless Podman for Android
+# Podroid
-Run Linux containers on your Android phone — no root required. Podroid launches a lightweight Alpine Linux VM via QEMU and gives you a fully working **Podman** container runtime with a built-in terminal emulator.
+**Run Linux containers on Android — no root required.**
-## Features
-
-- **Podman** — pull and run OCI containers (`podman run --rm alpine echo hello`)
-- **Alpine Linux 3.23** — minimal aarch64 VM with full networking
-- **Termux terminal** — proper VT100/xterm emulation with extra keys (Ctrl, arrows, ESC, TAB)
-- **Persistent storage** — 2GB ext4 disk, all VM data survives app restarts via overlayfs
-- **Port forwarding** — forward ports from the VM to the Android host, configurable in Settings
-- **Internet access** — QEMU user-mode networking (SLIRP), ping/wget/curl all work
-- **Job control** — Ctrl+C, Ctrl+Z, Ctrl+D work as expected
-- **One-tap start/stop** — clean Material 3 interface
-- **No root, no host binaries** — fully self-contained, works on any arm64 Android device
-
-## Screenshots
+Podroid spins up a lightweight Alpine Linux VM on your phone using QEMU and gives you a fully working [Podman](https://podman.io) container runtime with a built-in serial terminal.
<p>
<img src="screenshots/1.png" width="24%" />
@@ -23,170 +11,121 @@ Run Linux containers on your Android phone — no root required. Podroid launche
<img src="screenshots/4.png" width="24%" />
</p>
+## Highlights
+
+| | |
+|---|---|
+| **Containers** | Pull and run any OCI image — `podman run --rm -it alpine sh` |
+| **Terminal** | Full xterm emulation with Ctrl, Alt, F1-F12, arrows, and more |
+| **Persistence** | Packages, configs, and container images survive restarts |
+| **Networking** | Internet access out of the box, port forwarding to Android host |
+| **Self-contained** | No root, no Termux, no host binaries — just install the APK |
+
## Requirements
-- Android device with **arm64** (aarch64) CPU
+- **arm64** Android device
- Android **14+** (API 34)
-- ~200MB storage for the app
+- ~150 MB free storage
-## Architecture
+## Quick Start
-```
-┌─────────────────────────────────────────────┐
-│ Podroid App │
-│ │
-│ Home Screen ──► Terminal Screen │
-│ │ (Termux TerminalView) │
-│ │ │ │
-│ ▼ ▼ │
-│ PodroidService TerminalViewModel │
-│ │ (reflection-based │
-│ ▼ session wiring) │
-│ PodroidQemu │
-│ │ ├── stdin/stdout (serial I/O) │
-│ │ └── QMP socket (VM management) │
-│ ▼ │
-│ libqemu-system-aarch64.so │
-│ │ │
-│ ┌───▼───────────────────────────────────┐ │
-│ │ Alpine Linux VM (overlayfs root) │ │
-│ │ ┌─────────────────────────────────┐ │ │
-│ │ │ initramfs (read-only base) │ │ │
-│ │ │ + persistent overlay (ext4 disk)│ │ │
-│ │ ├─────────────────────────────────┤ │ │
-│ │ │ Podman + crun + netavark │ │ │
-│ │ │ fuse-overlayfs + slirp4netns │ │ │
-│ │ │ getty on ttyAMA0 (job control) │ │ │
-│ │ └─────────────────────────────────┘ │ │
-│ └───────────────────────────────────────┘ │
-└─────────────────────────────────────────────┘
-```
-
-## Project Structure
+1. Install the APK from [Releases](https://github.com/ExTV/Podroid/releases)
+2. Open Podroid and tap **Start Podman**
+3. Wait for boot (~20 s) — progress is shown on screen and in the notification
+4. Tap **Open Terminal**
+5. Run containers:
+```sh
+podman run --rm alpine echo hello
+podman run --rm -it alpine sh
+podman run -d -p 8080:80 nginx
```
-├── Dockerfile # Multi-stage initramfs builder
-├── docker-build-initramfs.sh # Build script (produces vmlinuz-virt + initrd.img)
-├── init-podroid # Custom /init for the Alpine VM
-├── app/
-│ └── src/main/
-│ ├── java/com/excp/podroid/
-│ │ ├── PodroidApplication.kt # Asset extraction on startup
-│ │ ├── MainActivity.kt # Single-activity Compose host
-│ │ ├── engine/
-│ │ │ ├── PodroidQemu.kt # QEMU lifecycle + serial I/O
-│ │ │ ├── QmpClient.kt # QMP protocol (port forwarding)
-│ │ │ └── VmState.kt # VM state machine
-│ │ ├── data/repository/
-│ │ │ ├── SettingsRepository.kt # App preferences
-│ │ │ └── PortForwardRepository.kt # Port forward rules
-│ │ ├── service/
-│ │ │ └── PodroidService.kt # Foreground service
-│ │ └── ui/screens/
-│ │ ├── home/ # Start/Stop + status
-│ │ ├── terminal/ # Termux TerminalView + extra keys
-│ │ └── settings/ # Port forwarding + app settings
-│ ├── jniLibs/arm64-v8a/
-│ │ ├── libqemu-system-aarch64.so # Pre-built QEMU
-│ │ └── libslirp.so # Network library
-│ └── assets/
-│ ├── vmlinuz-virt # Alpine kernel (generated)
-│ ├── initrd.img # Alpine initramfs (generated)
-│ └── qemu/ # QEMU firmware files
-```
-
-## Building
-### 1. Build the initramfs
+## Terminal
-Requires Docker with multi-arch support (`docker buildx` or `qemu-user-static`):
+The terminal is powered by [Termux](https://github.com/termux/termux-app)'s `TerminalView` with full VT100/xterm emulation wired directly to the VM's serial console.
-```bash
-./docker-build-initramfs.sh
-```
+**Extra keys bar** (scrollable):
-This produces `app/src/main/assets/vmlinuz-virt` and `app/src/main/assets/initrd.img`.
+`ESC` `TAB` `SYNC` `CTRL` `ALT` `arrows` `HOME` `END` `PGUP` `PGDN` `F1–F12` `-` `/` `|`
-### 2. Build the APK
-
-```bash
-./gradlew assembleDebug
-```
+- **CTRL / ALT** are sticky toggles — tap once, then press a letter
+- **SYNC** manually pushes the terminal dimensions to the VM
+- Terminal size auto-syncs on keyboard open/close so TUI apps (vim, btop, htop) render correctly
+- Bell character triggers haptic feedback
-### 3. Install
-
-```bash
-adb install app/build/outputs/apk/debug/app-debug.apk
-```
-
-## Usage
-
-1. Open Podroid
-2. Tap **Start Podman**
-3. Wait for the VM to boot (~20s)
-4. Tap **Open Terminal**
-5. Run containers:
- ```
- podman run --rm alpine echo hello
- podman run --rm -it alpine sh
- podman run -d -p 8080:80 nginx
- ```
-
-### Port Forwarding
+## Port Forwarding
Forward ports from the VM to your Android device:
1. Go to **Settings**
-2. Add a port forward rule (e.g. TCP 8080 -> 80)
-3. Access the service from your phone at `localhost:8080`
+2. Add a rule (e.g. TCP 8080 -> 80)
+3. Access the service at `localhost:8080` on your phone
-Rules are saved and automatically applied on VM start. You can also add/remove rules while the VM is running via QMP.
+Rules persist across restarts and can be added or removed while the VM is running.
-### Extra Keys
+## How It Works
-The terminal includes an extra keys bar with:
-- **ESC** / **TAB** — standard terminal keys
-- **CTRL** — toggle modifier, then press a key (e.g. CTRL + C to interrupt)
-- **Arrow keys** — navigate in shell history and editors
-- **ALT** — toggle modifier for alt combinations
-- **-** / **/** / **|** — common shell symbols
+```
+Android App
+├── Foreground Service (keeps VM alive)
+├── PodroidQemu
+│ ├── libqemu-system-aarch64.so (QEMU TCG, no KVM)
+│ ├── Serial stdio ←→ TerminalEmulator
+│ └── QMP socket (port forwarding, VM control)
+└── Alpine Linux VM
+ ├── initramfs (read-only base layer)
+ ├── ext4 disk (persistent overlay)
+ ├── getty on ttyAMA0 (job control)
+ └── Podman + crun + netavark + slirp4netns
+```
-## How It Works
+**Boot sequence:** QEMU loads `vmlinuz-virt` + `initrd.img`. A two-phase init (`init-podroid`) mounts a persistent ext4 disk as an overlayfs upper layer over the initramfs. Packages you install and containers you pull are written to the overlay and survive reboots.
-Podroid uses QEMU system emulation (TCG, no KVM) to run a headless aarch64 Alpine Linux VM inside an Android app process.
+**Terminal wiring:** The app cannot fork host processes, so `TerminalSession` is wired to QEMU's serial I/O via reflection — keyboard input goes to QEMU stdin, QEMU stdout feeds the terminal emulator. Terminal dimensions are synced to the VM via `stty` so TUI apps see the correct size.
-### VM Boot
+**Networking:** QEMU user-mode networking (SLIRP) puts the VM at `10.0.2.15`. Port forwarding uses QEMU's `hostfwd`, managed at startup via CLI args and at runtime via QMP.
-The VM boots from an initramfs containing a full Alpine rootfs. A two-phase init script (`init-podroid`) mounts a persistent ext4 disk and creates an overlayfs root — the initramfs is the read-only lower layer, and all changes (installed packages, container images, config files) are stored on the persistent upper layer.
+## Building from Source
-### Terminal
+### 1. Build the initramfs
-The terminal uses Termux's `TerminalView` and `TerminalEmulator` libraries for proper VT100/xterm emulation. Since the app cannot use any host binaries, the `TerminalSession` is created and wired to QEMU's serial console I/O via reflection — keyboard input is drained from the session's internal queue and forwarded to QEMU stdin, while QEMU stdout feeds the terminal emulator.
+Requires Docker with multi-arch support:
-A `getty` process runs on `/dev/ttyAMA0` inside the VM, providing a real controlling TTY with job control so signals like Ctrl+C work correctly.
+```sh
+./docker-build-initramfs.sh
+```
-### Networking
+### 2. Build the APK
-QEMU's user-mode networking (SLIRP) provides internet access with the VM at `10.0.2.15`. Port forwarding uses QEMU's `hostfwd` mechanism, managed at startup via command-line args and at runtime via QMP (`human-monitor-command`).
+```sh
+./gradlew assembleDebug
+adb install -r app/build/outputs/apk/debug/app-debug.apk
+```
-### Key QEMU Flags
+## Project Layout
```
--M virt -cpu max -m 1024 -accel tcg,thread=multi
--kernel vmlinuz-virt -initrd initrd.img
--append "console=ttyAMA0 loglevel=1 quiet"
--device virtio-blk-pci,drive=drive1 -drive file=storage.img,...
--netdev user,id=net0,hostfwd=... -device virtio-net,netdev=net0
--serial stdio -display none
--qmp unix:qmp.sock,server,nowait
+Dockerfile # Multi-stage initramfs builder (Alpine aarch64)
+docker-build-initramfs.sh # One-command build script
+init-podroid # Custom /init for the VM
+
+app/src/main/
+├── java/com/excp/podroid/
+│ ├── engine/ # QEMU lifecycle, QMP client, VM state machine
+│ ├── service/ # Foreground service with boot-stage notifications
+│ ├── data/repository/ # Settings + port forward persistence
+│ └── ui/screens/ # Home, Terminal, Settings (Jetpack Compose)
+├── jniLibs/arm64-v8a/ # Pre-built QEMU + libslirp
+└── assets/ # Kernel + initramfs (generated)
```
## Credits
- [QEMU](https://www.qemu.org) — machine emulation
-- [Alpine Linux](https://alpinelinux.org) — lightweight VM base
+- [Alpine Linux](https://alpinelinux.org) — VM base
- [Podman](https://podman.io) — container runtime
-- [Termux](https://github.com/termux/termux-app) — terminal emulator and terminal view libraries
+- [Termux](https://github.com/termux/termux-app) — terminal emulator libraries
- [Limbo PC Emulator](https://github.com/limboemu/limbo) — pioneered QEMU on Android
## License