A rootless Android app that boots Alpine Linux: run containers (Podman/Docker/LXC) and GUI desktop apps.
perf: QEMU TCG tuning for container-heavy workloads
ExTvd620f20055bb
diff --git a/CLAUDE.md b/CLAUDE.mdnew file mode 100644index 0000000..157423b--- /dev/null+++ b/CLAUDE.md@@ -0,0 +1,111 @@+# CLAUDE.md++This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.++## What Is This++Podroid is an Android app that runs a rootless Alpine Linux VM via QEMU (ARM64) to provide a Podman container runtime without root. It embeds a Termux-based VT100 terminal emulator and communicates with the VM over QEMU serial/unix sockets.++## Build Commands++All components are coordinated by `build-all.sh`:++```bash+./build-all.sh kernel # Build custom kernel only (podroid_kernel.config, ~5–10 min)+./build-all.sh initramfs # Build custom kernel + Alpine initramfs (~10–15 min total)+./build-all.sh qemu # Build QEMU + podroid-bridge via Docker (~30 min first time)+./build-all.sh termux # Build libtermux.so via local NDK (16KB page alignment)+./build-all.sh apk # Build Android APK via Gradle+./build-all.sh all # Build everything+./build-all.sh deploy # Full deploy workflow+./build-all.sh test # Boot validation: deploys APK, polls console.log for "Ready!"+```++`podroidKernelVersion` in `gradle.properties` controls the Linux version downloaded. Docker layer-caches the kernel build; only rebuilds if `podroid_kernel.config` or the version changes.++**APK only:**+```bash+./gradlew assembleDebug+./gradlew installDebug+```++**Monitor VM boot:**+```bash+adb logcat -s PodroidQemu+adb shell run-as com.excp.podroid.debug cat files/console.log+```++The app uses debug build for all releases (release signing not configured). Native binaries require 16KB page alignment (`-Wl,-z,max-page-size=16384`) — mandatory on Android 13+.++## Architecture++### Data Flow++```+Terminal UI (Compose)+ ↕ TerminalSession (Termux JNI)+libpodroid-bridge.so ←→ serial.sock / ctrl.sock ←→ QEMU ←→ ttyAMA0 (Alpine)+```++- **Terminal I/O:** TerminalSession runs `libpodroid-bridge.so` as a process; the bridge connects `serial.sock` (I/O relay) and `ctrl.sock` (SIGWINCH / resize signaling)+- **Port forwarding:** `QmpClient` sends `netdev_add`/`netdev_remove` commands to `qmp.sock` at runtime+- **Boot monitoring:** `PodroidQemu` reads `serial.sock` until it detects the "Ready!" marker, logging all output to `console.log`++### Key Components++**`engine/PodroidQemu.kt`** — the core singleton. Builds and launches the QEMU process, monitors boot output from serial, manages `TerminalSession` lifecycle, and auto-starts `podroid-bridge` after boot. State machine: `Idle → Starting → Running → Stopped` (see `VmState.kt`).++**`service/PodroidService.kt`** — foreground service that owns the QEMU process. Holds a `WakeLock`, updates the persistent notification with boot stages, and handles graceful stop when the app is swiped from recents.++**`podroid-bridge.c`** — native C binary (compiled to `libpodroid-bridge.so`) that Termux runs as a subprocess. Bidirectionally relays PTY ↔ `serial.sock`, answers ESC window-size queries locally, and sends `RESIZE rows cols\n` to `ctrl.sock` on SIGWINCH.++**`init-podroid`** — two-phase Alpine init script embedded as an asset. Phase 1 mounts overlayfs over `storage.img`; Phase 2 sets up cgroup v2, SLIRP networking, Podman, and Dropbear SSH, then prints the boot stage markers consumed by `PodroidQemu`.++**`data/repository/`** — `SettingsRepository` (RAM, CPUs, storage size, theme, SSH toggle) and `PortForwardRepository` (persistent rules) both use Jetpack DataStore. No database.++### Asset Extraction++`PodroidApplication.kt` copies `qemu/`, `vmlinuz-virt`, and `initrd.img` from APK assets to `filesDir` on startup (size-checked to skip if unchanged). All native binaries in `jniLibs/arm64-v8a/` are extracted automatically by Android.++### Navigation++Single-activity Compose app: `NavGraph.kt` routes `setup → home → terminal / settings`. The setup screen only appears until setup is marked complete in DataStore.++## Native Binaries in `jniLibs/arm64-v8a/`++| File | What it is |+|---|---|+| `libqemu-system-aarch64.so` | QEMU TCG emulator (PIE executable, 16KB aligned) |+| `libpodroid-bridge.so` | PTY ↔ serial relay (PIE executable, 16KB aligned) |+| `libtermux.so` | Termux terminal emulator JNI (rebuilt for 16KB pages) |+| `libslirp.so` | SLIRP user-mode networking (statically linked into QEMU) |++These are executed directly via `ProcessBuilder` / `TerminalSession`, not loaded as JNI libraries despite the `.so` extension.++## QEMU Command Construction++`PodroidQemu.buildCommand()` constructs the full QEMU cmdline including:+- `-serial unix:serial.sock` / `-chardev socket,path=ctrl.sock` / `-qmp unix:qmp.sock`+- RAM and CPU count from `SettingsRepository`+- Virtio block device backed by `storage.img` (resized on first boot to configured size)+- SLIRP networking with runtime port forwards via `QmpClient` (`netdev_add`/`netdev_remove` over `qmp.sock`)++All socket and image paths are under `context.filesDir`.++## Performance Tuning (TCG, no KVM)++All tuning applies under software emulation only — KVM is impossible without root.++**In `PodroidQemu.buildCommand()`:**+- `tcg,thread=multi` — one host thread per vCPU (already enabled)+- `tb-size`: 256 MB for <2 GB RAM, 512 MB for ≥2 GB — larger TB cache reduces re-translation for JIT-heavy workloads (Node, JVM in containers)+- `iothread=iothread0` on `virtio-blk-pci` — dedicated I/O thread decoupled from vCPU threads; biggest single win for container image pull/extraction+- `mitigations=off` in guest kernel cmdline — safe inside TCG VM (speculative execution attacks can't cross the emulated ISA boundary); 5–15% CPU gain+- `elevator=mq-deadline` in guest kernel cmdline — request merging for virtio-blk random writes (Podman overlay graph driver)+**In `init-podroid`:**+- ZRAM swap at half physical RAM using lz4 — gives 1.5–2× effective memory with near-zero I/O cost; swapon at priority 100 so it's preferred over any file swap++**In `Dockerfile` (QEMU build):**+- `-O3 -flto=thin` in `--extra-cflags` / `--extra-ldflags` — LLVM thin LTO optimises across QEMU's translation units including the TCG hot path; deps are built separately without LTO so mixed linking is intentional++**What won't work without root:** `io_uring` (Android 12+ seccomp block), CPU affinity/taskset, KSM memory dedup, TAP networking, huge pages on the host.diff --git a/app/src/main/java/com/excp/podroid/engine/PodroidQemu.kt b/app/src/main/java/com/excp/podroid/engine/PodroidQemu.ktindex d69027b..ce2224a 100644--- a/app/src/main/java/com/excp/podroid/engine/PodroidQemu.kt+++ b/app/src/main/java/com/excp/podroid/engine/PodroidQemu.kt@@ -469,7 +469,8 @@ class PodroidQemu @Inject constructor(args += "-cpu"; args += "max"args += "-smp"; args += "$cpus"args += "-m"; args += "$ramMb"- args += "-accel"; args += "tcg,thread=multi,tb-size=256"+ val tbSize = if (ramMb >= 2048) 512 else 256+ args += "-accel"; args += "tcg,thread=multi,tb-size=$tbSize"val kernelPath = File(context.filesDir, "vmlinuz-virt")val initrdPath = File(context.filesDir, "initrd.img")@@ -477,7 +478,7 @@ class PodroidQemu @Inject constructor(if (kernelPath.exists()) {args += "-kernel"; args += kernelPath.absolutePathval cmdline = buildString {- append("console=ttyAMA0 loglevel=1 quiet")+ append("console=ttyAMA0 loglevel=1 quiet mitigations=off elevator=mq-deadline")append(" androidip=$androidIp")if (sshEnabled) append(" ssh=1")}@@ -494,7 +495,8 @@ class PodroidQemu @Inject constructor(val storagePath = File(context.filesDir, "storage.img")if (storagePath.exists()) {- args += "-device"; args += "virtio-blk-pci,drive=drive1,num-queues=$cpus"+ args += "-object"; args += "iothread,id=iothread0"+ args += "-device"; args += "virtio-blk-pci,drive=drive1,num-queues=$cpus,iothread=iothread0"args += "-drive"; args += "file=${storagePath.absolutePath},if=none,id=drive1,format=raw,cache=writeback,aio=threads"}diff --git a/skill.md b/skill.mdindex 0568026..739d382 100644--- a/skill.md+++ b/skill.md@@ -1,6 +1,6 @@# Podroid AI Context-> **Last updated:** 2026-04-22+> **Last updated:** 2026-04-23> **Purpose:** Complete project context for AI-assisted development. Read this before touching any file.---@@ -39,13 +39,13 @@### High-Level Flow```Android App-├── PodroidApplication — extracts assets (vmlinuz, initrd, qemu/) on first run-├── PodroidService (foreground) — hosts QEMU, holds WakeLock+├── PodroidApplication — extracts assets (vmlinuz, initrd, qemu/) on first run (size-checked to skip if unchanged)+├── PodroidService (foreground) — hosts QEMU, holds WakeLock, updates notification with boot stages├── PodroidQemu (singleton)│ ├── QEMU process (libqemu-system-aarch64.so — ELF binary renamed .so for APK)│ ├── serial.sock — boot monitor reads until "Ready!", then bridge connects│ ├── ctrl.sock — virtio-console for RESIZE signals from bridge-│ └── qmp.sock — QEMU Machine Protocol for runtime control+│ └── qmp.sock — QEMU Machine Protocol for runtime control (port forwarding)└── Compose UI└── Screens: Setup → Home → Terminal / Settings```@@ -66,6 +66,25 @@ Android App---+## Performance Tuning (TCG, no KVM)++All tuning applies under software emulation only — KVM is impossible without root.++**In `PodroidQemu.buildCommand()`:**+- `tcg,thread=multi` — one host thread per vCPU.+- `tb-size`: 256 MB for <2 GB RAM, 512 MB for ≥2 GB — larger Translation Block cache reduces re-translation for JIT-heavy workloads (Node, JVM in containers).+- `iothread=iothread0` on `virtio-blk-pci` — dedicated I/O thread decoupled from vCPU threads; biggest win for container image pull/extraction.+- `mitigations=off` in guest kernel cmdline — safe inside TCG VM (speculative execution attacks can't cross the emulated ISA boundary); 5–15% CPU gain.+- `elevator=mq-deadline` in guest kernel cmdline — request merging for virtio-blk random writes (Podman overlay graph driver).++**In `init-podroid`:**+- ZRAM swap at half physical RAM using lz4 — gives 1.5–2× effective memory with near-zero I/O cost; swapon at priority 100 so it's preferred over any file swap.++**In `Dockerfile` (QEMU build):**+- `-O3 -flto=thin` in `--extra-cflags` / `--extra-ldflags` — LLVM thin LTO optimises across QEMU's translation units including the TCG hot path.++---+## Project Structure### Root Level@@ -155,12 +174,15 @@ Android App```### Native Libs (app/src/main/jniLibs/arm64-v8a/)-```-├── libqemu-system-aarch64.so # QEMU binary renamed .so for APK packaging-├── libslirp.so # SLIRP networking (soname patched from .so.0 via patchelf)-├── libpodroid-bridge.so # PTY↔serial bridge binary renamed .so for APK packaging-└── libtermux.so # Termux terminal JNI (custom-built with 16KB page alignment)-```++**Note:** All native binaries require 16KB page alignment (`-Wl,-z,max-page-size=16384`) — mandatory on Android 13+.++| File | What it is |+|---|---|+| `libqemu-system-aarch64.so` | QEMU TCG emulator (PIE executable, 16KB aligned) |+| `libpodroid-bridge.so` | PTY ↔ serial relay (PIE executable, 16KB aligned) |+| `libtermux.so` | Termux terminal emulator JNI (rebuilt for 16KB pages) |+| `libslirp.so` | SLIRP user-mode networking (statically linked into QEMU) |---@@ -168,6 +190,7 @@ Android App| Item | Value ||------|-------|+| podroidKernelVersion | Set in `gradle.properties` (controls kernel source version) || QEMU binary | `libqemu-system-aarch64.so` in `nativeLibraryDir` || Kernel | `filesDir/vmlinuz-virt` || Initrd | `filesDir/initrd.img` |@@ -335,13 +358,13 @@ arrow(final): if mod==1 → "\x1b[$final" else → "\x1b[1;$mod$final"- **Purpose**: Relay PTY (Termux-allocated) ↔ `serial.sock` (QEMU serial)- **Arguments**: `bridge_exe serial_sock_path ctrl_sock_path`-- **STDERR silenced** immediately via `dup2(/dev/null, STDERR_FILENO)` — bridge runs as TerminalSession subprocess so stderr IS the PTY-- **`cfmakeraw()`** on own stdin (VM's getty handles echo/line editing)-- **serial.sock retry**: 50 attempts × 200ms = 10s max-- **ctrl.sock retry**: 50 × 100ms = 5s max; lazy reconnect on each SIGWINCH if not yet connected-- **`filter_queries()`**: Intercepts `ESC[18t` / `ESC[19t` (xterm window size queries from busybox `less`), responds locally with fake size, strips bytes — prevents garbage in terminal output-- **`send_resize()`**: On SIGWINCH, reads new size via `TIOCGWINSZ`, writes `RESIZE rows cols\n` to ctrl.sock-- **select timeout**: 50ms (allows SIGWINCH handling without blocking)+- **STDERR silenced** immediately via `dup2(/dev/null, STDERR_FILENO)` — bridge runs as TerminalSession subprocess so stderr IS the PTY.+- **`cfmakeraw()`** on own stdin (VM's getty handles echo/line editing).+- **serial.sock retry**: 50 attempts × 200ms = 10s max.+- **ctrl.sock retry**: 50 × 100ms = 5s max; lazy reconnect on each SIGWINCH if not yet connected.+- **`filter_queries()`**: Intercepts `ESC[18t` / `ESC[19t` (xterm window size queries from busybox `less`), responds locally with fake size (using `TIOCGWINSZ`), strips bytes — prevents garbage in terminal output.+- **`send_resize()`**: On SIGWINCH, reads new size via `TIOCGWINSZ`, writes `RESIZE rows cols\n` to ctrl.sock.+- **select timeout**: 50ms (allows SIGWINCH handling without blocking).---@@ -383,40 +406,39 @@ dropbear ncurses-terminfo-base musl-locales## Build Commands-```bash-# Build initramfs (Docker required, ~3min first time, cached after)-./build-all.sh initramfs-# → app/src/main/assets/vmlinuz-virt + initrd.img+All components are coordinated by `build-all.sh`:-# Build QEMU + bridge (Docker, ~30min first time)-./build-all.sh qemu-# → app/src/main/jniLibs/arm64-v8a/{libqemu-system-aarch64.so,libslirp.so,libpodroid-bridge.so}-# → app/src/main/assets/qemu/--# Build Termux JNI lib (local NDK)-./build-all.sh termux-# → app/src/main/jniLibs/arm64-v8a/libtermux.so+```bash+./build-all.sh kernel # Build custom kernel only (podroid_kernel.config, ~5–10 min)+./build-all.sh initramfs # Build custom kernel + Alpine initramfs (~10–15 min total)+./build-all.sh qemu # Build QEMU + podroid-bridge via Docker (~30 min first time)+./build-all.sh termux # Build libtermux.so via local NDK (16KB page alignment)+./build-all.sh apk # Build Android APK via Gradle+./build-all.sh all # Build everything+./build-all.sh deploy # Full deploy workflow+./build-all.sh test # Boot validation: deploys APK, polls console.log for "Ready!"+```-# Build APK+**APK only:**+```bash./gradlew assembleDebug+./gradlew installDebug+```-# Uninstall + install (debug package)-adb uninstall com.excp.podroid.debug-adb install -r app/build/outputs/apk/debug/app-debug.apk--# Fast bridge rebuild (without full Docker QEMU build)+**Fast bridge rebuild (without full Docker QEMU build):**+```bashNDK=$HOME/Android/Sdk/ndk/$(ls ~/Android/Sdk/ndk/ | tail -1)CC=$NDK/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android28-clang$CC --sysroot=$NDK/toolchains/llvm/prebuilt/linux-x86_64/sysroot \-target aarch64-linux-android28 -fPIE -pie -Wl,-z,max-page-size=16384 \podroid-bridge.c -o app/src/main/jniLibs/arm64-v8a/libpodroid-bridge.so./gradlew :app:installDebug+```-# Full rebuild + deploy-./build-all.sh all--# Automated boot test-./build-all.sh test+**Monitor VM boot:**+```bash+adb logcat -s PodroidQemu+adb shell run-as com.excp.podroid.debug cat files/console.log```**Workflow**: