Try PolymerOS in a VM

You can boot a PolymerOS build in a virtual machine without installing it and without touching your boot disk. Every published download ships with the same runner script the build agents use, so trying it out is a download, a verify, and one command.

Download a build

Builds are published per channel on the downloads page. Today only the Chaos channel produces builds. A build is a directory of files from one channel publication, and it contains everything the runner needs:

• the live image (*.img, or *.img.zst, which the runner decompresses on first use)
• the kernel (Image or vmlinuz*)
• the initramfs (initramfs*)
• the dm-verity root hash file (*roothash*)
• SHA256SUMS and a signature over it
• the polymer-qemu-run.sh runner itself

Download the whole directory into one folder.

Verify before you boot

Run both commands from inside the download folder. Verifying the download is covered in full in Verify a download; the two commands are:

minisign -Vm SHA256SUMS -P RWQca8J06MT1pNV/h3ALWu97juZJzQ1KKIDyj4R88VhJTyLMG/l2yfBx
sha256sum -c SHA256SUMS

The first proves the checksums file was signed by the build pipeline; the second proves the files on disk match those checksums. Do not boot a build that fails either check.

First boot

From inside the download folder:

./polymer-qemu-run.sh .

The single argument is the download directory (. here means the current folder). On the first run the script:

• decompresses *.img.zst once, alongside the original, if the image is compressed
• creates a 20 GB persistent home disk (userdata.img) next to the image

That home disk is reused on later runs, so anything you do in the guest — including in-guest updates — survives a restart. To throw it away and start clean, pass --fresh.

The runner picks your host architecture by default and mounts the live image read-only, writing nothing outside the download directory.

RAM sizing

The guest gets 4 GB of memory by default. That is enough to try the desktop. If you plan to open heavy compartments, give it more:

./polymer-qemu-run.sh --mem 8G .

--mem takes any size QEMU accepts (for example 4G, 8G). The 20 GB persistent home disk is separate from this and is created automatically.

Watching the desktop: use a VNC viewer, not KRDC

The runner opens a window when your host has a graphical display. If it does not (a headless host, or you pass --display vnc), it runs headless and prints:

headless: connect a VNC viewer to 127.0.0.1:5900

Connect any VNC viewer to 127.0.0.1:5900 to see the desktop.

Two display notes from the current build's known issues:

• Do not use KRDC. KRDC mishandles the QEMU VNC framebuffer's pixel format and renders the screen as solid blue. Use TigerVNC instead.
• On Asahi hosts, the QEMU GTK window with GL enabled can become unresponsive. Use the software display or VNC instead.

Graphics

The runner attaches a virtio-GPU and disables the emulated VGA card. Graphics are software-rendered, which is fine for trying the desktop.

Speed without KVM

When the guest architecture matches your host and /dev/kvm is writable, the runner uses KVM (on macOS, HVF) and the VM feels close to native. Without that acceleration — a cross-architecture build, or no KVM access — the runner prints:

note: no KVM access — running emulated (slow)

Emulated boots are slow but they work. Expect a patient wait for the desktop to come up; nothing is wrong.

On Apple-Silicon Asahi hosts running nested virtualization, host memory fragmentation can stall guest vCPUs even with KVM, showing up as long boots or soft lockups. The current build's known issues list a workaround: set vm.compaction_proactiveness=0 and run echo 1 > /proc/sys/vm/compact_memory before launching the guest.

If the runner stops early

If QEMU is not installed, the runner tells you which package to install for your architecture (for example qemu-system-aarch64 or qemu-system-x86). Install your distribution's QEMU package and run it again.