qwin

Windows Server Core in a container — zero-touch install, KVM-accelerated, ready to SSH in minutes.

What’s included

Out of the box, the VM comes pre-configured with:

• undefinedOpenSSH Server — SSH into the VM from your terminal or attach a VS Code remote session
• undefinedDev-ready — Git, Node.js LTS, and Corepack pre-installed so you can git clone and start coding inside it
• undefinedInstant revert — qcow2 overlay snapshotting: ./run.sh --reset reverts the VM to its post-install state in seconds
• undefinedLean image — Defender removed, firewall disabled, WinSxS cleaned, free space zeroed for qcow2 compaction
• undefinedVirtIO guest tools — optimized storage/network drivers and memory ballooning
• undefinedVirtIO-FS — shared host directory mounted as Z:\ in the guest (via WinFsp)
• undefinedTotal Commander — file manager, launches at logon
• undefinedSerial console (EMS) — for headless debugging
• undefinednoVNC web console — browser-based VNC viewer, auto-opens during build

Prerequisites

undefinedNote: Linux is the primary and well-tested platform. macOS support is experimental and unstable — expect slower builds (no KVM) and missing features (no VirtIO-FS shared directories).

Linux

• undefinedQEMU (for host builds) or Docker (for containerized builds) — build.sh auto-detects which is available
• undefinedKVM strongly recommended
• genisoimage — for generating the answer ISO
• virtiofsd — for shared directory support (VirtIO-FS)

# Debian/Ubuntu
sudo apt install qemu-system-x86 genisoimage virtiofsd

# Fedora
sudo dnf install qemu-system-x86-core genisoimage virtiofsd

# Arch
sudo pacman -S qemu-system-x86 cdrtools virtiofsd

macOS

• undefinedQEMU and cdrtools (provides mkisofs for ISO generation)
• No KVM — macOS uses software emulation (TCG), so expect slower installs
• VirtIO-FS shared directories are not available (virtiofsd is Linux-only)

brew install qemu cdrtools

Quick Start

1. undefinedCreate .env with your Windows ISO URL:undefined

cp .env.example .env
# Edit .env — set WIN_ISO_URL to a Windows Server ISO (URL or local path)
# Get a free evaluation ISO from https://www.microsoft.com/en-us/evalcenter/evaluate-windows-server

2. undefinedBuild and run:undefined

./build.sh

This auto-detects the best build method: if QEMU is installed locally, it runs directly on the host; otherwise it builds and runs a Docker container. KVM is used when available (/dev/kvm), otherwise falls back to software emulation.

You can force a specific mode:

./build.sh --host    # Force host QEMU build
./build.sh --docker  # Force Docker build

3. undefinedConnect once installation completes:undefined
   • undefinedVNC: localhost:5900 (macOS opens Screen Sharing automatically; Linux uses vncviewer)
   • undefinedWeb console: http://localhost:16080 (Linux with noVNC installed)
   • undefinedSSH: ssh administrator@localhost -p 2222
   • undefinedRDP: localhost:13389

All ports are bound to 127.0.0.1 (localhost only).

Configuration

All settings are in .env (see .env.example):

Variable	Default	Description
WIN_ISO_URL	(required)	Windows ISO URL or local file path
WIN_ISO_SHA256	(empty)	SHA256 checksum for ISO verification
WIN_PRODUCT_KEY	(empty)	Product key (eval key used if empty)
WIN_ADMIN_PASSWORD	P@ssw0rd!	Administrator password
WIN_HOSTNAME	WINCORE	VM hostname
WIN_TIMEZONE	UTC	Windows timezone
DISK_SIZE	60G	Virtual disk size
RAM_MB	4096	VM RAM in MB
CPU_CORES	2	VM CPU cores
VNC_DISPLAY	:0	VNC display number
HOST_RDP_PORT	13389	Host port for RDP
HOST_SSH_PORT	2222	Host port for SSH
HOST_NOVNC_PORT	16080	Host port for noVNC web console
SHARED_DIR	./shared	Host directory shared into guest as Z:\
SSH_PUBKEY	(empty)	Path to SSH public key for passwordless login

Shared Directory (Linux only)

The shared/ directory on the host is mounted as Z:\ inside the guest via VirtIO-FS — no network or SCP needed to pass files in and out. Just drop files into ./shared/ and they appear instantly at Z:\ in the VM.

echo "hello from host" > shared/test.txt
ssh administrator@localhost -p 2222 "type Z:\test.txt"

Set SHARED_DIR in .env to change the host path.

undefinedNote: VirtIO-FS requires virtiofsd, which is Linux-only. On macOS, shared directories are not available — use SCP or RDP file transfer instead.

Persistence & Snapshots

After a fresh install, the build automatically creates a qcow2 overlay on top of the base disk. All runtime changes go to the overlay while the base image stays pristine.

# Quick-start the VM (boots from overlay)
./run.sh

# Discard all changes and revert to post-install state
./run.sh --reset

The overlay is a thin qcow2 file backed by the base disk — creating or resetting it is instant.

The images/ directory holds the virtual disk, overlay, and downloaded ISOs. In Docker mode, it’s automatically volume-mounted so artifacts persist across container restarts.

Rebuilding

To force a clean reinstall (wipes base disk + overlay):

./build.sh --clean

This wipes the virtual disk, overlay, and regenerated config, but preserves downloaded ISOs. Can be combined with --host/--docker.

Performance Optimizations

The build is tuned for fast installation:

• undefinedVirtIO disk with cache=unsafe and aio=io_uring (Linux) / aio=threads (macOS) — dramatically faster I/O than IDE during Windows file extraction
• undefinedVirtIO storage drivers loaded during windowsPE pass via the VirtIO ISO
• undefinedWindows Recovery disabled — reagentc /disable during specialize skips RE partition
• undefinedUnnecessary services disabled — Windows Search, SysMain, Windows Update, telemetry, MSDTC, IPsec
• undefinedWindows Defender fully removed — saves ~137 MB RAM and ~90 MB disk (realtime disabled during install for speed)
• undefinedWinSxS component store cleaned with /ResetBase — reclaims ~1.3 GB
• undefinedIME dictionaries removed — Japanese/Chinese input not needed headless
• undefinedVirtIO-FS with virtiofsd (Linux only) — near-native shared filesystem via vhost-user-fs-pci and shared memory (memfd)
• undefinedVirtIO serial — fast guest-host communication channel
• undefinedChocolatey package manager — reliable on Server Core (winget requires App Installer/Store framework which is unavailable)
• undefinedWinFsp — enables VirtIO-FS filesystem mount (virtiofs.exe requires WinFsp DLL)

Monitoring

During installation you can watch progress via the noVNC web console (opens automatically) or any VNC client on port 5900. The post-install steps show status in the PowerShell window title (e.g. [3/12] Installing OpenSSH Server). Detailed logs are written to C:\setup.log inside the VM.