Tools to Embed Windows Apps into Linux Desktop.This is an open-source tool that runs Windows apps on Linux without entering the full Windows desktop. It runs a Windows system in a container in the background and uses FreeRDP to turn each Windows app into an independent native Linux window, supporting pinning to the taskbar, Alt-Tab switching, file associations, and USB devices.
------------------------------
Windows pod system for Linux
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 / Task Manager / PowerShell each in their own Linux window, alongside the WinPodX Dashboard (live Pod / RAM / CPU gauges, workspace tiles).
English · 한국어 · Install · Usage · Features · Architecture · Comparison
WinPodX is in active development (v0.8.0). v0.7.0 introduced the bare-metal disguise (#246, opt-in / off by default): with
pod.disguise_level balanced | maxthe Windows guest reads like a physical machine to VM-detection software (Nvidia GPU-passthrough "code 43", launch-gate VM checks, VM-hostile installers) — verified against al-khaser 0.82 — and the default guest username becameWPX-User. v0.7.1 is a UX + integration release: discovered Windows apps now register automatic file associations so they appear in your file manager's "Open with" menu (#545, on by default, only added — never set as the default handler); the GUI gains app management — reset-to-detected, a custom-icon picker, multi-select bulk hide/remove, and a restore list for deleted apps (#530); a quick app launcher (winpodx launch, #561) gives a Start-menu-style picker bindable to a DE hotkey;winpodx guino longer blocks the terminal (#549);winpodx doctorwarns on an old FreeRDP with broken RemoteApp windows (#546); andinstall.sh --mainis now honoured on Atomic Fedora (#548). v0.7.2 is a bug-fix release: it fixes a GUI crash on Refresh Apps (#567) and the tray Terminate Session / USB Devices submenus (#573) on KDE/Plasma, discovers apps with Chinese/Japanese/Korean names (#553), keeps the container acrosspod stop(no more recreate-on-update), and gives a clear error when Windows credentials are missing (#569). v0.7.3 adds reverse-open of files on the Windows VM itself — not just your shared Home, the guestC:is shared over SMB and mounted with kio-fuse so a host app opens the real guest file and edits save back (#616, KDE) — an opt-in idle auto-stop that frees the VM's RAM (#622), and a+multitouchflag for touchscreen / stylus / pen passthrough (#623); it also fixeswinpodx app refreshtiming out on a slow guest (#619), the Dashboard RAM / Disk gauges sticking on "n/a" (#634), and removes the USB drive-letter auto-mapper that was destabilizing installs (#613, #638). v0.7.4 lets you choose where the Windows VM lives (install.sh --storage-dir, #646) and install from a local Windows ISO to skip the download (--win-iso, #647), defaults a 24 GB+ host to 8 GB VM RAM (#630); plus fixes — opening a second document in an already-running app, Open with on stripped-PATH desktops like Deepin, a clear error on a missing RDP password (#569), the GUI Logs buttons honouring the Docker backend, the.debpulling inpodman-compose(#644), and the maintenance dialog size (#550). v0.8.0 makes app discovery Start-Menu-only by default — only the apps your Windows Start Menu actually shows, grouped into nested folder sub-groups, with adesktop.full_app_scanopt-in for the old scan-everything behaviour (#581); passes your[pod] keyboardto FreeRDP as the session layout (#660); stages--win-isobefore compose-up so dockur installs from it instead of downloading (#647); self-heals the reverse-open listener; bumps bundled rdprrap to 0.3.0; and fixes several GUI crashes — the Refresh Apps SIGSEGV, an off-thread display-scale SIGABRT, the Debloat task dialog not auto-closing (#550), and a layout-recursion SIGSEGV with long / CJK app names (#553). The AppImage is Thin (~110 MB) — only FreeRDP + Python + Qt + winpodx — and uses the host'spodman/docker. The CLI surface settled in 0.6.0 stands:winpodx guest(guest-side ops),winpodx install(install / disk ops), andwinpodx doctor(diagnostics with--json/--quick/--fix); the post-create chain is the singlewinpodx provision. First install still takes ~5–10 minutes (Windows VM ISO download + Sysprep + OEM apply);winpodx pod wait-ready --logsshows 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).
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.
One-liner (any supported Linux distro):
curl -fsSL https://raw.githubusercontent.com/kernalix7/winpodx/main/install.sh | bashOr 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 setupAfter a package-manager / AppImage install: run
winpodx setuponce 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 soapt 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,dockeralso 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,kvmgroup membership, and/etc/subuid//etc/subgidfor rootless Podman.winpodx setup-hostfixes the kvm / subuid bits via a singlepkexecprompt;winpodx doctorsurfaces anything still missing.
See docs/INSTALL.md for offline / air-gapped builds, source installs, version pinning, and uninstall.
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 --customizeSetup 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 liveRun 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.)winpodx app run word # Launch Word
winpodx app run word ~/doc.docx # Open a file
winpodx app run desktop # Full Windows desktop
winpodx launch # Quick app launcher (Start-menu style picker)Or just click an app icon in your application menu. winpodx launch opens a searchable picker of your Windows apps — bind it to a desktop-environment custom shortcut (KDE: System Settings → Shortcuts → Custom; GNOME: Settings → Keyboard → Custom Shortcuts) for a system-wide hotkey. See docs/USAGE.md for the full CLI, the Qt6 GUI, health checks, and configuration.
|
Bare-metal disguise (VM-detection avoidance) — new in 0.7.0 · opt-in, off by default
| |
|
Reverse-open
|
Seamless app windows
|
|
Zero-config launch
|
Peripherals & sharing
|
|
Automation & security
|
Operations & resilience
|
See docs/FEATURES.md for deep dives, including multi-session RDP internals, app profile schema, and the reverse-open architecture.
| 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 |
| 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.
# From repo root (no install needed)
export PYTHONPATH="$PWD/src"
python3 -m pytest tests/ # 1800+ tests
ruff check src/ tests/ # Lint
ruff format --check src/ tests/from https://github.com/kernalix7/winpodx
