Skip to content

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

Revise README for clarity and formatting improvements

ExTV5d159f69055c
diff --git a/README.md b/README.md
index f4e40f2..449a3d6 100644
--- a/README.md
+++ b/README.md
@@ -1,69 +1,84 @@
# Podroid
+<p align="center">
+ <img src="https://img.shields.io/github/stars/ExTV/Podroid?style=for-the-badge" alt="Stars">
+ <img src="https://img.shields.io/github/forks/ExTV/Podroid?style=for-the-badge" alt="Forks">
+ <img src="https://img.shields.io/github/downloads/ExTV/Podroid/total?style=for-the-badge" alt="Downloads">
+</p>
+
+<p align="center">
+ <strong>Run Linux containers on your Android phone — no root required.</strong>
+</p>
+
<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">
+ <img src="https://img.shields.io/github/v/release/ExTV/Podroid?include_prereleases&style=flat-square&label=Download" alt="Download">
</a>
<a href="https://github.com/ExTV/Podroid/blob/main/LICENSE">
- <img src="https://img.shields.io/github/license/ExTV/Podroid?color=blue&style=flat" 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">
+ <img src="https://img.shields.io/github/license/ExTV/Podroid?style=flat-square" alt="License">
</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
-```
+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.
---
## Features
### Container Runtime
-- **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
+- **Rootless Podman** — Full Docker-compatible container runtime with no root access required
+- **Persistent Storage** — Packages, configurations, and images survive restarts via overlayfs
+- **Out-of-the-box Networking** — Internet access enabled via QEMU SLIRP
### Terminal
-- **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 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
+- **VT100/xterm Emulation** — Powered by Termux TerminalView
+- **Real PTY** — Proper job control, signal handling, and escape sequence support
+- **114 Color Themes** — Dracula, Nord, Solarized, Tokyo Night, Catppuccin, Gruvbox, and more
+- **13 Curated Fonts** — JetBrains Mono, Fira Code, Cascadia Code, Source Code Pro, Hack, and more
+- **Full Mouse Support** — CSI mouse tracking for btop, htop, mc, vim, and other TUI apps
+- **Extra Keys Bar** — ESC, TAB, CTRL, ALT (sticky), arrows, F1–F12, and common symbols
+- **Auto-resize** — vim, btop, nano automatically adapt to screen changes
### Networking
-- **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
+- **Port Forwarding** — Expose VM services to your Android device via runtime QMP control
+- **Service Presets** — One-tap setup for Pi-hole, Nginx, Gitea, Grafana, and more
+- **Built-in SSH** — Dropbear server running on port 9922
+
+### Performance
+- **ARM64-native** — Executes directly on your device's CPU
+- **Multi-core Support** — Configure 1-8 CPU cores
+- **Allocatable RAM** — 512MB to 4GB configurable
### Storage
-- **2–64 GB** — configurable persistent storage
-- **Downloads sharing** — mount Android Downloads via virtio-9p
+- **2–64 GB** — Configurable persistent storage
+- **Downloads Sharing** — Mount Android Downloads folder via virtio-9p
-### Performance
-- **ARM64-native** — runs on your device's CPU via QEMU TCG
-- **Multi-core** — configurable CPU count
-- **512 MB+** — allocatable RAM (default)
+---
+
+## Quick Start
+
+1. **Download** the latest APK from [Releases](https://github.com/ExTV/Podroid/releases)
+2. **Install** and open Podroid
+3. **Tap Start VM** — Boot progress shows in the notification
+4. **Wait ~20 seconds** for "Ready" status
+5. **Tap Open Terminal** to access the shell
+6. **Run containers:**
+
+```sh
+# Hello world
+podman run --rm alpine echo hello
+
+# Interactive shell
+podman run --rm -it alpine sh
+
+# Run Nginx
+podman run -d -p 8080:80 nginx
+
+# List running containers
+podman ps -a
+```
---
@@ -71,7 +86,7 @@ podman run -d -p 8080:80 nginx
| | |
|---|---|
-| **Device** | arm64 Android (most phones from 2018+) |
+| **Device** | ARM64 Android device (most phones from 2018+) |
| **Android** | 9.0+ (API 28) |
| **Storage** | ~150 MB app + VM disk size |
@@ -79,68 +94,115 @@ podman run -d -p 8080:80 nginx
## How It Works
-**Architecture:**
-
```
-App -> Foreground Service -> QEMU TCG VM -> Alpine Linux
- |
- +-------------------+-------------------+
- | | |
- Kernel Initramfs ext4 disk
- (vmlinuz) (Alpine) (overlayfs)
- | | |
- +-------------------+-------------------+
- |
- +-------------------+-------------------+
- | | |
- Podman Dropbear SLIRP
- (SSH:22) (networking)
+┌─────────────────────────────────────────────────────────────┐
+│ Android App │
+│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │
+│ │ Service │ │ QEMU VM │ │ Compose UI │ │
+│ │ (WakeLock) │ │ (TCG) │ │ Terminal View │ │
+│ └─────────────┘ └───────┬─────┘ └─────────┬───────┘ │
+└───────────────────────────┼──────────────────┼──────────────┘
+ │ │
+ ┌──────▼───────┐ ┌──────▼──────┐
+ │ Alpine Linux │ │ PTY Bridge │
+ │ + Podman │◄──│ (serial) │
+ │ + Dropbear │ └─────────────┘
+ │ + SLIRP │
+ └──────────────┘
```
**Boot Sequence:**
-1. QEMU loads Linux kernel + initramfs
+1. QEMU loads custom 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 VM `10.0.2.15`. Port forwards via `-netdev hostfwd` at startup, QMP at runtime.
+3. Phase 2 configures networking, Podman, SSH, and serial console
+4. Terminal connects to serial console for interactive shell
---
## Building from Source
-Requires Docker and Android NDK.
+### Prerequisites
-```sh
-# 1. Build VM initramfs and kernel (requires Docker with multi-arch)
+- Docker (for VM initramfs and QEMU builds)
+- Android NDK (for Termux terminal library)
+- Android SDK
+
+### Build Steps
+
+```bash
+# Clone the repository
+git clone https://github.com/ExTV/Podroid.git
+cd Podroid
+
+# 1. Build VM initramfs and kernel
./docker-build-initramfs.sh
-# 2. Build QEMU + terminal bridge (requires Docker)
+# 2. Build QEMU and terminal bridge
./build-qemu-android.sh
-# 3. Rebuild Termux terminal library with 16KB page alignment (requires NDK)
+# 3. Rebuild Termux terminal library with 16KB page alignment
./build-termux-android.sh
# 4. Build the APK
./gradlew assembleDebug
-```
-**Install:**
-```sh
+# 5. Install
adb install -r app/build/outputs/apk/debug/app-debug.apk
```
---
-## AI/LLM Integration
+## Architecture
-Give AI assistants full context on Podroid with `skill.md`:
+### Project Structure
-```sh
-# OpenCode
-/load_skill path/to/skill.md
+```
+Podroid/
+├── app/ # Android application
+│ └── src/main/
+│ ├── java/ # Kotlin source code
+│ ├── jniLibs/ # Native libraries (QEMU, bridge)
+│ └── assets/ # VM kernel, initramfs, fonts, themes
+├── init-podroid # VM initialization script
+├── podroid-bridge.c # PTY ↔ Serial socket relay
+├── Dockerfile # VM initramfs builder
+├── Dockerfile.qemu # QEMU Android cross-compiler
+├── build-termux-android.sh # Termux native library builder
+└── build-qemu-android.sh # QEMU Android builder
+```
+
+### Native Components
+
+| File | Description |
+|------|-------------|
+| `libqemu-system-aarch64.so` | QEMU executable (PIE, 16KB page aligned) |
+| `libslirp.so` | SLIRP networking library |
+| `libpodroid-bridge.so` | Terminal PTY ↔ Serial socket relay |
+| `libtermux.so` | Terminal emulation library (16KB page aligned) |
+
+---
+
+
+
+## TODO
+
+
+- [ ] **Better QEMU performance** — TCG optimization, and performance profiling
+- [ ] **Better terminal integration** — Improve TUI app support (nvim, vim, less, nano) with proper CSI escape sequence handling and resize propagation
+- [ ] **User account instead of root** — Run VM processes as a non-root user for improved security
+- [ ] **Docker socket compatibility** — Proper service scripts for `rc-service` and `docker` commands
+
+---
+
+## Contributing
+
+Contributions are welcome! Please read the [skill.md](skill.md) for complete project context before submitting PRs.
+
+### For AI Assistants
+
+Give AI assistants full context on Podroid:
-# Claude/Cline
+```markdown
Read the skill.md file at: /path/to/Podroid/skill.md
```
@@ -150,14 +212,16 @@ The skill file includes complete architecture, all source files, build commands,
## Credits
-- [QEMU](https://www.qemu.org) — machine emulation
-- [Alpine Linux](https://alpinelinux.org) — VM base
-- [Podman](https://podman.io) — container runtime
-- [Termux](https://github.com/termux/termux-app) — terminal emulator
-- [Limbo PC Emulator](https://github.com/limboemu/limbo) — QEMU on Android groundwork
+| Project | Purpose |
+|---------|---------|
+| [QEMU](https://www.qemu.org) | Machine emulation and virtualization |
+| [Alpine Linux](https://alpinelinux.org) | Lightweight VM base |
+| [Podman](https://podman.io) | Rootless container runtime |
+| [Termux](https://github.com/termux/termux-app) | Terminal emulator for Android |
+| [Limbo PC Emulator](https://github.com/limboemu/limbo) | QEMU on Android groundwork |
---
## License
-[GNU General Public License v2.0](LICENSE)
\ No newline at end of file
+[GNU General Public License v2.0](LICENSE)