Skip to content

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

docs: rewrite README with better structure and organization

ExTv6870c1b96623
diff --git a/README.md b/README.md
index c89f6fa..86972e8 100644
--- a/README.md
+++ b/README.md
@@ -1,141 +1,158 @@
# Podroid
+<p align="center">
+ <a href="https://github.com/ExTV/Podroid/releases">
+ <img src="https://img.shields.io/github/v/release/ExTV/Podroid?include_prereleases&label=Latest%20Release" alt="Latest Release">
+ </a>
+ <a href="https://github.com/ExTV/Podroid/blob/main/LICENSE">
+ <img src="https://img.shields.io/github/license/ExTV/Podroid?color=blue" alt="License">
+ </a>
+ <a href="https://github.com/ExTV/Podroid">
+ <img src="https://img.shields.io/github/last-commit/ExTV/Podroid/main?color=green" alt="Last Commit">
+ </a>
+</p>
+
**Run Linux containers on your Android phone — no root required.**
Podroid spins up a lightweight Alpine Linux VM using QEMU and gives you a fully working [Podman](https://podman.io) container runtime with a built-in terminal. Install the APK, tap Start, and you're running containers in under a minute.
---
+## Quick Start
+
+1. **Install** the APK from [Releases](https://github.com/ExTV/Podroid/releases)
+2. **Open** Podroid and tap **Start VM**
+3. **Wait** ~20 seconds — boot progress shows 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
+```
+
+---
+
## Features
### Container Runtime
-- **Podman** with crun, netavark, and slirp4netns — no root daemon, rootless by default
-- **Persistence** — packages, configs, and container images survive restarts via overlayfs
-- **Internet access** out of the box via QEMU SLIRP networking
-- `podman run --rm -it alpine sh` — works immediately after first boot
+- **Podman** — rootless container runtime with full Docker compatibility
+- **Persistence** — packages, configs, and images survive restarts via overlayfs
+- **Internet access** — out of the box via QEMU SLIRP networking
### Terminal
-- Full VT100/xterm emulation via [Termux](https://github.com/termux/termux-app)'s TerminalView
-- **Real PTY** — proper job control, signal handling, and escape sequences
+- **Full VT100/xterm** — via Termux TerminalView
+- **Real PTY** — proper job control, signals, and escape sequences
- **114 color themes** — Dracula, Nord, Solarized, Tokyo Night, Catppuccin, Gruvbox, and 108 more
-- **13 terminal fonts** — JetBrains Mono, Fira Code, Cascadia Code, Source Code Pro, Hack, and more
-- **Mouse support** — full CSI mouse tracking for TUI apps (btop, htop, mc, vim)
-- **Extra keys** — ESC, TAB, CTRL, ALT (sticky toggles), arrows, HOME, END, PGUP, PGDN, F1–F12, and common symbols
-- **Auto-resize** — TUI apps (vim, btop, nano) update dimensions on keyboard open/close
-- **Bell feedback** — haptic vibration on bell character
+- **13 fonts** — JetBrains Mono, Fira Code, Cascadia Code, Source Code Pro, Hack, and more
+- **Mouse support** — full CSI mouse tracking for btop, htop, mc, vim
+- **Extra keys** — ESC, TAB, CTRL, ALT (sticky), arrows, F1–F12, and common symbols
+- **Auto-resize** — vim, btop, nano update on keyboard open/close
### Networking
-- **Port forwarding** — expose VM services to your Android device with one tap
-- **Protocol support** — TCP, UDP, or both
-- **Runtime control** — add and remove forwards while the VM is running via QMP
-- **Service presets** — one-tap setup for common services:
- - Pi-hole (DNS + web), Nginx, Gitea, Grafana
-- **Built-in SSH** — connect from any SSH client on port 9922
+- **Port forwarding** — expose VM services to your Android device
+- **Runtime control** — add/remove forwards while VM runs via QMP
+- **Service presets** — one-tap setup for Pi-hole, Nginx, Gitea, Grafana
+- **SSH** — built-in Dropbear on port 9922
### Storage
-- **Configurable size** — 2, 4, 8, 16, 32, or 64 GB
-- **Downloads sharing** — mount your Android Downloads folder into the VM via virtio-9p
+- **2–64 GB** — configurable persistent storage
+- **Downloads sharing** — mount Android Downloads via virtio-9p
### Performance
-- **ARM64-native** — runs as aarch64 on your device's CPU via QEMU TCG
-- **Multi-core** — configurable CPU count (1–N based on your device)
-- **Allocatable RAM** — 512 MB default, adjustable to your workload
-- **GICv3, MTTCG** — hardware acceleration for the emulated interrupt controller and multi-threaded TCG
+- **ARM64-native** — runs on your device's CPU via QEMU TCG
+- **Multi-core** — configurable CPU count
+- **512 MB+** — allocatable RAM (default)
---
-## Quick Start
+## Requirements
-1. Install the APK from [Releases](https://github.com/ExTV/Podroid/releases)
-2. Open Podroid and tap **Start VM**
-3. Wait ~20 seconds — boot progress shows 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
-```
+| | |
+|---|---|
+| **Device** | arm64 Android (most phones from 2018+) |
+| **Android** | 8.0+ (API 26) |
+| **Storage** | ~150 MB app + VM disk size |
---
## How It Works
```
-Android App
-├── Foreground Service ← keeps the VM alive
-├── PodroidQemu engine
-│ ├── libqemu-system-aarch64 ← QEMU (TCG, no KVM)
-│ ├── podroid-bridge ← PTY ↔ serial.sock relay
-│ └── QMP socket ← port forwarding + VM control
-└── Alpine Linux VM
- ├── initramfs (read-only base)
- ├── ext4 disk (persistent overlay)
- ├── Dropbear SSH (port 22)
- └── Podman + crun + netavark + slirp4netns
+┌─────────────────────────────────────────────────────────┐
+│ Android Device │
+│ │
+│ ┌──────────────┐ ┌──────────────────────────────┐ │
+│ │ Podroid App │ │ Foreground Service │ │
+│ │ │ │ (keeps VM alive) │ │
+│ └──────────────┘ └──────────────┬───────────────┘ │
+│ │ │ │
+│ ▼ ▼ │
+│ ┌─────────────────────────────────────────────┐ │
+│ │ QEMU TCG VM │ │
+│ │ ┌─────────┐ ┌──────────┐ ┌───────────┐ │ │
+│ │ │ Kernel │ │ Initramfs│ │ ext4 disk │ │ │
+│ │ │vmlinuz │ │ (Alpine) │ │(overlayfs)│ │ │
+│ │ └─────────┘ └──────────┘ └───────────┘ │ │
+│ │ │ │
+│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
+│ │ │ Podman │ │ Dropbear │ │ SLIRP │ │ │
+│ │ │ │ │ SSH :22 │ │ Net │ │ │
+│ │ └──────────┘ └──────────┘ └──────────┘ │ │
+│ └─────────────────────────────────────────────┘ │
+│ │ │
+│ ▼ │
+│ ┌─────────────────────────────────────────────┐ │
+│ │ Terminal (Termux TerminalView) │ │
+│ │ PTY ↔ podroid-bridge ↔ serial socket │ │
+│ └─────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────┘
```
-**Boot:** QEMU loads a Linux kernel + initramfs. A two-phase init mounts a persistent ext4 disk as an overlayfs upper layer. Everything you install or pull persists across reboots.
-
-**Terminal:** Termux allocates a real PTY for the terminal session. A native bridge binary relays data between the PTY and QEMU's serial socket. Mouse events and resize signals flow through the same path, so TUI apps work correctly.
+**Boot Sequence:**
+1. QEMU loads Linux kernel + initramfs
+2. Phase 1 init mounts persistent ext4 as overlayfs
+3. Phase 2 configures networking, Podman, SSH, getty
+4. Terminal connects to serial console
-**Networking:** QEMU user-mode networking (SLIRP) gives the VM `10.0.2.15`. Port forwards are managed via QEMU's `-netdev hostfwd` at startup and QMP at runtime.
+**Networking:** QEMU user-mode networking (SLIRP) gives VM `10.0.2.15`. Port forwards via `-netdev hostfwd` at startup, QMP at runtime.
---
## Building from Source
-Requires Docker with multi-arch support and Android SDK.
-
```sh
-# Build the VM initramfs and kernel (requires Docker)
+# 1. Build VM initramfs and kernel (requires Docker)
./docker-build-initramfs.sh
-# Build QEMU and the terminal bridge binary (requires Docker)
+# 2. Build QEMU + terminal bridge (requires Docker)
./build-qemu-android.sh
-# Build the APK
+# 3. Build the APK
./gradlew assembleDebug
```
-Install: `adb install -r app/build/outputs/apk/debug/app-debug.apk`
-
----
-
-## Requirements
-
-- **arm64** Android device (most phones from 2018 onward)
-- Android **8.0+** (API 26)
-- ~150 MB storage for the app, plus your chosen VM disk size
+**Install:**
+```sh
+adb install -r app/build/outputs/apk/debug/app-debug.apk
+```
---
## AI/LLM Integration
-Podroid includes a comprehensive `skill.md` file that provides AI assistants with complete project context. This enables AI tools like Claude, OpenCode, or any LLM to work on Podroid without needing to learn the codebase structure.
+Give AI assistants full context on Podroid with `skill.md`:
-### Using with AI Assistants
-
-**For OpenCode users:**
-```
+```sh
+# OpenCode
/load_skill path/to/skill.md
-```
-**For Claude/Cline users:**
-```
+# Claude/Cline
Read the skill.md file at: /path/to/Podroid/skill.md
```
-The skill file includes:
-- Complete architecture overview
-- All source file locations and purposes
-- Build commands and workflows
-- Known issues and quirks
-- DataStore keys and settings
-- VM boot sequence and networking
-
-This makes it easy to delegate development tasks to AI assistants while maintaining full context.
+The skill file includes complete architecture, all source files, build commands, known issues, and settings.
---
@@ -151,4 +168,4 @@ This makes it easy to delegate development tasks to AI assistants while maintain
## License
-GNU General Public License v2.0
+[GNU General Public License v2.0](LICENSE)
\ No newline at end of file