Click an app. Word opens. That's it.

Native Linux windows for every Windows app — real icons, real WM_CLASS,
pin-to-taskbar. FreeRDP RemoteApp + dockur/windows. Zero config.

# Latest stable release (default)
curl -fsSL https://raw.githubusercontent.com/kernalix7/winpodx/main/install.sh | bash

# Latest main HEAD (development; may be unstable)
curl -fsSL https://raw.githubusercontent.com/kernalix7/winpodx/main/install.sh | bash -s -- --main

# Uninstall (keeps Windows VM data; pass --purge to wipe everything)
curl -fsSL https://raw.githubusercontent.com/kernalix7/winpodx/main/uninstall.sh | bash -s -- --confirm

_{Windows About / Performance Monitor / PowerShell each in their own Linux window, alongside the winpodx Apps grid.}

Works on

_{English  ·  한국어  ·  Install  ·  Usage  ·  Features  ·  Architecture  ·  Comparison}

---

Status: Beta

winpodx is in active development (v0.6.0). Reverse-open (v0.5.0) — Linux apps in the Windows "Open with…" menu — is default-on with per-app icons that round-trip to the host's xdg-open. v0.5.5 added a host-adaptive Windows-on-KVM tuning profile plus automatic UNRESPONSIVE → recover for stalled RDP sessions; v0.5.8 fixed the two big fresh-install dead-ends (#269 urlacl ownership and #287 OEM copy never running install.bat). v0.6.0 is a consolidation + UX release. The post-create chain (wait-ready → apply-fixes → discovery → reverse-open) collapses into a single winpodx provision that is now the only path used by install.sh, winpodx setup, winpodx migrate, and the GUI bring-up; install.sh's ~140 lines of provisioning drop to ~5. The AppImage is Thin (~50 MB) — only FreeRDP + Python + Qt + winpodx — and uses the host's podman / docker / libvirt, fixing the bundled-stack crashes #357 and #363 (the old fat AppImage shadowed the host stack). The CLI command surface is reorganised — winpodx guest owns guest-side operations (apply-fixes, sync, sync-password, multi-session, recover-oem), winpodx install owns install / disk operations (status, resume, grow-disk, disk-usage), winpodx doctor absorbs info and check and gains --json / --quick / --fix (idempotent auto-remediation for dead agent, stale locks, missing desktop entries, and OEM-version drift). All old pod <x> subcommand spellings still work through 0.6.x with a deprecation notice and will be removed in 0.7.0. First install still takes ~5–10 minutes (Windows VM ISO download + Sysprep + OEM apply); winpodx pod wait-ready --logs shows live progress. Please file issues at https://github.com/kernalix7/winpodx/issues if something breaks.

No full-screen RDP. Each Windows app becomes its own Linux window with its real icon — pinnable, alt-tabbable, file-associated, both directions. Drop into a full Windows desktop only when you actually want one (winpodx app run desktop).

winpodx runs a Windows container (via dockur/windows) in the background and presents Windows apps as native Linux applications through FreeRDP RemoteApp, while a bearer-authed HTTP agent inside the guest handles the host→guest command channel without flashing a PowerShell window. The reverse direction — Linux apps surfaced 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. Near-zero external Python dependencies (stdlib only on Python 3.11+; one pure-Python tomli fallback on 3.9/3.10).

Minimum requirements

Before installing, make sure your machine actually supports virtualisation. winpodx runs Windows in a KVM-backed container; without these three, the install will run to completion but Windows will never boot.

Requirement	How to check	Fix
Intel VT-x or AMD-V enabled in BIOS / UEFI	lscpu | grep -i virtualization shows VT-x or AMD-V	Reboot → firmware setup → enable "Intel Virtualization Technology" / "SVM Mode" / "VT-x". OFF by default on many laptops.
kvm kernel module loaded	lsmod | grep kvm lists kvm_intel or kvm_amd	sudo modprobe kvm_intel (Intel) or sudo modprobe kvm_amd (AMD). Auto-loads on next boot once BIOS allows it.
Your user is in the kvm group	id -nG | tr ' ' '\n' | grep kvm returns kvm	sudo usermod -aG kvm $USER, then log out + back in.

Hardware: x86_64 or aarch64 CPU with virtualisation extensions, 8 GB+ RAM (12 GB+ recommended), ~30 GB free disk for the Windows image. install.sh aborts with the same diagnostic if /dev/kvm is missing after the package install step — most "install ran fine but Windows never boots" bug reports trace back to one of the rows above.

Quick install

One-liner (any supported Linux distro):

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

Or via a native package manager:

# openSUSE Tumbleweed / Leap / Slowroll
sudo zypper addrepo https://download.opensuse.org/repositories/home:/Kernalix7/openSUSE_Tumbleweed/home:Kernalix7.repo
sudo zypper install winpodx

# Fedora 42 / 43 / 44 (dnf5 — Fedora 41+)
sudo dnf config-manager addrepo --from-repofile=https://download.opensuse.org/repositories/home:/Kernalix7/Fedora_43/home:Kernalix7.repo
sudo dnf install winpodx

# Debian / Ubuntu — grab the matching .deb from the latest release
sudo apt install ./winpodx_<version>_all_debian13.deb

# AlmaLinux / Rocky / RHEL 9 / 10 — grab the matching .rpm
sudo dnf install ./winpodx-<version>-0.noarch.el10.rpm

# Arch
yay -S winpodx

# Nix
nix run github:kernalix7/winpodx

# AppImage (distro-agnostic, single file)
# Download winpodx-<version>-x86_64.AppImage from the latest GitHub release
chmod +x winpodx-*-x86_64.AppImage
./winpodx-*-x86_64.AppImage setup

After a package-manager / AppImage install: run winpodx setup once to generate ~/.config/winpodx/winpodx.toml + compose.yaml. The curl one-liner does this for you (and waits ~5–10 min for the Windows first boot); package installs ship the binary only so apt install / dnf install / yay -S / first AppImage launch don't trigger a 10-minute Windows ISO download out of the blue. After setup, just launching an app (winpodx app run desktop) auto-provisions the pod the first time.

The Thin AppImage (0.6.0) bundles Python + Qt + winpodx + FreeRDP only — the container runtime lives on the host (podman ≥ 4 recommended, docker / libvirt also supported) so the AppImage no longer fights a host stack you already have (#357, #363). Pre-0.6.0 fat AppImages bundled the whole podman stack and shadowed the host's. Host-side requirements left: a container runtime via your package manager, /dev/kvm, kvm group membership, and /etc/subuid / /etc/subgid for rootless Podman. winpodx setup-host fixes the kvm / subuid bits via a single pkexec prompt; winpodx doctor surfaces anything still missing.

See docs/INSTALL.md for offline / air-gapped builds, source installs, version pinning, and uninstall.

First-time setup

If you used the curl install.sh one-liner, setup already ran and the Windows VM is booting -- skip to Launch. For every other install path (package managers, AppImage, source, pip) run setup once before the first app launch:

# Auto setup -- host-detected defaults, no prompts
winpodx setup

# Interactive wizard -- pick backend, cores, RAM, edition, language, timezone, debloat preset
winpodx setup --customize

Setup writes ~/.config/winpodx/winpodx.toml + compose.yaml, registers the GUI launcher, and confirms the host has FreeRDP + Podman / Docker + KVM. If any of those are missing, the output ends with a per-distro install command (e.g. sudo apt install xfreerdp3 podman podman-compose on Debian / Ubuntu, sudo dnf install ... on Fedora) -- run it and re-run winpodx setup.

The first app launch then provisions the pod, pulls the dockur image, runs the Windows ISO download + Sysprep + OEM apply, and reaches a usable RDP session in ~5-10 min. winpodx pod wait-ready --logs tails container progress live so you can watch each phase:

winpodx app run desktop          # First launch -- ~5-10 min, subsequent launches near-instant
winpodx pod wait-ready --logs    # Optional: watch first-boot progress live

Run winpodx doctor any time afterwards to re-check host state and surface the next fix command if something drifts:

winpodx doctor                   # Read-only -- prints what would need fixing
winpodx guest apply-fixes        # Re-applies guest-side runtime fixes (RDP timeouts, NIC power-save, etc.)

Launch

winpodx app run word              # Launch Word
winpodx app run word ~/doc.docx   # Open a file
winpodx app run desktop           # Full Windows desktop

Or just click an app icon in your application menu. See docs/USAGE.md for the full CLI, the Qt6 GUI, health checks, and configuration.

Key features

Reverse-open Linux apps appear in the Windows guest's right-click "Open with…" menu by default Correct per-app icons in both the short menu and the long "Choose another app" dialog Selecting one round-trips the file open to host xdg-open Auto-discovers host-side Linux apps + their MIME associations from freedesktop standards Manage via winpodx host-open CLI or the GUI Settings panel Details →	Seamless app windows RemoteApp (RAIL) renders each Windows app as a native Linux window — no full desktop Per-app taskbar icons via WM_CLASS matching (/wm-class:<stem> + StartupWMClass) Bidirectional file associations: double-click .docx in your file manager → Word opens Multi-session RDP: bundled rdprrap auto-enables up to 10 independent sessions RAIL prerequisites set automatically during unattended install
Zero-config launch First app click auto-provisions everything: config, container, desktop entries Auto-discovery on first boot scans the running Windows guest and registers every installed app with its real icon (Registry App Paths, Start Menu, UWP/MSIX, Chocolatey, Scoop) Manual rescan any time via winpodx app refresh or the GUI Refresh button Multi-backend: Podman (default), Docker, libvirt/KVM, manual RDP	Peripherals & sharing Clipboard: bidirectional copy-paste (text + images) — on by default Sound: RDP audio streaming (/sound:sys:alsa) — on by default Printer: Linux printers shared to Windows — on by default Home directory: shared as \\tsclient\home USB drives: auto-mapped to drive letters (E:, F:, …) via FileSystemWatcher; subfolders work for drives plugged in after session start; the USB desktop shortcut (\\tsclient\media) always resolves, opening an empty folder when nothing is mounted instead of erroring USB device passthrough: opt-in via extra_flags (/usb:auto)
Automation & security Auto suspend / resume: container pauses when idle, resumes on next launch Pod auto-start on login (v0.5.9, opt-in): winpodx autostart on installs a tray autostart entry so the pod starts/resumes at login — off by default (autostart off|status, or a GUI Settings checkbox) UNRESPONSIVE → recover (v0.5.5): stalled RDP guest is detected on RUNNING → UNRESPONSIVE and self-healed via in-guest TermService cycle, no pod restart needed Host-adaptive Windows-on-KVM tuning profile (v0.5.5): +invtsc, platform_tick and more, gated by host capability — tuning_profile = auto|safe|off Password auto-rotation: 20-char cryptographic password, 7-day cycle with atomic rollback Smart DPI scaling: auto-detects from GNOME, KDE, Sway, Hyprland, Cinnamon, xrdb Windows debloat: telemetry, ads, Cortana, search indexing disabled by default FreeRDP extra_flags allowlist (regex-validated) as the user-input safety boundary Time sync: force Windows clock resync after host sleep/wake	Operations & resilience Multilingual UI (v0.5.9): tray / GUI / CLI fully translated to 7 languages (en / ko / zh / ja / de / fr / it), auto-detected from $LANG — override with winpodx language <code> or GUI Settings → "winpodx UI language" Windows disk auto-grow (v0.5.9): C: grows itself when it fills past a threshold while idle, bounded by host free space — or grow on demand (winpodx install grow-disk [SIZE], winpodx install disk-usage, GUI Tools → Grow Disk) Guest sync (v0.5.9): push updated agent / urlacl / rdprrap / fixes into a running guest after a host upgrade — automatic once per pod start, or winpodx guest sync [--force] Offline / air-gapped install (--source + --image-tar) One-line uninstall (keeps Windows VM data unless --purge) Health checks via winpodx doctor (deps / pod / RDP / agent / disk / round-trip / password age; --json for machine-readable, --quick for cheap subset, --fix for idempotent auto-remediation of common findings) Qt6 GUI: Apps / Settings / Tools / Terminal / Info pages — plus a lighter system tray Stdlib-leaning Python (no pip-deps on 3.11+; one tomli fallback on 3.9 / 3.10)

See docs/FEATURES.md for deep dives, including multi-session RDP internals, app profile schema, and the reverse-open architecture.

Documentation

Document	What's inside
INSTALL.md	Every install path — one-liner, package managers, AppImage, offline, Nix, source
USAGE.md	CLI reference, Qt6 GUI tour, health checks, configuration file
FEATURES.md	Reverse-open, multi-session RDP, peripherals, app profiles, auto-discovery
ARCHITECTURE.md	How it works (diagram), tech stack, source tree, data flows
COMPARISON.md	winpodx vs winapps / LinOffice / winboat, and winpodx vs Wine
CHANGELOG.md	Full version history
CONTRIBUTING.md	Development setup and workflow
SECURITY.md	Security disclosure process

Supported distros

Distro	Package manager	Status
openSUSE Tumbleweed / Leap 15.6 / Leap 16.0 / Slowroll	zypper	Tested
Fedora 42 / 43 / 44 / Rawhide	dnf	Supported
Fedora Silverblue / Kinoite / Sericea / Bluefin / Bazzite (42 / 43 / 44)	rpm-ostree (OBS, --apply-live)	Supported
Debian 12 / 13, Ubuntu 24.04 / 25.04 / 25.10 / 26.04	apt	Supported
AlmaLinux / Rocky / RHEL 9 / 10	dnf	Supported
Arch / Manjaro	pacman + yay -S winpodx	Supported
NixOS (and Nix on any distro)	nix flake	Supported

Each tag push (v*.*.*) publishes to all channels automatically — see packaging/ for maintainer details.

Testing

# From repo root (no install needed)
export PYTHONPATH="$PWD/src"
python3 -m pytest tests/    # 1240+ tests
ruff check src/ tests/      # Lint
ruff format --check src/ tests/

Contributing

See CONTRIBUTING.md for development setup, branch naming, commit conventions, and CI expectations.

Security

For security issues, follow the process in SECURITY.md.

Star History

Support

If winpodx makes your Linux desktop a little nicer:

Ko-fi handles international cards and PayPal; fairy.hada.io is a Korean tipping platform. Bug reports, PRs, and stars on the repo are equally appreciated and free.

License

MIT — Kim DaeHyun (kernalix7@kodenet.io)