A small, daemonless command line tool for running Windows containers, built
directly on the Host Compute Service (HCS) APIs. No Docker, no containerd,
no background service of its own: a single executable that talks to
vmcompute the same way hcsshim does.
Status: early work in progress. Process-isolated containers run in the foreground or background, with NAT networking and published ports.
-
Windows 11 or Windows Server with the Containers optional feature enabled (and a reboot afterwards):
Enable-WindowsOptionalFeature -Online -FeatureName Containers -All
vmcompute,wcifsandbindfltalso ship with Hyper-V / WSL, so their presence does not prove the feature is on. Without it, creating a container fails withThe request is not supported (0x80070032). -
An elevated terminal. Layer import needs
SeBackupPrivilege/SeRestorePrivilege, and HCS requires administrator rights. Windows' built-insudoin inline mode works. -
If Defender's Controlled Folder Access is on, allow
winner.exe: layer processing writes directly to mounted VHDs and is otherwise blocked (surfacing asAccess is denied). -
Process isolation requires the image build to be compatible with the host (for example
ltsc2025/ 26100 on Windows 11 24H2+). Other images run with Hyper-V isolation, which needs the Hyper-V feature as well (Microsoft-Hyper-V) and an image no newer than the host.
winner image pull mcr.microsoft.com/windows/nanoserver:ltsc2025
winner run --remove mcr.microsoft.com/windows/nanoserver:ltsc2025 cmd /c ver
# background containers
winner run -d --name demo -v C:\data:C:\data mcr.microsoft.com/windows/nanoserver:ltsc2025 ping -t 127.0.0.1
winner logs --follow demo
winner exec demo cmd /c dir C:\data
winner stop demo
winner start demo
winner delete --force demo
# networking
winner run -d --name web -p 8080:8080 mcr.microsoft.com/dotnet/samples:aspnetapp-nanoserver-ltsc2025
curl http://localhost:8080/
winner network create --subnet 172.30.0.0/24 backend
winner run --remove --network backend nanoserver:ltsc2025 ipconfig
winner network list
winner system prune
winner create --name later nanoserver:ltsc2025 cmd /c echo hi
winner start later
winner list
winner inspect later
winner image listContainer operations live at the top level; other resources are grouped as
<noun> <verb> (image pull, image list, ...). ls and rm are accepted
as aliases for list and delete. A tty is detected automatically;
--tty / --no-tty override it.
- Without a command,
runuses the image's entrypoint and command;--entrypointreplaces the entrypoint. The image's environment, working directory and user apply unless--env,--workdiror--useroverride them. run --detachandstartrun the container in the background under a small supervisor process (winner shim); its output goes to the log thatlogsprints.stopasks the container to shut down and terminates it after--timeoutseconds;killterminates it at once.exec,stopandkillwork on foreground containers too.--volume HOST:CONTAINER[:ro]maps a host directory, e.g.-v C:\data:C:\data:ro. Host ACLs still apply: the image's defaultContainerUsercannot read a directory only your account may access; grant access or run with-u ContainerAdministrator.- Isolation is picked automatically: process isolation when the image build
is compatible with the host, Hyper-V otherwise.
--isolation hypervforces a utility VM (slower to start, own kernel); it does not support--network host. runpulls a missing image itself (--pull missing|always|never).- Image references must name the registry; there is no implicit Docker Hub.
Once pulled, a short form such as
nanoserver:ltsc2025finds the local image. - Containers are addressed by ID, a unique ID prefix, or
--name.deletetakes several at once and refuses running containers unless--force. image deletealso removes layers no image or container uses anymore.- Containers join the
winnerNAT network, created on first use (and again after a reboot, since NAT networks do not persist).--network NAMEpicks another network,--network noneruns without one, and--network hostshares the host's network stack (no isolation of ports or adapters). --publish HOST:CONTAINER[/udp](-p) maps a host port; it is reachable onlocalhostand the host's addresses.inspectshows a running container's IP address.- With a tty, resizing the terminal window resizes the container's console.
system prunedeletes containers that are not running, networks winner created that no container needs anymore, unused layers and leftovers of interrupted operations, and reports the space reclaimed.--allalso deletes images no container uses. It asks first;--forceskips that.network create|list|inspect|deletemanages NAT networks.network listalso shows networks of other tools (such asDefault Switch); only networks winner created can be deleted.listandimage listprint tables; pass--format jsonfor scripts.runandexecexit with the process's exit code, or 125 if winner itself fails.
Data is stored under %ProgramData%\winner.
cargo build --releaseThe release binary is a single ~7 MB executable with no runtime dependencies.
End-to-end tests need elevation; run the whole suite under one prompt:
sudo pwsh -NoProfile -File scripts/e2e.ps1 # add -Full for image deletion testsResults are also written to target\e2e.log.
- Registry pull with Windows platform selection
- Base layer import
- Scratch layer create / mount (process isolation)
- Run a process-isolated container in the foreground
- Non-base layer import
- Detached containers, logs, exec, stop / kill
- Networking (HCN): NAT, published ports, host and none modes
- Console resize forwarding,
system prune - Hyper-V isolation (HCS v1, utility VM managed by vmcompute)
See docs/development.md for design notes.