winpodx

winpodx domain command [arguments] [--flags]

winpodx runs a Windows guest inside a Podman or Docker container and presents individual Windows applications as native Linux windows through FreeRDP RemoteApp. Each app gets its own pinnable, alt-tabbable window with the original icon and file association, without exposing the underlying Windows desktop.A small HTTP agent inside the guest receives bearer-authenticated commands from the host so app launches do not flash a PowerShell window. Application discovery, password rotation, multi-session, and health checks are all driven from the winpodx CLI; a Qt6 GUI provides the same actions plus an allowlisted in-app terminal.winpodx targets Linux only. The first run downloads a Windows ISO, runs Sysprep, and applies an OEM customisation pass; expect five to ten minutes before the pod is usable.

app list

Show every Windows application detected inside the pod.

Launch the named application as a RemoteApp window. An optional file is opened with that application.

Register a custom application in the desktop launcher menu.

Register every detected application as a desktop launcher entry.

List active RemoteApp sessions.

Terminate a running RemoteApp session.

Rescan the Windows guest for newly installed applications.

Start the Windows container. --wait blocks until RDP is reachable.

Stop the Windows container.

Restart the Windows container.

Print container, RDP, and agent state.

Block until the first-boot Sysprep / OEM phase finishes. --logs streams progress.

Reapply Windows-side configuration tweaks (registry, services, defaults).

Synchronise the RDP password between winpodx.toml and the Windows guest.

Toggle bundled rdprrap multi-session support.

Pause the running container.

Resume a paused container.

Generate and apply a new RDP password.

Run the interactive first-time configuration wizard.

Run health probes (pod, RDP, agent, round-trip, disk) and print results.

Print system diagnostics (versions, paths, dependencies).

Remove stale Office lock files in the guest.

Force a time synchronisation in the Windows guest.

Disable telemetry and unneeded services in the guest.

Print the current configuration.

Update a configuration key (e.g. rdp.scale 140).

Import settings from an existing winapps.conf.

Launch the Qt6 main window.

Launch the system tray icon.

The configuration file lives at ~/.config/winpodx/winpodx.toml and is editable through winpodx config set:

$ [pod]
backend = "podman"        # or "docker"
cpus = 4
ram = "8G"
auto_start = true
idle_timeout = "30m"

[rdp]
host = "127.0.0.1"
port = 3389
scale = 100
dpi = 96
user = "winpodx"
password_rotation_days = 7

[agent]
port = 8765
token = "<generated>"

$ WINPODX_CONFIG       Override config file path
WINPODX_LOG_LEVEL    debug | info | warn | error

Requires a working Podman or Docker installation, a usable KVM accelerator, and a recent FreeRDP 3 build with RemoteApp support. The first boot performs a full Windows install plus Sysprep; do not interrupt winpodx pod wait-ready. Microsoft Windows itself remains subject to its own licensing terms and is not redistributed by winpodx; the user supplies a valid Windows installation. The guest agent listens on localhost:8765 with a bearer token; do not expose this port to other hosts.

winpodx is a Python 3.9+ project that pairs the dockur/windows container image with FreeRDP RemoteApp and a custom PowerShell HTTP guest agent. It targets the same use case as WinApps but ships container, agent, and GUI as a single tool rather than relying on a manually configured VM. Active development continues on the kernalix7/winpodx repository.

podman(1), docker(1), xfreerdp(1), virsh(1), wine(1)