A rootless Android app that boots Alpine Linux: run containers (Podman/Docker/LXC) and GUI desktop apps.
docs: add skill.md for AI/LLM context and update README
ExTvdb79c9efde0e
diff --git a/.gitignore b/.gitignoreindex 3b4de42..4502887 100644--- a/.gitignore+++ b/.gitignore@@ -40,9 +40,6 @@ app/src/main/jniLibs/arm64-v8a/libpodroid-bridge.so# Claude Code sessions.claude/-# AI Context (don't commit to repo)-skill.md-# Misc*.tmp/captures/diff --git a/README.md b/README.mdindex ae7dea4..c89f6fa 100644--- a/README.md+++ b/README.md@@ -111,6 +111,34 @@ Install: `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.++### Using with AI Assistants++**For OpenCode users:**+```+/load_skill path/to/skill.md+```++**For Claude/Cline users:**+```+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.++---+## Credits- [QEMU](https://www.qemu.org) — machine emulationdiff --git a/skill.md b/skill.mdnew file mode 100644index 0000000..9cbd068--- /dev/null+++ b/skill.md@@ -0,0 +1,631 @@+# Podroid AI Context++> **Last updated:** 2026-04-06+> **Purpose:** Complete project context for AI-assisted development without re-explaining structure every prompt.++---++## Project Overview++**Podroid** is an Android app that runs Linux containers (Podman) on arm64 Android devices without root required. It spins up a lightweight Alpine Linux VM using QEMU and provides a built-in serial terminal.++- **Package:** `com.excp.podroid`+- **Min SDK:** 26 (Android 8.0)+- **Target SDK:** 36+- **Architecture:** AArch64 only+- **License:** GNU GPL v2.0++---++## Tech Stack++| Layer | Technology |+|-------|------------|+| UI | Jetpack Compose (Material 3) |+| DI | Hilt |+| Async | Kotlin Coroutines + Flow |+| Persistence | DataStore Preferences |+| Terminal | Termux TerminalView (VT100/xterm emulation) |+| VM | QEMU TCG (no KVM) |+| Container Runtime | Podman + crun + netavark + slirp4netns |+| Init System | Custom two-phase initramfs (`init-podroid`) |+| VM Linux | Alpine Linux 3.23 |++---++## Architecture++### High-Level Flow+```+Android App+├── Foreground Service (PodroidService) ← keeps VM alive+├── PodroidQemu engine+│ ├── QEMU process (libqemu-system-aarch64.so)+│ ├── Serial socket → boot monitor+│ └── QMP socket (port forwarding, VM control)+└── Jetpack Compose UI+ └── Screens: Home, Terminal, Settings, Setup+```++### VM Boot Sequence+1. QEMU loads `vmlinuz-virt` + `initrd.img`+2. Phase 1 (`init-podroid`): Mounts persistent ext4 disk as overlayfs upper layer+3. Phase 2 (`--main`): Configures networking, Podman, Dropbear SSH, starts getty on ttyAMA0+4. Terminal connects to serial console++---++## Project Structure++### Root Level+```+/+├── app/ # Android application+├── init-podroid # Custom VM init script (shell)+├── podroid-bridge.c # Native PTY↔serial.sock relay binary+├── build.gradle.kts # Root build config+├── settings.gradle.kts # Gradle settings+├── gradle.properties # Gradle + QEMU version (11.0.0-rc2)+├── Dockerfile # Multi-stage initramfs builder+├── Dockerfile.qemu # QEMU Docker build+├── docker-build-initramfs.sh # Initramfs build script+├── build-termux-android.sh # Termux native library build+├── build-qemu-android.sh # QEMU Android build+└── gradle/, gradlew, gradlew.bat # Gradle wrapper+```++### app/src/main/java/com/excp/podroid/++```+├── MainActivity.kt # Single activity entry point+├── PodroidApplication.kt # Hilt Application - asset extraction on first run+│+├── engine/+│ ├── PodroidQemu.kt # QEMU lifecycle, serial.sock boot monitor, ctrl.sock chardev+│ │ └── KEY: releaseSerial() closes boot monitor so podroid-bridge can connect+│ ├── QmpClient.kt # QEMU QMP socket client for runtime port forwards+│ └── VmState.kt # Sealed class: Idle, Starting, Running, Paused, Saving, Resuming, Stopped, Error+│+├── service/+│ └── PodroidService.kt # Foreground service, WakeLock, notifications+│ └── Actions: ACTION_START, ACTION_STOP | SSH port: 9922+│+├── data/repository/+│ ├── SettingsRepository.kt # DataStore-backed settings (darkTheme, vmRam, vmCpus, storageSize, etc.)+│ ├── PortForwardRepository.kt # Port forward rules persistence+│ └── UpdateRepository.kt # GitHub release checker+│+├── di/+│ └── AppModule.kt # Hilt module (empty - constructor injection only)+│+└── ui/+ ├── navigation/+ │ └── NavGraph.kt # Routes: SETUP, HOME, TERMINAL, SETTINGS+ │ └── TerminalViewModel is scoped outside NavHost (survives navigation)+ │+ ├── theme/+ │ ├── Theme.kt # Material You (dynamic colors) + dark/light+ │ ├── Color.kt # Purple80/Grey80/Cyan80 palette + status colors+ │ └── Type.kt # Typography (default Material 3)+ │+ └── screens/+ ├── home/+ │ ├── HomeScreen.kt # Start/Stop VM, restart, open terminal, update dialog+ │ └── HomeViewModel.kt # checkForUpdate(), startPodroid(), stopVm(), restartVm()+ │+ ├── terminal/+ │ ├── TerminalScreen.kt # Termux TerminalView + extra keys bar, layout listener, auto keyboard+ │ └── TerminalViewModel.kt # TerminalSession with podroid-bridge subprocess, mouse support+ │+ ├── settings/+ │ ├── SettingsScreen.kt # Sections: Terminal → VM Resources → Network → Appearance → Diagnostics → About+ │ └── SettingsViewModel.kt # Port forward CRUD, VM reset, console log export+ │+ └── setup/+ ├── SetupScreen.kt # 3-page pager: Storage size, VM config + SSH, Downloads sharing+ └── SetupViewModel.kt # completeSetup() saves to DataStore, emits notification permission request+```++### app/src/main/res/+```+├── AndroidManifest.xml # INTERNET, WAKE_LOCK, VIBRATE, FOREGROUND_SERVICE, POST_NOTIFICATIONS+├── drawable/ # ic_vm_notification.xml, ic_stop.xml+├── mipmap-anydpi/ # App icons (ic_launcher.xml)+├── values/ # strings.xml, colors.xml, themes.xml+└── xml/+ ├── file_paths.xml # FileProvider paths+ ├── backup_rules.xml # Full backup rules+ └── data_extraction_rules.xml # Android 12+ extraction rules+```++### Assets (app/src/main/assets/)+```+├── vmlinuz-virt # Linux kernel (built by docker-build-initramfs.sh)+├── initrd.img # Alpine initramfs with Podman (~71MB, built by docker-build-initramfs.sh)+├── qemu/ # QEMU BIOS/firmware files+├── colors/ # 114 terminal color schemes (.properties files)+│ └── dracula.properties, nord.properties, gruvbox-dark.properties, etc.+└── fonts/ # 13 curated terminal fonts (.ttf files)+ └── JetBrains-Mono.ttf, Fira-Code.ttf, CascadiaCode.ttf, etc.+```++### Native Libs (app/src/main/jniLibs/arm64-v8a/)+```+├── libqemu-system-aarch64.so # QEMU executable (built by build-qemu-android.sh)+├── libslirp.so # SLIRP networking library+└── libpodroid-bridge.so # Terminal bridge (built by build-qemu-android.sh from podroid-bridge.c)+```++---++## Key Constants & Values++| Item | Value |+|------|-------|+| QEMU binary | `libqemu-system-aarch64.so` in nativeLibDir |+| Kernel | `vmlinuz-virt` in filesDir |+| Initrd | `initrd.img` in filesDir |+| Storage image | `storage.img` in filesDir (ext4) |+| QMP socket | `qmp.sock` in filesDir |+| Serial console | ttyAMA0 → `serial.sock` in filesDir (unix socket, boot monitor + bridge) |+| Control channel | hvc0 → `ctrl.sock` in filesDir (virtio-console, resize signals) |+| QMP port (via socket) | 4444 (via unix socket) |+| VM IP | 10.0.2.15 |+| Default gateway | 10.0.2.2 |+| DNS (QEMU SLIRP) | 10.0.2.3 |+| Default DNS | 8.8.8.8, 1.1.1.1 |+| SSH host port (auto) | 9922 → VM:22 (Dropbear) |+| Storage sizes | 2, 4, 8, 16, 32, 64 GB |+| Default RAM | 512 MB |+| Default CPUs | 1 |+| Default font size | 20sp |+| Boot stages | "Starting QEMU..." → "Booting kernel..." → "Mounting storage..." → "Loading kernel modules..." → "Setting up overlay..." → "Configuring containers..." → "Waiting for network..." → "Network found" → "Almost ready..." → "Starting SSH..." → "Ready" |+| QEMU args | `-M virt,gic-version=3 -cpu max -accel tcg,thread=multi,tb-size=256` |+| Storage access mount | virtio-9p with `mount_tag=downloads` → `/mnt/downloads` in VM |+| Resize daemon | Background shell loop reads `RESIZE rows cols` from `/dev/hvc0`, calls `stty rows N cols M < /dev/ttyAMA0` |++---++## DataStore Keys++| Key | Type | Default | Description |+|-----|------|---------|-------------|+| `dark_theme` | Boolean | true | Dark mode |+| `vm_ram_mb` | Int | 512 | VM RAM in MB |+| `vm_cpus` | Int | 1 | VM CPU cores |+| `terminal_font_size` | Int | 20 | Font size in sp |+| `terminal_color_theme` | String | "default" | Selected color scheme name |+| `terminal_font` | String | "default" | Selected font name |+| `storage_gb` | Int | 2 | Persistent storage size |+| `storage_access_enabled` | Boolean | false | Downloads folder sharing |+| `setup_done` | Boolean | false | Initial setup completed |+| `ssh_enabled` | Boolean | false | SSH server in VM |+| `port_forwards` | Set\<String\> | {} | Serialized PortForwardRule |+| `dismissed_update_version` | String | null | Dismissed update version |++---++## Port Forwarding System++### Format+```+"tcp:8080:80" → PortForwardRule(hostPort=8080, guestPort=80, protocol="tcp")+```++### Service Presets (in SettingsScreen)+- **Pi-hole:** 5300→53(both), 8080→80(tcp)+- **Nginx:** 8080→80, 8443→443+- **Gitea:** 3000→3000, 2222→22+- **Grafana:** 3001→3000++### Runtime Management+- At VM start: rules passed as QEMU `-netdev hostfwd` args+- At runtime: QMP `hostfwd_add`/`hostfwd_remove` via `human-monitor-command`++---++## Terminal Architecture++### Current Design (Podroid-Bridge PTY)+QEMU serial console exposed as a Unix socket (`serial.sock`). A native bridge binary+(`libpodroid-bridge.so`) runs as the `TerminalSession` subprocess — Termux allocates a+real PTY for it. The bridge relays PTY ↔ serial socket bidirectionally with no filtering.+The bridge sets its PTY to raw mode via `cfmakeraw()` (VM's getty handles+echo/line editing). Window resize propagates via the PTY/SIGWINCH chain:++```+TerminalView layout change+ → TerminalView.updateSize() [uses renderer font metrics]+ → TerminalSession.updateSize(cols, rows) [Termux JNI: ioctl TIOCSWINSZ on PTY master]+ → SIGWINCH → podroid-bridge+ → bridge reads new size via TIOCGWINSZ+ → writes "RESIZE rows cols\n" to ctrl.sock+ → VM resize daemon reads /dev/hvc0+ → stty rows N cols M < /dev/ttyAMA0 [Linux kernel sends SIGWINCH to fg process group]+ → nvim / htop / btop redraws correctly+```++Mouse tracking is fully supported: Termux TerminalView natively handles mouse events+(touch gestures, USB/Bluetooth mouse buttons and scroll). When TUI apps enable mouse+mode (CSI 1000h), mouse clicks and scrolls route to the PTY → bridge → serial → VM.++**Auto keyboard**: When TerminalScreen opens with VM running, the Android soft keyboard+is shown automatically via `InputMethodManager.showSoftInput()` so users can type immediately.++### Socket Files (in filesDir)+| File | Purpose |+|------|---------|+| `serial.sock` | QEMU serial chardev (ttyAMA0) — bridge connects here for terminal I/O |+| `ctrl.sock` | QEMU virtio-console chardev (hvc0) — bridge writes `RESIZE rows cols\n` here |+| `qmp.sock` | QEMU QMP control socket |++### Data Flow+```+Keyboard → TerminalView → TerminalSession.write() → PTY master → bridge stdin → serial.sock → ttyAMA0+VM output → serial.sock → bridge stdout → PTY slave → TerminalSession → TerminalEmulator → TerminalView+Resize → PTY TIOCSWINSZ → SIGWINCH → bridge → ctrl.sock → VM hvc0 daemon → stty → SIGWINCH in VM+Mouse → TerminalView (touch/mouse) → sendMouseEventCode() → PTY → bridge → serial → VM+```++### CSI 6n / nvim Support+No CSI 6n filtering in the bridge. The shell (`set +o checkwinsize` in `/etc/profile`)+does not send cursor position queries. nvim's TUI initializes correctly.++### Boot Monitoring+`PodroidQemu` connects to `serial.sock` via `android.net.LocalSocket` and reads until+the "Ready" stage is detected (writing to `console.log`). `releaseSerial()` shuts+down the socket input/output and closes it so `podroid-bridge` can connect when+the user opens the terminal.++**Serial handoff timing**: QEMU serial socket (`server,nowait`) only serves one client+at a time. `releaseSerial()` uses `shutdownInput()` + `shutdownOutput()` + `close()`+to reliably interrupt the boot monitor's blocking read. `createSession()` sleeps 500ms+after `releaseSerial()` to let QEMU re-listen. The bridge binary also has a retry+loop (50 attempts × 200ms = 10s max) as defense in depth.++### Extra Keys+ESC, TAB, CTRL (sticky), ALT (sticky),+arrows, HOME, END, PGUP, PGDN, F1-F12, -, /, |++---++## init-podroid (VM init script)++### Phase 1 (Early init, before overlay)+- Mount proc/sys/dev+- Load virtio modules (virtio_pci, virtio_net, virtio_blk)+- Detect persistent storage device (vda/vdb)+- Mount ext4, create overlayfs (lower=/, upper=/mnt/persist/upper, work=/mnt/persist/work)+- `chroot /mnt/overlay /init --main`++### Phase 2 (--main flag)+- Mount filesystems (proc, sys, devtmpfs, devpts, tmpfs)+- busybox --install -s+- Network setup (SLIRP: 10.0.2.15/24, gateway 10.0.2.2, DNS 10.0.2.3)+- Downloads folder mount via 9p virtio+- Container config (sysctl, /etc/subuid, containers.conf, storage.conf, registries.conf, crun.conf)+- SSH setup (Dropbear): RSA host key via `dropbearkey`, password "podroid"+- MOTD with VM info+- Resize control daemon: background loop reads `RESIZE rows cols` from `/dev/hvc0`,+ calls `stty rows N cols M < /dev/ttyAMA0`+- `podroid-login` wrapper for getty+- getty on ttyAMA0++---++## Build Commands++```bash+# Build initramfs (requires Docker with multi-arch)+./docker-build-initramfs.sh++# Build QEMU + bridge (requires Docker)+./build-qemu-android.sh++# Build APK+./gradlew assembleDebug++# Uninstall + install+adb uninstall com.excp.podroid.debug && adb install -r app/build/outputs/apk/debug/app-debug.apk+```++**Workflow**: If initramfs modified → `docker-build-initramfs.sh` → `gradlew assembleDebug` →+`adb uninstall com.excp.podroid.debug && adb install -r`. If only APK code modified → just the+last three steps.++---++## Permissions++| Permission | Purpose |+|------------|---------|+| INTERNET | SLIRP networking, QMP socket, GitHub API |+| ACCESS_NETWORK_STATE | Get device IP |+| WAKE_LOCK | Keep CPU awake during VM run |+| VIBRATE | Terminal bell feedback |+| FOREGROUND_SERVICE | Host QEMU process |+| FOREGROUND_SERVICE_SPECIAL_USE | QEMU "emulation" subtype |+| POST_NOTIFICATIONS | Android 13+ notification permission |+| MANAGE_EXTERNAL_STORAGE | Downloads folder sharing via virtio-9p |++---++## Design Patterns++- **Single Activity:** Compose Navigation with NavHost+- **Hilt:** Constructor injection, no @Provides needed+- **DataStore:** Preferences DataStore for all settings+- **StateFlow:** All UI state exposed as StateFlow+- **Reflection:** `TerminalView.mTermSession` and `mEmulator` set directly via reflection+- **Coroutines:** IO dispatcher for QEMU I/O, Main for UI updates+- **Sealed Classes:** VmState for lifecycle states+- **Persistence:** Two-layer (DataStore for config, ext4 image for VM data)++---++## Common Tasks Reference++### Add a new setting+1. Add key to `SettingsRepository.kt` (DataStore key + Flow)+2. Add UI in `SettingsScreen.kt` (Slider/Switch/etc.)+3. Add setter in `SettingsViewModel.kt`++### Add a new port forward preset+1. Add to `servicePresets` list in `SettingsScreen.kt`++### Add a new boot stage detection+1. Add case in `PodroidQemu.detectBootStage()`++### Modify QEMU arguments+1. Edit `PodroidQemu.buildCommand()`++### Modify the terminal bridge+1. Edit `podroid-bridge.c`+2. Rebuild with `./build-qemu-android.sh` (bridge is compiled alongside QEMU)++### Add a terminal color theme+1. Add `.properties` file to `app/src/main/assets/colors/`+2. Theme appears automatically in the Settings picker dialog++### Add a terminal font+1. Add `.ttf` file to `app/src/main/assets/fonts/`+2. Font appears automatically in the Settings picker dialog++### Add a new VM control signal (e.g. beyond RESIZE)+1. Add a new message format to `podroid-bridge.c` (write to ctrl.sock)+2. Add a new case to the resize daemon in `init-podroid` (read from `/dev/hvc0`)++### Modify VM init sequence+1. Edit `init-podroid` shell script++---++## Dependency Versions (gradle/libs.versions.toml)++| Library | Version |+|---------|---------|+| Android Gradle Plugin | 9.1.0 |+| Kotlin | 2.2.21 |+| KSP | 2.3.6 |+| Compose BOM | 2026.03.01 |+| Navigation Compose | 2.9.7 |+| Hilt | 2.59.2 |+| Coroutines | 1.9.0 |+| DataStore | 1.2.1 |+| Termux terminal | v0.118.1 |+| Lifecycle | 2.9.0 |+| Activity Compose | 1.10.1 |+| Room | 2.8.4 (declared but **NOT USED**) |++## Build Scripts++### docker-build-initramfs.sh+- Uses multi-stage Dockerfile+- Downloads Alpine 3.23 aarch64 netboot + virt ISO+- Installs packages via qemu-user-static on x86_64+- Outputs: `app/src/main/assets/{vmlinuz-virt,initrd.img}` (~71MB)++### build-qemu-android.sh+- Reads `podroidQemuVersion` from `gradle.properties`+- Builds via `Dockerfile.qemu`+- Compiles podroid-bridge alongside QEMU+- Outputs to `app/src/main/jniLibs/arm64-v8a/` and `app/src/main/assets/qemu/`++### build-termux-android.sh+- Clones Termux v0.118.1 from GitHub+- Compiles `libtermux.so` with **16KB page alignment** (`-Wl,-z,max-page-size=16384`)+- Verifies alignment via Python ELF parsing+- Required because Android may use 16KB page devices++## Dockerfile - VM Rootfs Packages++Installed via `apk` in Alpine aarch64:+```+linux-virt, busybox, ttyd, podman, netavark, aardvark-dns,+fuse-overlayfs, slirp4netns, shadow-uidmap, ca-certificates,+crun, curl, e2fsprogs, util-linux, openrc, dropbear,+ncurses-terminfo-base, musl-locales+```++## ProGuard Rules (app/proguard-rules.pro)++Keeps Termux reflection targets:+- `TerminalView.mTermSession` — set directly in TerminalScreen to wire the session+- `TerminalView.mEmulator` — set directly in TerminalScreen to wire the display emulator++## 16KB Page Alignment Requirement++All native libs (QEMU, slirp, termux.so) must have `p_align >= 16384` in ELF headers. This is verified by Python scripts in the build scripts. Reason: some Android devices use 16KB system pages.++## Terminal Resize Sequence++When the view layout changes (keyboard open/close, rotation):+1. `addOnLayoutChangeListener` calls `TerminalView.updateSize()` (uses renderer's exact font metrics)+2. TerminalView calculates cols/rows, calls `TerminalSession.updateSize(cols, rows)`+3. Termux JNI: `ioctl(pty_master_fd, TIOCSWINSZ)` → SIGWINCH to `podroid-bridge`+4. Bridge: `ioctl(STDIN, TIOCGWINSZ)` → writes `RESIZE rows cols\n` to `ctrl.sock`+5. VM daemon reads `/dev/hvc0` → `stty rows N cols M < /dev/ttyAMA0`+6. Linux kernel sends SIGWINCH to the foreground process group of ttyAMA0++No stdin injection. No debounce. nvim/htop/btop resize automatically.++## Settings.gradle.kts++- **Root project name:** `VirtuDroid`+- **App module:** `:app`+- **Repositories:** google, mavenCentral, **JitPack** (for Termux)+- **Toolchain:** foojay-resolver-convention 1.0.0++## Dockerfile.qemu - QEMU Build Details++### Build Dependencies+- NDK r27c (Android API 34)+- Cross-compile from debian:bookworm+- Dependencies: pcre2, libffi, glib 2.82.5, pixman 0.44.2, libattr, **libucontext**++### libucontext Shim+Android Bionic lacks proper `ucontext.h`. Built from [kaniini/libucontext](https://github.com/kaniini/libucontext). Provides `getcontext`, `swapcontext`, etc. A header shim remaps the standard functions to the libucontext versions.++### QEMU Patches Applied+1. **librt optional** — Bionic has librt functions in libc, not a separate library+2. **memfd_create shim** — `qemu_shm_alloc` uses `syscall(__NR_memfd_create)` instead of `shm_open` (API 26+)+3. **libattr stub** — `libattr = declare_dependency()` bypasses pkg-config detection (xattr in Bionic's libc)+4. **st_\*_nsec undef** — Undefines `st_atime_nsec` etc. macros from Android's sys/stat.h that clash with 9p struct fields++### QEMU Configure Flags+```+--enable-tcg --enable-kvm --enable-system --enable-slirp --enable-virtfs --enable-pie+--disable-werror --disable-docs --disable-gtk --disable-sdl --disable-opengl --disable-vnc+--disable-capstone --disable-seccomp --disable-libiscsi --disable-libnfs --disable-libssh+--disable-curl --disable-spice --disable-vde --disable-linux-io-uring+--with-coroutine=ucontext ← REQUIRED: PAC fix for Android 15+ on Tensor devices+```++### podroid-bridge Build (in Dockerfile.qemu)+```+${CC} ${CFLAGS} -fPIE -pie ${LDFLAGS} podroid-bridge.c -o podroid-bridge+cp podroid-bridge libpodroid-bridge.so+```+Same NDK, same CFLAGS/LDFLAGS (16KB page alignment enforced). Outputs `libpodroid-bridge.so`.++### podroid-bridge Responsibilities+- Connect to `serial.sock` (QEMU serial unix socket)+- Allocate PTY via `forkpty()` (Termux provides the PTY master)+- Set `cfmakeraw()` on PTY slave (VM's getty handles echo/line editing)+- Relay bidirectionally: PTY ↔ serial.sock+- No filtering — all escape sequences pass through unmodified+- On SIGWINCH: read PTY size via `TIOCGWINSZ`, write `RESIZE rows cols\n` to `ctrl.sock`++### PAC (Pointer Authentication) Fix+Android 15+ on Pixel (Tensor) uses ARMv9.2 with PAC. Default QEMU sigaltstack coroutine calls `siglongjmp` across alternate signal stacks — this fails PAC validation and raises SIGILL. Fix: `--with-coroutine=ucontext` uses `swapcontext` instead.++### Output Artifacts+```+app/src/main/jniLibs/arm64-v8a/+├── libqemu-system-aarch64.so # QEMU binary renamed to .so for APK packaging+├── libslirp.so # SLIRP networking (soname patched from .so.0)+└── libpodroid-bridge.so # Terminal bridge binary renamed to .so for APK packaging++app/src/main/assets/qemu/+├── efi-virtio.rom # VirtIO EFI ROM+└── keymaps/ # QEMU keyboard maps+```++### 16KB Page Alignment+All artifacts must have `p_align >= 16384`. Enforced via `LDFLAGS=-Wl,-z,max-page-size=16384` in both NDK toolchain and QEMU link step. Verified by Python ELF parser in build script.++## test-deploy.sh++Automated build → install → boot test script:+1. Check ADB device connected+2. Optionally rebuild initramfs+3. Build debug APK with Gradle+4. Install via `adb install -r`+5. Force stop app + delete `storage.img` (clean state)+6. Launch app via `am start`+7. Wait for user to press "Start VM"+8. Poll `console.log` for boot completion (timeout 60s)+9. Run validation checks (banner, IP, persistent, internet, Ready!, kernel modules, network)+10. Detect kernel panics/crashes++## Known Quirks++- **Room declared but unused** — DataStore is used for persistence instead+- **KSP version differs from Kotlin** — Kotlin 2.2.21, KSP 2.3.6+- **QEMU packaged as `.so`** — Actually an ELF executable renamed from binary to `.so` for Android packaging+- **podroid-bridge packaged as `.so`** — Same trick: PIE executable renamed to `.so` for APK extraction+- **Project name in Gradle is "VirtuDroid"** — `rootProject.name` in settings.gradle.kts+- **SLIRP soname patched** — `libslirp.so.0` → `libslirp.so` via patchelf for APK compatibility+- **libtermux.so custom-built** — Termux's prebuilt uses 4KB pages; rebuilt with 16KB alignment via `build-termux-android.sh`+- **Boot monitor connects to serial.sock first** — PodroidQemu reads boot output from serial.sock until "Ready", then `releaseSerial()` uses `shutdownInput()`+`close()` to interrupt blocking read; bridge has 50-retry connect loop as defense in depth+- **releaseSerial() sets bootStage="Ready"** — With persistent overlay the VM boots faster than the boot monitor can detect boot completion strings; `releaseSerial()` unconditionally marks boot as "Ready" when the terminal takes over+- **nvim hangs on Podroid** — `nvim --headless` hangs even without terminal I/O; likely a LuaJIT runtime issue on Alpine ARM64. nvim works fine over SSH (Dropbear).++## GitHub++- **Repo:** github.com/ExTV/Podroid+- **Releases API:** https://api.github.com/repos/ExTV/Podroid/releases/latest+- **Update check:** `UpdateRepository.checkForUpdate()` compares tag_name vs BuildConfig.VERSION_NAME++---++## TODO (Future Work)++### High Priority+- [ ] **nvim hangs on Podroid** — `nvim` (and `nvim --headless`) hangs silently when run in the Podroid terminal. Works over SSH. Likely a LuaJIT or process initialization issue specific to the Podroid VM environment.+- [ ] **Container Hub** — SSH-based container management via JSch. Pre-built service catalog (Pi-hole, Vaultwarden, code-server, Gitea, Jellyfin, Uptime Kuma, Filebrowser, Nginx, Grafana). Live `podman ps` polling.+- [ ] **Docker socket compatibility** (#6) — `rc-service` and `docker` commands don't work. The custom init-podroid lacks proper OpenRC integration. Needs proper service scripts for Podman to work as expected.+- [ ] **ARM native Debian base** (#4) — Option to use Debian ARM as VM base instead of Alpine. Large scope, separate base OS layer.++### Known Issues (Investigation Notes)++#### Issue #10: QEMU copy_file_range on Android 12++**Problem:** QEMU crashes on devices with Android 12 (kernel 5.x) with error:+```+cannot locate symbol "copy_file_range" referenced by libqemu-system-aarch64.so+```++**Root Cause Analysis:**+1. QEMU's `block/file-posix.c` contains a fallback implementation of `copy_file_range`:+ ```c+ #ifndef HAVE_COPY_FILE_RANGE+ static ssize_t copy_file_range(...) {+ #ifdef __NR_copy_file_range+ return syscall(__NR_copy_file_range, ...);+ #else+ errno = ENOSYS;+ return -1;+ #endif+ }+ #endif+ ```+2. The fallback is only compiled when `HAVE_COPY_FILE_RANGE` is NOT defined+3. QEMU's build system (Meson) auto-detects and defines this macro when glibc has the function+4. Our Android NDK toolchain links against glibc (via NDK sysroot), so the macro gets defined+5. This causes the fallback to NOT be compiled, and QEMU references the glibc symbol instead++**Attempted Fixes (Both Failed):**+1. `-DHAVE_COPY_FILE_RANGE=0` — This DEFINES the macro to value 0, which makes `#ifndef` FALSE, so fallback is still NOT compiled+2. No flag (leave undefined) — QEMU build system still auto-defines the macro via Meson detection+3. `-UHAVE_COPY_FILE_RANGE` — Doesn't work because Meson re-adds the define during build++**Why the Fallback Should Work:**+- The fallback uses `syscall(__NR_copy_file_range, ...)` directly+- The syscall number 285 exists in Linux kernel headers (since ~2019)+- On Android 12 kernels (5.4+), the syscall may not be implemented, but at least the symbol reference wouldn't be external++**Investigation Status:** Ongoing - waiting for user response about what fix worked for them.++---++### Moderate Priority+- [ ] **Initramfs size reduction** — The ~71MB initramfs could be trimmed (podman-remote, GPG tools, busybox-extras, iptables, traceroute are unused). Kernel module stripping could reduce from 883 to ~8 modules. Caution: previous attempt broke ext4 mount and network — kernel/module version mismatch caused virtio modules to fail loading.+- [ ] **Overlay mount validation** — init-podroid falls back silently if overlayfs mount fails. Detect and warn user with actionable error.+- [ ] **DNS configurable** — Currently hardcoded 8.8.8.8 and 1.1.1.1. Add gateway DNS (10.0.2.3) as primary with fallback options. Per-VM DNS config in Settings.+- [ ] **OpenRC integration** — Replace manual `init-podroid` boot with proper OpenRC service scripts. This would also fix the `rc-service` and `docker` issues.++### Low Priority / Nice-to-Have+- [ ] **Terminal title → TopAppBar** — `onTitleChanged()` in `TerminalSessionClient` is a no-op. Could update the app bar title when the shell sets the terminal title via OSC sequences.+- [ ] **APK size reduction** — Currently ~29MB of fonts and full QEMU. Options: deferred font download, split APK, font subsetting, strip debug symbols.+- [ ] **Custom font loading** — Issue #5 (Allow loading custom fonts). Allow users to load their own `.ttf`/`.otf` fonts in addition to the built-in collection.