Hypervisor-native
Designed for QEMU q35 with OVMF firmware. VirtIO block, GPU, network, keyboard and tablet; Intel HDA audio. No emulated legacy VGA.
ProxDroid is a reproducible Android 17 appliance for QEMU/KVM and Proxmox VE. It boots an unmodified upstream GKI kernel through its own UEFI launcher, uses VirtIO hardware throughout, and ships pure FOSS — no Google Mobile Services, no proprietary binaries.
Virtual Android. Real Infrastructure.
Every component is pinned, every build step is scripted, and every claim is backed by runtime evidence from a real boot. This page documents the complete build process from source sync to the final disk image.
Designed for QEMU q35 with OVMF firmware. VirtIO block, GPU, network, keyboard and tablet; Intel HDA audio. No emulated legacy VGA.
AOSP only. No GMS, no Houdini, no libndk_translation (PD-ADR-006). Proprietary add-ons can only be installed locally by the user, through a fail-closed path.
Pinned AOSP tag, pinned GSI, pinned ACK manifest (58 projects). Kernel, launcher, initrd and /system extension are verified byte-identical across independent builds.
An unmodified GKI kernel from common-android17-6.18. Module-signature enforcement stays on; ProxDroid holds no kernel signing key.
The boot splash and Android boot animation live inside the image. Nothing depends on a host splash setting or host artwork.
SELinux Enforcing, sys.boot_completed=1, fscrypt active, honest ABI advertising — measured on every accepted boot, never asserted.
The production layout (“Shape B”, PD-ADR-030) separates a tiny ProxDroid launcher from an untouched upstream kernel.
The launcher supplies the first-stage initramfs through EFI_LOAD_FILE2_PROTOCOL.
UEFI x86_64 firmware boots \EFI\BOOT\BOOTX64.EFI from the virtio-blk disk.
12 KiB EFI app: GOP splash, grow-only GPT, LoadFile2 initrd, explicit LoadOptions.
kernel.efi — ACK 6.18.32-android17-5, EFI stub, LoadImage/StartImage.
Real AOSP first-stage ramdisk + ProxDroid overlay (fstab, 6 VirtIO modules).
/system ← super, /vendor ← vendor_boot, /odm ← odm.
Boot animation from ODM, SurfaceFlinger, launcher; SELinux Enforcing.
Source: boot/branding/launcher_shapeb.c, built with the AOSP Clang toolchain into a PE32+ EFI application.
\EFI\PROXDROID\proxdroid-splash.bmp via GOP Blt; a missing or invalid BMP only skips the splash.userdata partition — grow-only, never anything else (PD-ADR-020, 74 golden test vectors).EFI_LOAD_FILE2_PROTOCOL on LINUX_EFI_INITRD_MEDIA_GUID to serve \EFI\PROXDROID\initrd.img; fails closed if it is missing.console=ttynull (PD-ADR-035).Passed by the launcher through LoadOptions:
console=ttyS0,115200n8
androidboot.hardware=cutf_cvm
androidboot.fstab_suffix=proxdroid
androidboot.boot_devices=pci0000:00/0000:00:01.0
androidboot.verifiedbootstate=orange
androidboot.hardware.gralloc=minigbm
androidboot.hardware.egl=angle
androidboot.hardware.hwcomposer.display_finder_mode=drm
androidboot.hardware.hwcomposer.display_framebuffer_format=rgba
androidboot.vendor.apex.com.android.hardware.graphics.composer=
com.android.hardware.graphics.composer.drm_hwcomposer
androidboot.vendor.apex.com.android.hardware.keymint=
com.android.hardware.keymint.rust_nonsecure
androidboot.vendor.apex.com.google.cf.wifi=none # … further APEX selectorsvirtio_gpu DRM → minigbm → drm_hwcomposer (generic backend, connector Virtual-1) → AIDL composer3 → SurfaceFlinger.
GLES runs through ANGLE/SwiftShader: a real display pipeline with software rendering.
/data is ext4 with file-based encryption and dm-default-key. It grows in two halves: the launcher grows the GPT, then
/odm/bin/pd_data_grow grows ext4 online from its own SELinux domain with only CAP_SYS_RESOURCE (PD-ADR-044).
TRIM is batch FITRIM via IdleMaint, discard=unmap on the host (PD-ADR-021).
The release image advertises only x86_64,x86; ARM-only APKs are refused at install (PD-ADR-022).
Berberis riscv64 → x86_64 is built from AOSP source and shipped in an additive /system extension.
ARM apps do not run — no FOSS ARM-on-x86 translator exists.
Specified in docs/VM_HARDWARE_CONTRACT.md (PROXDROID-SPEC-001). Targets Proxmox VE 8.x+, QEMU 8.x+, KVM on x86_64.
| Subsystem | Primary | Alternative | Notes |
|---|---|---|---|
| Machine | q35 | i440fx (testing only) | -vga none is required (PD-ADR-037) |
| Firmware | OVMF / UEFI x86_64 | — | read-only OVMF_CODE_4M.fd + fresh writable OVMF_VARS_4M.fd copy |
| CPU | host / x86-64-v2-AES | x86-64-v3 | SSE4.1/4.2, POPCNT, CMPXCHG16B, AES-NI, PCLMULQDQ required · ≥2 vCPU, 4 recommended |
| RAM | 4096–8192 MB | min. 2048 MB | shared memory-backend-memfd for blob scanout |
| Disk | virtio-blk-pci | virtio-scsi-pci | RAW or QCOW2, discard=unmap, 512 B logical / 4096 B physical sectors (PD-ADR-019) |
| Display | virtio-gpu-pci,blob=true | — | mandatory (PD-ADR-018/050); without blob scanout red and blue are swapped |
| Network | virtio-net-pci | — | production default: user-mode NAT, no hostfwd, no ADB port forwarding |
| Input | virtio-tablet-pci, virtio-keyboard-pci | usb-tablet, PS/2 | absolute coordinates 0–32767, direct-touch .idc (PD-ADR-049) |
| Audio | intel-hda + hda-output | ich9-intel-hda, virtio-sound-pci | PD-ADR-017 |
| Console | 16550A ttyS0 | virtio-serial | three virtconsole ports (hvc0–2) |
| RNG / Balloon | virtio-rng-pci / virtio-balloon-pci | — | ballooning is owed by Phase 11 (STORAGE-005) |
/dev/kvm and /dev/udmabuf.
The boot runner checks this and refuses to start, because a missing udmabuf would not fail — it would silently swap colour channels.Supported resolutions: 1280×720 @ 160 dpi, 1920×1080 @ 240 dpi (reference), 2560×1440 @ 320 dpi, 3840×2160 @ 480 dpi — 60 Hz, RGBA8888. Measured on the reference run: 1280×800.
appliance.rawThe Android 17 production pipeline is a fixed sequence of scripts in tools/. Each step consumes pinned inputs and
produces a hashed output that the next step verifies.
proxdroid-builderDefined in docker/Dockerfile: ubuntu:24.04, user builder (UID 1000), workdir /workspace, ccache 50 GB.
repobash docker/build.sh # → proxdroid-builder:latest ./proxdroid container build # same, via the CLI ./proxdroid doctor # host diagnostics python3 tools/check_android_readiness.py --verify-remote
NINJA_HIGHMEM_NUM_JOBS=1).--jobs=4.OUT_DIR must be relative — Soong rejects absolute paths.ninja; Siso (Android 17 default) failed bootstrap.zip/unzip are required; AOSP ziptool is not a substitute./dev/kvm for boot tests.| Component | Pin | Source of truth |
|---|---|---|
| /system | AOSP GSI aosp_x86_64, build CP2A.260605.012 (no GMS, user / release-keys), raw ext4 | manifests/aosp-android17.json |
| Vendor / ODM | AOSP tag android-17.0.0_r1, BUILD_ID CP2A.260605.016, lunch aosp_cf_x86_64_phone-trunk_staging-userdebug, device vsoc_x86_64 | manifests/aosp-android17.json |
| Platform | Android 17, API 37, SDK extension 22, vendor API 202604, SPL 2026-06-05 | manifests/aosp-android17.json |
| Kernel | ACK common-android17-6.18, 6.18.32-android17-5-g68974e235117, 58 projects | manifests/ack-6.18.json, ack-6.18-pinned.xml |
| Toolchain | AOSP prebuilt Clang clang-r584948 | manifests/aosp-android17.json |
| Firmware | OVMF OVMF_CODE_4M.fd / OVMF_VARS_4M.fd | config/proxdroid.conf.example |
The GSI/vendor build-ID difference (.012 vs .016) is intentional and recorded in PD-ADR-024.
TARGET_RELEASE=cp2a must be exported — lunch's default trunk_staging resolves to the next development release.
tests/android17_version_pin_consistency_test.py fails if the config drifts from the manifests.
PROXDROID_SRC_DIR=./src_tree PROXDROID_OUT_DIR=./out PROXDROID_CACHE_DIR=./cache PROXDROID_CCACHE_SIZE=50G PROXDROID_ANDROID_VERSION=17 PROXDROID_AOSP_BRANCH=android17-release PROXDROID_AOSP_TAG=android-17.0.0_r1 PROXDROID_KERNEL_VERSION=6.18 PROXDROID_ACK_BRANCH=common-android17-6.18 PROXDROID_AOSP_TARGET=aosp_cf_x86_64_phone-trunk_staging-userdebug PROXDROID_KERNEL_TARGET=//common:kernel_x86_64 PROXDROID_BUILD_JOBS=4 PROXDROID_OVMF_CODE=/usr/share/OVMF/OVMF_CODE_4M.fd PROXDROID_OVMF_VARS=/usr/share/OVMF/OVMF_VARS_4M.fd
Every session starts with a fail-closed governance check and a verification of the pinned rollback references.
python3 tools/check_project_state.py # must print PROJECT_STATE = CONSISTENT sha256sum -c docs/android17_rollback_reference.sha256
ACK: per-project shallow fetch of each pinned revision (git init → git fetch --depth 1 <url> <rev> → git checkout FETCH_HEAD), each verified with git rev-parse.
AOSP: platform/manifest at the pinned commit, then a resumable per-project fetch. GSI: download the archive and check its SHA-256 (mandatory) before extracting system.img.
ack-6.18-pinned.xml, AOSP tag, GSI archive aosp_x86_64-exp-CP2A.260605.012-15430684-…zipgit, curl, sha256sum, ./proxdroid fetchsystem.img (2,114,260,992 B)Two source patches are applied to the AOSP tree: offline resize support for vold, and master volume/mute controls for the primary audio HAL.
git -C system/vold apply artifacts/phase6/aosp-vold-offline-resize.patch git -C hardware/interfaces apply config/phase9_5/audio-primary-master-controls-a17.patch
The Cuttlefish x86_64 vendor image is built from source, then rebuilt deterministically by tools/build_phase95_vendor.py (PD-ADR-042):
three sensor files removed, deterministic AVB salt, fixed EROFS timestamp and UUID.
export TARGET_RELEASE=cp2a source build/envsetup.sh lunch aosp_cf_x86_64_phone-trunk_staging-userdebug NINJA_HIGHMEM_NUM_JOBS=1 m -j4 vendorimage python3 tools/build_phase95_vendor.py … # deterministic rebuild
android-17.0.0_r1build_imagevendor.img (EROFS, 339,595,264 B) → partition vendor_bootThe ODM partition carries everything device-specific ProxDroid adds: the audio APEX, the device-node helper, the Lights HAL with its full 14-library closure, VINTF fragments, the fstab, input descriptors and the retraction of sensor/Bluetooth/NFC/telephony features the VM does not have.
python3 tools/build_phase8_audio_apex.py --aosp … --out … # proxdroid.audio.apex (stock key kept) bash tools/build_phase8_init_dev_config.sh AOSP OUT # proxdroid_init_dev_config python3 tools/build_a17_odm.py --aosp … --base-tree … \ --file-contexts … --audio-apex … --host-bin … --out odm_a17 python3 tools/audit_a17_odm.py … # expect: RETAIN_PHASE8_FILES = 4/4, RETAIN_LIGHTS_CLOSURE = 14/14, ALLOCATOR_PROVIDERS = 1
m odmimage android.hardware.lights-service.example, config/phase8/*mkfs.erofs -T 1788411697 -U … -z lz4hc --all-root --mount-point=/odmodm_a17/{odm.img, tree, file_contexts.txt}, asserted ≤ 64 MiBThe kernel is built with Kleaf from the pinned ACK tree. A small device fragment (PD-ADR-043) enables eight VirtIO/HDA symbols; after the build, the achieved
.config is read back and every symbol is checked. Built twice, byte-identical.
python3 tools/build_shapeb_kernel.py --ack-root … \ --fragment kernel/configs/proxdroid_shapeb_6.18_devices.defconfig \ --destdir … --jobs 4 --record … # wraps: tools/bazel run --jobs=4 --config=stamp //common:kernel_x86_64_dist -- --destdir=<dist>
DRM_VIRTIO_GPU, DMABUF_HEAPS_SYSTEM, VIRTIO_NET, VIRTIO_INPUT, HW_RANDOM_VIRTIO, SND_HDA_INTEL, SND_HDA_GENERIC, SND_HDA_CODEC_ANALOGtools/check_kernel_config.py, tools/verify_efi_image.pybzImage → \EFI\PROXDROID\kernel.efi (27,264,000 B)The initrd is the product's real AOSP first-stage ramdisk (PD-ADR-036) with a ProxDroid overlay cpio appended: the first-stage fstab and the modules needed to reach the disk.
python3 tools/build_shapeb_production_initrd.py --base-ramdisk ramdisk.img \
--fstab … --fstab-name … --modules-dep … --modules-load … \
--module … --output initrd.imgvirtio_pci_modern_dev, virtio_pci_legacy_dev, virtio_pci, virtio_blk, virtio_console, vmw_vsock_virtio_transportswitch_root into Android (PD-ADR-034)\EFI\PROXDROID\initrd.img (6,310,220 B)launcher_shapeb.c is compiled with the AOSP Clang into an EFI application (lld-link, EFI subsystem, /timestamp:0, EDK II headers from AOSP external/coreboot). Reproducible across clean rebuilds.
bash tools/build_shapeb_efi.sh "$AOSP_ROOT" "$OUT_DIR" [clang]boot/branding/launcher_shapeb.c\EFI\BOOT\BOOTX64.EFI (12,288 B, unsigned)The GPT base disk is created with sgdisk, mkfs.fat, mke2fs and mtools and validated with sgdisk --verify.
The guest-side /data grow helper is compiled as a PIE that links only against libc.so; it runs once from on post-fs-data,
grows the encrypted ext4 with EXT4_IOC_RESIZE_FS and never shrinks.
python3 tools/build_pd_data_grow.py --out … # /odm/bin/pd_data_grow (12,456 B)
config/storage/pd_data_grow.c, .rc, .cilpd_data_growThe boot artwork assets/boot/proxdroid-splash.bmp (1280×800, 24-bit BMP) is copied to the ESP unchanged and deterministically turned into the Android
bootanimation.zip (six PNG frames at 3 fps, stored entries, fixed timestamps). The ODM is rebuilt with the animation and
ro.product.bootanim.file, the ESP is written as deterministic FAT32 (label PROXDROID, serial 5052-4F58).
Only ESP and ODM are written into a copy of the base image; test APKs and test .rc files are rejected.
python3 tools/build_boot_branding.py \ --base-image … --odm-tree odm_a17/tree \ --file-contexts odm_a17/file_contexts.txt \ --efi BOOTX64.EFI --kernel kernel.efi --initrd initrd.img \ --vendor-img vendor.img --data-grow-helper pd_data_grow \ --expect-data-grow-sha256 … --out … python3 tools/audit_a17_boot_branding.py …
/system extensionBerberis riscv64 → x86_64 is built from the in-tree AOSP source with a build-only product
(lunch proxdroid_cf_x86_64_riscv64-cp2a-userdebug, defined in config/phase10/aosp-overlay/). Its 73 artifacts are pinned by a payload manifest
and added to the GSI's /system as a deterministic, add-only extension (PD-ADR-032): 76 entries added, 0 removed, 0 changed.
The ODM sets the three native-bridge properties.
python3 tools/build_berberis_payload_manifest.py … python3 tools/build_system_extension.py --base system.img --base-sha256 … \ --manifest … --payload-root … --out … --record … --workdir … python3 tools/audit_system_extension.py … # → ADDITIVE_ONLY python3 tools/stage_production_bridge_odm.py … python3 tools/install_system_extension.py --appliance appliance.raw \ --expect-appliance-sha256 … --system-img … --record … --out …
ro.dalvik.vm.native.bridge=libberberis_riscv64.so, ro.dalvik.vm.isa.riscv64=x86_64, ro.enable.native.bridge.exec=1base_gsi_sha256 + payload manifest + result_sha256appliance.raw with extended /system in superBOOTX64.EFI is unsigned — Secure Boot and measured boot are not yet part of the image.appliance.raw is a 12 GiB raw GPT disk (12,884,901,888 B, 25,165,824 sectors) with eight partitions.
No A/B slots, no dynamic partitions, no lpmake. Disk GUID 50524F58-4452-4F49-4400-000000000000.
| # | Partition | Start LBA | Size | Contents |
|---|---|---|---|---|
| 1 | ESP | 2048 | 128 MiB | FAT32: BOOTX64.EFI, kernel.efi, initrd.img, splash BMP |
| 2 | frp | 264192 | 1 MiB | PersistentDataBlock |
| — | gap | 266240 | 95 MiB | unallocated contingency for ODM growth |
| 3 | odm | 460800 | 64 MiB | EROFS /odm |
| 4 | vendor_boot | 591872 | 400 MiB | EROFS /vendor |
| 5 | super | 1411072 | 5840 MiB | raw ext4 /system (GSI + additive extension), read-only |
| 6 | metadata | 13371392 | 32 MiB | Android metadata (encryption keys) |
| 7 | misc | 13436928 | 8 MiB | bootloader control block / flags |
| 8 | userdata | 13453312 | 5719 MiB | ext4 /data with FBE, ends at the last usable LBA; grows with the virtual disk |
/system ← by-name/super (ext4, ro) · /vendor ← vendor_boot (EROFS) · /odm ← odm (EROFS) ·
fstab at /odm/etc/fstab.proxdroid (PD-ADR-038).
Enlarge the virtual disk on the host; on the next boot the launcher extends the userdata GPT entry and pd_data_grow resizes the
encrypted filesystem online. Shrinking is never performed.
A build that compiles is not a build that works. Acceptance requires runtime evidence from real boots, recorded in the repository.
Boot markers, SELinux AVC review, fscrypt, device matrix, app corpus, ABI list, storage, GPT, forbidden names, pytest, reproducibility, project state and a no-weakening diff.
A reproducible API-37 corpus covering Java/Kotlin at targetSdk 37, x86_64 and x86 JNI, WebView, HTTP incl. Local Network Protections, app storage with
reboot persistence, update/downgrade/uninstall and the ARM negative control: 145 checks, 0 failed, 0 unknown.
The integrated production artefact was booted twice formally; the affected gate subset was re-measured on its own bytes:
GATE_RERUN = PASS, 226 conjuncts, 0 failed.
python3 -m pytest -q tests ./proxdroid test --suite all # or: project-state, storage, phase0 … phase9.5, hygiene python3 tools/check_project_state.py --handover python3 tools/check_kernel_config.py --report python3 tools/storage_audit.py all appliance.raw python3 tools/apk_compat_runner.py …
python3 tools/run_shapeb_production_boot.py \ --run-dir <fresh-dir> --image appliance.raw \ --expect-image-sha256 <sha256> --accel kvm \ --timeout … --grace … --overlay … # success: sys.boot_completed=1, SELinux Enforcing, # source image hash unchanged before and after
The production launch shape used for acceptance boots. No -kernel, -initrd or -append: everything boots from the image itself.
qemu-system-x86_64 \
-machine q35,memory-backend=ram0 \
-object memory-backend-memfd,id=ram0,size=8G,share=on \
-accel kvm -cpu max -m 8192 -smp 4 -vga none \
-drive if=pflash,unit=0,format=raw,readonly=on,file=OVMF_CODE_4M.fd \
-drive if=pflash,unit=1,format=raw,file=OVMF_VARS_4M.copy.fd \
-drive id=proxdroid-disk,file=appliance.raw,format=raw,if=none,discard=unmap \
-device virtio-blk-pci,drive=proxdroid-disk,bootindex=0 \
-device virtio-gpu-pci,blob=true \
-device virtio-keyboard-pci -device virtio-tablet-pci \
-netdev user,id=net0 -device virtio-net-pci,netdev=net0 \
-audiodev none,id=snd0 -device intel-hda -device hda-output,audiodev=snd0 \
-device virtio-serial-pci,id=virtio-serial0 \
-serial stdio -boot menu=offUse a fresh copy of OVMF_VARS_4M.fd per VM. Attach a display frontend of your choice instead of -display none used by the headless gate runner.
Design reference from the hardware contract. Proxmox integration is the current phase and this configuration is not yet validated.
name: proxdroid-vm ostype: l26 machine: q35 bios: ovmf efidisk0: local-lvm:vm-500-disk-0,efitype=4m,pre-enrolled-keys=0,size=4M cpu: host cores: 4 sockets: 1 memory: 4096 virtio0: local-lvm:vm-500-disk-1,discard=on,iothread=1,size=32G net0: virtio,bridge=vmbr0,firewall=1 serial0: socket tablet: 1
virtio-gpu-pci,blob=true with shared memfd RAM through Proxmox (a plain vga: virtio-gl is not the blob-scanout path)./dev/udmabuf access for the QEMU process on the node.virtio-balloon, STORAGE-005)../proxdroid doctor ./proxdroid fetch --target kernel|aosp|all [--dry-run] ./proxdroid container build|shell|run <cmd> ./proxdroid kernel build|initramfs|boot ./proxdroid test --suite <suite>
ProxDroid is in active development and has no public release yet. Phases 1–10 are accepted; Proxmox integration is current.
| AOSP | Apache-2.0 / BSD-3-Clause |
| Linux kernel / ACK | GPL-2.0-only with syscall note |
| Berberis | Apache-2.0 |
| minigbm, drm_hwcomposer | BSD-3 / Apache-2.0 |
| TinyALSA | BSD-3 |
| OVMF (EDK II) | BSD-2-Clause-Patent |
| ProxDroid tooling | Apache-2.0 |
EFI_LOAD_FILE2_PROTOCOL, sets the command line, draws the image-owned splash and performs the grow-only GPT update — all without touching the kernel.blob=true mandatory?/dev/udmabuf.