Skip to content

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

docs: add documentation site and link it from the README and landing page

ExTvafcf1bc774af
diff --git a/README.md b/README.md
index 68e09bf..60b2db7 100644
--- a/README.md
+++ b/README.md
@@ -18,6 +18,7 @@ A real Alpine VM, a real Linux kernel, rootless Podman, and an in-app X11 viewer
</p>
<a href="https://extv.github.io/Podroid/"><strong>Website</strong></a> ·
+<a href="https://extv.github.io/Podroid/guide/"><strong>Documentation</strong></a> ·
<a href="https://github.com/ExTV/Podroid/releases/latest"><strong>Download</strong></a> ·
<a href="#quick-start"><strong>Quick Start</strong></a> ·
<a href="#build"><strong>Build</strong></a> ·
diff --git a/docs/guide/backends.html b/docs/guide/backends.html
new file mode 100644
index 0000000..130f7fe
--- /dev/null
+++ b/docs/guide/backends.html
@@ -0,0 +1,174 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <title>Backends: QEMU &amp; AVF · Podroid docs</title>
+ <meta name="description" content="How to choose between QEMU (TCG) and AVF (pKVM), how to grant AVF permissions, and what differs between the two backends." />
+ <link rel="icon" type="image/png" href="https://github.com/ExTV.png" />
+ <link rel="preconnect" href="https://fonts.googleapis.com" />
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+ <link href="https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,300;0,9..40,400;0,9..40,500;0,9..40,600;1,9..40,400&family=DM+Mono:wght@400;500&display=swap" rel="stylesheet" />
+ <link rel="stylesheet" href="style.css" />
+</head>
+<body>
+ <nav>
+ <a class="nav-logo" href="../index.html"><img src="../logo.png" alt="Podroid" />Podroid</a>
+ <button class="menu-toggle" aria-label="Toggle menu">&#9776;</button>
+ <ul class="nav-links">
+ <li><a href="../index.html">Home</a></li>
+ <li><a href="index.html" class="cta">Docs</a></li>
+ <li><a href="https://github.com/ExTV/Podroid">GitHub</a></li>
+ </ul>
+ </nav>
+
+ <div class="layout">
+ <aside class="sidebar">
+ <h4>Getting started</h4>
+ <ul>
+ <li><a href="index.html">Overview</a></li>
+ <li><a href="getting-started.html">Getting started</a></li>
+ <li><a href="how-it-works.html">How it works</a></li>
+ </ul>
+ <h4>Going deeper</h4>
+ <ul>
+ <li><a href="performance.html">Performance &amp; why it's slow</a></li>
+ <li><a href="backends.html" class="active">Backends: QEMU &amp; AVF</a></li>
+ <li><a href="networking.html">Networking &amp; ports</a></li>
+ <li><a href="packages.html">Packages &amp; services</a></li>
+ <li><a href="desktop.html">Desktops &amp; X11 viewer</a></li>
+ <li><a href="settings.html">Terminal &amp; settings</a></li>
+ </ul>
+ <h4>Reference</h4>
+ <ul>
+ <li><a href="limitations.html">Limitations &amp; troubleshooting</a></li>
+ <li><a href="use-cases.html">Use cases</a></li>
+ </ul>
+ </aside>
+
+ <main class="content">
+ <h1>Backends: QEMU &amp; AVF</h1>
+ <p class="lead">Podroid has two VM engines behind one setting. The default uses QEMU with software CPU emulation and works on any device. On Pixel 8/9/10 and similar devices that ship pKVM, the AVF backend runs the guest on real CPU cores for near-native speed.</p>
+
+ <h2>Choosing a backend</h2>
+ <p>Go to <strong>Settings &rarr; Advanced &rarr; Backend</strong>. The three options are:</p>
+ <ul>
+ <li><strong>Auto</strong> (default) - Podroid probes the device at startup and uses AVF if the feature, both permissions, and non-protected VM support are all present; otherwise it falls back to QEMU. This is the right choice for most users.</li>
+ <li><strong>AVF (KVM)</strong> - always use AVF; the VM will fail to start if the prerequisites are not met.</li>
+ <li><strong>QEMU (TCG)</strong> - always use software emulation, even on a device that supports AVF.</li>
+ </ul>
+
+ <div class="callout note">
+ <span class="label">Stop the VM first</span>
+ <p>Changing the backend setting takes effect at the next VM start. The VM must be stopped before you switch.</p>
+ </div>
+
+ <h2>QEMU (TCG)</h2>
+ <p>The QEMU backend is the default and works on <strong>any ARM64 Android 9+ device</strong> with no setup beyond installing the app. The guest CPU is emulated in software via TCG (Tiny Code Generator). See <a href="performance.html">Performance &amp; why it's slow</a> for a full explanation of where the overhead comes from and what Podroid does to reduce it. The short version: simple workloads are 2-5x slower than native; JIT-heavy workloads (Node, JVM, compilers) are slower still because of double-JIT and cold-cache process-spawn costs.</p>
+
+ <p>QEMU supports both <strong>TCP and UDP port forwarding</strong>. Rules you configure in the Port Forwarding screen work for both protocols.</p>
+
+ <h2>AVF (pKVM)</h2>
+ <p>The Android Virtualization Framework (AVF) is a system hypervisor shipped on some Android devices. On devices that include pKVM (protected Kernel-based Virtual Machine), Podroid can run the guest directly on physical CPU cores - no TCG translation, no double-JIT, no cold-cache overhead. CPU-bound tasks that crawl on QEMU run at near-native speed on AVF.</p>
+
+ <p>AVF is currently available on <strong>Pixel 8, Pixel 8a, Pixel 9, Pixel 9 Pro, Pixel 9 Pro XL, and Pixel 10</strong> series devices (and any other Android device your manufacturer ships with pKVM). Two development-mode permissions must be granted once before Podroid can open a VM.</p>
+
+ <h3>Setting up AVF</h3>
+
+ <p><strong>Step 1 - Confirm the device supports AVF.</strong> Run the following in a terminal with ADB access to the device:</p>
+ <pre><code><span class="p">$</span> adb shell pm list features | grep virtualization_framework</code></pre>
+ <p>If the command prints a line containing <code>android.software.virtualization_framework</code>, the device supports AVF. If the command prints nothing, the device does not have pKVM and AVF is not available.</p>
+
+ <p><strong>Step 2 - Grant the two permissions.</strong> These are development-mode permissions not exposed in the system UI. Grant them over ADB:</p>
+ <pre><code><span class="p">$</span> adb shell pm grant com.excp.podroid android.permission.MANAGE_VIRTUAL_MACHINE
+<span class="p">$</span> adb shell pm grant com.excp.podroid android.permission.USE_CUSTOM_VIRTUAL_MACHINE</code></pre>
+
+ <div class="callout note">
+ <span class="label">No PC? Use Shizuku.</span>
+ <p>If you do not have a computer handy, install <a href="https://shizuku.rikka.app/">Shizuku</a> and start it (over ADB or wireless debugging). Then open Shizuku's <code>rish</code> shell and run the same two <code>pm grant</code> lines above, replacing <code>adb shell</code> with just the <code>pm grant ...</code> command directly inside <code>rish</code>.</p>
+ </div>
+
+ <p><strong>Step 3 - Run the AVF diagnostic.</strong> In Podroid, go to <strong>Settings &rarr; About &rarr; "AVF (pKVM) diagnostic"</strong>. This runs a probe and a smoke test that checks: the virtualization_framework feature flag, both permissions, the presence of <code>/apex/com.android.virt</code>, the AVF system service, and the hypervisor capabilities reported by the kernel. If it reports success on all points, you are ready. Set <strong>Backend</strong> to <strong>Auto</strong> (or <strong>AVF</strong> if you want to force it) and start the VM.</p>
+
+ <h3>Permission lifetime</h3>
+ <p>The two <code>pm grant</code> permissions <strong>persist across reboots and in-place app updates</strong>. You do not need to re-grant them after an OTA or a Podroid update installed over the existing app. However, they are <strong>lost on uninstall</strong>: if you uninstall and reinstall Podroid, run the two <code>pm grant</code> commands again before using AVF.</p>
+
+ <h2>How Auto-selection works</h2>
+ <p>When the backend is set to Auto, Podroid checks four conditions at startup: (1) the <code>android.software.virtualization_framework</code> feature is present, (2) <code>MANAGE_VIRTUAL_MACHINE</code> is granted, (3) <code>USE_CUSTOM_VIRTUAL_MACHINE</code> is granted, and (4) the device advertises support for <strong>non-protected VMs</strong>. All four must pass. If any fails, Podroid silently falls back to QEMU - no error, the VM just starts with software emulation.</p>
+
+ <p>Condition (4) is the non-obvious one. pKVM can operate in two modes: <em>protected</em> (guest memory is encrypted and the host cannot inspect it) and <em>non-protected</em>. Podroid's guest image is a standard Alpine Linux squashfs - it does not meet the signing and measurement requirements for protected VMs. A device that only advertises protected VM support cannot run Podroid's image under AVF, so Auto falls back to QEMU on such devices.</p>
+
+ <h2>Differences between backends</h2>
+
+ <table>
+ <thead>
+ <tr>
+ <th>Feature</th>
+ <th>QEMU (TCG)</th>
+ <th>AVF (pKVM)</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>Device requirement</td>
+ <td>Any ARM64 Android 9+</td>
+ <td>Device must ship pKVM (recent Pixels and select others)</td>
+ </tr>
+ <tr>
+ <td>Setup required</td>
+ <td>None</td>
+ <td>Two <code>pm grant</code> commands (once)</td>
+ </tr>
+ <tr>
+ <td>CPU speed</td>
+ <td>Software emulation (2-5x+ overhead)</td>
+ <td>Near-native (hardware VMs, no TCG)</td>
+ </tr>
+ <tr>
+ <td>Port forwarding protocols</td>
+ <td>TCP and UDP</td>
+ <td>TCP only (UDP rules are silently ignored)</td>
+ </tr>
+ <tr>
+ <td>vCPU count</td>
+ <td>Configurable (1 to device core count)</td>
+ <td>1 vCPU = one physical core; &gt;1 vCPU = all host cores</td>
+ </tr>
+ <tr>
+ <td>Terminal console</td>
+ <td>hvc0 via QEMU virtio-console</td>
+ <td>hvc0 (same guest view, different host path)</td>
+ </tr>
+ <tr>
+ <td>Downloads folder sharing</td>
+ <td>Supported</td>
+ <td>May be a no-op on shipping Pixel AVF builds (requires an AOSP-main SharedPath API not yet in stable releases)</td>
+ </tr>
+ <tr>
+ <td>Verbose logging toggle</td>
+ <td>Not applicable</td>
+ <td>"Verbose AVF logging" in Settings &rarr; Advanced (useful for bug reports)</td>
+ </tr>
+ </tbody>
+ </table>
+
+ <div class="callout warn">
+ <span class="label">AVF boot failures on some Pixel 8 / 8a / 9 units</span>
+ <p>Some Pixel 8, Pixel 8a, and Pixel 9 units reboot the device during AVF VM startup. This appears to be a pKVM firmware issue on certain builds. If AVF causes a reboot, switch the backend to <strong>QEMU (TCG)</strong> in Settings &rarr; Advanced. QEMU is the reliable fallback on all devices. See <a href="limitations.html">Limitations &amp; troubleshooting</a> for the current status.</p>
+ </div>
+
+ <div class="pagenav">
+ <a class="prev" href="performance.html"><span class="dir">Previous</span>&larr; Performance</a>
+ <a class="next" href="networking.html"><span class="dir">Next</span>Networking &amp; ports &rarr;</a>
+ </div>
+ <p class="docfoot">Podroid is free software (GPL). Docs for v1.2.1. Found something inaccurate? <a href="https://github.com/ExTV/Podroid/issues">Open an issue</a>.</p>
+ </main>
+ </div>
+
+ <script>
+ document.querySelector('.menu-toggle').addEventListener('click', function () {
+ document.querySelector('.sidebar').classList.toggle('open');
+ });
+ </script>
+</body>
+</html>
diff --git a/docs/guide/desktop.html b/docs/guide/desktop.html
new file mode 100644
index 0000000..9de952b
--- /dev/null
+++ b/docs/guide/desktop.html
@@ -0,0 +1,162 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <title>Desktops &amp; the X11 viewer · Podroid docs</title>
+ <meta name="description" content="Run an X11 Linux desktop inside Podroid and view it with the built-in VNC viewer. Covers setup-desktop, supported DEs, viewer settings, and known limitations." />
+ <link rel="icon" type="image/png" href="https://github.com/ExTV.png" />
+ <link rel="preconnect" href="https://fonts.googleapis.com" />
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+ <link href="https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,300;0,9..40,400;0,9..40,500;0,9..40,600;1,9..40,400&family=DM+Mono:wght@400;500&display=swap" rel="stylesheet" />
+ <link rel="stylesheet" href="style.css" />
+</head>
+<body>
+ <nav>
+ <a class="nav-logo" href="../index.html"><img src="../logo.png" alt="Podroid" />Podroid</a>
+ <button class="menu-toggle" aria-label="Toggle menu">&#9776;</button>
+ <ul class="nav-links">
+ <li><a href="../index.html">Home</a></li>
+ <li><a href="index.html" class="cta">Docs</a></li>
+ <li><a href="https://github.com/ExTV/Podroid">GitHub</a></li>
+ </ul>
+ </nav>
+
+ <div class="layout">
+ <aside class="sidebar">
+ <h4>Getting started</h4>
+ <ul>
+ <li><a href="index.html">Overview</a></li>
+ <li><a href="getting-started.html">Getting started</a></li>
+ <li><a href="how-it-works.html">How it works</a></li>
+ </ul>
+ <h4>Going deeper</h4>
+ <ul>
+ <li><a href="performance.html">Performance &amp; why it's slow</a></li>
+ <li><a href="backends.html">Backends: QEMU &amp; AVF</a></li>
+ <li><a href="networking.html">Networking &amp; ports</a></li>
+ <li><a href="packages.html">Packages &amp; services</a></li>
+ <li><a href="desktop.html" class="active">Desktops &amp; X11 viewer</a></li>
+ <li><a href="settings.html">Terminal &amp; settings</a></li>
+ </ul>
+ <h4>Reference</h4>
+ <ul>
+ <li><a href="limitations.html">Limitations &amp; troubleshooting</a></li>
+ <li><a href="use-cases.html">Use cases</a></li>
+ </ul>
+ </aside>
+
+ <main class="content">
+ <h1>Desktops &amp; the X11 viewer</h1>
+ <p class="lead">Podroid includes a built-in VNC viewer that connects to <strong>Xvnc</strong> running inside the VM on display <code>:0</code> (port 5900, auto-forwarded). Tap the monitor icon in the terminal's top bar to open it.</p>
+
+ <h2>Installing a desktop</h2>
+ <p>Alpine ships <code>setup-desktop</code> as part of the <code>alpine-conf</code> package. It is an interactive helper that creates a user and installs a desktop environment of your choice. Run it in the Podroid terminal:</p>
+ <pre><code><span class="p">#</span> setup-desktop</code></pre>
+ <p>Follow the prompts to pick a desktop and create a user account. The script handles the <code>apk add</code> steps for you.</p>
+
+ <div class="callout warn">
+ <span class="label">X11 only - Wayland desktops will not appear</span>
+ <p>The built-in viewer speaks RFB (VNC), so it connects to an X11 display. It cannot show a Wayland compositor. Use <strong>Xfce, LXQt, or MATE</strong> - they run on X11 and render correctly. <strong>KDE Plasma 6, GNOME, and Sway are Wayland on Alpine</strong> and will not appear in the viewer, even after launching them.</p>
+ </div>
+
+ <h2>Launching a desktop</h2>
+ <p>You do not need a display manager. Xvnc is already the X server on <code>:0</code>, and <code>DISPLAY=:0</code> is preset in the environment. After installing a desktop, start it directly from the terminal:</p>
+ <pre><code><span class="c"># Xfce example</span>
+<span class="p">$</span> startxfce4 &amp;
+
+<span class="c"># LXQt example</span>
+<span class="p">$</span> startlxqt &amp;
+
+<span class="c"># MATE example</span>
+<span class="p">$</span> mate-session &amp;</code></pre>
+
+ <div class="callout warn">
+ <span class="label">Do not install or enable a display manager</span>
+ <p>Installing <code>lightdm</code> or any other display manager and enabling it with <code>rc-update add</code> will cause it to fight Xvnc for display <code>:0</code>. Xvnc is already the X server; no display manager is needed.</p>
+ </div>
+
+ <h2>Single GUI apps</h2>
+ <p>You do not need a full desktop to run individual X11 applications. Install any X11 app and launch it directly; <code>DISPLAY=:0</code> is already exported:</p>
+ <pre><code><span class="p">#</span> apk add firefox
+<span class="p">$</span> firefox &amp;</code></pre>
+ <p>The app will appear in the viewer as soon as it opens a window.</p>
+
+ <h2>Viewer settings reference</h2>
+ <p>Tap the tune/gear icon in the X11 viewer's top bar to open viewer settings.</p>
+
+ <h3>Resolution</h3>
+ <p>Controls what resolution Xvnc presents to the desktop. Uses the RFB ExtendedDesktopSize extension to resize live without restarting the VM.</p>
+ <ul>
+ <li><strong>Match viewport</strong> - the desktop tracks your screen size exactly, resizing whenever the viewer resizes. Pixel-perfect on most devices.</li>
+ <li><strong>Preset</strong> - fixed resolutions: 720p, 900p, 1080p, or 1440p. Pick a lower preset for smoother rendering on heavy desktops over a high-DPI display.</li>
+ <li><strong>Custom</strong> - enter any width and height in pixels.</li>
+ </ul>
+
+ <h3>Touch input</h3>
+ <ul>
+ <li><strong>Direct</strong> - tap to click at the point you touch; drag to drag; long-press activates drag-lock. Intuitive for touch-first use.</li>
+ <li><strong>Trackpad</strong> - relative pointer: your finger position moves the cursor rather than placing it. Sensitivity is adjustable (0.5x to 3.0x) with optional pointer acceleration.</li>
+ </ul>
+ <p>In both modes: two-finger tap sends a right-click; two-finger drag scrolls.</p>
+
+ <h3>External input</h3>
+ <p>A connected hardware keyboard passes through fully, including Ctrl, Alt, Shift, and composed shortcuts (e.g. Ctrl+L in a browser). An external mouse's scroll wheel scrolls, and all three buttons map to their X11 equivalents.</p>
+
+ <h3>Other settings</h3>
+ <table>
+ <thead>
+ <tr>
+ <th>Setting</th>
+ <th>Notes</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>Fullscreen</td>
+ <td>Hides the system UI. Back exits fullscreen.</td>
+ </tr>
+ <tr>
+ <td>Rotation lock</td>
+ <td>Auto, Landscape, or Portrait. Auto follows the device sensor.</td>
+ </tr>
+ <tr>
+ <td>Extra-keys bar</td>
+ <td>Show or hide the keyboard shortcut bar below the viewer.</td>
+ </tr>
+ <tr>
+ <td>Server DPI</td>
+ <td>96 to 192. Tells Xvnc what DPI to report to apps. Takes effect on the next VM start.</td>
+ </tr>
+ <tr>
+ <td>Audio</td>
+ <td>PulseAudio streams PCM from the VM to the app over port 4713. Toggle to enable or disable.</td>
+ </tr>
+ </tbody>
+ </table>
+
+ <div class="callout warn">
+ <span class="label">Known limitation: external mouse right-click</span>
+ <p>With an external mouse, right-click currently exits fullscreen instead of reaching the desktop. Android maps the mouse's right button to the Back action. Two-finger touch right-click works correctly as a workaround. A fix is planned.</p>
+ </div>
+
+ <div class="callout note">
+ <span class="label">Performance</span>
+ <p>The viewer currently uses uncompressed Raw encoding (ZRLE was disabled after it desynced on complex content). On a high-DPI phone, selecting the 720p or 900p preset reduces the amount of screen data transferred each frame and noticeably improves smoothness on heavy desktops. See the <a href="performance.html">Performance</a> page for general tuning advice.</p>
+ </div>
+
+ <div class="pagenav">
+ <a class="prev" href="packages.html"><span class="dir">Previous</span>← Packages &amp; services</a>
+ <a class="next" href="settings.html"><span class="dir">Next</span>Terminal &amp; settings →</a>
+ </div>
+ <p class="docfoot">Podroid is free software (GPL). Docs for v1.2.1. Found something inaccurate? <a href="https://github.com/ExTV/Podroid/issues">Open an issue</a>.</p>
+ </main>
+ </div>
+
+ <script>
+ document.querySelector('.menu-toggle').addEventListener('click', function () {
+ document.querySelector('.sidebar').classList.toggle('open');
+ });
+ </script>
+</body>
+</html>
diff --git a/docs/guide/getting-started.html b/docs/guide/getting-started.html
new file mode 100644
index 0000000..5fd1910
--- /dev/null
+++ b/docs/guide/getting-started.html
@@ -0,0 +1,137 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <title>Getting started · Podroid docs</title>
+ <meta name="description" content="Install Podroid, run the setup wizard, and boot your first Alpine Linux VM on Android." />
+ <link rel="icon" type="image/png" href="https://github.com/ExTV.png" />
+ <link rel="preconnect" href="https://fonts.googleapis.com" />
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+ <link href="https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,300;0,9..40,400;0,9..40,500;0,9..40,600;1,9..40,400&family=DM+Mono:wght@400;500&display=swap" rel="stylesheet" />
+ <link rel="stylesheet" href="style.css" />
+</head>
+<body>
+ <nav>
+ <a class="nav-logo" href="../index.html"><img src="../logo.png" alt="Podroid" />Podroid</a>
+ <button class="menu-toggle" aria-label="Toggle menu">☰</button>
+ <ul class="nav-links">
+ <li><a href="../index.html">Home</a></li>
+ <li><a href="index.html" class="cta">Docs</a></li>
+ <li><a href="https://github.com/ExTV/Podroid">GitHub</a></li>
+ </ul>
+ </nav>
+
+ <div class="layout">
+ <aside class="sidebar">
+ <h4>Getting started</h4>
+ <ul>
+ <li><a href="index.html">Overview</a></li>
+ <li><a href="getting-started.html" class="active">Getting started</a></li>
+ <li><a href="how-it-works.html">How it works</a></li>
+ </ul>
+ <h4>Going deeper</h4>
+ <ul>
+ <li><a href="performance.html">Performance &amp; why it's slow</a></li>
+ <li><a href="backends.html">Backends: QEMU &amp; AVF</a></li>
+ <li><a href="networking.html">Networking &amp; ports</a></li>
+ <li><a href="packages.html">Packages &amp; services</a></li>
+ <li><a href="desktop.html">Desktops &amp; X11 viewer</a></li>
+ <li><a href="settings.html">Terminal &amp; settings</a></li>
+ </ul>
+ <h4>Reference</h4>
+ <ul>
+ <li><a href="limitations.html">Limitations &amp; troubleshooting</a></li>
+ <li><a href="use-cases.html">Use cases</a></li>
+ </ul>
+ </aside>
+
+ <main class="content">
+ <h1>Getting started</h1>
+ <p class="lead">From APK download to a running Alpine Linux VM in about five minutes, plus a first boot that takes a little longer than you might expect - and why.</p>
+
+ <h2>Install</h2>
+ <p>Podroid is distributed as a standard APK sideload. There is no Play Store listing.</p>
+ <ol>
+ <li>Download the latest <code>Podroid-release-*.apk</code> from <a href="https://github.com/ExTV/Podroid/releases">GitHub Releases</a>.</li>
+ <li>Enable "Install unknown apps" for your browser or file manager in Android Settings, then open the APK.</li>
+ <li>Tap <strong>Install</strong>.</li>
+ </ol>
+
+ <div class="callout note">
+ <span class="label">Requirements</span>
+ <p>ARM64 (arm64-v8a) only. Android 9 (API 28) or newer. The APK will not install on 32-bit or x86 devices.</p>
+ </div>
+
+ <h2>Setup wizard</h2>
+ <p>The first time you open Podroid a three-step wizard runs before anything else.</p>
+
+ <h3>Step 1: Persistent storage size</h3>
+ <p>Choose how large the writable VM disk image will be: 2, 4, 8, 16, 32, or 64 GB. This image lives in the app's private storage and holds everything you install inside the VM - packages, container images, config files. Pick more than you think you need.</p>
+
+ <div class="callout warn">
+ <span class="label">Choose carefully</span>
+ <p>The storage size is set once and cannot be changed later without a full reset that wipes all VM data. If you run out of space you will need to reset.</p>
+ </div>
+
+ <h3>Step 2: VM configuration</h3>
+ <p>Set the number of virtual CPU cores and the RAM allocation (default 512 MB). You can also toggle SSH here - when enabled, Dropbear starts automatically and the VM is reachable at port 9922 over your local network. These settings can be changed later in Settings.</p>
+
+ <h3>Step 3: Downloads sharing (optional)</h3>
+ <p>Grants access to your phone's Downloads folder so you can move files between Android and the VM. Useful, but skip it if you don't need it.</p>
+
+ <div class="callout warn">
+ <span class="label">Instability warning</span>
+ <p>Downloads sharing can be unstable on some devices. If the VM behaves oddly after enabling it, try disabling it in Settings.</p>
+ </div>
+
+ <h2>First boot</h2>
+ <p>Tap <strong>Start VM</strong> on the home screen. The first boot takes roughly 50-60 seconds, noticeably longer than the 10-15 seconds of later boots. Two one-time tasks run:</p>
+ <ul>
+ <li><strong>SSH host key generation:</strong> Dropbear generates RSA, ECDSA, and ED25519 host keys. This takes 25-35 seconds on a typical phone and happens only once; the keys are stored on the persistent overlay and reused on every subsequent boot.</li>
+ <li><strong>Filesystem formatting:</strong> the ext4 storage image is formatted to the size you chose in step 1.</li>
+ </ul>
+ <p>The notification shows boot stages as they complete: "Starting SSH...", "Almost ready...", then "Ready!" - at which point the VM is fully up and the terminal is interactive.</p>
+
+ <h2>Home screen at a glance</h2>
+ <p>Once the VM is running the home screen shows:</p>
+ <ul>
+ <li><strong>VM status</strong> and uptime</li>
+ <li><strong>Network info</strong> - your phone's IP address, SSH endpoint, and how many port-forward rules are active</li>
+ <li><strong>Start / Stop</strong> button</li>
+ </ul>
+
+ <h2>Terminal and X11 viewer</h2>
+ <p>Tap the terminal icon from the home screen to open a full VT100 terminal connected to the VM shell. Inside the terminal, tap the monitor icon in the top bar to open the X11 viewer - needed for GUI Linux apps and desktop environments.</p>
+
+ <h2>Default credentials</h2>
+ <p>The default login is <code>root</code> with password <code>podroid</code>. The terminal banner reminds you of this on every boot. To create a regular user with sudo-equivalent access:</p>
+ <pre><code><span class="p">$</span> adduser -G wheel &lt;username&gt;</code></pre>
+ <p>Members of <code>wheel</code> can use <code>doas</code> (and <code>sudo</code> if installed).</p>
+
+ <h2>SSH from another device</h2>
+ <p>With SSH enabled and both devices on the same Wi-Fi, connect from a laptop or desktop:</p>
+ <pre><code><span class="p">$</span> ssh root@&lt;phone-ip&gt; -p 9922
+<span class="c"># password: podroid</span></code></pre>
+ <p>Port 9922 is the default; see the <a href="networking.html">Networking &amp; ports</a> page for how SLIRP forwarding works and how to add more port rules.</p>
+
+ <div class="callout warn">
+ <span class="label">VM killed when you switch apps?</span>
+ <p>If you see "QEMU crashed (SIGKILL)" after backgrounding the app, Android's phantom-process killer is terminating the QEMU process. This is an OS-level restriction, not a bug. See <a href="limitations.html">Limitations &amp; troubleshooting</a> for the workaround.</p>
+ </div>
+
+ <div class="pagenav">
+ <a class="prev" href="index.html"><span class="dir">Previous</span>&larr; Overview</a>
+ <a class="next" href="how-it-works.html"><span class="dir">Next</span>How it works &rarr;</a>
+ </div>
+ <p class="docfoot">Podroid is free software (GPL). Docs for v1.2.1. Found something inaccurate? <a href="https://github.com/ExTV/Podroid/issues">Open an issue</a>.</p>
+ </main>
+ </div>
+
+ <script>
+ document.querySelector('.menu-toggle').addEventListener('click', function () {
+ document.querySelector('.sidebar').classList.toggle('open');
+ });
+ </script>
+</body>
+</html>
diff --git a/docs/guide/how-it-works.html b/docs/guide/how-it-works.html
new file mode 100644
index 0000000..8994e06
--- /dev/null
+++ b/docs/guide/how-it-works.html
@@ -0,0 +1,148 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <title>How it works · Podroid docs</title>
+ <meta name="description" content="Architecture of the Podroid Alpine Linux VM: kernel, OpenRC, squashfs, ext4 overlay, QEMU/AVF, and how the app keeps it alive." />
+ <link rel="icon" type="image/png" href="https://github.com/ExTV.png" />
+ <link rel="preconnect" href="https://fonts.googleapis.com" />
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+ <link href="https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,300;0,9..40,400;0,9..40,500;0,9..40,600;1,9..40,400&family=DM+Mono:wght@400;500&display=swap" rel="stylesheet" />
+ <link rel="stylesheet" href="style.css" />
+</head>
+<body>
+ <nav>
+ <a class="nav-logo" href="../index.html"><img src="../logo.png" alt="Podroid" />Podroid</a>
+ <button class="menu-toggle" aria-label="Toggle menu">☰</button>
+ <ul class="nav-links">
+ <li><a href="../index.html">Home</a></li>
+ <li><a href="index.html" class="cta">Docs</a></li>
+ <li><a href="https://github.com/ExTV/Podroid">GitHub</a></li>
+ </ul>
+ </nav>
+
+ <div class="layout">
+ <aside class="sidebar">
+ <h4>Getting started</h4>
+ <ul>
+ <li><a href="index.html">Overview</a></li>
+ <li><a href="getting-started.html">Getting started</a></li>
+ <li><a href="how-it-works.html" class="active">How it works</a></li>
+ </ul>
+ <h4>Going deeper</h4>
+ <ul>
+ <li><a href="performance.html">Performance &amp; why it's slow</a></li>
+ <li><a href="backends.html">Backends: QEMU &amp; AVF</a></li>
+ <li><a href="networking.html">Networking &amp; ports</a></li>
+ <li><a href="packages.html">Packages &amp; services</a></li>
+ <li><a href="desktop.html">Desktops &amp; X11 viewer</a></li>
+ <li><a href="settings.html">Terminal &amp; settings</a></li>
+ </ul>
+ <h4>Reference</h4>
+ <ul>
+ <li><a href="limitations.html">Limitations &amp; troubleshooting</a></li>
+ <li><a href="use-cases.html">Use cases</a></li>
+ </ul>
+ </aside>
+
+ <main class="content">
+ <h1>How it works</h1>
+ <p class="lead">Podroid is a real virtual machine, not a translation layer or a container trick. An Alpine Linux 3.23 guest running a custom Linux 7.0.5 kernel boots inside the Android app, with full process isolation and a persistent filesystem.</p>
+
+ <h2>A real VM</h2>
+ <p>When you tap "Start VM", the app launches a real hypervisor with a real aarch64 Alpine Linux guest. The guest kernel, the init system, the shell, and every process you run are all executing real ARM64 machine code inside a fully virtualized machine. There is no instruction translation of Alpine binaries, no Android kernel namespace trick, and no chroot. The guest sees a completely clean Linux environment.</p>
+
+ <h2>Two backends</h2>
+ <p>Podroid supports two hypervisor backends, selectable in Settings. The guest is identical either way - only the host-side virtualization layer differs.</p>
+ <ul>
+ <li><strong>QEMU (default):</strong> software CPU emulation via TCG. Works on any ARM64 Android 9+ device. Slower than native because every guest instruction is translated and executed by the host CPU. See the <a href="backends.html">Backends</a> page for tuning options.</li>
+ <li><strong>AVF / pKVM:</strong> hardware virtualization via Android's Virtualization Framework. Available on recent Pixel devices that ship pKVM. Runs at near-native speed. Requires two one-time <code>adb</code> permission grants. See <a href="backends.html">Backends: QEMU &amp; AVF</a>.</li>
+ </ul>
+
+ <h2>The filesystem: squashfs + ext4 overlay</h2>
+ <p>The Alpine root is split across two virtual block devices so that the base system stays compact and reproducible while your changes persist across reboots.</p>
+ <ul>
+ <li><strong>/dev/vdb - read-only squashfs:</strong> the complete Alpine system (packages, OpenRC services, configs) is baked into a compressed squashfs image shipped inside the APK. It is never written to. Updates to the base system ship as a new APK release.</li>
+ <li><strong>/dev/vda - writable ext4 image:</strong> the persistent overlay upper layer. Every file you create or modify - <code>apk add</code> output, container images, SSH keys, home directories - lands here and survives reboots. You sized this in the setup wizard.</li>
+ </ul>
+ <p>A minimal initramfs boots first. It mounts both block devices, stacks them with <strong>overlayfs</strong> (squashfs as lower, ext4 as upper), then calls <code>switch_root</code> to hand control to the real Alpine root. From that point on the guest sees a single unified filesystem, with writes silently redirected to the ext4 overlay.</p>
+
+ <div class="callout note">
+ <span class="label">Why switch_root, not chroot?</span>
+ <p>An earlier version used <code>chroot</code> to pivot into the overlay. That broke <code>podman exec -it</code>: when <code>crun</code> calls <code>setns(MNT)</code> to enter a container's namespace, it resets the root, and exec'd processes saw raw kernel paths like <code>/mnt/overlay/proc</code> instead of <code>/proc</code>. <code>switch_root</code> reorganizes the kernel mount tree itself, so namespace forks always see a clean <code>/</code>.</p>
+ </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>
+ <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>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>
+
+ <h2>Keeping the VM alive</h2>
+ <p>A foreground Android service holds a partial WakeLock for the lifetime of the VM. The WakeLock keeps the CPU running so QEMU (or AVF) is not paused by Android's power scheduler while the app is in the background. The foreground service also shows the persistent notification required by Android for any long-running background work.</p>
+
+ <div class="callout warn">
+ <span class="label">Phantom-process killer</span>
+ <p>On some Android builds, the OS aggressively kills child processes of apps running in the background, including the QEMU process. If your VM dies when you switch apps, see <a href="limitations.html">Limitations &amp; troubleshooting</a>.</p>
+ </div>
+
+ <h2>Native binaries and page alignment</h2>
+ <p>QEMU, the terminal bridge, and the Termux JNI library are compiled as ARM64 native binaries with 16 KB page alignment (<code>-Wl,-z,max-page-size=16384</code>). This alignment is mandatory on Android 13+ and on devices with 16 KB memory pages (some Pixel 9/10 variants). The app is arm64-v8a only; there is no 32-bit or x86 build.</p>
+
+ <h2>Component summary</h2>
+ <table>
+ <thead>
+ <tr>
+ <th>Component</th>
+ <th>Role</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>Linux 7.0.5 kernel</td>
+ <td>Custom-built arm64 guest kernel with overlayfs, cgroups v2, netfilter, FUSE, and VETH built in</td>
+ </tr>
+ <tr>
+ <td>OpenRC (PID 1)</td>
+ <td>Service manager and init system inside the Alpine guest</td>
+ </tr>
+ <tr>
+ <td>squashfs (/dev/vdb)</td>
+ <td>Read-only, compressed Alpine base system; shipped inside the APK, never written to</td>
+ </tr>
+ <tr>
+ <td>ext4 overlay (/dev/vda)</td>
+ <td>Writable persistent layer; all user changes and installed packages live here</td>
+ </tr>
+ <tr>
+ <td>QEMU / AVF</td>
+ <td>Hypervisor backend; QEMU (software TCG) works on any device, AVF (hardware) on supported Pixels</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>
+ </tr>
+ </tbody>
+ </table>
+
+ <div class="pagenav">
+ <a class="prev" href="getting-started.html"><span class="dir">Previous</span>&larr; Getting started</a>
+ <a class="next" href="performance.html"><span class="dir">Next</span>Performance &amp; why it's slow &rarr;</a>
+ </div>
+ <p class="docfoot">Podroid is free software (GPL). Docs for v1.2.1. Found something inaccurate? <a href="https://github.com/ExTV/Podroid/issues">Open an issue</a>.</p>
+ </main>
+ </div>
+
+ <script>
+ document.querySelector('.menu-toggle').addEventListener('click', function () {
+ document.querySelector('.sidebar').classList.toggle('open');
+ });
+ </script>
+</body>
+</html>
diff --git a/docs/guide/index.html b/docs/guide/index.html
new file mode 100644
index 0000000..8911287
--- /dev/null
+++ b/docs/guide/index.html
@@ -0,0 +1,93 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <title>Overview · Podroid docs</title>
+ <meta name="description" content="Podroid documentation: run Linux containers and a Linux desktop on Android with no root, via a real Alpine VM on QEMU or AVF/pKVM." />
+ <link rel="icon" type="image/png" href="https://github.com/ExTV.png" />
+ <link rel="preconnect" href="https://fonts.googleapis.com" />
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+ <link href="https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,300;0,9..40,400;0,9..40,500;0,9..40,600;1,9..40,400&family=DM+Mono:wght@400;500&display=swap" rel="stylesheet" />
+ <link rel="stylesheet" href="style.css" />
+</head>
+<body>
+ <nav>
+ <a class="nav-logo" href="../index.html"><img src="../logo.png" alt="Podroid" />Podroid</a>
+ <button class="menu-toggle" aria-label="Toggle menu">☰</button>
+ <ul class="nav-links">
+ <li><a href="../index.html">Home</a></li>
+ <li><a href="index.html" class="cta">Docs</a></li>
+ <li><a href="https://github.com/ExTV/Podroid">GitHub</a></li>
+ </ul>
+ </nav>
+
+ <div class="layout">
+ <aside class="sidebar">
+ <h4>Getting started</h4>
+ <ul>
+ <li><a href="index.html" class="active">Overview</a></li>
+ <li><a href="getting-started.html">Getting started</a></li>
+ <li><a href="how-it-works.html">How it works</a></li>
+ </ul>
+ <h4>Going deeper</h4>
+ <ul>
+ <li><a href="performance.html">Performance &amp; why it's slow</a></li>
+ <li><a href="backends.html">Backends: QEMU &amp; AVF</a></li>
+ <li><a href="networking.html">Networking &amp; ports</a></li>
+ <li><a href="packages.html">Packages &amp; services</a></li>
+ <li><a href="desktop.html">Desktops &amp; X11 viewer</a></li>
+ <li><a href="settings.html">Terminal &amp; settings</a></li>
+ </ul>
+ <h4>Reference</h4>
+ <ul>
+ <li><a href="limitations.html">Limitations &amp; troubleshooting</a></li>
+ <li><a href="use-cases.html">Use cases</a></li>
+ </ul>
+ </aside>
+
+ <main class="content">
+ <h1>Podroid documentation</h1>
+ <p class="lead">Podroid runs real Linux - Podman, Docker, LXC, and a Linux desktop - on an Android phone, with no root and no custom recovery. It boots an Alpine Linux VM with a custom Linux 7.0.5 kernel inside the app.</p>
+
+ <p>There are two ways the VM runs. By default it uses <strong>QEMU</strong> with software CPU emulation (TCG), which works on any ARM64 Android 9+ device. On recent Pixel devices that ship pKVM, Podroid can instead use the <strong>Android Virtualization Framework (AVF)</strong> for near-native speed. Either way you get the same Alpine guest, the same terminal, and the same in-app X11 viewer for GUI apps.</p>
+
+ <div class="callout note">
+ <span class="label">No root required</span>
+ <p>Everything here works on a stock, unrooted phone. The only optional setup that needs a computer is enabling the AVF backend, which uses two one-time <code>adb</code> permission grants (or Shizuku). The default QEMU path needs nothing.</p>
+ </div>
+
+ <h2>What you can do with it</h2>
+ <ul>
+ <li><strong>Run containers</strong> - rootless Podman is wired up out of the box; Docker and LXC are pre-installed. Self-host Pi-hole, Gitea, code-server, Vaultwarden and more.</li>
+ <li><strong>A real Linux shell</strong> - a full Alpine system with <code>apk</code> package management that persists across reboots. SSH in from your laptop on the same Wi-Fi.</li>
+ <li><strong>GUI Linux apps</strong> - install a desktop or single X11 apps and view them in the app, with touch, trackpad, external keyboard and mouse, and audio.</li>
+ <li><strong>Learn Linux &amp; containers</strong> - cgroups, namespaces, overlayfs, netfilter, OpenRC services - all on a device you already own.</li>
+ </ul>
+
+ <h2>How these docs are organized</h2>
+ <p><strong>Getting started</strong> covers installing the app, the first boot, and a tour of how the whole thing fits together. <strong>Going deeper</strong> explains performance (and honestly, why some things are slow), the two backends and how to enable AVF, networking and port forwarding, Alpine package management, the desktop/X11 viewer, and every in-app setting. <strong>Reference</strong> is the complete limitations + troubleshooting list and a set of grounded use cases.</p>
+
+ <h2>The honest summary</h2>
+ <p>Podroid is a real VM, not a translation layer, so it is far more capable than userspace tricks - but on the default QEMU path the CPU is emulated in software, so CPU-heavy work (compiling, <code>npm install</code>, JVM apps) is slow. The <a href="performance.html">Performance</a> page explains exactly why, and how AVF and a few settings help. The <a href="limitations.html">Limitations &amp; troubleshooting</a> page is the place to look when something behaves unexpectedly.</p>
+
+ <div class="callout tip">
+ <span class="label">New here?</span>
+ <p>Start with <a href="getting-started.html">Getting started</a>, then skim <a href="how-it-works.html">How it works</a>. If you have a Pixel 8/9/10, the <a href="backends.html">Backends</a> page shows how to switch on AVF for a big speed jump.</p>
+ </div>
+
+ <div class="pagenav">
+ <span></span>
+ <a class="next" href="getting-started.html"><span class="dir">Next</span>Getting started →</a>
+ </div>
+ <p class="docfoot">Podroid is free software (GPL). Docs for v1.2.1. Found something inaccurate? <a href="https://github.com/ExTV/Podroid/issues">Open an issue</a>.</p>
+ </main>
+ </div>
+
+ <script>
+ document.querySelector('.menu-toggle').addEventListener('click', function () {
+ document.querySelector('.sidebar').classList.toggle('open');
+ });
+ </script>
+</body>
+</html>
diff --git a/docs/guide/limitations.html b/docs/guide/limitations.html
new file mode 100644
index 0000000..d60ca01
--- /dev/null
+++ b/docs/guide/limitations.html
@@ -0,0 +1,200 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <title>Limitations &amp; troubleshooting · Podroid docs</title>
+ <meta name="description" content="Known limitations of Podroid and a troubleshooting guide for common issues." />
+ <link rel="icon" type="image/png" href="https://github.com/ExTV.png" />
+ <link rel="preconnect" href="https://fonts.googleapis.com" />
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+ <link href="https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,300;0,9..40,400;0,9..40,500;0,9..40,600;1,9..40,400&family=DM+Mono:wght@400;500&display=swap" rel="stylesheet" />
+ <link rel="stylesheet" href="style.css" />
+</head>
+<body>
+ <nav>
+ <a class="nav-logo" href="../index.html"><img src="../logo.png" alt="Podroid" />Podroid</a>
+ <button class="menu-toggle" aria-label="Toggle menu">&#9776;</button>
+ <ul class="nav-links">
+ <li><a href="../index.html">Home</a></li>
+ <li><a href="index.html" class="cta">Docs</a></li>
+ <li><a href="https://github.com/ExTV/Podroid">GitHub</a></li>
+ </ul>
+ </nav>
+
+ <div class="layout">
+ <aside class="sidebar">
+ <h4>Getting started</h4>
+ <ul>
+ <li><a href="index.html">Overview</a></li>
+ <li><a href="getting-started.html">Getting started</a></li>
+ <li><a href="how-it-works.html">How it works</a></li>
+ </ul>
+ <h4>Going deeper</h4>
+ <ul>
+ <li><a href="performance.html">Performance &amp; why it's slow</a></li>
+ <li><a href="backends.html">Backends: QEMU &amp; AVF</a></li>
+ <li><a href="networking.html">Networking &amp; ports</a></li>
+ <li><a href="packages.html">Packages &amp; services</a></li>
+ <li><a href="desktop.html">Desktops &amp; X11 viewer</a></li>
+ <li><a href="settings.html">Terminal &amp; settings</a></li>
+ </ul>
+ <h4>Reference</h4>
+ <ul>
+ <li><a href="limitations.html" class="active">Limitations &amp; troubleshooting</a></li>
+ <li><a href="use-cases.html">Use cases</a></li>
+ </ul>
+ </aside>
+
+ <main class="content">
+ <h1>Limitations &amp; troubleshooting</h1>
+ <p class="lead">Podroid runs a real VM on hardware that was not designed for it. This page documents every known limitation honestly, and explains how to work around the most common problems.</p>
+
+ <h2>Limitations</h2>
+
+ <table>
+ <thead>
+ <tr>
+ <th>Category</th>
+ <th>Limitation</th>
+ <th>Detail</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>CPU / acceleration</td>
+ <td>No KVM on the default QEMU path</td>
+ <td>KVM requires root access to <code>/dev/kvm</code>, which Podroid does not have. The default backend uses QEMU TCG (software CPU emulation), which is 5-20x slower than native for CPU-bound work. AVF/pKVM is the only hardware-accelerated option and is Pixel-only; see <a href="backends.html">Backends</a>.</td>
+ </tr>
+ <tr>
+ <td>Architecture</td>
+ <td>ARM64 only</td>
+ <td>The app ships an <code>arm64-v8a</code> ABI only. x86, x86_64, and 32-bit ARM devices are not supported. x86 container images pulled inside the VM will run under double emulation (guest ARM64 + QEMU TCG re-emulates x86), which is extremely slow.</td>
+ </tr>
+ <tr>
+ <td>OS version</td>
+ <td>Android 9+ required (minSdk 28)</td>
+ <td>Features such as <code>memfd_create</code> and the required SELinux/seccomp policy are only stable from API 28. Android 8 is blocked additionally by glib/iconv linking issues in the QEMU build.</td>
+ </tr>
+ <tr>
+ <td>AVF backend</td>
+ <td>Pixel pKVM devices only; two ADB permissions required</td>
+ <td>AVF uses the Android Virtualization Framework, which requires a device that ships pKVM (currently Pixel 8 and later). Two one-time <code>adb</code> grants (or Shizuku) are needed before AVF can start. Devices that only support protected VMs and not non-protected VMs cannot use the AVF backend at all; Podroid falls back to QEMU automatically.</td>
+ </tr>
+ <tr>
+ <td>AVF networking</td>
+ <td>TCP port forwarding only</td>
+ <td>The AVF backend forwards TCP ports via the in-app port-forward rules. UDP rules are silently ignored when AVF is active. If you need UDP (e.g. DNS on port 53 serving LAN clients), switch to QEMU.</td>
+ </tr>
+ <tr>
+ <td>AVF CPU count</td>
+ <td>No fine-grained vCPU selection</td>
+ <td>Requesting more than one vCPU under AVF gives the VM all available host cores rather than the exact count chosen in Settings. The CPU count setting has full effect on the QEMU backend only.</td>
+ </tr>
+ <tr>
+ <td>Storage</td>
+ <td>Size cannot be changed after setup without a full reset</td>
+ <td>The persistent ext4 overlay image (<code>storage.img</code>) is created at first-boot time and cannot be non-destructively resized later. Choose your storage size in the setup wizard. A future release may add live resize; for now a factory reset is required to change the allocation.</td>
+ </tr>
+ <tr>
+ <td>Background stability</td>
+ <td>Phantom-process killer terminates the VM (exit 137) on Android 12+</td>
+ <td>Android 12 and later aggressively kill processes that are not direct children of an app's own process. QEMU is a subprocess of the foreground service; if Android classifies it as a phantom process, it sends SIGKILL (exit code 137). See the troubleshooting section below for the ADB command that disables this limit permanently.</td>
+ </tr>
+ <tr>
+ <td>Downloads sharing (AVF)</td>
+ <td>May silently do nothing, or crash QEMU's 9p worker on some ARMv9.2 devices</td>
+ <td>The virtio-9p driver used to expose the host Downloads folder is unstable on some hardware. On shipping Pixel AVF builds the share may be a silent no-op. On some ARMv9.2 devices (including the Pixel 10) the 9p worker in QEMU can crash and bring down the VM. If your VM crashes shortly after boot, disable Downloads sharing in Settings as the first diagnostic step.</td>
+ </tr>
+ <tr>
+ <td>X11 viewer: Wayland desktops</td>
+ <td>Wayland sessions do not render</td>
+ <td>The in-app X11 viewer connects to an Xvnc (X11) display. Wayland-native desktops (GNOME on Wayland, Plasma Wayland session, sway, Hyprland) start a compositor that does not render to an X display. Use XFCE, LXDE, or another X11 session, or force GNOME into its X11/Xorg session.</td>
+ </tr>
+ <tr>
+ <td>X11 viewer: compression</td>
+ <td>Raw encoding only - heavier bandwidth</td>
+ <td>ZRLE compression is currently disabled in the VNC client. Every frame is sent as uncompressed Raw pixels. At high resolutions on a high-DPI phone this means more bandwidth and slower screen updates. Choose a 720p or 900p resolution preset in the X11 viewer settings to compensate.</td>
+ </tr>
+ <tr>
+ <td>X11 viewer: right-click</td>
+ <td>External-mouse right-click exits fullscreen</td>
+ <td>A right-click from a paired Bluetooth or USB mouse is currently intercepted by the Android fullscreen gesture handler and dismisses fullscreen mode. As a workaround, use a two-finger touch to right-click; that gesture is passed through correctly to the VNC session.</td>
+ </tr>
+ <tr>
+ <td>X11 viewer: DPI</td>
+ <td>Server DPI changes need a VM restart</td>
+ <td>The guest Xvnc server is started with a fixed DPI argument. Changing the DPI setting in the app requires stopping and restarting the VM to take effect; hot-reloading is not supported.</td>
+ </tr>
+ <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>
+ </tr>
+ <tr>
+ <td>CPU performance</td>
+ <td>TCG emulation is 5-20x slower than native for CPU-bound work</td>
+ <td>QEMU TCG translates ARM64 guest instructions to host ARM64 instructions in software. The overhead is highest for workloads that execute many unique code paths (compilers, JVM startup, <code>npm install</code>). IO-bound and memory-bound workloads fare better. See <a href="performance.html">Performance &amp; why it's slow</a> for full detail and tuning options.</td>
+ </tr>
+ </tbody>
+ </table>
+
+ <h2>Troubleshooting</h2>
+
+ <h3>VM dies or "QEMU crashed (SIGKILL)" when I switch apps</h3>
+ <p>This is Android's phantom-process killer, active on Android 12 and later. When the app is backgrounded, the OS may classify QEMU as a phantom process and send SIGKILL, producing exit code 137 in the diagnostic log.</p>
+ <p>The fix is a one-time ADB command sequence that persists across reboots. Run these from a PC with <code>adb</code> installed:</p>
+ <pre><code><span class="c"># Disable phantom-process monitoring persistently (survives reboots)</span>
+<span class="p">$</span> adb shell device_config set_sync_disabled_for_tests persistent
+<span class="p">$</span> adb shell device_config put activity_manager max_phantom_processes 2147483647
+<span class="p">$</span> adb shell settings put global settings_enable_monitor_phantom_procs false</code></pre>
+ <p>If you have root on-device, the equivalent commands via <code>su</code>:</p>
+ <pre><code><span class="p">#</span> On-device with root
+<span class="p">$</span> su -c "device_config set_sync_disabled_for_tests persistent"
+<span class="p">$</span> su -c "device_config put activity_manager max_phantom_processes 2147483647"
+<span class="p">$</span> su -c "setprop persist.sys.fflag.override.settings_enable_monitor_phantom_procs false"</code></pre>
+
+ <div class="callout note">
+ <span class="label">Why these commands work</span>
+ <p><code>device_config</code> writes to the <code>device_config</code> namespace backed by <code>Settings.Config</code>. Setting <code>set_sync_disabled_for_tests persistent</code> prevents subsequent OTA flag pushes from reverting your values. The three properties together raise the phantom-process cap to <code>Integer.MAX_VALUE</code> and disable the monitor that enforces it.</p>
+ </div>
+
+ <h3>It's slow. Can I enable KVM?</h3>
+ <p>Not on the QEMU backend - KVM requires <code>/dev/kvm</code> access, which needs root. If you have a Pixel 8 or later (pKVM), switch to the <a href="backends.html">AVF backend</a> for near-native CPU speed. On any other device, the <a href="performance.html">Performance</a> page covers the TCG tuning options already applied (multi-threaded TCG, larger TB cache, iothread for disk I/O) and sets realistic expectations.</p>
+
+ <h3>QEMU crashes with a hint about "Downloads sharing is unstable"</h3>
+ <p>This is the virtio-9p crash on certain ARMv9.2 devices, including the Pixel 10. Open Settings inside Podroid and disable <strong>Downloads sharing</strong>. The crash will stop. The underlying 9p driver instability is an open issue in the QEMU build for those chips.</p>
+
+ <h3>AVF stops on boot with reason=5 / STOP_REASON_REBOOT</h3>
+ <p>This is a known issue on some Pixel 8, 8a, and 9 units where the pKVM firmware raises a stop event before the guest kernel finishes booting. To diagnose: enable <strong>Verbose AVF logging</strong> in Settings, reproduce the boot failure, then use <strong>Export diagnostic log</strong> to capture the output. While investigating, switch the Backend setting to <strong>QEMU</strong> to continue using the app.</p>
+
+ <h3>VM won't start / stuck on "Starting"</h3>
+ <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 &rarr; 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>
+
+ <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>
+
+ <h3>X11 is blurry or laggy</h3>
+ <p>The VNC client uses uncompressed Raw encoding (ZRLE is currently disabled), so high resolutions generate large frame payloads. Open the X11 viewer settings and pick a lower resolution preset (720p or 900p are good starting points). If you are on AVF, the latency should be much lower than on QEMU; on QEMU, latency will scale with how busy the TCG threads are.</p>
+
+ <h3>I changed RAM or CPU count and nothing happened</h3>
+ <p>RAM and CPU count are passed to QEMU at launch time and cannot be hot-changed. Stop the VM from the main screen, then start it again - the new values will be used. Port-forward rules and SSH toggle changes take effect without a restart.</p>
+
+ <div class="pagenav">
+ <a class="prev" href="settings.html"><span class="dir">Previous</span>&larr; Terminal &amp; settings</a>
+ <a class="next" href="use-cases.html"><span class="dir">Next</span>Use cases &rarr;</a>
+ </div>
+ <p class="docfoot">Podroid is free software (GPL). Docs for v1.2.1. Found something inaccurate? <a href="https://github.com/ExTV/Podroid/issues">Open an issue</a>.</p>
+ </main>
+ </div>
+
+ <script>
+ document.querySelector('.menu-toggle').addEventListener('click', function () {
+ document.querySelector('.sidebar').classList.toggle('open');
+ });
+ </script>
+</body>
+</html>
diff --git a/docs/guide/networking.html b/docs/guide/networking.html
new file mode 100644
index 0000000..fb5bad7
--- /dev/null
+++ b/docs/guide/networking.html
@@ -0,0 +1,182 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <title>Networking &amp; port forwarding &middot; Podroid docs</title>
+ <meta name="description" content="How guest networking works in Podroid, implicit and user-defined port forwards, LAN reachability, and the privileged-port limit." />
+ <link rel="icon" type="image/png" href="https://github.com/ExTV.png" />
+ <link rel="preconnect" href="https://fonts.googleapis.com" />
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+ <link href="https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,300;0,9..40,400;0,9..40,500;0,9..40,600;1,9..40,400&family=DM+Mono:wght@400;500&display=swap" rel="stylesheet" />
+ <link rel="stylesheet" href="style.css" />
+</head>
+<body>
+ <nav>
+ <a class="nav-logo" href="../index.html"><img src="../logo.png" alt="Podroid" />Podroid</a>
+ <button class="menu-toggle" aria-label="Toggle menu">&#9776;</button>
+ <ul class="nav-links">
+ <li><a href="../index.html">Home</a></li>
+ <li><a href="index.html" class="cta">Docs</a></li>
+ <li><a href="https://github.com/ExTV/Podroid">GitHub</a></li>
+ </ul>
+ </nav>
+
+ <div class="layout">
+ <aside class="sidebar">
+ <h4>Getting started</h4>
+ <ul>
+ <li><a href="index.html">Overview</a></li>
+ <li><a href="getting-started.html">Getting started</a></li>
+ <li><a href="how-it-works.html">How it works</a></li>
+ </ul>
+ <h4>Going deeper</h4>
+ <ul>
+ <li><a href="performance.html">Performance &amp; why it's slow</a></li>
+ <li><a href="backends.html">Backends: QEMU &amp; AVF</a></li>
+ <li><a href="networking.html" class="active">Networking &amp; ports</a></li>
+ <li><a href="packages.html">Packages &amp; services</a></li>
+ <li><a href="desktop.html">Desktops &amp; X11 viewer</a></li>
+ <li><a href="settings.html">Terminal &amp; settings</a></li>
+ </ul>
+ <h4>Reference</h4>
+ <ul>
+ <li><a href="limitations.html">Limitations &amp; troubleshooting</a></li>
+ <li><a href="use-cases.html">Use cases</a></li>
+ </ul>
+ </aside>
+
+ <main class="content">
+ <h1>Networking &amp; port forwarding</h1>
+ <p class="lead">The Alpine guest has full outbound internet access from first boot. Inbound access - SSH, VNC, container services - works through port forwarding, with a few rules injected automatically and the rest configured in Settings.</p>
+
+ <h2>Guest network: SLIRP user-mode</h2>
+ <p>On the QEMU backend the guest network is provided by <strong>SLIRP</strong>, a userspace TCP/IP stack embedded inside QEMU. No root, no kernel TUN/TAP device, and no host-side network interface are involved. From inside the guest the network looks like a small NAT:</p>
+
+ <table>
+ <thead>
+ <tr><th>Address</th><th>Role</th></tr>
+ </thead>
+ <tbody>
+ <tr><td><code>10.0.2.15/24</code></td><td>Guest IP (eth0)</td></tr>
+ <tr><td><code>10.0.2.2</code></td><td>Default gateway (SLIRP host)</td></tr>
+ <tr><td><code>10.0.2.3</code></td><td>Built-in DNS resolver</td></tr>
+ <tr><td><code>8.8.8.8</code>, <code>1.1.1.1</code></td><td>Fallback DNS (in <code>/etc/resolv.conf</code>)</td></tr>
+ </tbody>
+ </table>
+
+ <p>IPv6 is disabled on the QEMU netdev (<code>ipv6=off</code>). Outbound TCP and UDP both work. The <code>podroid-network</code> OpenRC service brings up eth0 with these addresses at boot.</p>
+
+ <div class="callout note">
+ <span class="label">AVF backend</span>
+ <p>On the AVF backend the guest receives its IP from Android's built-in tethering via DHCP (udhcpc), rather than a static SLIRP address. The default route and DNS are assigned by the Android network stack. Inbound connectivity still works through port forwarding as described below, but the transport is vsock rather than SLIRP hostfwd.</p>
+ </div>
+
+ <h2>Implicit port forwards</h2>
+ <p>Three port forwards are injected automatically every time the VM starts. They never appear in the port-forward UI and cannot be removed from there:</p>
+
+ <table>
+ <thead>
+ <tr><th>Service</th><th>Host port</th><th>Guest port</th><th>Protocol</th><th>When active</th></tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>SSH (dropbear)</td>
+ <td><code>9922</code></td>
+ <td><code>22</code></td>
+ <td>TCP</td>
+ <td>When SSH is enabled in Settings</td>
+ </tr>
+ <tr>
+ <td>X11 / VNC (Xvnc)</td>
+ <td><code>5900</code></td>
+ <td><code>5900</code></td>
+ <td>TCP</td>
+ <td>Always (backs the in-app screen viewer)</td>
+ </tr>
+ <tr>
+ <td>PulseAudio</td>
+ <td><code>4713</code></td>
+ <td><code>4713</code></td>
+ <td>TCP</td>
+ <td>Always (backs the in-app audio stream)</td>
+ </tr>
+ </tbody>
+ </table>
+
+ <p>The SSH forward is conditional: if you turn SSH off in Settings, the 9922&rarr;22 rule is not added and dropbear does not start inside the guest. The VNC and PulseAudio forwards are unconditional because the in-app X11 viewer depends on them.</p>
+
+ <h2>Adding your own rules</h2>
+ <p>Open <strong>Settings &rarr; Port forwards &rarr; Add</strong>. Enter a host port (on the Android device), a VM port (inside the guest), and pick TCP, UDP, or Both. On the QEMU backend rules apply live via the QMP protocol - no VM restart is needed. Rules are persisted across reboots.</p>
+
+ <p>A typical setup for a container service listening on guest port 8080:</p>
+
+ <pre><code><span class="c"># Inside the guest: start your service on port 8080</span>
+podman run -d -p 8080:80 nginx
+
+<span class="c"># In Settings -> Port forwards -> Add:
+# Host port: 8080
+# VM port: 8080
+# Protocol: TCP
+#
+# Then from your laptop on the same Wi-Fi:</span>
+curl http://&lt;phone-ip&gt;:8080</code></pre>
+
+ <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>
+
+ <pre><code><span class="c"># SSH from a laptop on the same Wi-Fi</span>
+<span class="p">$</span> ssh root@&lt;phone-ip&gt; -p 9922
+<span class="c"># password: podroid</span>
+
+<span class="c"># VNC from any viewer</span>
+<span class="p">$</span> vncviewer &lt;phone-ip&gt;:5900
+
+<span class="c"># HTTP service forwarded to host port 8080</span>
+<span class="p">$</span> curl http://&lt;phone-ip&gt;:8080</code></pre>
+
+ <h2>The privileged-port limit</h2>
+ <p>Android apps run as unprivileged Linux users and do not hold <code>CAP_NET_BIND_SERVICE</code>. The Linux kernel refuses to bind a TCP or UDP socket to any port below 1024 for a process without that capability. This is a kernel-level rule, not a Podroid restriction, and there is no in-app workaround without root.</p>
+
+ <p>Consequences:</p>
+
+ <ul>
+ <li><strong>SSH is exposed on host port 9922, not 22.</strong> Port 22 is below 1024; 9922 is not.</li>
+ <li>You cannot listen on host ports <code>:80</code> or <code>:443</code> directly.</li>
+ <li>The Add-rule dialog accepts any value from 1 to 65535, but a host port below 1024 will fail to bind at VM start time with a bind error in the logs. The rule itself is accepted - the failure happens when QEMU or the vsock forwarder tries to open the socket.</li>
+ </ul>
+
+ <div class="callout warn">
+ <span class="label">Workaround</span>
+ <p>Forward to a high host port instead of the standard one: map host <code>8080</code> to guest <code>80</code>, and host <code>8443</code> to guest <code>443</code>. Services inside the guest can still listen on port 80 or 443 as usual - only the host-side port is restricted.</p>
+ </div>
+
+ <pre><code><span class="c"># Forward a web server on guest :80 to a high host port</span>
+<span class="c"># Settings -> Port forwards -> Add: 8080 -> 80 TCP</span>
+
+<span class="c"># Then reach it from outside:</span>
+<span class="p">$</span> curl http://&lt;phone-ip&gt;:8080</code></pre>
+
+ <h2>Port forwarding on AVF</h2>
+ <p>On the AVF backend, port forwarding is implemented over <strong>vsock</strong> rather than SLIRP hostfwd. Each rule creates a TCP listener on <code>0.0.0.0:hostPort</code> on the Android side, which is bridged to a vsock port on the guest via the <code>podroid-vsock-agent</code> service. The privileged-port limit applies here too, for the same reason.</p>
+
+ <div class="callout note">
+ <span class="label">UDP on AVF</span>
+ <p>UDP rules are ignored on the AVF backend. The vsock transport is TCP-only. If you need UDP forwarding, use the QEMU backend.</p>
+ </div>
+
+ <div class="pagenav">
+ <a class="prev" href="backends.html"><span class="dir">Previous</span>&larr; Backends: QEMU &amp; AVF</a>
+ <a class="next" href="packages.html"><span class="dir">Next</span>Packages &amp; services &rarr;</a>
+ </div>
+ <p class="docfoot">Podroid is free software (GPL). Docs for v1.2.1. Found something inaccurate? <a href="https://github.com/ExTV/Podroid/issues">Open an issue</a>.</p>
+ </main>
+ </div>
+
+ <script>
+ document.querySelector('.menu-toggle').addEventListener('click', function () {
+ document.querySelector('.sidebar').classList.toggle('open');
+ });
+ </script>
+</body>
+</html>
diff --git a/docs/guide/packages.html b/docs/guide/packages.html
new file mode 100644
index 0000000..49f9267
--- /dev/null
+++ b/docs/guide/packages.html
@@ -0,0 +1,207 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <title>Packages &amp; services &middot; Podroid docs</title>
+ <meta name="description" content="Alpine package management with apk, what ships pre-installed in Podroid, and how to manage OpenRC services inside the VM." />
+ <link rel="icon" type="image/png" href="https://github.com/ExTV.png" />
+ <link rel="preconnect" href="https://fonts.googleapis.com" />
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+ <link href="https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,300;0,9..40,400;0,9..40,500;0,9..40,600;1,9..40,400&family=DM+Mono:wght@400;500&display=swap" rel="stylesheet" />
+ <link rel="stylesheet" href="style.css" />
+</head>
+<body>
+ <nav>
+ <a class="nav-logo" href="../index.html"><img src="../logo.png" alt="Podroid" />Podroid</a>
+ <button class="menu-toggle" aria-label="Toggle menu">&#9776;</button>
+ <ul class="nav-links">
+ <li><a href="../index.html">Home</a></li>
+ <li><a href="index.html" class="cta">Docs</a></li>
+ <li><a href="https://github.com/ExTV/Podroid">GitHub</a></li>
+ </ul>
+ </nav>
+
+ <div class="layout">
+ <aside class="sidebar">
+ <h4>Getting started</h4>
+ <ul>
+ <li><a href="index.html">Overview</a></li>
+ <li><a href="getting-started.html">Getting started</a></li>
+ <li><a href="how-it-works.html">How it works</a></li>
+ </ul>
+ <h4>Going deeper</h4>
+ <ul>
+ <li><a href="performance.html">Performance &amp; why it's slow</a></li>
+ <li><a href="backends.html">Backends: QEMU &amp; AVF</a></li>
+ <li><a href="networking.html">Networking &amp; ports</a></li>
+ <li><a href="packages.html" class="active">Packages &amp; services</a></li>
+ <li><a href="desktop.html">Desktops &amp; X11 viewer</a></li>
+ <li><a href="settings.html">Terminal &amp; settings</a></li>
+ </ul>
+ <h4>Reference</h4>
+ <ul>
+ <li><a href="limitations.html">Limitations &amp; troubleshooting</a></li>
+ <li><a href="use-cases.html">Use cases</a></li>
+ </ul>
+ </aside>
+
+ <main class="content">
+ <h1>Packages &amp; services</h1>
+ <p class="lead">The VM is a standard Alpine Linux system. Install packages with <code>apk</code> as you would on any Alpine machine. Changes persist across reboots on the writable ext4 overlay.</p>
+
+ <h2>Package management with apk</h2>
+ <p>Both the <strong>main</strong> and <strong>community</strong> repositories are pre-configured in <code>/etc/apk/repositories</code>. Any package available on Alpine 3.23 for aarch64 can be installed directly.</p>
+
+ <table>
+ <thead>
+ <tr><th>Command</th><th>What it does</th></tr>
+ </thead>
+ <tbody>
+ <tr><td><code>apk update</code></td><td>Refresh the package index from the repositories</td></tr>
+ <tr><td><code>apk upgrade</code></td><td>Upgrade all installed packages to the latest versions</td></tr>
+ <tr><td><code>apk add &lt;pkg&gt;</code></td><td>Install a package (and its dependencies)</td></tr>
+ <tr><td><code>apk del &lt;pkg&gt;</code></td><td>Remove a package</td></tr>
+ <tr><td><code>apk search &lt;kw&gt;</code></td><td>Search for packages by name or description</td></tr>
+ <tr><td><code>apk info &lt;pkg&gt;</code></td><td>Show details about an installed or available package</td></tr>
+ </tbody>
+ </table>
+
+ <div class="callout tip">
+ <span class="label">Alpine documentation</span>
+ <p>The Alpine project maintains authoritative documentation for package management and everything else in the distribution. These are the best references for what packages exist and how to use them:</p>
+ <ul>
+ <li><strong>Package search:</strong> <a href="https://pkgs.alpinelinux.org/packages" target="_blank" rel="noopener">pkgs.alpinelinux.org/packages</a></li>
+ <li><strong>Alpine User Handbook</strong> (covers apk, storage, users, services): <a href="https://docs.alpinelinux.org/user-handbook/0.1a/index.html" target="_blank" rel="noopener">docs.alpinelinux.org/user-handbook</a></li>
+ <li><strong>Alpine Wiki:</strong> <a href="https://wiki.alpinelinux.org/" target="_blank" rel="noopener">wiki.alpinelinux.org</a></li>
+ </ul>
+ </div>
+
+ <h2>What ships pre-installed</h2>
+ <p>The following packages are baked into the Alpine squashfs that Podroid ships. You do not need to install them.</p>
+
+ <table>
+ <thead>
+ <tr><th>Category</th><th>Packages</th></tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>Rootless containers</td>
+ <td><code>podman</code>, <code>crun</code>, <code>netavark</code>, <code>aardvark-dns</code>, <code>fuse-overlayfs</code>, <code>slirp4netns</code>, <code>shadow</code>, <code>shadow-uidmap</code></td>
+ </tr>
+ <tr>
+ <td>Docker</td>
+ <td><code>docker</code>, <code>docker-openrc</code>, <code>docker-cli-compose</code></td>
+ </tr>
+ <tr>
+ <td>LXC</td>
+ <td><code>lxc</code>, <code>lxc-templates</code>, <code>lxc-openrc</code>, <code>lxc-bridge</code></td>
+ </tr>
+ <tr>
+ <td>Networking tools</td>
+ <td><code>iptables</code>, <code>ip6tables</code>, <code>nftables</code>, <code>bridge-utils</code>, <code>iproute2</code></td>
+ </tr>
+ <tr>
+ <td>SSH server</td>
+ <td><code>dropbear</code>, <code>dropbear-openrc</code></td>
+ </tr>
+ <tr>
+ <td>X11 / audio</td>
+ <td><code>tigervnc</code> (Xvnc), <code>pulseaudio</code>, <code>pulseaudio-utils</code>, <code>font-misc-misc</code>, <code>font-cursor-misc</code>, <code>ttf-dejavu</code></td>
+ </tr>
+ <tr>
+ <td>System base</td>
+ <td><code>alpine-base</code>, <code>openrc</code>, <code>busybox-openrc</code>, <code>bash</code>, <code>curl</code>, <code>ca-certificates</code>, <code>doas</code>, <code>sudo</code>, <code>gcompat</code>, <code>libcap-utils</code>, <code>gzip</code></td>
+ </tr>
+ </tbody>
+ </table>
+
+ <div class="callout tip">
+ <span class="label">Podman, Docker and LXC are all ready at boot</span>
+ <p>Rootless Podman needs no daemon and works immediately. The Docker and LXC services are enabled in the <code>default</code> runlevel, so they start automatically on every boot - there is nothing to run. Confirm with <code>rc-status</code>, and use <code>rc-service docker stop</code> if you want to free memory when you are not using it.</p>
+ </div>
+
+ <h2>OpenRC service management</h2>
+ <p>The VM uses <strong>OpenRC</strong> as its init system (PID 1 is busybox init; OpenRC manages the service tree). Standard OpenRC commands work as-is:</p>
+
+ <pre><code><span class="c"># List all services and their status</span>
+<span class="p">~#</span> rc-status
+
+<span class="c"># Start, stop, restart, or check a service</span>
+<span class="p">~#</span> rc-service dropbear start
+<span class="p">~#</span> rc-service docker stop
+<span class="p">~#</span> rc-service podroid-x11 restart
+<span class="p">~#</span> rc-service podroid-x11 status
+
+<span class="c"># Enable a service you installed on every boot (adds to the 'default' runlevel)</span>
+<span class="p">~#</span> rc-update add crond default
+
+<span class="c"># Disable a service from auto-starting (e.g. Docker, to save memory)</span>
+<span class="p">~#</span> rc-update del docker default</code></pre>
+
+ <h2>Podroid system services</h2>
+ <p>These OpenRC services are part of Podroid's Alpine image. Most start automatically; a few are conditional.</p>
+
+ <table>
+ <thead>
+ <tr><th>Service</th><th>What it does</th></tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><code>podroid-bootstrap</code></td>
+ <td>First service to run. Sets the system clock (AVF path), enables cgroup v2, loads kernel modules, mounts devpts/shm/mqueue, configures ZRAM swap, sets sysctl tunables, sets the hostname, and bind-mounts the persistent ext4 storage onto the Podman/Docker/LXC data directories.</td>
+ </tr>
+ <tr>
+ <td><code>podroid-network</code></td>
+ <td>Brings up eth0 (10.0.2.15/24 on QEMU, DHCP on AVF), adds the default route, and writes <code>/etc/resolv.conf</code>.</td>
+ </tr>
+ <tr>
+ <td><code>podroid-resize</code></td>
+ <td>Runs the terminal resize daemon: reads <code>RESIZE rows cols</code> messages from the ctrl virtio-console (hvc1) and calls <code>stty</code> on hvc0 so the shell prompt redraws correctly after keyboard or orientation changes.</td>
+ </tr>
+ <tr>
+ <td><code>podroid-x11</code></td>
+ <td>Starts Xvnc on display <code>:0</code> (port 5900) and PulseAudio on port 4713. These back the in-app X11 viewer and audio stream.</td>
+ </tr>
+ <tr>
+ <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-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>
+ </tr>
+ <tr>
+ <td><code>dropbear</code></td>
+ <td>SSH server on guest port 22, started at boot. It is reachable from the host and LAN only when the SSH toggle is on (which adds the <code>9922&rarr;22</code> forward). Default credentials: <code>root</code> / <code>podroid</code>.</td>
+ </tr>
+ <tr>
+ <td><code>docker</code></td>
+ <td>Docker daemon. Enabled in the default runlevel, so it starts automatically at boot. Stop it (<code>rc-service docker stop</code>) or disable it (<code>rc-update del docker default</code>) to save memory if you only use Podman.</td>
+ </tr>
+ <tr>
+ <td><code>lxc</code></td>
+ <td>LXC container manager. Also enabled in the default runlevel and starts automatically at boot.</td>
+ </tr>
+ <tr>
+ <td><code>dnsmasq.lxcbr0</code></td>
+ <td>DHCP and DNS for the LXC bridge network (<code>lxcbr0</code>). Started alongside the <code>lxc</code> service.</td>
+ </tr>
+ </tbody>
+ </table>
+
+ <div class="pagenav">
+ <a class="prev" href="networking.html"><span class="dir">Previous</span>&larr; Networking &amp; ports</a>
+ <a class="next" href="desktop.html"><span class="dir">Next</span>Desktops &amp; X11 viewer &rarr;</a>
+ </div>
+ <p class="docfoot">Podroid is free software (GPL). Docs for v1.2.1. Found something inaccurate? <a href="https://github.com/ExTV/Podroid/issues">Open an issue</a>.</p>
+ </main>
+ </div>
+
+ <script>
+ document.querySelector('.menu-toggle').addEventListener('click', function () {
+ document.querySelector('.sidebar').classList.toggle('open');
+ });
+ </script>
+</body>
+</html>
diff --git a/docs/guide/performance.html b/docs/guide/performance.html
new file mode 100644
index 0000000..0169b7c
--- /dev/null
+++ b/docs/guide/performance.html
@@ -0,0 +1,157 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <title>Performance &amp; why it's slow · Podroid docs</title>
+ <meta name="description" content="Why QEMU TCG is slow, where the bottlenecks are, and every tuning knob Podroid exposes to help." />
+ <link rel="icon" type="image/png" href="https://github.com/ExTV.png" />
+ <link rel="preconnect" href="https://fonts.googleapis.com" />
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+ <link href="https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,300;0,9..40,400;0,9..40,500;0,9..40,600;1,9..40,400&family=DM+Mono:wght@400;500&display=swap" rel="stylesheet" />
+ <link rel="stylesheet" href="style.css" />
+</head>
+<body>
+ <nav>
+ <a class="nav-logo" href="../index.html"><img src="../logo.png" alt="Podroid" />Podroid</a>
+ <button class="menu-toggle" aria-label="Toggle menu">&#9776;</button>
+ <ul class="nav-links">
+ <li><a href="../index.html">Home</a></li>
+ <li><a href="index.html" class="cta">Docs</a></li>
+ <li><a href="https://github.com/ExTV/Podroid">GitHub</a></li>
+ </ul>
+ </nav>
+
+ <div class="layout">
+ <aside class="sidebar">
+ <h4>Getting started</h4>
+ <ul>
+ <li><a href="index.html">Overview</a></li>
+ <li><a href="getting-started.html">Getting started</a></li>
+ <li><a href="how-it-works.html">How it works</a></li>
+ </ul>
+ <h4>Going deeper</h4>
+ <ul>
+ <li><a href="performance.html" class="active">Performance &amp; why it's slow</a></li>
+ <li><a href="backends.html">Backends: QEMU &amp; AVF</a></li>
+ <li><a href="networking.html">Networking &amp; ports</a></li>
+ <li><a href="packages.html">Packages &amp; services</a></li>
+ <li><a href="desktop.html">Desktops &amp; X11 viewer</a></li>
+ <li><a href="settings.html">Terminal &amp; settings</a></li>
+ </ul>
+ <h4>Reference</h4>
+ <ul>
+ <li><a href="limitations.html">Limitations &amp; troubleshooting</a></li>
+ <li><a href="use-cases.html">Use cases</a></li>
+ </ul>
+ </aside>
+
+ <main class="content">
+ <h1>Performance &amp; why it's slow</h1>
+ <p class="lead">On the default QEMU path, every guest CPU instruction is emulated in software. There is no shortcut: KVM hardware virtualization is impossible without root on Android. This page explains exactly what that means, where it hurts most, and every tuning knob Podroid applies.</p>
+
+ <h2>The core bottleneck: TCG software emulation</h2>
+ <p>QEMU's CPU backend on Podroid is <strong>TCG</strong> (Tiny Code Generator), a software JIT that translates guest ARM64 instructions into host ARM64 instructions at runtime. The pipeline for each guest basic block is: fetch guest instructions, decode, translate to host IR, optimize, emit host code, cache the result as a "translation block" (TB), execute. Simple scalar code runs at roughly 2-5x the cost of native; anything that creates many short-lived blocks (branch-heavy code, dynamic dispatch, interpreters) compounds that badly.</p>
+
+ <p>Hardware virtualization via KVM would eliminate the translation entirely, letting the guest run directly on the physical CPU cores. KVM requires <code>CAP_SYS_ADMIN</code> or the Android Virtualization Framework's special permissions. The QEMU path has neither. AVF (pKVM) does, which is why it is dramatically faster on devices that support it - see <a href="backends.html">Backends: QEMU &amp; AVF</a>.</p>
+
+ <h2>Why npm, Node, JVM, and compilers crawl</h2>
+
+ <h3>The double-JIT problem</h3>
+ <p>Node.js, the JVM, and similar runtimes are themselves JIT compilers: they watch hot code paths in the guest and emit new machine code at runtime to speed them up. Under TCG, that freshly-generated guest machine code has never been seen before. QEMU must translate it, cache it as TBs, and then the JIT runtime modifies or discards those code pages when it deoptimizes or garbage-collects - which invalidates the TBs. The cycle repeats: generate guest code, translate, invalidate, translate again. The translation-block cache (<code>tb-size</code>) is finite; JIT output that is larger than the cache evicts older entries, causing retranslation stalls on every cache miss. You are paying TCG overhead on top of what the JIT was already doing.</p>
+
+ <h3>Process-spawn cost</h3>
+ <p>Commands like <code>npm install</code>, <code>./configure</code>, and <code>make</code> spawn hundreds or thousands of short-lived child processes. Each new QEMU process starts with a <strong>cold translation cache</strong>. There is no shared TB cache between QEMU process invocations, and no persistent cache on disk. That means the same tiny utilities (<code>sh</code>, <code>awk</code>, <code>grep</code>, <code>cp</code>) are fully re-translated from scratch on every invocation. Even a build step that does trivially little actual computation feels slow because the TCG startup cost dominates. This is the mechanism behind "even small builds feel slow."</p>
+
+ <h2>I/O</h2>
+ <p>Disk I/O travels through three layers: guest virtio-blk driver to QEMU device emulation, then to the host Android filesystem. Podroid assigns a dedicated <strong>I/O thread</strong> to each virtio-blk device so disk requests are handled on a separate thread and do not stall vCPU execution. The guest uses the <code>mq-deadline</code> I/O scheduler for request merging, which matters most for the random small writes Podman's overlay graph driver generates during container image extraction. The ext4 overlay volume is mounted with <code>noatime,commit=60,barrier=0</code> to reduce metadata write amplification.</p>
+
+ <h2>Memory</h2>
+ <p>The default allocation is 512 MB of guest RAM - enough for a shell and basic containers, but tight for npm or a JVM process. Podroid configures <strong>ZRAM swap</strong> inside the guest at <strong>1.5x the VM's RAM</strong>, using lz4 compression. Because lz4 averages around 3x on heap and text pages, that compressed swap costs only a fraction of its size in real RAM - so a 512 MB VM gets roughly 768 MB of extra swap on top of its RAM at near-zero I/O cost (ZRAM lives in RAM; there is no disk read or write). That headroom is what keeps an <code>npm install</code> or a browser tab from immediately hitting the out-of-memory killer. For memory-heavy work, raise RAM in <strong>Settings &rarr; RAM</strong>.</p>
+
+ <h2>Network</h2>
+ <p>Podroid uses <strong>SLIRP</strong>, a userspace TCP/IP stack embedded inside QEMU. It is adequate for bulk transfers (container image pulls, SSH, HTTP) but adds per-packet CPU overhead compared to a kernel network path. High-connection-count workloads - tools that open hundreds of parallel connections like <code>npm install</code> with many dependencies - will feel this overhead in addition to the CPU emulation cost. There is no alternative without root: TAP networking requires a TUN/TAP device or elevated permissions.</p>
+
+ <h2>Tuning summary</h2>
+ <p>The table below lists every tuning measure Podroid applies and what it buys. All of these are already active by default; they are not optional settings you need to find.</p>
+
+ <table>
+ <thead>
+ <tr>
+ <th>Measure</th>
+ <th>Where it lives</th>
+ <th>What it buys</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><code>-cpu max,pauth-impdef=on</code></td>
+ <td>QEMU command line</td>
+ <td>Enables all host CPU extensions in the guest, including non-cryptographic pointer authentication (fast, TCG-native). Up to ~50% on PAuth-heavy code (Rust, recent Clang output).</td>
+ </tr>
+ <tr>
+ <td><code>-accel tcg,thread=multi</code></td>
+ <td>QEMU command line</td>
+ <td>One host thread per vCPU. Without this all vCPUs share one host thread and can't use more than one core. Enables real SMP scaling.</td>
+ </tr>
+ <tr>
+ <td><code>tb-size=256</code> (&lt;2 GB RAM) / <code>tb-size=512</code> (&ge;2 GB RAM)</td>
+ <td>QEMU command line</td>
+ <td>Larger translation-block cache reduces re-translation for JIT-heavy workloads (Node, JVM in containers). Default QEMU value is 32 MB.</td>
+ </tr>
+ <tr>
+ <td>Per-disk <code>iothread</code></td>
+ <td>QEMU command line</td>
+ <td>Dedicated I/O thread per virtio-blk device, decoupled from vCPU threads. Largest single win for container image pull and extraction.</td>
+ </tr>
+ <tr>
+ <td><code>mitigations=off</code> in kernel cmdline</td>
+ <td>Guest kernel boot args</td>
+ <td>Disables Spectre/Meltdown mitigations inside the guest. Safe inside a TCG VM: speculative execution attacks cannot cross the emulated ISA boundary. Saves 5-15% CPU on syscall-heavy workloads.</td>
+ </tr>
+ <tr>
+ <td><code>mq-deadline</code> I/O scheduler</td>
+ <td>Guest kernel cmdline (<code>elevator=mq-deadline</code>)</td>
+ <td>Request merging for virtio-blk random writes. Reduces write amplification on Podman overlay graph driver operations.</td>
+ </tr>
+ <tr>
+ <td>ZRAM swap at 1.5x RAM (lz4)</td>
+ <td>Guest init (<code>podroid-bootstrap</code> OpenRC service)</td>
+ <td>lz4 (~3x on heap/text) makes the compressed swap cost a fraction of its size, giving large headroom against the out-of-memory killer at near-zero I/O cost. Priority 100 so it is preferred over any file swap.</td>
+ </tr>
+ <tr>
+ <td>ext4 <code>noatime,commit=60,barrier=0</code></td>
+ <td>Overlay volume mount options</td>
+ <td>Skips access-time updates, batches journal commits to 60-second windows, and omits write barriers (safe: data loss on crash only risks the 60-second window, not the filesystem). Reduces metadata I/O on package-install workloads.</td>
+ </tr>
+ <tr>
+ <td><code>metacopy=on</code> on overlayfs</td>
+ <td>Overlay mount options</td>
+ <td>Copies only inode metadata (not data) when a file is stat'd or chmod'd on the overlay. Speeds up container image layer application.</td>
+ </tr>
+ </tbody>
+ </table>
+
+ <h2>What won't help without root</h2>
+ <p>Some common Linux performance tricks are simply unavailable on a stock Android device: <code>io_uring</code> is blocked by Android 12+ seccomp policy; CPU affinity (<code>taskset</code>) requires elevated scheduling permissions; KSM memory deduplication is a kernel knob; huge pages on the host are not user-configurable; TAP networking requires a TUN/TAP device. These are hard limits, not oversights.</p>
+
+ <div class="callout tip">
+ <span class="label">Biggest wins</span>
+ <p>If you have a Pixel 8, 9, or 10 (or another device shipping pKVM), switch the backend to <strong>AVF</strong> in Settings &rarr; Advanced. AVF runs the guest on real hardware CPU cores via the kernel hypervisor - no TCG, no double-JIT overhead, no cold-cache process-spawn cost. See <a href="backends.html">Backends: QEMU &amp; AVF</a> for setup. For heavy workloads on any backend, also raise RAM in Settings and lower the X11 viewer resolution if you are running a desktop.</p>
+ </div>
+
+ <div class="pagenav">
+ <a class="prev" href="how-it-works.html"><span class="dir">Previous</span>&larr; How it works</a>
+ <a class="next" href="backends.html"><span class="dir">Next</span>Backends: QEMU &amp; AVF &rarr;</a>
+ </div>
+ <p class="docfoot">Podroid is free software (GPL). Docs for v1.2.1. Found something inaccurate? <a href="https://github.com/ExTV/Podroid/issues">Open an issue</a>.</p>
+ </main>
+ </div>
+
+ <script>
+ document.querySelector('.menu-toggle').addEventListener('click', function () {
+ document.querySelector('.sidebar').classList.toggle('open');
+ });
+ </script>
+</body>
+</html>
diff --git a/docs/guide/settings.html b/docs/guide/settings.html
new file mode 100644
index 0000000..cc17a37
--- /dev/null
+++ b/docs/guide/settings.html
@@ -0,0 +1,211 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <title>Terminal &amp; settings · Podroid docs</title>
+ <meta name="description" content="Reference for the Podroid terminal (Quick Settings, themes, fonts) and every in-app setting: RAM, CPU, storage, SSH, port forwards, backend, advanced QEMU args, diagnostics." />
+ <link rel="icon" type="image/png" href="https://github.com/ExTV.png" />
+ <link rel="preconnect" href="https://fonts.googleapis.com" />
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+ <link href="https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,300;0,9..40,400;0,9..40,500;0,9..40,600;1,9..40,400&family=DM+Mono:wght@400;500&display=swap" rel="stylesheet" />
+ <link rel="stylesheet" href="style.css" />
+</head>
+<body>
+ <nav>
+ <a class="nav-logo" href="../index.html"><img src="../logo.png" alt="Podroid" />Podroid</a>
+ <button class="menu-toggle" aria-label="Toggle menu">&#9776;</button>
+ <ul class="nav-links">
+ <li><a href="../index.html">Home</a></li>
+ <li><a href="index.html" class="cta">Docs</a></li>
+ <li><a href="https://github.com/ExTV/Podroid">GitHub</a></li>
+ </ul>
+ </nav>
+
+ <div class="layout">
+ <aside class="sidebar">
+ <h4>Getting started</h4>
+ <ul>
+ <li><a href="index.html">Overview</a></li>
+ <li><a href="getting-started.html">Getting started</a></li>
+ <li><a href="how-it-works.html">How it works</a></li>
+ </ul>
+ <h4>Going deeper</h4>
+ <ul>
+ <li><a href="performance.html">Performance &amp; why it's slow</a></li>
+ <li><a href="backends.html">Backends: QEMU &amp; AVF</a></li>
+ <li><a href="networking.html">Networking &amp; ports</a></li>
+ <li><a href="packages.html">Packages &amp; services</a></li>
+ <li><a href="desktop.html">Desktops &amp; X11 viewer</a></li>
+ <li><a href="settings.html" class="active">Terminal &amp; settings</a></li>
+ </ul>
+ <h4>Reference</h4>
+ <ul>
+ <li><a href="limitations.html">Limitations &amp; troubleshooting</a></li>
+ <li><a href="use-cases.html">Use cases</a></li>
+ </ul>
+ </aside>
+
+ <main class="content">
+ <h1>Terminal &amp; settings</h1>
+ <p class="lead">The Podroid terminal is built on the Termux engine: xterm-256color, true color, mouse tracking, and live resize. This page covers the Quick Settings drawer in the terminal and every option in the main Settings screen.</p>
+
+ <h2>Terminal Quick Settings</h2>
+ <p>Tap the tune icon in the terminal's top bar to open the Quick Settings drawer. All changes apply immediately without restarting the VM.</p>
+ <ul>
+ <li><strong>Font size slider</strong> - drag to resize text live.</li>
+ <li><strong>Color themes</strong> - over 100 themes including Dracula, Nord, Solarized Dark and Light, Tokyo Night, Catppuccin, Gruvbox, Monokai, and the full base16 family. You can also import any theme via a terminalcolors.com URL.</li>
+ <li><strong>Fonts</strong> - 13 built-in fonts including JetBrains Mono, Fira Code, Cascadia Code, Hack, Iosevka, and Victor Mono. Import any <code>.ttf</code> file for a custom font.</li>
+ <li><strong>Extra-keys toggle</strong> - show or hide the row of shortcut keys below the terminal.</li>
+ <li><strong>Haptics toggle</strong> - enable or disable vibration feedback on key presses.</li>
+ </ul>
+
+ <h2>Settings reference</h2>
+
+ <h3>Appearance</h3>
+ <table>
+ <thead>
+ <tr>
+ <th>Setting</th>
+ <th>Control</th>
+ <th>Notes</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>Dark theme</td>
+ <td>Toggle</td>
+ <td>Switches the app UI between light and dark. Applies immediately.</td>
+ </tr>
+ <tr>
+ <td>Dynamic color / Material You</td>
+ <td>Toggle</td>
+ <td>Uses your wallpaper's colors as the app accent palette. Android 12+ only.</td>
+ </tr>
+ </tbody>
+ </table>
+
+ <h3>VM resources</h3>
+
+ <div class="callout note">
+ <span class="label">Restart required</span>
+ <p>RAM, CPU, and Backend changes take effect only after the VM is restarted. These controls are locked (grayed out) while the VM is running. Port-forward and SSH changes apply live without a restart.</p>
+ </div>
+
+ <table>
+ <thead>
+ <tr>
+ <th>Setting</th>
+ <th>Control</th>
+ <th>Notes</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>RAM</td>
+ <td>512 MB / 1 GB / 2 GB / 4 GB</td>
+ <td>Memory allocated to the VM. Requires a VM restart. Locked while running.</td>
+ </tr>
+ <tr>
+ <td>CPU cores</td>
+ <td>1 / 2 / 4 / 6 / 8</td>
+ <td>vCPU count passed to QEMU. Requires a VM restart. On AVF, any value above 1 uses all available host cores.</td>
+ </tr>
+ <tr>
+ <td>Storage size</td>
+ <td>Set at first-run setup</td>
+ <td>The size of the persistent overlay image (<code>storage.img</code>). Set during setup; changing it requires a full VM reset.</td>
+ </tr>
+ </tbody>
+ </table>
+
+ <h3>Connectivity</h3>
+ <table>
+ <thead>
+ <tr>
+ <th>Setting</th>
+ <th>Control</th>
+ <th>Notes</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>SSH</td>
+ <td>Toggle</td>
+ <td>Exposes dropbear on host port 9922 (forwarded to guest port 22). Default credentials: username <code>root</code>, password <code>podroid</code>. Injects and removes the 9922 forward live via QMP.</td>
+ </tr>
+ <tr>
+ <td>Port forwards</td>
+ <td>Add / Remove</td>
+ <td>Add TCP, UDP, or both forwarding rules. Changes apply live via QMP without a VM restart.</td>
+ </tr>
+ <tr>
+ <td>Downloads sharing</td>
+ <td>Toggle</td>
+ <td>Shares the Android Downloads folder into the VM as a virtio-fs mount. May be a no-op on some AVF devices. Can be unstable on some QEMU configurations; disable it if the VM crashes on boot.</td>
+ </tr>
+ </tbody>
+ </table>
+
+ <h3>Advanced</h3>
+ <table>
+ <thead>
+ <tr>
+ <th>Setting</th>
+ <th>Control</th>
+ <th>Notes</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>Backend</td>
+ <td>Auto / AVF (KVM) / QEMU (TCG)</td>
+ <td>Auto picks AVF when the device supports it, otherwise QEMU. Requires a VM restart. See the <a href="backends.html">Backends</a> page for details.</td>
+ </tr>
+ <tr>
+ <td>Extra QEMU args</td>
+ <td>Editable text field + Reset</td>
+ <td>
+ Appended verbatim to the QEMU command line. Default:<br />
+ <code>-cpu max,sve=off,pauth-impdef=on -accel tcg,thread=multi,tb-size=512 -object rng-random,id=rng0,filename=/dev/urandom -device virtio-rng-pci,rng=rng0 -overcommit mem-lock=off</code>
+ </td>
+ </tr>
+ <tr>
+ <td>Extra kernel cmdline</td>
+ <td>Editable text field + Reset</td>
+ <td>
+ Appended to the kernel command line. Default:<br />
+ <code>loglevel=1 quiet mitigations=off</code>
+ </td>
+ </tr>
+ <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>
+ </tr>
+ </tbody>
+ </table>
+
+ <h2>Diagnostics</h2>
+ <p>Open <strong>Settings &rarr; About</strong> for diagnostics tools:</p>
+ <ul>
+ <li><strong>Export diagnostic log</strong> - writes and shares a <code>log.txt</code> containing app version, device info, current settings, VM state, port-forward rules, AVF capability probe results, recent app logcat, and the full guest <code>console.log</code>. Attach this to bug reports.</li>
+ <li><strong>Verbose AVF logging</strong> - toggle that adds extra detail to AVF-related log output. Useful when investigating AVF-specific issues.</li>
+ <li><strong>AVF (pKVM) diagnostic</strong> - runs the capability and permission probe immediately and shows the result, so you can confirm whether your device meets AVF requirements without attempting a boot.</li>
+ </ul>
+
+ <div class="pagenav">
+ <a class="prev" href="desktop.html"><span class="dir">Previous</span>← Desktops &amp; X11 viewer</a>
+ <a class="next" href="limitations.html"><span class="dir">Next</span>Limitations &amp; troubleshooting →</a>
+ </div>
+ <p class="docfoot">Podroid is free software (GPL). Docs for v1.2.1. Found something inaccurate? <a href="https://github.com/ExTV/Podroid/issues">Open an issue</a>.</p>
+ </main>
+ </div>
+
+ <script>
+ document.querySelector('.menu-toggle').addEventListener('click', function () {
+ document.querySelector('.sidebar').classList.toggle('open');
+ });
+ </script>
+</body>
+</html>
diff --git a/docs/guide/style.css b/docs/guide/style.css
new file mode 100644
index 0000000..0d6fea7
--- /dev/null
+++ b/docs/guide/style.css
@@ -0,0 +1,148 @@
+/* Podroid documentation - shared styles. Matches the landing page (../index.html):
+ Tokyo Night palette, DM Sans + DM Mono. */
+
+*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+:root {
+ --bg: #1a1b26;
+ --bg-dark: #16161e;
+ --bg-card: #1f2335;
+ --bg-card2: #24283b;
+ --border: #292e42;
+ --text: #c0caf5;
+ --text-dim: #a9b1d6;
+ --muted: #7982b0;
+ --green: #9ece6a;
+ --green-dim: #1e3319;
+ --blue: #7aa2f7;
+ --cyan: #7dcfff;
+ --yellow: #e0af68;
+ --red: #f7768e;
+ --purple: #bb9af7;
+}
+
+html { scroll-behavior: smooth; }
+
+body {
+ font-family: 'DM Sans', sans-serif;
+ background: var(--bg);
+ color: var(--text);
+ line-height: 1.65;
+ -webkit-font-smoothing: antialiased;
+}
+
+a { color: var(--blue); text-decoration: none; }
+a:hover { color: var(--cyan); text-decoration: underline; }
+
+code, pre, .mono { font-family: 'DM Mono', monospace; }
+
+/* ── top nav (matches landing) ─────────────────────────── */
+nav {
+ position: sticky; top: 0; z-index: 100;
+ display: flex; align-items: center; justify-content: space-between;
+ padding: 0 1.5rem; height: 56px;
+ background: rgb(22 22 30 / 0.9);
+ backdrop-filter: blur(14px);
+ border-bottom: 1px solid var(--border);
+}
+.nav-logo { display: flex; align-items: center; gap: 0.6rem; font-weight: 600; font-size: 1rem; color: var(--text); text-decoration: none !important; }
+.nav-logo img { width: 26px; height: 26px; border-radius: 6px; }
+.nav-links { display: flex; align-items: center; gap: 1.4rem; list-style: none; }
+.nav-links a { color: var(--muted); font-size: 0.875rem; font-weight: 500; white-space: nowrap; transition: color 0.15s; }
+.nav-links a:hover { color: var(--text-dim); text-decoration: none; }
+.nav-links a.cta { color: var(--green); }
+.menu-toggle { display: none; background: none; border: 1px solid var(--border); color: var(--text-dim); border-radius: 6px; padding: 0.35rem 0.6rem; font-size: 1rem; cursor: pointer; }
+
+/* ── docs layout ───────────────────────────────────────── */
+.layout { display: flex; max-width: 1200px; margin: 0 auto; align-items: flex-start; }
+
+.sidebar {
+ position: sticky; top: 56px;
+ width: 248px; flex: none;
+ height: calc(100vh - 56px);
+ overflow-y: auto;
+ padding: 1.75rem 1rem 3rem 1.5rem;
+ border-right: 1px solid var(--border);
+}
+.sidebar h4 {
+ font-size: 0.72rem; text-transform: uppercase; letter-spacing: 0.08em;
+ color: var(--muted); margin: 1.4rem 0 0.5rem; font-weight: 600;
+}
+.sidebar h4:first-child { margin-top: 0; }
+.sidebar ul { list-style: none; }
+.sidebar li a {
+ display: block; padding: 0.32rem 0.7rem; border-radius: 6px;
+ color: var(--text-dim); font-size: 0.9rem; transition: background 0.12s, color 0.12s;
+}
+.sidebar li a:hover { background: var(--bg-card); color: var(--text); text-decoration: none; }
+.sidebar li a.active { background: var(--green-dim); color: var(--green); font-weight: 600; }
+
+.content { flex: 1; min-width: 0; padding: 2.5rem 2.5rem 5rem; max-width: 820px; }
+
+/* ── prose ─────────────────────────────────────────────── */
+.content h1 { font-size: 2.1rem; font-weight: 600; letter-spacing: -0.02em; margin-bottom: 0.4rem; color: #fff; }
+.content h2 { font-size: 1.45rem; font-weight: 600; margin: 2.6rem 0 0.9rem; padding-top: 0.6rem; color: #fff; border-top: 1px solid var(--border); }
+.content h3 { font-size: 1.12rem; font-weight: 600; margin: 1.8rem 0 0.6rem; color: var(--text); }
+.content p { margin: 0.85rem 0; color: var(--text-dim); }
+.content .lead { font-size: 1.12rem; color: var(--text); margin: 0.6rem 0 1.6rem; }
+.content ul, .content ol { margin: 0.85rem 0 0.85rem 1.4rem; color: var(--text-dim); }
+.content li { margin: 0.35rem 0; }
+.content strong { color: var(--text); font-weight: 600; }
+.content hr { border: none; border-top: 1px solid var(--border); margin: 2rem 0; }
+
+/* inline + block code */
+.content :not(pre) > code {
+ background: var(--bg-card2); color: var(--cyan);
+ padding: 0.12em 0.4em; border-radius: 4px; font-size: 0.86em;
+ border: 1px solid var(--border);
+}
+.content pre {
+ background: var(--bg-dark); border: 1px solid var(--border); border-radius: 8px;
+ padding: 1rem 1.1rem; overflow-x: auto; margin: 1rem 0; font-size: 0.85rem; line-height: 1.55;
+}
+.content pre code { color: var(--text); background: none; border: none; padding: 0; }
+.content pre .c { color: var(--muted); } /* comment */
+.content pre .p { color: var(--green); } /* prompt / key */
+
+/* tables */
+.content table { width: 100%; border-collapse: collapse; margin: 1.2rem 0; font-size: 0.88rem; }
+.content th, .content td { text-align: left; padding: 0.6rem 0.8rem; border: 1px solid var(--border); vertical-align: top; }
+.content th { background: var(--bg-card2); color: var(--text); font-weight: 600; }
+.content td { color: var(--text-dim); }
+.content tr:nth-child(even) td { background: var(--bg-card); }
+
+/* callouts */
+.callout { border-radius: 8px; padding: 0.85rem 1.1rem; margin: 1.2rem 0; border: 1px solid var(--border); border-left-width: 3px; background: var(--bg-card); }
+.callout p { margin: 0.3rem 0; color: var(--text-dim); }
+.callout strong { color: var(--text); }
+.callout.note { border-left-color: var(--blue); }
+.callout.tip { border-left-color: var(--green); }
+.callout.warn { border-left-color: var(--yellow); }
+.callout.danger { border-left-color: var(--red); }
+.callout .label { font-weight: 600; font-size: 0.78rem; text-transform: uppercase; letter-spacing: 0.06em; display: block; margin-bottom: 0.2rem; }
+.callout.note .label { color: var(--blue); }
+.callout.tip .label { color: var(--green); }
+.callout.warn .label { color: var(--yellow); }
+.callout.danger .label { color: var(--red); }
+
+/* page footer nav (prev/next) */
+.pagenav { display: flex; justify-content: space-between; gap: 1rem; margin-top: 3rem; padding-top: 1.5rem; border-top: 1px solid var(--border); }
+.pagenav a { display: inline-flex; flex-direction: column; gap: 0.15rem; padding: 0.7rem 1rem; border: 1px solid var(--border); border-radius: 8px; font-size: 0.9rem; max-width: 48%; }
+.pagenav a:hover { border-color: var(--muted); text-decoration: none; background: var(--bg-card); }
+.pagenav .dir { font-size: 0.72rem; color: var(--muted); text-transform: uppercase; letter-spacing: 0.05em; }
+.pagenav .next { text-align: right; margin-left: auto; }
+
+.docfoot { color: var(--muted); font-size: 0.8rem; margin-top: 2.5rem; }
+
+/* ── responsive ────────────────────────────────────────── */
+@media (max-width: 860px) {
+ .menu-toggle { display: inline-block; }
+ .layout { display: block; }
+ .sidebar {
+ position: static; width: auto; height: auto; border-right: none;
+ border-bottom: 1px solid var(--border); display: none; padding: 1rem 1.5rem;
+ }
+ .sidebar.open { display: block; }
+ .content { padding: 1.75rem 1.5rem 4rem; max-width: none; }
+ .content h1 { font-size: 1.7rem; }
+}
diff --git a/docs/guide/use-cases.html b/docs/guide/use-cases.html
new file mode 100644
index 0000000..e11b534
--- /dev/null
+++ b/docs/guide/use-cases.html
@@ -0,0 +1,174 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <title>Use cases · Podroid docs</title>
+ <meta name="description" content="Practical use cases for Podroid: self-hosting containers, local Linux development, GUI apps, and learning Linux." />
+ <link rel="icon" type="image/png" href="https://github.com/ExTV.png" />
+ <link rel="preconnect" href="https://fonts.googleapis.com" />
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+ <link href="https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,300;0,9..40,400;0,9..40,500;0,9..40,600;1,9..40,400&family=DM+Mono:wght@400;500&display=swap" rel="stylesheet" />
+ <link rel="stylesheet" href="style.css" />
+</head>
+<body>
+ <nav>
+ <a class="nav-logo" href="../index.html"><img src="../logo.png" alt="Podroid" />Podroid</a>
+ <button class="menu-toggle" aria-label="Toggle menu">&#9776;</button>
+ <ul class="nav-links">
+ <li><a href="../index.html">Home</a></li>
+ <li><a href="index.html" class="cta">Docs</a></li>
+ <li><a href="https://github.com/ExTV/Podroid">GitHub</a></li>
+ </ul>
+ </nav>
+
+ <div class="layout">
+ <aside class="sidebar">
+ <h4>Getting started</h4>
+ <ul>
+ <li><a href="index.html">Overview</a></li>
+ <li><a href="getting-started.html">Getting started</a></li>
+ <li><a href="how-it-works.html">How it works</a></li>
+ </ul>
+ <h4>Going deeper</h4>
+ <ul>
+ <li><a href="performance.html">Performance &amp; why it's slow</a></li>
+ <li><a href="backends.html">Backends: QEMU &amp; AVF</a></li>
+ <li><a href="networking.html">Networking &amp; ports</a></li>
+ <li><a href="packages.html">Packages &amp; services</a></li>
+ <li><a href="desktop.html">Desktops &amp; X11 viewer</a></li>
+ <li><a href="settings.html">Terminal &amp; settings</a></li>
+ </ul>
+ <h4>Reference</h4>
+ <ul>
+ <li><a href="limitations.html">Limitations &amp; troubleshooting</a></li>
+ <li><a href="use-cases.html" class="active">Use cases</a></li>
+ </ul>
+ </aside>
+
+ <main class="content">
+ <h1>Use cases</h1>
+ <p class="lead">What Podroid is genuinely good for, what it does with caveats, and what to avoid - with honest notes on TCG performance throughout.</p>
+
+ <h2>Self-hosting via containers</h2>
+ <p>Rootless Podman, Docker and LXC are all ready the moment the VM boots: Podman needs no daemon, and the Docker and LXC services are enabled in the default runlevel, so they start automatically. You can run any ARM64 container image from Docker Hub or GHCR.</p>
+ <p>Port forwarding rules (see <a href="networking.html">Networking &amp; ports</a>) expose guest ports on the phone's real IP. Use a host port above 1024 for anything you expose, because an unprivileged Android app cannot bind host ports below 1024.</p>
+ <pre><code><span class="c"># Pi-hole (DNS + ad-blocking)</span>
+<span class="p">$</span> podman run -d --name pihole \
+ -p 8080:80 -p 5353:53/tcp \
+ -e TZ=Europe/London \
+ docker.io/pihole/pihole:latest
+
+<span class="c"># Gitea (self-hosted Git)</span>
+<span class="p">$</span> podman run -d --name gitea \
+ -p 3000:3000 -p 2222:22 \
+ -v gitea-data:/data \
+ docker.io/gitea/gitea:latest-linux-arm64
+
+<span class="c"># Vaultwarden (Bitwarden-compatible password server)</span>
+<span class="p">$</span> podman run -d --name vaultwarden \
+ -p 8888:80 \
+ -v vaultwarden-data:/data \
+ docker.io/vaultwarden/server:latest
+
+<span class="c"># code-server (VS Code in the browser)</span>
+<span class="p">$</span> podman run -d --name code-server \
+ -p 8443:8443 \
+ -v "$HOME/.config:/home/coder/.config" \
+ -v "$PWD:/home/coder/project" \
+ ghcr.io/coder/code-server:latest \
+ --bind-addr 0.0.0.0:8443 /home/coder/project</code></pre>
+
+ <div class="callout note">
+ <span class="label">JVM-heavy services</span>
+ <p>Services backed by a JVM - Gitea's built-in runner, Jenkins, Gradle builds inside code-server, and anything running on Java or Kotlin - are noticeably slow on the QEMU TCG backend. JVM startup alone can take 10-30 seconds. If you rely on these services heavily, enabling the <a href="backends.html">AVF backend</a> on a Pixel device makes a large practical difference.</p>
+ </div>
+
+ <h2>Local Linux development environment</h2>
+ <p>The Alpine guest is a full persistent Linux system. Install your toolchain once and it survives every reboot on the ext4 overlay.</p>
+ <pre><code><span class="c"># Install a development toolchain</span>
+<span class="p">$</span> apk add git nodejs npm python3 py3-pip go gcc musl-dev make
+
+<span class="c"># SSH in from a laptop on the same Wi-Fi</span>
+<span class="p">$</span> ssh root@&lt;phone-ip&gt; -p 9922</code></pre>
+ <p>Once SSH is working, VS Code Remote-SSH and JetBrains Gateway both connect without any plugin beyond their standard remote-development extension. The phone acts exactly like any remote Linux server from the laptop's point of view.</p>
+ <p>Persistence is handled by the overlayfs stack: all writes go to the ext4 <code>storage.img</code>. Packages you install with <code>apk add</code>, files you create, services you enable with <code>rc-update add</code> - all survive reboots and app updates.</p>
+
+ <div class="callout tip">
+ <span class="label">IO-bound vs CPU-bound work</span>
+ <p>Text editing, shell scripting, Git operations, and short Python scripts are comfortable on TCG - these workloads spend most time on IO and memory, where the emulation overhead is low. Long compilations (LLVM, Linux kernel, large Rust projects) will be painfully slow; for those, prefer cross-compiling on the laptop and copying binaries over SSH.</p>
+ </div>
+
+ <h2>GUI Linux apps</h2>
+ <p>The in-app X11 viewer connects to an Xvnc display in the guest. Install a desktop environment or individual X11 apps and they appear directly in the viewer with touch, external keyboard and mouse, and audio forwarding.</p>
+ <pre><code><span class="c"># Install XFCE and common accessories</span>
+<span class="p">$</span> apk add xfce4 xfce4-terminal mousepad ristretto xfce4-taskmanager
+
+<span class="c"># Install Firefox (ARM64 build)</span>
+<span class="p">$</span> apk add firefox
+
+<span class="c"># Install GIMP</span>
+<span class="p">$</span> apk add gimp</code></pre>
+ <p>See <a href="desktop.html">Desktops &amp; X11 viewer</a> for how to start and configure the Xvnc session. Note that only X11 desktop sessions render correctly; Wayland sessions (GNOME on Wayland, Plasma Wayland, sway) do not render in the viewer - see <a href="limitations.html">Limitations</a>.</p>
+
+ <h2>Learning Linux and containers</h2>
+ <p>Podroid gives you a real Linux kernel with cgroup v2, network namespaces, overlayfs, netfilter/nftables, and OpenRC - all on hardware you already own. Nothing is simulated or mocked; the same kernel features that production servers use are present and explorable.</p>
+ <pre><code><span class="c"># Inspect the cgroup v2 hierarchy</span>
+<span class="p">$</span> mount | grep cgroup
+<span class="p">$</span> ls /sys/fs/cgroup/
+
+<span class="c"># Run a container and inspect its namespaces</span>
+<span class="p">$</span> podman run --rm -it alpine sh
+<span class="p">$</span> ls -la /proc/1/ns/
+
+<span class="c"># Examine the overlayfs mount used by Podman's graph driver</span>
+<span class="p">$</span> podman info | grep graphDriver
+<span class="p">$</span> mount | grep overlay
+
+<span class="c"># Explore OpenRC service management</span>
+<span class="p">$</span> rc-status
+<span class="p">$</span> rc-update add sshd default
+<span class="p">$</span> rc-service sshd start
+
+<span class="c"># Inspect nftables rules added by Podman for port forwarding</span>
+<span class="p">$</span> nft list ruleset</code></pre>
+ <p>Because this is a real VM, experiments that would break a shared server are safe here - a factory reset restores a clean Alpine image in under a minute. You can deliberately crash the kernel, fill the disk, or misconfigure networking and recover immediately.</p>
+
+ <h2>Lightweight CLI tools and scripts</h2>
+ <p>Running cron jobs, personal bots, data processing scripts, or static site generators is one of the most practical uses on TCG. These workloads are typically IO-bound or short-lived, so the 5-20x CPU penalty of TCG emulation is barely noticeable compared to the time spent waiting on network or disk.</p>
+ <pre><code><span class="c"># Install common CLI tooling</span>
+<span class="p">$</span> apk add curl jq rsync htop tmux vim ffmpeg yt-dlp
+
+<span class="c"># Run a Python script on a schedule</span>
+<span class="p">$</span> echo "*/15 * * * * python3 /root/sync.py" | crontab -
+<span class="p">$</span> rc-update add crond default &amp;&amp; rc-service crond start</code></pre>
+
+ <h2>What works poorly</h2>
+ <ul>
+ <li><strong>Wayland desktops</strong> - GNOME Wayland, Plasma Wayland, sway, and Hyprland do not render in the X11 viewer. Use XFCE or another X11 session instead.</li>
+ <li><strong>Heavy compilation on TCG</strong> - building LLVM, the Linux kernel, or large Rust crates inside the VM is feasible but very slow (hours, not minutes). Cross-compile on a real machine and copy the result over SSH.</li>
+ <li><strong>x86 Docker images</strong> - pulling an <code>linux/amd64</code> image runs it under double emulation (QEMU TCG emulating ARM64 guest, which then runs QEMU user-mode emulating x86). Expect 50-100x slowdown. Always prefer <code>linux/arm64</code> images.</li>
+ <li><strong>UDP port forwarding on AVF</strong> - UDP rules are silently ignored on the AVF backend; switch to QEMU if you need UDP (e.g. a game server or DNS resolver serving LAN clients).</li>
+ <li><strong>A full desktop environment at 512 MB RAM</strong> - XFCE with a browser open will page heavily into ZRAM swap at 512 MB. Set RAM to 1 GB or more in Settings if you plan to run a desktop regularly.</li>
+ </ul>
+
+ <div class="callout tip">
+ <span class="label">Getting better performance</span>
+ <p>If TCG is too slow for your workload, the most impactful step is switching to the <a href="backends.html">AVF backend</a> on a Pixel 8 or later - it provides near-native CPU speed. Bumping RAM above 1 GB also helps containers and desktops avoid swap pressure. The <a href="performance.html">Performance &amp; why it's slow</a> page covers every tuning option in detail. For hard limits such as Wayland or UDP-on-AVF, see <a href="limitations.html">Limitations &amp; troubleshooting</a>.</p>
+ </div>
+
+ <div class="pagenav">
+ <a class="prev" href="limitations.html"><span class="dir">Previous</span>&larr; Limitations &amp; troubleshooting</a>
+ <span></span>
+ </div>
+ <p class="docfoot">Podroid is free software (GPL). Docs for v1.2.1. Found something inaccurate? <a href="https://github.com/ExTV/Podroid/issues">Open an issue</a>.</p>
+ </main>
+ </div>
+
+ <script>
+ document.querySelector('.menu-toggle').addEventListener('click', function () {
+ document.querySelector('.sidebar').classList.toggle('open');
+ });
+ </script>
+</body>
+</html>
diff --git a/docs/index.html b/docs/index.html
index 51a3ac6..cf2049e 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -543,6 +543,7 @@
<li><a href="#how">How it works</a></li>
<li><a href="#quickstart">Quick start</a></li>
<li><a href="#faq">FAQ</a></li>
+ <li><a href="guide/">Docs</a></li>
</ul>
</nav>
@@ -559,6 +560,10 @@
<svg width="14" height="14" fill="none" stroke="currentColor" stroke-width="2.2" viewBox="0 0 24 24"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><polyline points="7 10 12 15 17 10"/><line x1="12" y1="15" x2="12" y2="3"/></svg>
Download APK
</a>
+ <a href="guide/" class="btn btn-ghost">
+ <svg width="14" height="14" fill="none" stroke="currentColor" stroke-width="2.2" viewBox="0 0 24 24"><path d="M2 3h6a4 4 0 0 1 4 4v14a3 3 0 0 0-3-3H2z"/><path d="M22 3h-6a4 4 0 0 0-4 4v14a3 3 0 0 1 3-3h7z"/></svg>
+ Read the docs
+ </a>
<a href="https://github.com/ExTV/Podroid" class="btn btn-ghost">
<svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor"><path d="M12 0C5.37 0 0 5.37 0 12c0 5.31 3.435 9.795 8.205 11.385.6.105.825-.255.825-.57 0-.285-.015-1.23-.015-2.235-3.015.555-3.795-.735-4.035-1.41-.135-.345-.72-1.41-1.23-1.695-.42-.225-1.02-.78-.015-.795.945-.015 1.62.87 1.845 1.23 1.08 1.815 2.805 1.305 3.495.99.105-.78.42-1.305.765-1.605-2.67-.3-5.46-1.335-5.46-5.925 0-1.305.465-2.385 1.23-3.225-.12-.3-.54-1.53.12-3.18 0 0 1.005-.315 3.3 1.23.96-.27 1.98-.405 3-.405s2.04.135 3 .405c2.295-1.56 3.3-1.23 3.3-1.23.66 1.65.24 2.88.12 3.18.765.84 1.23 1.905 1.23 3.225 0 4.605-2.805 5.625-5.475 5.925.435.375.81 1.095.81 2.22 0 1.605-.015 2.895-.015 3.3 0 .315.225.69.825.57A12.02 12.02 0 0 0 24 12c0-6.63-5.37-12-12-12z"/></svg>
View on GitHub
@@ -879,7 +884,7 @@ qmp.sock → runtime port-forward control</div>
<div class="container">
<p class="section-label">FAQ</p>
<h2>Common questions</h2>
- <p class="section-sub">If something isn't covered here, open an issue on GitHub.</p>
+ <p class="section-sub">For the full picture, read the <a href="guide/">documentation</a>. If something still isn't covered, open an issue on GitHub.</p>
<div class="faq-list">