A rootless Android app that boots Alpine Linux: run containers (Podman/Docker/LXC) and GUI desktop apps.
docs: state which device each VM backend needs for testing
ExTvc740769d1ac6
diff --git a/CLAUDE.md b/CLAUDE.mdindex f2576a7..39d5086 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -115,6 +115,12 @@ Lets guest processes call back to Android. Guest side: `podroid-hostd` (multi-ca> **Gotcha:** `/dev/hvc2` is a virtio-console **TTY** that defaults to echo on. The daemon must `cfmakeraw()` it, or the TTY echoes Android's responses back and the protocol desyncs after the first request. AVF (a raw vsock socket) is unaffected.+### Downloads sharing over 9p (`engine/avf/AvfDownloadsShare.kt` + `engine/avf/ninep/`)++**AVF only.** Serves the real Android Downloads directory into the guest by running an in-process **9p2000.L** server (`Ninep2000LServer.kt`, ~886 LoC; wire format in `NinepCodec.kt`) over vsock. This is why the guest can read and write user files without the app holding broad storage permissions, and it is how `podroid-backup` archives land in `Downloads/Podroid/backups` for `ContainerBackupRepository` to list.++There is no QEMU equivalent, so any feature built on the share is backend-asymmetric by construction and must degrade cleanly on QEMU.+### USB passthrough (`engine/usb/UsbPassthroughManager.kt`)QEMU backend only. An unprivileged app can't open `/dev/bus/usb`, so it takes the already-open fd from `UsbManager`/`UsbDeviceConnection` and streams it to QEMU over `qmp.sock` as SCM_RIGHTS (`add-fd`), then hot-plugs with `device_add usb-host,hostdevice=/dev/fdset/N`. A code-registered `BroadcastReceiver` (no manifest `device_filter.xml`) is live only while the VM is `Running`. Gated by the `usb_passthrough_enabled` setting, which also makes `buildCommand()` emit `-device qemu-xhci`. Needs a libusb-enabled QEMU build.@@ -149,14 +155,18 @@ Single-activity Compose app: `ui/navigation/NavGraph.kt` routes `setup → home│ │ │ ├── QmpClient.kt # QMP: port forwards + USB add-fd│ │ │ ├── ResizeNotifyingSession.kt, VmState.kt│ │ │ ├── avf/ # AVF/pKVM backend (engine, reflection, vsock, console)+│ │ │ │ ├── AvfDownloadsShare.kt # live Downloads share, AVF only (see below)+│ │ │ │ ├── AvfDiagnostics.kt # AVF diagnostic + smoke-test entry point+│ │ │ │ └── ninep/ # in-process 9p2000.L server (Ninep2000LServer, NinepCodec)│ │ │ ├── hostbridge/ # guest->Android bridge (transport, server, dispatcher, notify)+│ │ │ │ └── HeadlessModeManager.kt # single source of truth for server (headless) mode│ │ │ └── usb/ # UsbPassthroughManager│ │ ├── service/PodroidService.kt # foreground service; owns VM lifecycle, wakelock, notification-│ │ ├── data/repository/ # Settings, PortForward, Update, Language (all DataStore)+│ │ ├── data/repository/ # Settings, PortForward, Update, Language, ContainerBackup, ContainerStats (all DataStore)│ │ ├── di/ # Hilt module-│ │ ├── util/ # NetworkUtils etc.+│ │ ├── util/ # NetworkUtils, ShellQuote, HostMetrics + VmLoadSampler (Status screen), DeviceResourcePolicy (load-balance sizing)│ │ ├── x11/ # X11/VNC viewer engine-│ │ └── ui/ # Compose: navigation, theme, screens/{setup,home,terminal,settings,x11}, components+│ │ └── ui/ # Compose: navigation, theme, screens/{setup,home,terminal,settings,x11,status,backup}, components│ ├── res/values, res/values-zh/ # strings (EN + Chinese)│ ├── assets/ # vmlinuz-virt, initrd.img, alpine-rootfs.squashfs (all gitignored, built locally),│ │ # qemu/, colors/ (122), fonts/ (13), ui-fonts/@@ -240,3 +250,28 @@ The guest system layer updates across app versions with **no VM reset and no dat- **New setting** → add a DataStore key + Flow in `SettingsRepository`, UI in `SettingsScreen`, setter in `SettingsViewModel`, and plumb into `VmConfig`/`buildCommand()` if it affects the VM.- **New user-facing string** → add to `res/values` AND `res/values-zh`, use `stringResource`.- **Verify before "done"**: compile, run `:app:testDebugUnitTest`, and for behavior changes install and walk the flow on a device (unit tests don't catch DI/graph or backend-specific issues).++## Proving a change on a device++Unit tests cover pure logic only. Anything touching VM behavior, the engine boundary, or a user-visible flow is unproven until it runs on hardware, and **the two backends need two different devices**:++| Backend | Device requirement | Extra setup |+|---|---|---|+| QEMU | any arm64 Android 8+ device | none; this is the default path |+| AVF | a device reporting `android.software.virtualization_framework` (Pixel-class) | `pm grant` both `MANAGE_VIRTUAL_MACHINE` and `USE_CUSTOM_VIRTUAL_MACHINE`, then force-stop the app |++Check AVF capability before assuming a device can exercise it:++```bash+adb shell pm list features | grep virtualization+```++A device without that feature can *never* run `AvfEngine`, no matter the `EngineSelection` setting. `EngineHolder.pick()` re-evaluates only at process start, so a fresh `pm grant` does not take effect until the app is force-stopped and relaunched.++**A change that touches both backends is unproven until it has been installed and walked on both.** Backend asymmetry is the #1 source of bugs (see Quirks & gotchas), and `AvfEngine.kt` is the most-churned file in the repository, so a QEMU-only test is the easiest way to ship a regression.++Reading the VM console depends on build type: `run-as` works on debug, but **release builds are not `run-as`-able**, so use `su` or **Settings → Diagnostics → Export Log** there.++```bash+adb shell run-as com.excp.podroid.debug cat files/console.log # debug only+```diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 9f48e58..1cee7ad 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -59,7 +59,7 @@ adb shell run-as com.excp.podroid.debug cat files/console.log1. Fork the repository and create a topic branch (`fix/issue-42`, `feature/whatever`).2. Keep pull requests focused: one fix or one feature per PR.-3. Test on a real arm64 device before submitting. Emulators do not exercise the QEMU + native binary path the way real hardware does.+3. Test on a real arm64 device before submitting. Emulators do not exercise the QEMU + native binary path the way real hardware does. If your change touches the engine boundary or AVF, note that only a device reporting `android.software.virtualization_framework` (`adb shell pm list features | grep virtualization`) can exercise the AVF backend at all; see [Proving a change on a device](CLAUDE.md#proving-a-change-on-a-device) for the grant sequence and for which backend needs which device. Say in the PR which backends you actually tested on.4. If your change is user-facing, update [`README.md`](README.md). If it changes the architecture, boot pipeline, terminal layer, or kernel options, update [`CLAUDE.md`](CLAUDE.md) too.5. Match the existing code style of the file you are editing.