Skip to content

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

updated ai context

ExTV4f5786704433
diff --git a/skill.md b/skill.md
index ed4bc1f..9de010d 100644
--- a/skill.md
+++ b/skill.md
@@ -1,6 +1,6 @@
# Podroid AI Context
-> **Last updated:** 2026-04-10
+> **Last updated:** 2026-04-15
> **Purpose:** Complete project context for AI-assisted development without re-explaining structure every prompt.
---
@@ -64,36 +64,36 @@ Android App
├── 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
+├── 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
+├── docker-build-initramfs.sh # Initramfs build script
├── build-termux-android.sh # Termux native library build
-├── build-qemu-android.sh # QEMU Android 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
+├── 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
+│ └── 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.)
+│ ├── SettingsRepository.kt # DataStore-backed settings (darkTheme, vmRam, vmCpus, storageSize, etc.)
│ ├── PortForwardRepository.kt # Port forward rules persistence
-│ └── UpdateRepository.kt # GitHub release checker
+│ └── UpdateRepository.kt # GitHub release checker
│
├── di/
│ └── AppModule.kt # Hilt module (empty - constructor injection only)
@@ -119,7 +119,7 @@ Android App
│
├── settings/
│ ├── SettingsScreen.kt # Sections: Terminal → VM Resources → Network → Appearance → Diagnostics → About
- │ └── SettingsViewModel.kt # Port forward CRUD, VM reset, console log export
+ │ └── SettingsViewModel.kt # Port forward CRUD, VM reset, console log export
│
└── setup/
├── SetupScreen.kt # 3-page pager: Storage size, VM config + SSH, Downloads sharing
@@ -129,23 +129,23 @@ Android App
### 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
+├── 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
+ ├── 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)
+├── 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)
+└── fonts/ # 13 curated terminal fonts (.ttf files)
└── JetBrains-Mono.ttf, Fira-Code.ttf, CascadiaCode.ttf, etc.
```
@@ -176,8 +176,8 @@ Android App
| 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 RAM | 512 MB | Range: 512MB – 4GB (512, 1024, 2048, 4096) |
+| Default CPUs | 1 | Range: 1 – 8 (1, 2, 4, 6, 8) |
| 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` |
@@ -562,7 +562,7 @@ Automated build → install → boot test script:
- **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).
+- **Some tui apps hangs on Podroid** — Works inside tmux or by using SSH .
## GitHub
@@ -571,77 +571,3 @@ Automated build → install → boot test script:
- **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 (FIXED)
-
-**Problem:** QEMU crashes on devices with Android 12 (OnePlus 7 Pro, kernel 5.x) with error:
-```
-cannot locate symbol "copy_file_range" referenced by libqemu-system-aarch64.so
-```
-
-**Root Cause:**
-- Built against Android 34 (API 34) sysroot
-- glibc in API 34 has `copy_file_range` symbol, but Android 12's Bionic doesn't
-- Linker fails to resolve the symbol at runtime
-
-**Fix Applied (v1.1.1):**
-1. Changed `app/build.gradle.kts`: minSdk 26 → 28, targetSdk 36
-2. Changed `Dockerfile.qemu`: API 34 → 28
-3. QEMU now builds against Android 28 sysroot which doesn't have `copy_file_range`
-4. Uses only Bionic functions available in API 28
-
-**Note:** This raises the minimum Android version from 8.0 (API 26) to 9.0 (API 28).
-
----
-
-### 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.
-
----
-
-## Recent Fixes (2026-04-08 to 2026-04-10)
-
-### v1.1.2: Wakelock race, Android 14+ crash, restart race, socket cleanup, diagnostic log
-
-**Files changed:** `PodroidService.kt`, `PodroidQemu.kt`, `HomeViewModel.kt`, `SettingsScreen.kt`, `SettingsViewModel.kt`
-
-**Fixes:**
-- **PodroidService:** Fix StateFlow replay releasing wakelock immediately by adding `seenActive` guard; add `VmState.Error` to cleanup; use `ServiceCompat.startForeground` with `FOREGROUND_SERVICE_TYPE_SPECIAL_USE` for Android 14+
-- **PodroidQemu:** Remove unnecessary `Thread.sleep(500)`; add `qmp.sock` to stale socket cleanup; change socket timeout to throw exception instead of silently proceeding
-- **HomeViewModel:** Replace `delay(2000)` with await terminal state via `first()` for reliable restart
-- **SettingsViewModel:** Rewrite `exportConsoleLogs` to create comprehensive `log.txt` with app info, device, settings, VM state, port forwards, logcat, and QEMU console
-- **SettingsScreen:** Update UI label and add explanatory subtitle
-
-### Fix: Storage slider and terminal theme/font persistence
-
-**Files changed:** `NavGraph.kt`, `SettingsScreen.kt`, `SetupScreen.kt`, `TerminalViewModel.kt`
-
-**Fixes:**
-- **SetupScreen:** Fix slider steps to show 6 discrete storage values (2-64GB)
-- **SettingsScreen:** Add callback to invalidate terminal view when theme/font changes
-- **TerminalViewModel:** Add `terminalColorTheme`/`terminalFont` StateFlows and `invalidateTerminalView()`
-- **NavGraph:** Pass theme/font change callback to SettingsScreen
-
-### Fix: Duplicate PNG launcher icons
-
-**Files changed:** `app/src/main/res/`
-
-**Fix:** Remove duplicate PNG launcher icons causing build failures