WSL Manager · 0.1.0

A lightweight Windows desktop utility for managing registered WSL distributions and their systemd services. Built with Python and Tkinter, with no third-party Python runtime dependencies.

The screenshot is an actual Tk window in demo mode, rendered on Linux. It is not evidence of a native Windows integration test. The Windows title bar and fonts may differ.

What it does

Select a distribution, inspect its services, and manage runtime activity separately from autostart. The default Development services scope covers common web, PHP, database, cache and search services. All services also includes other installed and loaded systemd services, including instantiated and transient units.

• Explicitly start or stop a particular distribution; never issue a global wsl --shutdown.
• Start, stop or restart services. Enable or disable autostart, optionally combined with start/stop.
• Show runtime, autostart, descriptions, aliases and optional TCP/UDP listeners. Static, masked, runtime-enabled and other install states are not flattened into a misleading checkbox.
• Search, filter and sort services; use Ctrl/Shift multi-selection; read the last 120 journal entries on request.
• Light, dark and system appearance; remembered geometry/selection; optional 15–120-second refresh.
• Check Forgejo releases, download with progress, verify SHA-256, and install only after a separate explicit choice.
• Copy diagnostics and inspect rotating application logs.

This is not a distribution installer, backup tool, Linux boot configurator or network/firewall manager. It does not delete distributions, install packages, unmask units or enable systemd for you. Legacy saved profile records are retained, but there is no automatic profile execution or distribution-isolation workflow.

Requirements and support boundary

The intended deployment is Windows 11 x64 with a recent Microsoft WSL installation. Service management requires a running Linux distribution with systemd/systemctl. Host-side enumeration and explicit distribution controls are independent of systemd. WSL1 version information is displayed, but service support is determined by the actual Linux system manager, not inferred from the WSL version.

Source execution targets CPython 3.11–3.13 with Tkinter. The release build includes Python/Tk so installed users do not need Python. Windows ARM64-native and 32-bit packages are not supplied by this build script.

Validation status: the source, real Tk UI, simulated backend, parsers and updater verification have been exercised on Linux. A native Windows EXE/installer and live WSL integration have not been built or tested in the preparation environment. Complete the release checklist before publishing a stable binary. See the exact validation record.

Start from source

Open PowerShell in the extracted repository on the Windows filesystem:

py -3.13 -m venv .venv
.\.venv\Scripts\python.exe -m app

No pip install is required for normal source execution. The Python Windows installer must include Tcl/Tk.

For a preview without any WSL or update-network calls:

.\.venv\Scripts\python.exe -m app --demo --theme dark

The title and subtitle clearly identify demo mode. Its settings are kept separately. python -m app --version prints the source version; --theme light, --theme dark and --theme system select appearance. Demo mode also works on a Linux desktop with Tk installed, but normal Linux execution is not a supported WSL management deployment.

Safe everyday use

Refresh first reads the distribution list using host-side WSL list commands. It does not read /etc/os-release in every distribution. Service inspection targets only the selected distribution, and each Linux command is preceded by a fresh running-list check. A distribution already reported stopped is not inspected; use Start explicitly.

Important limitation: the stock WSL CLI does not provide an atomic “execute only if still running” option used by this implementation. An external stop can race between the running check and wsl --exec. In that narrow interval the CLI can start the distribution again. This guard is best effort, not an absolute no-start guarantee. Automatic refresh is off by default. Avoid externally terminating the selected distro during inspection; refresh afterward. See the audit for the exact boundary.

Service commands run as root inside the selected distribution so they cannot wait for an interactive sudo password. The Windows GUI and per-user installer do not normally need Windows administrator elevation. Review selected services before actions, especially in All services. Stopping a distribution terminates all of its processes and is confirmed with a consequence-focused dialog.

Runtime answers what a service is doing now. Autostart describes unit-file enablement. Enabled does not guarantee a successful boot start; Disabled does not prevent a dependency, socket or manual command starting a service. An active one-shot service is shown as Active (exited), not Running.

Port information describes Linux listeners, not guaranteed Windows/localhost reachability. A dash means no listeners were attributed from a sufficiently complete snapshot; Unavailable means attribution was incomplete or failed. Off means the option is disabled. Socket-owned listeners may be shown for an inactive socket-activated service.

Cancelling or closing stops waiting for a command client. It does not roll back an already-submitted systemd operation. Refresh before retrying any state change.

Keyboard and interaction

Action	Shortcut / interaction
Refresh	F5
Focus search	Ctrl+F
Settings	Ctrl+,
Clear search and filters	Escape in search
Service details	Enter or double-click
Copy selected names	Ctrl+C in service table
Multiple services	Ctrl/Shift selection
Context actions	Right-click a row
Close a dialog	Escape, except while installer launch is being verified

The interface remains searchable and navigable during reads. State-changing buttons are disabled until the relevant snapshot is current and the command lane is idle. Reads are coalesced; WSL mutations are serialized. Refresh pauses while minimized or while a modal confirmation/settings dialog is open.

Settings and diagnostics

Normal configuration: %APPDATA%\WslManager\config.json. Previous OS-identity cache and profile records are preserved. Invalid settings fall back to defaults; a malformed JSON file is backed up beside the original on the next save. Small configuration files are validated and written with a unique temporary file and atomic replacement.

Logs: %LOCALAPPDATA%\WslManager\Logs\wsl-manager.log, up to 2 MiB per file with three backups. Normal polling output is not dumped to logs. Explicit journal content is not automatically logged; it can contain application data, so inspect it before copying. Activity → Copy diagnostics copies diagnostic text; nothing is uploaded automatically.

Downloaded updates: %LOCALAPPDATA%\WslManager\Updates\download-*. Failed/cancelled downloads are removed on handled failure; abandoned generated directories older than seven days are cleaned during update checks. Abrupt process termination can leave a partial directory for that later cleanup.

Updates and trust

The app reads the repository's /api/v1/repos/andriiuok/wsl-manager/releases/latest endpoint. It accepts a newer stable vX.Y.Z tag with both exact assets:

WslManager-Setup-X.Y.Z.exe
WslManager-Setup-X.Y.Z.exe.sha256

The checksum contains the SHA-256 digest and exact installer filename. The URL policy permits only HTTPS on git.abdev.top, including redirects. Moving attachments to another origin requires a deliberate code/policy change, not disabling verification.

The dialog shows the installed/new versions, publisher-provided notes as plain text, download progress, verification, and a separate Install update action. Metadata, installer size and download time are bounded. Before launch the installer is hashed again; on Windows a read handle denies write/delete sharing through process creation. Arbitrary file paths are not accepted by the launch API.

SHA-256 from the same server detects corruption; it is not publisher authentication. This project does not verify an Authenticode publisher or an independently signed update manifest. A compromised release server/account remains a trust risk. No installer is executed solely because a newer release was discovered.

Validate the project

.\.venv\Scripts\python.exe tools\validate.py --require-ui

This checks imports, Python syntax, resources, manifest, installer identity and version, then runs the tests. Tests use fixtures, not your real distributions. Two Windows-only tests exercise file sharing and mutex behavior on a Windows host. On Linux they explicitly skip; --require-ui prevents accidentally counting a headless UI skip as successful UI validation.

Linux CI/development equivalents:

xvfb-run -a -s '-screen 0 1600x1000x24' python tools/validate.py --require-ui
xvfb-run -a -s '-screen 0 1920x1080x24' python tools/check_scaling.py

Optional development tooling:

.\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
.\.venv\Scripts\python.exe -m ruff check .

tools/render_preview.py requires Pillow and a visible/virtual desktop. It captures actual demo widgets into docs/screenshots/; it does not modify production data. tools/check_scaling.py checks visible controls at four simulated Tk scales; it is not a substitute for native multi-monitor DPI/accessibility testing.

Build the Windows release

Use a clean Windows x64 CPython 3.11–3.13 virtual environment and Inno Setup 6.3 or newer. Do not build the Windows executable from WSL/Linux.

.\.venv\Scripts\python.exe -m pip install -r requirements-build.txt
.\build.ps1

To use custom paths:

.\build.ps1 -Python "C:\Tools\wsl-build\Scripts\python.exe" -Iscc "C:\Tools\Inno Setup 6\ISCC.exe"

The script validates first, checks every compiler exit code, removes old target artifacts, generates the Windows version resource from VERSION, freezes the application, compiles the per-user installer and writes the matching checksum. A failed PyInstaller stage cannot be followed by packaging a stale EXE. The exact legacy Inno AppId is retained for upgrade continuity. The application mutex is shared with the installer; previous installation directories are respected.

Outputs:

dist/WslManager.exe
release/WslManager-Setup-0.1.0.exe
release/WslManager-Setup-0.1.0.exe.sha256

After completing the Windows checklist, commit the reviewed source, tag v0.1.0, and manually attach both release files to the matching published Forgejo release. A tag alone does not provide an updater asset. The build script does not commit, push, upload or publish. Keep build output, virtual environments and caches out of Git.

Engineering documents

Full audit · UI/UX redesign · Change summary · Release notes draft · Validation · Windows release checklist

MIT licensed; see LICENSE. Existing application artwork and authorship have been retained.