PODWIN / DOCUMENTATION
A good place to begin.
Understand the foundation before you connect. PodWin is a native Windows 11 app for WSLc container management, currently in early development.
Foundation preview, not a production release. No public installer, automatic update feed, or Microsoft Store listing is available. The repository is currently private; building from source requires repository access.
What the preview does
The current foundation supports runtime discovery, selection of existing WSLc sessions, confirmation-based connections, container and image inventories, container filtering, and bounded log snapshots.
The application uses native WinUI 3 controls, Mica, and light, dark, or system appearance. Appearance is selected per launch. Runtime operations are cancellable, time-bounded, and output-bounded; failures are surfaced rather than shown as empty inventories.
Requirements
| Component | Current baseline |
|---|---|
| Operating system | Windows 11 22H2 or later. |
| Container runtime | WSLc 3.0.3 or later, installed at the standard Microsoft WSL location. This is the initial reviewed output/schema baseline, not a claim that every feature requires this version. |
| Development SDK | .NET SDK 10.0.403, pinned by the repository's global.json. Use the pin in your checked-out revision if it changes. |
| Architecture | x64 is the first qualification target. CI cross-compiles ARM64; native ARM64 release acceptance remains a gate. |
A detected CLI does not prove that the WSL components or an existing session are healthy. PodWin can still be used for dependency diagnosis without a session.
Build from source
With access to the project repository, clone it and run these commands in a Windows PowerShell terminal. The app is self-contained when published; the SDK requirement here is for development.
git clone https://github.com/swigerb/PodWin.git
cd PodWin
dotnet test tests\PodWin.Core.Tests\PodWin.Core.Tests.csproj
dotnet build src\PodWin.App\PodWin.App.csproj
& .\src\PodWin.App\bin\Debug\net10.0-windows10.0.26100.0\win-x64\PodWin.exeThe project uses public nuget.org packages. No Visual Studio extension is required. If a restore fails, see the repository README for supported troubleshooting; never disable TLS verification.
Your first connection
- Discover. Open PodWin and discover existing WSLc sessions. Discovery does not create a session or change global WSL settings.
- Select. Choose the exact existing session you want to inspect. PodWin does not silently fall back to a default session.
- Confirm. Review the connection prompt. Reading inventory can activate an idle session's VM, so connecting is a deliberate action.
- Inspect. Read the container or image inventory. Filter containers by name or image, or select a container to view a bounded log snapshot.
Logs can contain secrets. Review all log content before copying, sharing, or attaching it to an issue. A bounded snapshot is not a continuous log stream.
Scope and limitations
PodWin connects to WSLc, not the Docker Engine socket. Existing Docker Desktop containers will not appear in PodWin.
| Available in the foundation | Not implemented yet |
|---|---|
| Discover and select existing sessions | Create and manage session lifetimes |
| Read container and image inventories | Pull images; create, start, stop, restart, or remove containers |
| Filter containers and read bounded logs | Streaming logs, terminal access, and resource metrics |
| Read-only, explicit-session workflows | Volumes, networks, registry login, and image build/push workflows |
| Compose compatibility intent shown in the app | Compose file parsing, validation, planning, and execution |
The Compose page describes a future contract; it does not load or run Compose files. Kubernetes, Docker API compatibility, and full Docker Compose parity are not promised.
Troubleshooting
WSLc is missing or discovery fails
Check that the required WSLc runtime is installed at the standard Microsoft WSL location. PodWin does not install it for you. Follow the official WSL container guidance and use the exact diagnostic shown in the app.
No sessions or containers are listed
Discovery lists existing WSLc sessions only. This preview does not create them. Connect to the intended session explicitly before reading its inventory, and do not expect Docker Desktop containers to appear. A reported error is a failed read, not evidence that the session is empty.
A read is canceled, times out, or reaches its output limit
The process boundary deliberately caps execution time and output. Read the surfaced error and retry only when appropriate. Do not interpret a canceled or truncated operation as a complete inventory.
Privacy and your environment
The current PodWin foundation does not send app telemetry, retain container logs, store registry credentials, poll in the background, automatically install runtimes, or change global WSL configuration. WSLc is a separate Microsoft runtime with its own data handling.
This website has no analytics, advertising, tracking cookies, third-party fonts, or embedded third-party scripts. The theme control operates in the current page and URL; it does not store a tracking identifier. GitHub Pages serves the site and may process request information under GitHub's privacy statement. Links to GitHub and other resources take you to those providers.
This describes current behavior, not a legal policy for an unreleased future installer or Store package. A distribution privacy policy remains a release gate.
Distribution and licensing
PodWin is intended to be free to use. Its repository is currently private, and no source-code license has been selected. Do not assume an MIT license or an open-source redistribution grant.
The direct distribution design uses a per-user, self-contained Velopack installer. Startup hooks exist, but no update feed is configured and automatic apply-on-startup is disabled. Code signing and public binary release acceptance are still required.
A separate Microsoft Store MSIX channel is planned. It would exclude Velopack and use Store-managed updates. No Store identity, listing, or certification is implied.
Project and resources
- Public website source and website corrections and feedback. This repository contains the site only, not the application source.
- PodWin on GitHub and issue tracker (currently restricted to repository collaborators).
- Microsoft WSL container documentation and WSL developer documentation.
- WinUI 3, Fluent 2, and Velopack.
PodWin is an original implementation, inspired in part by Zack Way's WSLc Desktop Manager, Docker Desktop, and Podman Desktop. It does not copy their application code, branding, or assets.