A rootless Android app that boots Alpine Linux: run containers (Podman/Docker/LXC) and GUI desktop apps.
docs(site): correct SSH/ZRAM details and document the guest bridge
ExTv068ffab80afe
diff --git a/docs/guide/how-it-works.html b/docs/guide/how-it-works.htmlindex 42aaf9a..47ef2ea 100644--- a/docs/guide/how-it-works.html+++ b/docs/guide/how-it-works.html@@ -74,13 +74,16 @@</div><h2>Init system: OpenRC</h2>- <p>OpenRC is PID 1 inside the guest. Three app-specific services on the squashfs handle bring-up:</p>+ <p>OpenRC is PID 1 inside the guest. Several app-specific services on the squashfs handle bring-up; the three that drive the boot log are:</p><ul><li><strong>podroid-bootstrap:</strong> kernel modules, cgroup v2, ZRAM swap, devpts/shm/mqueue mounts, sysctl, hostname.</li><li><strong>podroid-network:</strong> brings up eth0, assigns 10.0.2.15/24, sets the default route and /etc/resolv.conf (SLIRP provides NAT).</li><li><strong>podroid-ready:</strong> emits the "Starting SSH...", "Almost ready...", and "Ready!" markers that the app tracks to update the notification and unlock the terminal.</li></ul>+ <h2>Guest-to-Android bridge</h2>+ <p>A small daemon, <code>podroid-hostd</code>, lets processes inside the VM reach back to Android. It listens on a guest-local Unix socket and relays one-line requests to the app over the same control transport the VM already uses - a virtio-console port on QEMU, vsock on AVF. Two CLIs are wired to it: <code>podroid-notify</code> posts an Android notification, and <code>podroid-forward</code> creates or removes port-forward rules without leaving the shell. The app posts the notification or writes the rule on the host side. See <a href="networking.html">Networking & ports</a> for usage.</p>+<h2>Boot stages</h2><p>The app watches the VM's serial console and updates the persistent notification as each stage marker appears. You can follow along in real time during the first boot, where host-key generation adds a visible pause between "Starting SSH..." and the next stage.</p>@@ -124,6 +127,10 @@<td>QEMU / AVF</td><td>Hypervisor backend; QEMU (software TCG) works on any device, AVF (hardware) on supported Pixels</td></tr>+ <tr>+ <td>podroid-hostd</td>+ <td>Guest-to-Android bridge daemon; relays <code>podroid-notify</code> and <code>podroid-forward</code> requests to the app over a virtio-console port (QEMU) or vsock (AVF)</td>+ </tr><tr><td>Foreground service</td><td>Holds a partial WakeLock and the persistent notification to keep the VM running in the background</td>diff --git a/docs/guide/packages.html b/docs/guide/packages.htmlindex c5c8fa1..057707f 100644--- a/docs/guide/packages.html+++ b/docs/guide/packages.html@@ -167,6 +167,10 @@<td><code>podroid-vsock</code></td><td>AVF only. Starts the vsock port-forwarding agent that bridges Android-side TCP connections to guest vsock ports. On QEMU this service marks itself inactive and does nothing.</td></tr>+ <tr>+ <td><code>podroid-hostd</code></td>+ <td>The guest-to-Android bridge daemon (both backends). Listens on a guest-local Unix socket and relays requests from the <code>podroid-notify</code> and <code>podroid-forward</code> CLIs to the Android app over its control transport (a virtio-console port on QEMU, vsock on AVF), which posts the notification or writes the port-forward rule. See <a href="networking.html">Networking & ports</a>.</td>+ </tr><tr><td><code>podroid-ready</code></td><td>Runs last (after all other services). Emits the boot-stage markers (<code>Starting SSH...</code>, <code>Almost ready...</code>, <code>Ready!</code>) that the Android app watches to detect a successful boot. Also sets OOM scores on infrastructure processes so the kernel reaps user apps before killing the VM.</td>diff --git a/docs/index.html b/docs/index.htmlindex 1935b1f..045226e 100644--- a/docs/index.html+++ b/docs/index.html@@ -618,7 +618,7 @@<svg width="18" height="18" fill="none" stroke="currentColor" stroke-width="1.8" viewBox="0 0 24 24"><path d="M22 16.92v3a2 2 0 0 1-2.18 2 19.79 19.79 0 0 1-8.63-3.07A19.5 19.5 0 0 1 4.69 12 19.79 19.79 0 0 1 1.63 3.42 2 2 0 0 1 3.6 1.24h3a2 2 0 0 1 2 1.72c.127.96.361 1.903.7 2.81a2 2 0 0 1-.45 2.11L7.91 8.84a16 16 0 0 0 6.29 6.29l.96-.96a2 2 0 0 1 2.11-.45c.907.339 1.85.573 2.81.7A2 2 0 0 1 22 16.92z"/></svg></div><h3>Built-in SSH</h3>- <p>Dropbear SSH server on port 9922 (configurable). Connect from your laptop, VS Code Remote, or any SSH client on the same network.</p>+ <p>Dropbear SSH server, toggled on in the setup wizard or Settings, reachable on host port 9922. Connect from your laptop, VS Code Remote, or any SSH client on the same network.</p></div><div class="feature-card">@@ -634,7 +634,7 @@<svg width="18" height="18" fill="none" stroke="currentColor" stroke-width="1.8" viewBox="0 0 24 24"><path d="M13 2L3 14h9l-1 8 10-12h-9l1-8z"/></svg></div><h3>Persistent & Fast</h3>- <p>Overlayfs over a persistent ext4 image. Containers, packages, and configs survive reboots. ZRAM swap gives 2× effective RAM. Boots in 6–30 seconds.</p>+ <p>Overlayfs over a persistent ext4 image. Containers, packages, and configs survive reboots. ZRAM lz4 swap at 1.5× RAM adds headroom against the OOM killer. Boots in 6–30 seconds.</p></div><div class="feature-card">@@ -658,7 +658,15 @@<svg width="18" height="18" fill="none" stroke="currentColor" stroke-width="1.8" viewBox="0 0 24 24"><polyline points="22 12 18 12 15 21 9 3 6 12 2 12"/></svg></div><h3>Tuned for Software Emulation</h3>- <p>KVM needs root, so we leaned hard on TCG instead. Multi-thread TCG with a 512 MB translation cache, a dedicated I/O thread for the rootfs disk, ZRAM lz4 swap at half RAM, and <code>mitigations=off</code> in the guest combine for a 5–15% CPU win. Native 16 KB page alignment, so Pixel 8/9/10 are first-class.</p>+ <p>KVM needs root, so we leaned hard on TCG instead. Multi-thread TCG with a 512 MB translation cache, a dedicated I/O thread for the rootfs disk, ZRAM lz4 swap at 1.5× RAM, and <code>mitigations=off</code> in the guest combine for a 5–15% CPU win. Native 16 KB page alignment, so Pixel 8/9/10 are first-class.</p>+ </div>++ <div class="feature-card">+ <div class="feature-icon">+ <svg width="18" height="18" fill="none" stroke="currentColor" stroke-width="1.8" viewBox="0 0 24 24"><rect x="4" y="4" width="16" height="16" rx="2"/><rect x="9" y="9" width="6" height="6"/><line x1="9" y1="1" x2="9" y2="4"/><line x1="15" y1="1" x2="15" y2="4"/><line x1="9" y1="20" x2="9" y2="23"/><line x1="15" y1="20" x2="15" y2="23"/><line x1="20" y1="9" x2="23" y2="9"/><line x1="20" y1="14" x2="23" y2="14"/><line x1="1" y1="9" x2="4" y2="9"/><line x1="1" y1="14" x2="4" y2="14"/></svg>+ </div>+ <h3>Hardware acceleration (AVF)</h3>+ <p>On a Pixel that ships pKVM, switch the backend to the Android Virtualization Framework and the same Alpine guest runs on real CPU cores - no TCG, near-native speed. Two one-time <code>adb</code> grants, then it's automatic. Falls back to QEMU everywhere else. <a href="guide/backends.html">Backends guide</a>.</p></div><div class="feature-card">@@ -720,7 +728,7 @@</tr><tr><td class="row-label">VM isolation</td>- <td class="col-podroid"><span class="check">✓ QEMU</span></td>+ <td class="col-podroid"><span class="check">✓ QEMU + AVF</span></td><td><span class="cross">✗ shared kernel</span></td><td><span class="check">✓ AVF</span></td></tr>@@ -783,7 +791,7 @@<div class="container"><p class="section-label">Architecture</p><h2>How it works</h2>- <p class="section-sub">Four sockets, one VM, zero root. Here's what happens when you tap Start.</p>+ <p class="section-sub">Five sockets, one VM, zero root. Here's what happens when you tap Start.</p><div class="arch-diagram"><span class="arch-white">┌────────────────────── Android App (Compose) ─────────────────────────┐│ │@@ -810,6 +818,7 @@<span class="arch-green">terminal.sock</span> ↔ hvc0 → primary shell I/O<span class="arch-blue">ctrl.sock </span> ↔ hvc1 → debounced SIGWINCH resize signals<span class="arch-white">serial.sock </span> ↔ ttyAMA0 → boot log stream → boot stage detection+<span class="arch-green">host.sock </span> ↔ hvc2 → guest → Android bridge (notify / port forwards)qmp.sock → runtime port-forward control</div><div class="steps">@@ -921,14 +930,28 @@ qmp.sock → runtime port-forward control</div><details><summary>How is this different from Google Terminal / AVF?</summary><div class="faq-answer">- Google's Terminal app uses Android Virtualization Framework (AVF), a system-level hypervisor available only on recent Pixel devices. It gives you a Debian VM but no container runtime and limited configurability. Podroid uses QEMU TCG (software emulation), so it works on <em>any</em> ARM64 Android 9+ device, not just Pixels, and ships with three container engines, port forwarding, SSH, and a configurable terminal.+ Google's Terminal app uses Android Virtualization Framework (AVF), a system-level hypervisor available only on recent Pixel devices. It gives you a Debian VM but no container runtime and limited configurability. Podroid runs on <em>any</em> ARM64 Android 9+ device via QEMU TCG (software emulation), and on a Pixel that ships pKVM it can use AVF too for near-native speed - the same Alpine guest either way. It ships with three container engines, port forwarding, SSH, an in-app X11 desktop, and a configurable terminal.</div></details><details><summary>Is performance usable? QEMU is slow.</summary><div class="faq-answer">- TCG is software emulation, so compute-heavy workloads are slower than native. Podroid ships several optimizations: a 256–512 MB translation cache, a dedicated I/O thread for virtio-blk (big win for image pulls), ZRAM swap for 2× effective RAM, and <code>mitigations=off</code> in the guest kernel for a 5–15% CPU gain. For typical dev tasks like running a web server, a database, or CLI tools, it's very usable.+ TCG is software emulation, so compute-heavy workloads are slower than native. Podroid ships several optimizations: a 256–512 MB translation cache, a dedicated I/O thread for virtio-blk (big win for image pulls), ZRAM lz4 swap at 1.5× RAM, and <code>mitigations=off</code> in the guest kernel for a 5–15% CPU gain. For typical dev tasks like running a web server, a database, or CLI tools, it's very usable. On a Pixel that ships pKVM you can switch to the <a href="guide/backends.html">AVF backend</a> for near-native CPU speed.+ </div>+ </details>++ <details>+ <summary>Can Podroid use hardware acceleration instead of emulation?</summary>+ <div class="faq-answer">+ Yes, on devices that ship pKVM (Pixel 8 and later, and any other device whose maker enables it). Set the backend to AVF in Settings and Podroid runs the guest on real CPU cores through the Android Virtualization Framework - no TCG translation, near-native speed. It needs two one-time <code>adb</code> permission grants (or Shizuku, no PC required); after that, Auto mode picks AVF when available and falls back to QEMU everywhere else. Still no root. See the <a href="guide/backends.html">Backends guide</a> for setup.+ </div>+ </details>++ <details>+ <summary>Can I do things on Android from inside the VM?</summary>+ <div class="faq-answer">+ Yes. Two CLIs ship in the guest: <code>podroid-notify "build done"</code> pops an Android notification (with a title, priority, and an <code>--id</code> to update one in place), and <code>podroid-forward 8888 80</code> adds a port-forward rule without opening Settings. Both work on either backend and are handy for long builds, downloads, and cron jobs. See <a href="guide/networking.html">Networking & ports</a>.</div></details>@@ -956,7 +979,7 @@ qmp.sock → runtime port-forward control</div><details><summary>Can I connect from my laptop over SSH?</summary><div class="faq-answer">- Yes. Dropbear SSH runs on port 9922 by default (configurable in Settings). As long as your laptop and phone are on the same network, <code>ssh root@<phone-ip> -p 9922</code> gives you a remote shell. Useful for VS Code Remote or any SSH client.+ Yes. Turn SSH on in the setup wizard or later in Settings, and Dropbear is reachable on host port 9922 (it forwards to the guest's port 22; an unprivileged Android app can't bind ports below 1024, which is why it's 9922 and not 22). As long as your laptop and phone are on the same network, <code>ssh root@<phone-ip> -p 9922</code> gives you a remote shell. Useful for VS Code Remote or any SSH client.</div></details>