kernalix7/winpodx: Windows pod system for Linux · GitHub

winpodx is in active development (v0.3.0). v0.3.0 ships a redesigned host→guest pipeline — bearer-authed HTTP agent on 127.0.0.1:8765 is now the default command channel, with FreeRDP RemoteApp kept as fallback. App launches no longer flash a PowerShell window. New winpodx check CLI + GUI Health card surface live pod / RDP / agent / round-trip / disk state. 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. 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. No manual VM setup, no ISO downloads, no registry editing. Near-zero external Python dependencies (stdlib only on Python 3.11+; one pure-Python tomli fallback on 3.9/3.10).

Existing tools for running Windows apps on Linux all have trade-offs:

winboat is the closest peer in scope and was an inspiration. We focus on a different mix — stdlib-leaning Python + Qt6 instead of Electron, deeper auto-config (auto suspend, 7-day password rotation, multi-DE HiDPI), and an explicit air-gapped install path. Both projects build on dockur/windows; that ecosystem is bigger than any one app.

winpodx is not a Wine replacement. Wine translates Windows API calls; winpodx runs the actual Windows OS in a container. The two solve different problems and many users have both installed.

Wine wins on speed and on GPU when DXVK/VKD3D translate cleanly. winpodx wins on 100% Windows feature parity for everything else — every app runs on a real Windows kernel, rendered into your Linux desktop as a native window via FreeRDP RemoteApp.

                     ┌─────────────────────────────┐
  Click "Word"       │     Linux Desktop (KDE,      │
  in app menu  ───>  │     GNOME, Sway, ...)        │
                     └──────────────┬──────────────┘
                                    │
                     ┌──────────────▼──────────────┐
                     │         winpodx              │
                     │  ┌─────────────────────┐     │
                     │  │ auto-provision:      │     │
                     │  │  config → password   │     │
                     │  │  → container → RDP   │     │
                     │  │  → desktop entries   │     │
                     │  └─────────────────────┘     │
                     └──────────────┬──────────────┘
                                    │ FreeRDP RemoteApp
                     ┌──────────────▼──────────────┐
                     │   Windows Container (Podman) │
                     │   ┌──────────────────────┐   │
                     │   │  Word  Excel  PPT ... │   │
                     │   │ multi-session/rdprrap │   │
                     │   └──────────────────────┘   │
                     │   127.0.0.1:3390 (TLS)       │
                     └─────────────────────────────┘

Launch with winpodx gui. The Qt6 main window has four pages:

The system tray (winpodx tray) is a lighter-weight alternative — pod controls, app launcher submenu (top 20 + Full Desktop), maintenance submenu (Clean Locks / Sync Time / Suspend), and an optional idle-monitor thread.

winpodx check runs every probe used by the GUI Health card and prints a one-line verdict for each:

=== winpodx check ===

  [OK  ] pod_running        running (ip=127.0.0.1)  (58ms)
  [OK  ] rdp_port           127.0.0.1:3390 reachable  (0ms)
  [OK  ] agent_health       version=0.2.2-rev4  (63ms)
  [OK  ] oem_version        bundle=12  (3ms)
  [OK  ] password_age       7d remaining (max_age=7d)  (0ms)
  [OK  ] apps_discovered    41 app(s) in /home/.../discovered  (3ms)
  [OK  ] disk_free          401.0/3725 GiB free  (0ms)

Overall: OK

Status legend: OK (green) / WARN (yellow — informational, exit 0) / FAIL (red — exit 1) / SKIP (grey — disabled by config). Use --json for machine-readable output.

One-line install (any supported Linux distro):

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

Detects your distro, installs missing system dependencies (Podman, FreeRDP,
KVM, Python 3.9+) with your confirmation, drops winpodx into
~/.local/bin/winpodx-app/. The Windows-app menu populates automatically
the first time the pod boots — discovery scans your running Windows guest
and registers every installed app with its real icon. No root required
except for the dependency install step. Works on
openSUSE, Fedora, Debian/Ubuntu, RHEL-family, and Arch.

By default the installer pins to the latest published GitHub release
(currently v0.1.9). Pre-release / development versions stay opt-in.

Choose a version — pass --main (or --ref TAG) for development
builds, otherwise stick with the default release:

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

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

# Install a specific tag, branch, or commit
curl -fsSL https://raw.githubusercontent.com/kernalix7/winpodx/main/install.sh | bash -s -- --ref v0.1.9

# Env-var equivalent (works under curl | bash without -s --)
WINPODX_REF=main  curl -fsSL https://raw.githubusercontent.com/kernalix7/winpodx/main/install.sh | bash
WINPODX_REF=v0.1.9 curl -fsSL https://raw.githubusercontent.com/kernalix7/winpodx/main/install.sh | bash

Offline / air-gapped install — the installer takes three optional flags
for machines with no registry / package-repo access:

# Copy winpodx from a local clone instead of git clone (also env: WINPODX_SOURCE)
./install.sh --source /media/usb/winpodx

# Preload the Windows image tar instead of fetching at first boot (env: WINPODX_IMAGE_TAR)
./install.sh --image-tar /media/usb/windows-image.tar

# Skip distro package install (env: WINPODX_SKIP_DEPS=1) — fails early if deps aren't present
./install.sh --skip-deps

# Everything at once:
./install.sh --source /media/usb/winpodx --image-tar /media/usb/windows-image.tar --skip-deps

Env vars are honored even under curl | bash, so
WINPODX_SKIP_DEPS=1 curl ... | bash works.

One-line uninstall — --confirm or --purge is required under pipe
(the interactive prompts can’t read from a terminal while bash consumes
stdin from curl):

# Remove winpodx files, keep the Windows container + its data
curl -fsSL https://raw.githubusercontent.com/kernalix7/winpodx/main/uninstall.sh | bash -s -- --confirm

# Full wipe: container, volume, config, launcher, everything
curl -fsSL https://raw.githubusercontent.com/kernalix7/winpodx/main/uninstall.sh | bash -s -- --purge

Prefer a native package manager? Prebuilt RPM / .deb / AUR packages are
attached to every GitHub Release
— openSUSE/Fedora RPMs from the
openSUSE Build Service (home:Kernalix7/winpodx),
the rest from GitHub Actions:

openSUSE Tumbleweed / Leap 15.6 / Leap 16.0 / Slowroll

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

Replace openSUSE_Tumbleweed with openSUSE_Leap_16.0, openSUSE_Leap_15.6,
or openSUSE_Slowroll as needed.

Fedora 42 / 43

sudo dnf config-manager --add-repo \
  https://download.opensuse.org/repositories/home:/Kernalix7/Fedora_43/home:Kernalix7.repo
sudo dnf install winpodx

Debian 12 / 13, Ubuntu 24.04 / 25.04 / 25.10

Download the matching .deb from the
latest release and
install:

sudo apt install ./winpodx_<version>_all_debian13.deb   # pick your flavor

AlmaLinux / Rocky / RHEL 9 & 10

EPEL is required on el9 for python3-tomli. Download the matching .rpm
from the latest release
and install:

sudo dnf install epel-release                     # el9 only
sudo dnf install ./winpodx-<version>-1.noarch.el9.rpm   # or .el10.rpm

Arch Linux (AUR)

Note: AUR publishing is wired up but pending a one-time maintainer setup
(see packaging/aur/README.md). Once activated,
tag pushes publish automatically.

yay -S winpodx        # or:
paru -S winpodx

From source (development)

git clone https://github.com/kernalix7/winpodx.git
cd winpodx
./install.sh

The source installer automatically:

1. Detects your distro (openSUSE, Fedora, Ubuntu, Arch, …)
2. Installs missing dependencies (Podman, FreeRDP, KVM), asks before installing
3. Copies winpodx to ~/.local/bin/winpodx-app/
4. Creates config and compose.yaml
5. Auto-discovery (winpodx app refresh) fires on first pod boot to populate the menu

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 menu.

git clone https://github.com/kernalix7/winpodx.git
cd winpodx
export PYTHONPATH="$PWD/src"
python3 -m winpodx app run word

# Apps
winpodx app list                  # List available apps
winpodx app run word              # Launch Word (auto-provisions on first run)
winpodx app run word ~/doc.docx   # Open a file in Word
winpodx app run desktop           # Full Windows desktop session
winpodx app install-all           # Register all apps in desktop menu
winpodx app sessions              # Show active sessions
winpodx app kill word             # Kill an active session

# Pod management
winpodx pod start --wait          # Start and wait for RDP readiness
winpodx pod stop                  # Stop (warns about active sessions)
winpodx pod status                # Status with session count
winpodx pod restart
winpodx pod apply-fixes           # Re-apply Windows-side runtime fixes (idempotent)
winpodx pod sync-password         # Recover from password drift (cfg ↔ Windows)
winpodx pod multi-session on      # Toggle bundled rdprrap multi-session RDP
winpodx pod multi-session status
winpodx pod wait-ready --logs     # Wait for Windows first-boot with progress + container logs

# Power management
winpodx power --suspend           # Pause container (free CPU, keep memory)
winpodx power --resume            # Resume paused container

# Security
winpodx rotate-password           # Rotate Windows RDP password

# Maintenance
winpodx cleanup                   # Remove Office lock files (~$*.*)
winpodx timesync                  # Force Windows time synchronization
winpodx debloat                   # Disable telemetry, ads, bloat
winpodx uninstall                 # Remove winpodx files (keeps container)
winpodx uninstall --purge         # Remove everything including config

# System
winpodx setup                     # Interactive setup wizard
winpodx info                      # Display, dependencies, config diagnostics
winpodx check                     # Run all health probes (pod / RDP / agent / disk / …)
winpodx check --json              # Same probes, machine-readable JSON
winpodx gui                       # Launch Qt6 main window (Apps / Settings / Tools / Terminal)
winpodx tray                      # Launch Qt system tray icon
winpodx config show               # Show current config
winpodx config set rdp.scale 140  # Change a config value
winpodx config import             # Import existing winapps.conf

Plug in USB on Linux
    │
    ▼
Linux mounts to /run/media/$USER/USBNAME
    │
    ▼
FreeRDP shares as \\tsclient\media\USBNAME
    │
    ▼
media_monitor.ps1 detects → net use E: \\tsclient\media\USBNAME
    │
    ▼
Windows Explorer shows E: drive

Config file: ~/.config/winpodx/winpodx.toml (auto-created, 0600 permissions)

[rdp]
user = "User"
password = ""                # Auto-generated random password
password_updated = ""        # ISO 8601 timestamp
password_max_age = 7         # Days before auto-rotation (0 = disable)
ip = "127.0.0.1"
port = 3390
scale = 100                  # Auto-detected from your DE
dpi = 0                      # Windows DPI % (0 = auto)
extra_flags = ""             # Additional FreeRDP flags (allowlisted)

[pod]
backend = "podman"
win_version = "11"                               # 11 | 10 | ltsc10 | tiny11 | tiny10
cpu_cores = 4
ram_gb = 4
vnc_port = 8007
auto_start = true                                # Start pod automatically when launching an app
idle_timeout = 0                                 # Seconds before auto-suspend (0 = disabled)
boot_timeout = 300                               # Seconds to wait for first-boot unattended install
image = "ghcr.io/dockur/windows:latest"          # Container image (override for air-gapped mirror)
disk_size = "64G"                                # Virtual disk size passed to dockur

App profiles are metadata only: they describe where a Windows app lives so winpodx can launch it through FreeRDP RemoteApp. The actual Windows application must be installed inside the Windows container.

Starting from v0.1.9 winpodx ships no curated profile list. The first time the Windows pod boots, the provisioner runs winpodx app refresh and that scans the running guest:

• Registry App Paths (HKLM + HKCU)
• Start Menu .lnk recursion (depth-capped)
• UWP / MSIX packages via Get-AppxPackage + AppxManifest.xml
• Chocolatey + Scoop shims

For each result it extracts the icon directly from the binary (or the package’s logo asset for UWP) and writes the entry to ~/.local/share/winpodx/discovered//. Re-run any time:

winpodx app refresh        # CLI
# or click "Refresh Apps" on the GUI Apps page

mkdir -p ~/.local/share/winpodx/apps/myapp
cat > ~/.local/share/winpodx/apps/myapp/app.toml << 'EOF'
name = "myapp"
full_name = "My Application"
executable = "C:\\Program Files\\MyApp\\myapp.exe"
categories = ["Utility"]
mime_types = []
EOF

winpodx app install myapp   # Register in desktop menu

Stock Windows Desktop editions limit RDP to one session per user; a second app
would otherwise reconnect and steal the first session. winpodx bundles
rdprrap — a Rust reimplementation of
RDPWrap — inside the package itself and installs it automatically during the
Windows unattended install, so each RemoteApp window gets its own independent
session.

RAIL prerequisites. RemoteApp itself requires three registry settings that
winpodx applies during unattended setup: fDisabledAllowList=1 (enables
RemoteApp publishing), fInheritInitialProgram=1 (required for
/app:program:... to launch the target executable instead of a shell), and
MaxInstanceCount=10 paired with fSingleSessionPerUser=0 (lifts the
single-session cap up to 10 concurrent RemoteApp windows). These are set
regardless of whether rdprrap installs successfully — rdprrap is what makes
the sessions independent, but the registry keys are what make RemoteApp
work at all. After rdprrap install TermService is cycled so the wrapper
DLL activates without a reboot.

Authentication channel. NLA is disabled (UserAuthentication=0) so the
FreeRDP command line can authenticate unattended from under
podman unshare --rootless-netns, but SecurityLayer=2 keeps the RDP
channel itself encrypted with TLS (so /sec:tls /cert:ignore against
127.0.0.1 is the full authenticated + encrypted path — no cleartext on the
wire even though NLA is off).

Works fully offline. The rdprrap zip ships inside winpodx’s data directory
(config/oem/) and is staged into C:\OEM\ during the guest’s first boot.
sha256 is verified against a pin file before extraction. No network access is
required at install time.

Install is one-shot: the patch is applied during dockur’s unattended setup
phase. If anything in that step fails (hash mismatch, extraction, installer
error), winpodx logs a warning and the guest stays in single-session mode —
app launch never blocks on this step. A guest-side management channel
(enable/disable/status after install) is planned for a later release.

# From a cloned repo:
./install.sh                # Install (detects distro, installs deps, registers apps)
./uninstall.sh              # Uninstall (interactive, asks before each step)
./uninstall.sh --confirm    # Uninstall (auto, keeps config)
./uninstall.sh --purge      # Uninstall (removes everything including config)

# Or one-liner (no clone needed):
curl -fsSL https://raw.githubusercontent.com/kernalix7/winpodx/main/install.sh   | bash
curl -fsSL https://raw.githubusercontent.com/kernalix7/winpodx/main/uninstall.sh | bash -s -- --confirm
curl -fsSL https://raw.githubusercontent.com/kernalix7/winpodx/main/uninstall.sh | bash -s -- --purge

Uninstall only removes winpodx files. It never touches:

• Your Podman containers/volumes (Windows VM data)
• System packages (podman, freerdp, python3)
• Your home directory files

winpodx/
├── install.sh             # One-line installer (no pip)
├── uninstall.sh           # Clean uninstaller
├── src/winpodx/
│   ├── cli/               # argparse commands (app, pod, config, setup, ...)
│   ├── core/              # Config, RDP, pod lifecycle, provisioner, daemon
│   ├── backend/           # Podman, Docker, libvirt, manual
│   ├── desktop/           # .desktop entries, icons, MIME, tray, notifications
│   ├── display/           # X11/Wayland detection, DPI scaling
│   ├── gui/               # Qt6 main window, app dialog, theme
│   └── utils/             # XDG paths, deps, TOML writer, winapps compat
├── data/                  # winpodx GUI desktop entry + icon + config example
├── config/oem/            # Windows OEM scripts (post-install)
├── scripts/windows/       # PowerShell scripts (debloat, time sync, USB mapping, app discovery)
├── .github/workflows/     # CI: lint + test + upstream update checker
└── tests/                 # pytest test suite (411 tests)

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

See CONTRIBUTING.md for development setup and workflow.

Each tag push (v*.*.*) publishes to all supported channels automatically:

Maintainer setup for each channel lives under packaging/:

• packaging/obs/README.md — openSUSE Build Service (RPM family).
• packaging/aur/README.md — Arch User Repository.
• Debian/Ubuntu and AlmaLinux builds are self-contained in their respective GitHub Actions workflows and need no external setup.

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

MIT – Kim DaeHyun (kernalix7@kodenet.io)