Skip to content

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

docs(site): cover backup, status, load balance; fix AVF Downloads sharing

ExTv43aaaa0e597d
diff --git a/docs/guide/backends.html b/docs/guide/backends.html
index 1322146..10162f9 100644
--- a/docs/guide/backends.html
+++ b/docs/guide/backends.html
@@ -147,8 +147,8 @@
</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>
+ <td>Supported (virtio-9p)</td>
+ <td>Supported (in-process 9p2000.L server over vsock)</td>
</tr>
<tr>
<td>USB device passthrough</td>
diff --git a/docs/guide/getting-started.html b/docs/guide/getting-started.html
index 81e6cb0..c8c79a2 100644
--- a/docs/guide/getting-started.html
+++ b/docs/guide/getting-started.html
@@ -79,11 +79,11 @@
<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>
+ <p>Grants access to your phone's Downloads folder so you can move files between Android and the VM. Works on both the QEMU and AVF backends. 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>
+ <p>On the QEMU backend, Downloads sharing can be unstable on some devices. If the VM behaves oddly after enabling it, try disabling it in Settings. The AVF path is stable.</p>
</div>
<h2>First boot</h2>
@@ -97,9 +97,11 @@
<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>VM status</strong> and uptime, with a shutting-down indicator while the VM stops</li>
<li><strong>Network info</strong> - your phone's IP address, SSH endpoint, and how many port-forward rules are active</li>
+ <li><strong>Containers created</strong> - a running count of containers you've created</li>
<li><strong>Start / Stop</strong> button</li>
+ <li><strong>Backup</strong> and <strong>Status</strong> buttons - see <a href="use-cases.html">Use cases</a> for what each does</li>
</ul>
<h2>Terminal and X11 viewer</h2>
diff --git a/docs/guide/limitations.html b/docs/guide/limitations.html
index c0a6682..164105d 100644
--- a/docs/guide/limitations.html
+++ b/docs/guide/limitations.html
@@ -108,9 +108,9 @@
<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>
+ <td>Downloads sharing (QEMU)</td>
+ <td>Can crash QEMU's 9p worker on some ARMv9.2 devices</td>
+ <td>The virtio-9p driver used to expose the host Downloads folder on the QEMU backend is unstable on some hardware. 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. The AVF backend uses a separate 9p2000.L server over vsock and is not affected.</td>
</tr>
<tr>
<td>X11 viewer: Wayland desktops</td>
diff --git a/docs/guide/settings.html b/docs/guide/settings.html
index ca79170..8c61714 100644
--- a/docs/guide/settings.html
+++ b/docs/guide/settings.html
@@ -107,6 +107,11 @@
</tr>
</thead>
<tbody>
+ <tr>
+ <td>Load balance</td>
+ <td>Toggle</td>
+ <td>When on, Podroid automatically tunes CPU, RAM, storage, and bandwidth for the device, and the manual controls below are managed for you. Turn it off to set CPU, RAM, and storage manually.</td>
+ </tr>
<tr>
<td>RAM</td>
<td>512 MB / 1 GB / 2 GB / 4 GB</td>
@@ -145,10 +150,15 @@
<td>Add / Remove</td>
<td>Add TCP, UDP, or both forwarding rules. Changes apply live via QMP without a VM restart. Can also be managed from inside the VM with <code>podroid-forward</code> (see <a href="networking.html">Networking</a>).</td>
</tr>
+ <tr>
+ <td>Bandwidth limit</td>
+ <td>Mbps value / Unlimited</td>
+ <td>Caps the VM's network throughput. Managed automatically when Load balance is on.</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>
+ <td>Shares the Android Downloads folder into the VM at <code>/mnt/downloads</code>: virtio-9p on QEMU, an in-process 9p2000.L server over vsock on AVF. Can be unstable on some QEMU configurations; disable it if the VM crashes on boot. The AVF path is stable.</td>
</tr>
<tr>
<td>USB passthrough</td>
diff --git a/docs/guide/use-cases.html b/docs/guide/use-cases.html
index 90468e9..d567308 100644
--- a/docs/guide/use-cases.html
+++ b/docs/guide/use-cases.html
@@ -85,6 +85,16 @@
<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>Backing up containers</h2>
+ <p>The <strong>Backup</strong> screen (the home screen's <strong>Backup</strong> button, or Settings) builds shell commands for exporting a container, saving an image, listing existing backups, or backing up everything at once. It doesn't run anything itself - it builds the command and you copy it into the terminal.</p>
+ <pre><code><span class="c"># The screen builds a command like this one, which you paste into the terminal</span>
+<span class="p">$</span> podman export pihole -o /mnt/downloads/Podroid/backups/pihole.tar</code></pre>
+ <p>It uses a <code>podroid-backup</code> helper when one is present in the guest, and falls back to plain <code>podman save</code> / <code>podman export</code> otherwise. Backups are written inside the guest to <code>/mnt/downloads/Podroid/backups</code>. With <a href="settings.html">Downloads folder sharing</a> enabled, that path appears on the phone under <code>Download/Podroid/backups</code>; with sharing off, backups stay inside the VM at <code>/var/backups/podroid</code>.</p>
+
+ <h2>Checking VM and phone status</h2>
+ <p>The <strong>Status</strong> screen (the home screen's <strong>Status</strong> button, or the monitor icon in the header) gives a single view of both sides of the system: phone RAM, storage, CPU cores, and load average (when readable) alongside the VM's status, uptime, active backend (QEMU or AVF), and the phone's IP.</p>
+ <p>It also shows a VM CPU-load graph, available on the QEMU backend only - on AVF the screen shows a note that the graph is QEMU-only - plus the VM's allocated RAM, CPU cores, disk-image usage, and bandwidth limit.</p>
+
<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>
diff --git a/docs/index.html b/docs/index.html
index ea17002..8f95332 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -784,7 +784,7 @@
</tr>
<tr>
<td class="row-label">Downloads folder sharing</td>
- <td class="col-podroid"><span class="check">✓ virtio-9p</span></td>
+ <td class="col-podroid"><span class="check">✓ virtio-9p (QEMU) + vsock (AVF)</span></td>
<td><span class="check">✓</span></td>
<td><span class="cross">✗</span></td>
</tr>
@@ -991,7 +991,7 @@ qmp.sock → runtime port-forward control</div>
<details>
<summary>Can I access my Android files from the VM?</summary>
<div class="faq-answer">
- Yes. Toggle <strong>Downloads folder sharing</strong> in Settings and the Android Downloads folder is exposed to the VM via <code>virtio-9p</code>, mounted inside the guest at <code>/mnt/downloads</code>. Files you drop in Downloads on the phone show up there immediately, and anything the VM writes to <code>/mnt/downloads</code> appears back in Downloads.
+ Yes. Toggle <strong>Downloads folder sharing</strong> in Settings and the Android Downloads folder is exposed to the VM on both backends - via <code>virtio-9p</code> on QEMU, and via an in-process 9p2000.L server over vsock on AVF - mounted inside the guest at <code>/mnt/downloads</code>. It's bidirectional: files you drop in Downloads on the phone show up there immediately, and anything the VM writes to <code>/mnt/downloads</code> appears back in Downloads.
</div>
</details>