A rootless Android app that boots Alpine Linux: run containers (Podman/Docker/LXC) and GUI desktop apps.
docs: correct statements that no longer match the code
ExTv73276693fb60
diff --git a/CLAUDE.md b/CLAUDE.mdindex a2124b9..e54127f 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -215,7 +215,7 @@ The terminal emulator JNI is built from the vendored `terminal-emulator` module## Performance tuning (TCG path; KVM is impossible without root)-In `QemuEngine.buildCommand()`: `tcg,thread=multi`, larger `tb-size` for ≥2GB RAM, dedicated `iothread` on `virtio-blk-pci`, `-cpu max,pauth-impdef=on`. More vCPUs are not better here: on an 8-core phone, 8 measured slower than 4 on every metric. Guest cmdline: `mitigations=off` (safe inside TCG), per-device `mq-deadline`. `init-podroid`/bootstrap: ZRAM lz4 swap at half RAM. `CONFIG_EXT4_FS_SECURITY=y` + `CONFIG_SQUASHFS_XATTR=y` keep `security.capability` xattrs across the overlay (rootless podman's `newuidmap` needs them). What won't work without root: `io_uring` (seccomp), CPU affinity, KSM, TAP networking, host hugepages.+In `QemuEngine.buildCommand()`: `tcg,thread=multi`, larger `tb-size` for ≥2GB RAM, dedicated `iothread` on `virtio-blk-pci`, `-cpu max,pauth-impdef=on`. More vCPUs are not better here: on an 8-core phone, 8 measured slower than 4 on every metric. Guest cmdline: `mitigations=off` (safe inside TCG), per-device `mq-deadline`. `init-podroid`/bootstrap: ZRAM lz4 swap at 1.5x RAM (lz4 averages about 3x, so the backing store stays well under RAM). `CONFIG_EXT4_FS_SECURITY=y` + `CONFIG_SQUASHFS_XATTR=y` keep `security.capability` xattrs across the overlay (rootless podman's `newuidmap` needs them). What won't work without root: `io_uring` (seccomp), CPU affinity, KSM, TAP networking, host hugepages.## Quirks & gotchasdiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 5f9d856..037e705 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -27,10 +27,9 @@ You will need:./build-all.sh initramfs # kernel + minimal initramfs./build-all.sh rootfs # Alpine squashfs (~30 s, Docker-cached)./build-all.sh qemu # QEMU + podroid-bridge (~30 min first run)-./build-all.sh termux # terminal-emulator JNI via local NDK./build-all.sh apk # Android APK via Gradle./build-all.sh all # everything-./build-all.sh deploy # all + install + launch+./build-all.sh deploy # APK + install in place (adb install -r)./build-all.sh test # deploys APK, polls console.log for "Ready!"```diff --git a/CREDITS.md b/CREDITS.mdindex acb40d9..be7afa2 100644--- a/CREDITS.md+++ b/CREDITS.md@@ -59,7 +59,7 @@ The in-app X11 viewer is backed by these components running inside the VM. Podro## Emulation### QEMU-QEMU provides the machine emulation that makes everything else possible. Podroid currently builds against QEMU 11.0.2, cross-compiled for arm64 Android.+QEMU provides the machine emulation that makes everything else possible. Podroid currently builds against QEMU 11.0.4, cross-compiled for arm64 Android.- Project: https://www.qemu.org- Repository: https://gitlab.com/qemu-project/qemudiff --git a/docs/guide/limitations.html b/docs/guide/limitations.htmlindex eef53ec..6579e36 100644--- a/docs/guide/limitations.html+++ b/docs/guide/limitations.html@@ -88,9 +88,9 @@<td>The AVF API exposes only one vCPU or all host cores, not an exact count, so the CPU count setting is precise on the QEMU backend only. As of v1.2.5, multi-core AVF works reliably: if a device cannot bring up every core at boot (seen on Tensor G3/G4 Pixels), Podroid automatically retries with fewer cores and remembers the highest count that boots.</td></tr><tr>- <td>AVF on the Android 17 beta</td>- <td>VMs fail to boot (boot loop, empty console)</td>- <td>On the Android 17 beta, the system VM manager and its bundled crosvm disagree on guest networking, so AVF VMs reset before the guest loads. This is a platform-side beta regression, not a Podroid bug. Switch the backend to QEMU (TCG) in Settings until Google resolves it; QEMU is unaffected.</td>+ <td>AVF networking on some OEM builds</td>+ <td>AVF VMs boot without a network interface</td>+ <td>Guest networking over AVF depends on a build-time flag in the device's virtualization module. Some manufacturer builds ship it disabled, and the system VM manager then starts the VM without a network device no matter what Podroid requests. There is no in-app workaround; use the QEMU backend on those devices, which is unaffected.</td></tr><tr><td>USB passthrough</td>@@ -135,7 +135,7 @@<tr><td>First boot</td><td>Slower due to SSH host-key generation</td>- <td>On the very first boot, Dropbear generates RSA and ECDSA host keys. This is a one-time cost that typically adds 15-60 seconds on slower devices. Subsequent boots skip key generation and are noticeably faster.</td>+ <td>On the very first boot, Dropbear generates RSA, ECDSA and ED25519 host keys. This is a one-time cost that typically adds 15-60 seconds on slower devices. Subsequent boots skip key generation and are noticeably faster.</td></tr><tr><td>CPU performance</td>@@ -178,7 +178,7 @@<p>Two timeouts govern boot: QEMU fails and surfaces an error if it cannot create its Unix sockets within 10 seconds (this usually means a stale socket file from a previous crash - try a force-stop and re-open). If sockets open but the guest never emits the <code>Ready!</code> marker, a 60-second boot timeout fires and the app declares the boot failed. In either case, go to <strong>Settings → Export diagnostic log</strong> and inspect <code>console.log</code>; the last few lines usually show exactly where the guest stalled.</p><h3>First boot is very slow</h3>- <p>Expected. Dropbear generates RSA and ECDSA host keys on the first boot, which takes 15-60 seconds on low-end hardware under TCG emulation. Once the keys exist on the persistent overlay they are never regenerated; subsequent boots skip this step entirely.</p>+ <p>Expected. Dropbear generates RSA, ECDSA and ED25519 host keys on the first boot, which takes 15-60 seconds on low-end hardware under TCG emulation. Once the keys exist on the persistent overlay they are never regenerated; subsequent boots skip this step entirely.</p><h3>Right-click exits fullscreen when I use a mouse</h3><p>This is a known limitation of the X11 viewer: Android's fullscreen gesture handler intercepts the right mouse button before it reaches the VNC client. Use a two-finger touch gesture to right-click instead - that path bypasses the gesture handler and is delivered correctly to the guest X session.</p>diff --git a/docs/guide/migrations.html b/docs/guide/migrations.htmlindex eda774f..03915d6 100644--- a/docs/guide/migrations.html+++ b/docs/guide/migrations.html@@ -121,7 +121,7 @@<ol><li>Create <code>build-rootfs/files/etc/podroid/migrations/<versionCode>.sh</code>. Use the app's <code>versionCode</code> (an integer, found in <code>app/build.gradle.kts</code>) as the filename.</li><li>Make the script <strong>idempotent</strong>. It may run more than once if the guest crashes mid-migration; it must be safe to re-run.</li>- <li>Register it in <code>build-rootfs.sh</code> so it is copied into the squashfs.</li>+ <li>That is all. Every <code>*.sh</code> file in that directory is copied into the squashfs and made executable by the rootfs build, so no build script edit is needed.</li></ol><p>Example - enabling a newly-added service:</p>diff --git a/docs/guide/networking.html b/docs/guide/networking.htmlindex fa479bd..99014f6 100644--- a/docs/guide/networking.html+++ b/docs/guide/networking.html@@ -182,7 +182,7 @@ podroid-server status</code></pre></div><h2>LAN reachability</h2>- <p>All port forward listeners bind <code>0.0.0.0</code>, not <code>127.0.0.1</code>. This means any device on the same Wi-Fi network can reach the phone by its local IP address. The phone's current IP is shown in <strong>Settings</strong>.</p>+ <p>Port forwards you create, and the SSH forward, bind <code>0.0.0.0</code> rather than <code>127.0.0.1</code>. This means any device on the same Wi-Fi network can reach the phone by its local IP address. The phone's current IP is shown in <strong>Settings</strong>. The two implicit desktop forwards are the exception: VNC (5900) and audio (4713) bind loopback only, so the passwordless X session is never exposed to the network.</p><pre><code><span class="c"># SSH from a laptop on the same Wi-Fi</span><span class="p">$</span> ssh root@<phone-ip> -p 9922diff --git a/docs/guide/settings.html b/docs/guide/settings.htmlindex d232e5d..723148d 100644--- a/docs/guide/settings.html+++ b/docs/guide/settings.html@@ -168,7 +168,7 @@<tr><td>USB passthrough</td><td>Toggle</td>- <td>Passes a physically attached USB device (Wi-Fi adapter, storage, serial adapter, audio interface) into the VM, with no root. QEMU backend only. It adds a USB controller at boot, so the toggle takes effect only after a VM restart and is locked while the VM is running. When it is on, each device you attach prompts for permission once and then appears inside the guest while the app runs.</td>+ <td>Passes a physically attached USB device (Wi-Fi adapter, storage, serial adapter, audio interface) into the VM, with no root. QEMU backend only. It adds a USB controller at boot, so the toggle takes effect only after a VM restart and is locked while the VM is running. When it is on, each device you attach prompts for permission once and then appears inside the guest while the app runs. A Wi-Fi adapter also needs firmware installed inside the guest before it will associate, since the guest image ships none: <code>apk add linux-firmware-rtw88</code> for RTL8821AU/8812AU/8814AU dongles, <code>apk add linux-firmware-rtlwifi</code> for RTL8188/8192 ones, then replug the adapter.</td></tr></tbody></table>@@ -207,7 +207,7 @@<tr><td>Reset VM</td><td>Button</td>- <td>Wipes all VM data: the persistent overlay (<code>storage.img</code>) is deleted and recreated on next boot. Does not affect app settings.</td>+ <td>Clears all application data: the persistent overlay (<code>storage.img</code>), your settings and your port forward rules. The app closes and returns to a freshly installed state, so the setup wizard runs again. There is no way to keep settings while wiping only the VM.</td></tr></tbody></table>diff --git a/docs/index.html b/docs/index.htmlindex 5afd649..a7287d7 100644--- a/docs/index.html+++ b/docs/index.html@@ -998,14 +998,14 @@ qmp.sock → runtime port-forward control</div><details><summary>Can I plug in a USB device?</summary><div class="faq-answer">- Yes, on the QEMU backend. Enable <strong>USB passthrough</strong> in Settings (it adds a USB controller at boot, so set it while the VM is stopped), then attach a device through a USB-C hub or OTG adapter. Android asks for permission once per device, and it then appears inside the guest while Podroid is running. Works with Wi-Fi adapters, storage, serial adapters, audio interfaces, and more. Not available on the AVF backend, which has no channel to hand the device to the VM.+ Yes, on the QEMU backend. Enable <strong>USB passthrough</strong> in Settings (it adds a USB controller at boot, so set it while the VM is stopped), then attach a device through a USB-C hub or OTG adapter. Android asks for permission once per device, and it then appears inside the guest while Podroid is running. Wi-Fi adapters need firmware installed inside the guest before they will associate, because the guest image ships none. Install the package for your chipset, for example <code>apk add linux-firmware-rtw88</code> for RTL8821AU/8812AU/8814AU dongles or <code>apk add linux-firmware-rtlwifi</code> for RTL8188/8192 ones, then replug the adapter. Works with Wi-Fi adapters, storage, serial adapters, audio interfaces, and more. Not available on the AVF backend, which has no channel to hand the device to the VM.</div></details><details><summary>How much storage does it use?</summary><div class="faq-answer">- The APK is ~200 MB (QEMU + kernel + initramfs + Alpine squashfs + fonts). On first launch you choose a VM disk size between 2 GB and 64 GB; this is a sparse <code>storage.img</code> that only grows as you pull images and install packages.+ The APK is ~200 MB (QEMU + kernel + initramfs + Alpine squashfs + fonts). On first launch you choose a VM disk size between 2 GB and 512 GB; this is a sparse <code>storage.img</code> that only grows as you pull images and install packages.</div></details>