Skip to content

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

Rewrite README with updated features, architecture, and credits

ExTv69d9365f7cb3
diff --git a/README.md b/README.md
index 3f545c7..73a4982 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,22 @@
# Podroid — Rootless Podman for Android
-Run Linux containers on your Android phone. Podroid launches a lightweight Alpine Linux VM via QEMU and gives you a fully working **Podman** container runtime, accessible through a built-in serial terminal.
+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.
## Features
-- **Podman** — pull and run OCI containers (`podman run alpine echo hello`)
-- **Alpine Linux 3.23** — minimal aarch64 VM with networking
-- **Internet access** — QEMU user-mode networking (SLIRP), DNS via 8.8.8.8
-- **Persistent storage** — 2GB ext4 disk for `/var/lib/containers`
-- **Built-in terminal** — serial console UI, no browser needed
-- **One-tap start/stop** — simple Material 3 interface
+- **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
+
+*Coming soon*
## Requirements
@@ -20,25 +27,34 @@ Run Linux containers on your Android phone. Podroid launches a lightweight Alpin
## Architecture
```
-┌──────────────────────────────────────┐
-│ Podroid App │
-│ │
-│ Home Screen ──► Terminal Screen │
-│ │ (serial I/O) │
-│ ▼ │
-│ PodroidQemu (process manager) │
-│ │ │
-│ libqemu-system-aarch64.so │
-│ │ │
-│ ┌───▼──────────────────────────┐ │
-│ │ Alpine Linux VM (initramfs) │ │
-│ │ - Podman + crun │ │
-│ │ - fuse-overlayfs │ │
-│ │ - netavark networking │ │
-│ │ - virtio-net (SLIRP) │ │
-│ │ - virtio-blk (storage) │ │
-│ └──────────────────────────────┘ │
-└──────────────────────────────────────┘
+┌─────────────────────────────────────────────┐
+│ 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
@@ -54,13 +70,17 @@ Run Linux containers on your Android phone. Podroid launches a lightweight Alpin
│ │ ├── 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/ # Serial console UI
-│ │ └── settings/ # App settings
+│ │ ├── terminal/ # Termux TerminalView + extra keys
+│ │ └── settings/ # Port forwarding + app settings
│ ├── jniLibs/arm64-v8a/
│ │ ├── libqemu-system-aarch64.so # Pre-built QEMU
│ │ └── libslirp.so # Network library
@@ -104,23 +124,56 @@ adb install app/build/outputs/apk/debug/app-debug.apk
```
podman run --rm alpine echo hello
podman run --rm -it alpine sh
+ podman run -d -p 8080:80 nginx
```
-> **Tip:** Use `ping`, `wget`, or `curl` to test connectivity.
+### 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`
+
+Rules are saved and automatically applied on VM start. You can also add/remove rules while the VM is running via QMP.
+
+### Extra Keys
+
+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
## How It Works
-Podroid uses QEMU system emulation (TCG) to run a headless aarch64 Alpine Linux VM inside an Android app process. The VM boots from an initramfs containing a full Alpine rootfs with Podman, crun, fuse-overlayfs, and netavark pre-installed.
+Podroid uses QEMU system emulation (TCG, no KVM) to run a headless aarch64 Alpine Linux VM inside an Android app process.
+
+### VM Boot
+
+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.
+
+### Terminal
+
+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.
+
+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.
+
+### Networking
+
+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`).
-Communication happens via QEMU's serial console (`-serial stdio`), which maps to the Android process's stdin/stdout. The app reads stdout in a background thread and accumulates it in a StateFlow for the Compose terminal UI.
+### Key QEMU Flags
-Key QEMU flags:
```
-M virt -cpu max -m 1024 -accel tcg,thread=multi
-kernel vmlinuz-virt -initrd initrd.img
-append "console=ttyAMA0 loglevel=1 quiet"
--netdev user,id=net0 -device virtio-net,netdev=net0
+-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
```
## Credits
@@ -128,6 +181,7 @@ Key QEMU flags:
- [QEMU](https://www.qemu.org) — machine emulation
- [Alpine Linux](https://alpinelinux.org) — lightweight VM base
- [Podman](https://podman.io) — container runtime
+- [Termux](https://github.com/termux/termux-app) — terminal emulator and terminal view libraries
- [Limbo PC Emulator](https://github.com/limboemu/limbo) — pioneered QEMU on Android
## License