WinPodX: Windows apps as native Linux windows, with URL schemes routed both ways

The problem WinPodX picks: one Windows app, not one Windows desktop

Most ways of running Windows software on Linux hand you a second computer. You get an RDP session, a virtual desktop, or a full-screen VM, and every Windows program lives inside that box. Alt-tab crosses an application boundary, not a window manager one. The taskbar is the guest's taskbar. File associations point at the guest, so double-clicking a .docx on your Linux desktop does nothing useful.

WinPodX takes the opposite unit of work. Its README opens with the claim that each Windows app becomes its own Linux window with its real icon, pinnable, alt-tabbable and file-associated, and that you drop into a full Windows desktop only when you want one via winpodx app run desktop. The intended reader is a Linux desktop user who needs Word, Outlook, or an internal line-of-business tool, and who does not want to move their whole working day into a VM window. The README is explicit that this is a beta, and pyproject.toml still carries the Development Status :: 2 - Pre-Alpha classifier, so the audience is people who can tolerate that.

How WinPodX works: a container, a RemoteApp channel, and two shim directions

The architecture described in the README has four moving parts. A Windows container runs in the background via dockur/windows. FreeRDP RemoteApp publishes individual applications out of that guest so each one arrives on the Linux side as a window with a real WM_CLASS. A bearer-authenticated HTTP agent inside the guest carries the host-to-guest command channel, which the README says avoids flashing a PowerShell window. The reverse direction, Linux apps appearing in the Windows Open with menu, is handled by a host-side listener that consumes JSON requests written by per-slug Rust shims inside the guest.

That per-slug shim design is the part worth understanding before you commit. Discovery walks the guest, harvests app schemes such as slack: and vnc:, and registers them as x-scheme-handlers on the Linux side. The same mechanism covers mailto: links, so clicking one in a Linux browser can open Outlook in the guest. Because the mapping is built from what discovery actually found, an app that was never discovered has no scheme handler, and the README does not document a manual override for that case.

The dependency story is deliberately thin. The README states near-zero external Python dependencies, stdlib only on Python 3.11+, with one pure-Python tomli fallback on 3.9 and 3.10. pyproject.toml confirms this: the only unconditional dependency is tomli, gated on python_version < '3.11'. Everything heavier is an optional extra. The gui extra pulls PySide6, the docker extra pulls the docker client, and the reverse-open extra pulls Pillow, cairosvg and pyxdg for icon conversion. Without reverse-open installed, the README says discovery still works but ICO conversion falls back to a logged warning and no file is written.

Checking KVM before you install WinPodX

The README is unusually direct that the install can complete and Windows still never boot. Three host conditions decide that, and all three are checkable in a terminal. Run this to see whether the CPU exposes virtualisation extensions; the README says the output should contain VT-x or AMD-V.

lscpu | grep -i virtualization

Next, confirm the kvm kernel module is loaded. The README expects kvm_intel or kvm_amd to appear in the output.

lsmod | grep kvm

Finally, check that your user is in the kvm group. If it is not, the README gives the fix and notes that you must log out and back in afterwards.

id -nG | tr ' ' '\n' | grep kvm
sudo usermod -aG kvm $USER

Installing WinPodX and launching the first Windows app

The README gives a one-liner for any supported distro. It fetches install.sh and pipes it to bash, and the default is the latest stable release. The README notes a --main variant for the development HEAD, which it warns may be unstable.

curl -fsSL https://raw.githubusercontent.com/kernalix7/winpodx/main/install.sh | bash

If you prefer a native package, the README lists repositories for openSUSE Tumbleweed, Leap and Slowroll, Fedora 42 and newer via dnf5, and matching .deb or .rpm files from the latest release.

sudo zypper addrepo https://download.opensuse.org/repositories/home:/Kernalix7/openSUSE_Tumbleweed/home:Kernalix7.repo
sudo zypper install winpodx

After a package-manager or AppImage install, the README says to run setup once. This generates the config file and compose.yaml and completes first provisioning; the curl one-liner does it for you, while package installs ship the binary only so that apt install or dnf install does not trigger a long Windows ISO download unexpectedly.

winpodx setup

Once setup has finished, launch an app. The README uses the full desktop as its example, and winpodx launch opens a Start-menu-style picker that can be bound to a hotkey.

winpodx app run desktop
winpodx launch

If something is still missing on the host, winpodx setup-host fixes the kvm group and subuid entries behind a single pkexec prompt, and winpodx doctor reports what remains.

winpodx setup-host
winpodx doctor

Where WinPodX is the wrong tool

The clearest failure mode is documented by the project itself: install runs to completion, Windows never boots, and the cause is almost always a missing /dev/kvm. The README says install.sh aborts with the same diagnostic if /dev/kvm is absent after the package install step, and that most bug reports of this shape trace back to BIOS virtualisation being off, the kvm module not being loaded, or the user not being in the kvm group. If you are already inside a VM without nested virtualisation, none of the fixes apply and WinPodX is simply not available to you.

The second limit is scope. WinPodX is a desktop integration layer, not a way to avoid Windows. You still need a Windows licence for the guest, and the project takes no position on that. The README also does not document rollback beyond the uninstall script, which by default keeps Windows VM data and only wipes everything with --purge. There is no documented downgrade path between releases.

Third, the thin AppImage change in 0.6.0 moved the container runtime back onto the host on purpose, per issues #357 and #363, because the earlier fat AppImage bundled the whole podman stack and shadowed the host's. That is a sensible call, but it means the AppImage no longer carries its own runtime. You still need podman 4 or newer, or docker, plus /dev/kvm, kvm group membership, and /etc/subuid and /etc/subgid entries for rootless Podman.

WinPodX compared with WinBoat and WinApps

The repository ships a docs/COMPARISON.md, which is the honest place to start, but the architectural difference is visible from the README alone. WinPodX is built on dockur/windows for the guest and FreeRDP RemoteApp for the windowing, and it adds two directions of integration that a plain RemoteApp setup does not have: a bearer-authed HTTP command channel into the guest, and per-slug Rust shims plus a host-side listener for the guest-to-host direction.

That second direction is the real dividing line. If your need is only to see Windows applications in Linux windows, a RemoteApp configuration gets you most of the way. WinPodX's extra machinery exists so that Linux applications can appear in the Windows Open with menu and so that URL schemes like mailto: and slack: cross the boundary in both directions. The cost is a guest-side agent, a set of shims, and a discovery pass that has to run before any of it works. For a single application, that is a lot of moving parts. For a desktop where Windows apps and Linux apps are expected to hand files and links to each other all day, it is the part that matters.

Licence, maintenance and what an upgrade costs you

WinPodX is MIT licensed, and the repository carries THIRD_PARTY_LICENSES.md alongside LICENSE, which is where the obligations of the bundled or downloaded components are recorded. The MIT grant covers WinPodX itself. It does not cover Windows, which you supply and license separately, and it does not cover dockur/windows or FreeRDP, which are separate projects with their own terms. Read THIRD_PARTY_LICENSES.md before redistributing anything; that is a factual pointer, not legal advice.

The maintenance signal is straightforward. The last push was on 2026-07-27, and the most recent release in the list is v0.10.4 on the same date, following v0.10.3 on 2026-07-21 and v0.10.2 on 2026-07-20. The repository is not archived. Release cadence has been tight, but pyproject.toml declares version 0.11.0 while the README advertises v0.10.4 as the current release, so the working tree runs ahead of the published tag. Expect the documented version and the installed version to disagree during development windows.

Upgrade cost is mostly the guest, not the package. The uninstall script keeps Windows VM data unless you pass --purge, which implies the VM disk is the expensive, persistent artifact and the host-side package is cheap to replace. A package upgrade therefore does not force a Windows reinstall, but it may change the compose.yaml or the generated winpodx.toml, and the README does not document a migration step for those files.

Editorial conclusion

Adopt WinPodX if you are on an x86_64 or aarch64 Linux desktop with VT-x or AMD-V enabled, your user in the kvm group, at least 8 GB of RAM and 64 GB of free disk, and you want per-app Windows windows rather than a full desktop. Do not adopt it if the host is a VM without nested virtualisation, if you need a stable interface rather than a beta whose pyproject.toml still says Pre-Alpha, or if you cannot accept that a Windows licence is yours to sort out. Verify three things first: that lscpu reports VT-x or AMD-V, that id -nG lists kvm, and that winpodx doctor reports nothing missing after winpodx setup writes ~/.config/winpodx/winpodx.toml.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes