Windows pod system for Linux
See the code
Windows apps as native Linux windows — real icons, real WM_CLASS, pin-to-taskbar.
FreeRDP RemoteApp over dockur/windows. No permanent full-screen desktop, no manual setup.
# Install (latest stable release)
curl -fsSL https://raw.githubusercontent.com/kernalix7/winpodx/main/install.sh | bash
# Development branch (may be unstable)
curl -fsSL https://raw.githubusercontent.com/kernalix7/winpodx/main/install.sh | bash -s -- --main
# Uninstall (keeps the Windows VM; add --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 its own Linux window, next to the WinPodX Dashboard.
English · 한국어 · Install · Usage · Features · Architecture · Comparison
Contents: Requirements · Install · Launch · Desktop app · Key features · Documentation · Testing · Contributing
Status: Beta
WinPodX is in active development, v0.12.0.
- A six-page Windows-style setup wizard in the desktop app (Welcome, Configuration, Prerequisites, Review, Install, Finish), with storage directory and a local Windows ISO picked from one place
- Setup progress in CLI and GUI, shared GUI dialog chrome, and localized installer messages
- First GUI provisioning requires the guest agent; automatic discovery retries use 60/120/180/240/300-second delays when needed
- Install-time recovery notifications stay suppressed for the duration of a GUI install, without changing recovery-toast behaviour for non-install launches
- Installed PNG icons gain SVG wrappers without vectorization; hicolor
index.themeis repaired, and.desktopIcon=values remain theme names- AppImage source delivery is implemented: SHA256-verified originals, indexes, licenses, input locks, and recipes form
winpodx-appimage-sources.tar.gz; tag builds attach it withPROVENANCE.json,SOURCE-OFFER.txt, andSHA256SUMSalongside the binary. Each artifact has its own provenance and source-delivery record; this is not blanket legal or security clearance.- Opt-in
[pod] extra_portsaccepts port-mapping strings, for example["25000:30000/tcp"]- Reverse-open shim builds have a recorded lockfile and build inventory; crate and Rust standard-library notices accompany guest copies
Full detail in the CHANGELOG.
Each Windows app opens as its own Linux window, keeping its icon, taskbar entry, and file associations. Clipboard, audio, printers, and your home directory are shared both ways. You only see a full Windows desktop when you ask for one with winpodx app run desktop.
WinPodX runs Windows in a container in the background and starts it on demand — the pod pauses when idle and wakes on your next launch.
Virtualization must be available before Windows can boot. These three checks catch almost every "installed fine but Windows never started" report:
| Requirement | Check | Fix |
|---|---|---|
| Intel VT-x or AMD-V enabled | lscpu | grep -i virtualization | Enable Intel Virtualization Technology, SVM Mode, or VT-x in firmware. |
| KVM module loaded | lsmod | grep kvm | sudo modprobe kvm_intel or sudo modprobe kvm_amd. |
| Your user can reach KVM | id -nG | tr ' ' '\n' | grep kvm | sudo usermod -aG kvm $USER, then log out and back in. |
Hardware: x86_64 or aarch64 with virtualization extensions, 8 GB RAM (12 GB recommended), and room for the 64 GB default Windows disk plus an installer ISO.
Software: FreeRDP 3+ and Podman with a compose provider, or Docker. Rootless Podman also needs /etc/subuid and /etc/subgid entries. Run winpodx setup-host to fix the group and subuid setup in one prompt, and winpodx doctor any time to see what is still missing.
The curl one-liner in the header works on every supported distribution and finishes setup for you. Native packages are also available:
# 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 — the matching .deb from the latest release
sudo apt install ./winpodx_<version>_all_debian13.deb
# AlmaLinux / Rocky / RHEL 9 / 10 — the matching .rpm
sudo dnf install ./winpodx-<version>-0.noarch.el10.rpm
# Arch
yay -S winpodx
# Nix
nix run github:kernalix7/winpodx
# AppImage — one file, any x86_64 distro
chmod +x winpodx-x86_64.AppImage
./winpodx-x86_64.AppImage setup
After a package, AppImage, source, or wheel install, run setup once. Package installs deliberately ship the binary only, so apt install never triggers a long Windows download on its own:
winpodx setup # host-detected defaults, no prompts
winpodx setup --customize # pick backend, VM settings, storage directory, and optional local Windows ISO
Setup writes the configuration, verifies the host, provisions Windows, discovers your apps, and registers desktop entries.
In --customize, press Enter at the storage and ISO prompts to keep the default storage directory and download Windows; the wizard reviews both choices before creating the pod. Existing guest storage is not moved or replaced by setup; use winpodx setup --migrate-storage to relocate it.
winpodx gui first-run setup uses the same six-page wizard: Welcome, Configuration, Prerequisites, Review, Install, Finish. It selects Podman or Docker, VM specs, edition, storage directory, and an optional local ISO, then checks those exact choices before provisioning. A local ISO does not promise a fully offline install. Reinstall keeps the existing backend, storage, and installation media, and asks for wipe confirmation only after review.
Updating: re-run the curl installer to upgrade a curl install in place, keeping your config and VM (this works on Bazzite and other rpm-ostree hosts too). Package and AppImage installs update through whatever you installed them with.
On RHEL 9, AlmaLinux 9, and Rocky Linux 9 the default python3 is older than WinPodX supports; the el9 package pulls in the Python 3.11 stack from AppStream automatically.
Offline and air-gapped installs, building from source, Nix, and full uninstall are covered in INSTALL.md.
winpodx app run word # Launch Word
winpodx app run word ~/doc.docx # Open a file with it
winpodx app run desktop # Full Windows desktop
winpodx launch # Searchable Start-style app picker
winpodx gui # Desktop app
Or just click a Windows app in your application menu — WinPodX installs real desktop entries for everything it discovers. Bind winpodx launch to a custom shortcut (KDE: System Settings → Shortcuts; GNOME: Settings → Keyboard) for a system-wide hotkey.
winpodx gui opens a Windows 11 Settings-style shell with eight pages:
| Page | What it holds |
|---|---|
| Dashboard | Pod state with Start/Stop, RAM / CPU / disk rings, quick actions, running sessions, pinned apps |
| Applications | Start Menu tiles with search, category counts, grid or list view, and per-app actions |
| Settings | Connection, hardware, Windows Update, integration, and language, grouped by intent, with a marker until you save |
| Tools | Pod and guest operations — suspend, resume, grow disk, debloat, apply fixes |
| Terminal | Pod and app logs with a filtered command bar |
| Info | Version, health checks, and one-click copyable diagnostics |
| Devices | USB and PCI passthrough, grouped by bus, with risky assignments flagged |
| License | License text and third-party acknowledgements |
The navigation pane is 320 px wide normally and collapses to a 48 px icon rail below 1100 px, where the hamburger button overlays it on top of the content. The theme follows your desktop's light or dark preference; set WINPODX_COLOR_SCHEME=light|dark to override it, or WINPODX_NATIVE_TITLEBAR=1 to use your window manager's decorations instead of the built-in title bar. See the GUI tour for the rest.
| Area | What it does |
|---|---|
| Seamless apps | RemoteApp opens each app as a native window with real icons, WM_CLASS, taskbar integration, file associations, multi-monitor support, and up to 50 concurrent RDP sessions. |
| App discovery | Imports Start Menu-visible Win32 and UWP apps with their icons. Rescan with winpodx app refresh or from Applications. |
| Sharing | Two-way clipboard, audio, printers, \\tsclient\home, removable media, and USB or PCI passthrough. |
| Reverse-open | Linux apps appear in the Windows Open with menu and receive files back on the host through a controlled listener. |
| Pod operation | Podman by default, with Docker and manual RDP supported. Auto-pauses when idle, recovers a stalled guest, rotates passwords, and grows the Windows disk. |
| Privacy and tuning | Optional Windows debloat, host-adaptive KVM tuning, DPI detection, an allowlist for FreeRDP flags, time sync, and optional bare-metal disguise. |
| Languages | CLI, tray, and desktop app in English, Korean, Chinese, Japanese, German, French, and Italian. |
| Document | Contents |
|---|---|
| INSTALL.md | Every install path, updating, offline, source, Nix, uninstall |
| USAGE.md | CLI reference, GUI tour, health checks, configuration |
| FEATURES.md | RemoteApp, reverse-open, peripherals, discovery, passthrough |
| ARCHITECTURE.md | System diagram, source tree, data flows |
| COMPARISON.md | WinPodX vs winapps, LinOffice, winboat, and Wine |
| CHANGELOG.md | Version history |
| CONTRIBUTING.md | Development setup and workflow |
| SECURITY.md | Security reporting process |
export PYTHONPATH="$PWD/src"
python3 -m pytest tests/ -n auto # 4000+ tests, seconds in parallel
ruff check src/ tests/
ruff format --check src/ tests/
Read CONTRIBUTING.md before sending a change; security reports follow SECURITY.md. WinPodX is MIT licensed, Kim DaeHyun.
For setup help, questions, and release chatter, join the Discord community. Bugs and feature requests still belong in issues so they stay searchable.
If WinPodX makes your Linux desktop a little nicer:
GitHub Sponsors handles recurring or one-time sponsorship, Ko-fi covers international cards and PayPal, and fairy.hada.io is a Korean tipping platform. Bug reports, PRs, and stars are just as welcome — and free.
3,475 followers · starred Jun 2026
468 followers · starred May 2026
36 followers · starred May 2026
145 followers · starred May 2026
Windows pod system for Linux
See the code
Windows apps as native Linux windows — real icons, real WM_CLASS, pin-to-taskbar.
FreeRDP RemoteApp over dockur/windows. No permanent full-screen desktop, no manual setup.
# Install (latest stable release)
curl -fsSL https://raw.githubusercontent.com/kernalix7/winpodx/main/install.sh | bash
# Development branch (may be unstable)
curl -fsSL https://raw.githubusercontent.com/kernalix7/winpodx/main/install.sh | bash -s -- --main
# Uninstall (keeps the Windows VM; add --purge to wipe everything)
curl -fsSL https://raw.githubusercontent.com/kernalix7/winpodx/main/uninstall.sh | bash -s -- --confirmWindows About / Task Manager / PowerShell, each in its own Linux window, next to the WinPodX Dashboard.
English · 한국어 · Install · Usage · Features · Architecture · Comparison
Contents: Requirements · Install · Launch · Desktop app · Key features · Documentation · Testing · Contributing
Status: Beta
WinPodX is in active development, v0.12.0.
- A six-page Windows-style setup wizard in the desktop app (Welcome, Configuration, Prerequisites, Review, Install, Finish), with storage directory and a local Windows ISO picked from one place
- Setup progress in CLI and GUI, shared GUI dialog chrome, and localized installer messages
- First GUI provisioning requires the guest agent; automatic discovery retries use 60/120/180/240/300-second delays when needed
- Install-time recovery notifications stay suppressed for the duration of a GUI install, without changing recovery-toast behaviour for non-install launches
- Installed PNG icons gain SVG wrappers without vectorization; hicolor
index.themeis repaired, and.desktopIcon=values remain theme names- AppImage source delivery is implemented: SHA256-verified originals, indexes, licenses, input locks, and recipes form
winpodx-appimage-sources.tar.gz; tag builds attach it withPROVENANCE.json,SOURCE-OFFER.txt, andSHA256SUMSalongside the binary. Each artifact has its own provenance and source-delivery record; this is not blanket legal or security clearance.- Opt-in
[pod] extra_portsaccepts port-mapping strings, for example["25000:30000/tcp"]- Reverse-open shim builds have a recorded lockfile and build inventory; crate and Rust standard-library notices accompany guest copies
Full detail in the CHANGELOG.
Each Windows app opens as its own Linux window, keeping its icon, taskbar entry, and file associations. Clipboard, audio, printers, and your home directory are shared both ways. You only see a full Windows desktop when you ask for one with winpodx app run desktop.
WinPodX runs Windows in a container in the background and starts it on demand — the pod pauses when idle and wakes on your next launch.
Virtualization must be available before Windows can boot. These three checks catch almost every "installed fine but Windows never started" report:
| Requirement | Check | Fix |
|---|---|---|
| Intel VT-x or AMD-V enabled | lscpu | grep -i virtualization | Enable Intel Virtualization Technology, SVM Mode, or VT-x in firmware. |
| KVM module loaded | lsmod | grep kvm | sudo modprobe kvm_intel or sudo modprobe kvm_amd. |
| Your user can reach KVM | id -nG | tr ' ' '\n' | grep kvm | sudo usermod -aG kvm $USER, then log out and back in. |
Hardware: x86_64 or aarch64 with virtualization extensions, 8 GB RAM (12 GB recommended), and room for the 64 GB default Windows disk plus an installer ISO.
Software: FreeRDP 3+ and Podman with a compose provider, or Docker. Rootless Podman also needs /etc/subuid and /etc/subgid entries. Run winpodx setup-host to fix the group and subuid setup in one prompt, and winpodx doctor any time to see what is still missing.
The curl one-liner in the header works on every supported distribution and finishes setup for you. Native packages are also available:
# 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 — the matching .deb from the latest release
sudo apt install ./winpodx_<version>_all_debian13.deb
# AlmaLinux / Rocky / RHEL 9 / 10 — the matching .rpm
sudo dnf install ./winpodx-<version>-0.noarch.el10.rpm
# Arch
yay -S winpodx
# Nix
nix run github:kernalix7/winpodx
# AppImage — one file, any x86_64 distro
chmod +x winpodx-x86_64.AppImage
./winpodx-x86_64.AppImage setup
After a package, AppImage, source, or wheel install, run setup once. Package installs deliberately ship the binary only, so apt install never triggers a long Windows download on its own:
winpodx setup # host-detected defaults, no prompts
winpodx setup --customize # pick backend, VM settings, storage directory, and optional local Windows ISO
Setup writes the configuration, verifies the host, provisions Windows, discovers your apps, and registers desktop entries.
In --customize, press Enter at the storage and ISO prompts to keep the default storage directory and download Windows; the wizard reviews both choices before creating the pod. Existing guest storage is not moved or replaced by setup; use winpodx setup --migrate-storage to relocate it.
winpodx gui first-run setup uses the same six-page wizard: Welcome, Configuration, Prerequisites, Review, Install, Finish. It selects Podman or Docker, VM specs, edition, storage directory, and an optional local ISO, then checks those exact choices before provisioning. A local ISO does not promise a fully offline install. Reinstall keeps the existing backend, storage, and installation media, and asks for wipe confirmation only after review.
Updating: re-run the curl installer to upgrade a curl install in place, keeping your config and VM (this works on Bazzite and other rpm-ostree hosts too). Package and AppImage installs update through whatever you installed them with.
On RHEL 9, AlmaLinux 9, and Rocky Linux 9 the default python3 is older than WinPodX supports; the el9 package pulls in the Python 3.11 stack from AppStream automatically.
Offline and air-gapped installs, building from source, Nix, and full uninstall are covered in INSTALL.md.
winpodx app run word # Launch Word
winpodx app run word ~/doc.docx # Open a file with it
winpodx app run desktop # Full Windows desktop
winpodx launch # Searchable Start-style app picker
winpodx gui # Desktop app
Or just click a Windows app in your application menu — WinPodX installs real desktop entries for everything it discovers. Bind winpodx launch to a custom shortcut (KDE: System Settings → Shortcuts; GNOME: Settings → Keyboard) for a system-wide hotkey.
winpodx gui opens a Windows 11 Settings-style shell with eight pages:
| Page | What it holds |
|---|---|
| Dashboard | Pod state with Start/Stop, RAM / CPU / disk rings, quick actions, running sessions, pinned apps |
| Applications | Start Menu tiles with search, category counts, grid or list view, and per-app actions |
| Settings | Connection, hardware, Windows Update, integration, and language, grouped by intent, with a marker until you save |
| Tools | Pod and guest operations — suspend, resume, grow disk, debloat, apply fixes |
| Terminal | Pod and app logs with a filtered command bar |
| Info | Version, health checks, and one-click copyable diagnostics |
| Devices | USB and PCI passthrough, grouped by bus, with risky assignments flagged |
| License | License text and third-party acknowledgements |
The navigation pane is 320 px wide normally and collapses to a 48 px icon rail below 1100 px, where the hamburger button overlays it on top of the content. The theme follows your desktop's light or dark preference; set WINPODX_COLOR_SCHEME=light|dark to override it, or WINPODX_NATIVE_TITLEBAR=1 to use your window manager's decorations instead of the built-in title bar. See the GUI tour for the rest.
| Area | What it does |
|---|---|
| Seamless apps | RemoteApp opens each app as a native window with real icons, WM_CLASS, taskbar integration, file associations, multi-monitor support, and up to 50 concurrent RDP sessions. |
| App discovery | Imports Start Menu-visible Win32 and UWP apps with their icons. Rescan with winpodx app refresh or from Applications. |
| Sharing | Two-way clipboard, audio, printers, \\tsclient\home, removable media, and USB or PCI passthrough. |
| Reverse-open | Linux apps appear in the Windows Open with menu and receive files back on the host through a controlled listener. |
| Pod operation | Podman by default, with Docker and manual RDP supported. Auto-pauses when idle, recovers a stalled guest, rotates passwords, and grows the Windows disk. |
| Privacy and tuning | Optional Windows debloat, host-adaptive KVM tuning, DPI detection, an allowlist for FreeRDP flags, time sync, and optional bare-metal disguise. |
| Languages | CLI, tray, and desktop app in English, Korean, Chinese, Japanese, German, French, and Italian. |
| Document | Contents |
|---|---|
| INSTALL.md | Every install path, updating, offline, source, Nix, uninstall |
| USAGE.md | CLI reference, GUI tour, health checks, configuration |
| FEATURES.md | RemoteApp, reverse-open, peripherals, discovery, passthrough |
| ARCHITECTURE.md | System diagram, source tree, data flows |
| COMPARISON.md | WinPodX vs winapps, LinOffice, winboat, and Wine |
| CHANGELOG.md | Version history |
| CONTRIBUTING.md | Development setup and workflow |
| SECURITY.md | Security reporting process |
export PYTHONPATH="$PWD/src"
python3 -m pytest tests/ -n auto # 4000+ tests, seconds in parallel
ruff check src/ tests/
ruff format --check src/ tests/
Read CONTRIBUTING.md before sending a change; security reports follow SECURITY.md. WinPodX is MIT licensed, Kim DaeHyun.
For setup help, questions, and release chatter, join the Discord community. Bugs and feature requests still belong in issues so they stay searchable.
If WinPodX makes your Linux desktop a little nicer:
GitHub Sponsors handles recurring or one-time sponsorship, Ko-fi covers international cards and PayPal, and fairy.hada.io is a Korean tipping platform. Bug reports, PRs, and stars are just as welcome — and free.
3,475 followers · starred Jun 2026
468 followers · starred May 2026
36 followers · starred May 2026
145 followers · starred May 2026