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.mdindex 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 ForwardingForward 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