Headless Windows 11 VM
Manage a headless Windows 11 VM running via dockur/windows in Docker with KVM acceleration. The VM is accessible via SSH only — no RDP or GUI required.
Host prerequisites
- Docker
- KVM support (
/dev/kvm must exist — check with ls /dev/kvm)
sshpass (sudo apt install sshpass)
imagemagick (optional, for screenshot debugging: sudo apt install imagemagick)
Configuration
- Container name:
windows11
- VM directory:
$HOME/windows-vm/
storage/ — VM disk image (managed by dockur, wiped on recreate)
iso/win11x64.iso — cached Windows ISO (7.3GB, persists across recreates)
oem/install.bat — post-install script (installs OpenSSH Server)
- Credentials: user / password
- SSH:
localhost:2222 (bound to 127.0.0.1 only)
- RDP:
localhost:3389 (bound to 127.0.0.1 only, fallback)
- Web console:
localhost:8006 (VNC in browser, for debugging)
- Resources: 8GB RAM, 4 CPU cores, 64GB disk
Actions
create — First-time setup or full recreate
Ensure directories exist:
mkdir -p "$HOME/windows-vm/oem" "$HOME/windows-vm/storage" "$HOME/windows-vm/iso"
Ensure $HOME/windows-vm/oem/install.bat exists with OpenSSH setup:
@echo off
echo Installing OpenSSH Server...
powershell -Command "Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0" 2>nul
powershell -Command "Get-WindowsCapability -Online -Name OpenSSH.Server* | Add-WindowsCapability -Online" 2>nul
dism /Online /Add-Capability /CapabilityName:OpenSSH.Server~~~~0.0.1.0 2>nul
powershell -Command "Start-Service sshd" 2>nul
powershell -Command "Set-Service -Name sshd -StartupType Automatic"
powershell -Command "New-ItemProperty -Path 'HKLM:\SOFTWARE\OpenSSH' -Name DefaultShell -Value 'C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe' -PropertyType String -Force"
powershell -Command "New-NetFirewallRule -Name 'OpenSSH-Server' -DisplayName 'OpenSSH Server' -Enabled True -Direction Inbound -Protocol TCP -Action Allow -LocalPort 22"
powershell -Command "Get-Service sshd" 2>nul
echo Done.
If recreating, remove the old container and disk:
docker stop windows11 && docker rm windows11
rm -f "$HOME/windows-vm/storage/data.img"
Launch the container. There are two cases:
If cached ISO exists ($HOME/windows-vm/iso/win11x64.iso):
docker run -d \
--name windows11 \
-p 127.0.0.1:3389:3389 \
-p 127.0.0.1:2222:22 \
-p 127.0.0.1:8006:8006 \
-e RAM_SIZE="8G" \
-e CPU_CORES="4" \
-e DISK_SIZE="64G" \
-e USERNAME="user" \
-e PASSWORD="password" \
--cap-add NET_ADMIN \
--device /dev/kvm \
-v "$HOME/windows-vm/storage:/storage" \
-v "$HOME/windows-vm/oem:/oem" \
-v "$HOME/windows-vm/iso/win11x64.iso:/boot.iso" \
dockurr/windows
First time (no cached ISO) — omit the /boot.iso mount and add VERSION:
docker run -d \
--name windows11 \
-p 127.0.0.1:3389:3389 \
-p 127.0.0.1:2222:22 \
-p 127.0.0.1:8006:8006 \
-e RAM_SIZE="8G" \
-e CPU_CORES="4" \
-e DISK_SIZE="64G" \
-e VERSION="win11" \
-e USERNAME="user" \
-e PASSWORD="password" \
--cap-add NET_ADMIN \
--device /dev/kvm \
-v "$HOME/windows-vm/storage:/storage" \
-v "$HOME/windows-vm/oem:/oem" \
dockurr/windows
After the ISO downloads and Windows boots, immediately copy the ISO out before
the container is ever stopped (dockur wipes /storage on recreate):
cp "$HOME/windows-vm/storage/win11x64.iso" "$HOME/windows-vm/iso/win11x64.iso"
Wait for Windows install + OpenSSH setup to complete. This takes 20-30 minutes for a
fresh install (the OEM install.bat runs at the end of Windows OOBE and downloads OpenSSH
from Microsoft, which is slow). Monitor with:
docker logs -f windows11
You can also watch the VM screen via the web console at http://localhost:8006.
To check if SSH is up:
sshpass -p 'password' ssh -o StrictHostKeyChecking=no -o ConnectTimeout=5 -p 2222 user@localhost "whoami"
Once SSH is responding, install Node.js and Claude Code by piping a setup script via stdin
(avoids PowerShell escaping hell over SSH):
cat << 'PS' | sshpass -p 'password' ssh -o StrictHostKeyChecking=no -p 2222 user@localhost "powershell -ExecutionPolicy Bypass -Command -"
# Download and install Node.js silently
Invoke-WebRequest -Uri 'https://nodejs.org/dist/v22.14.0/node-v22.14.0-x64.msi' -OutFile 'C:\Users\user\node-install.msi'
Start-Process msiexec.exe -ArgumentList '/i C:\Users\user\node-install.msi /qn /norestart' -Wait -Verb RunAs
Write-Host "Node.js installed"
# Install Claude Code globally
& 'C:\Program Files\nodejs\npm.cmd' install -g @anthropic-ai/claude-code
Write-Host "Claude Code installed"
# Add npm global bin to SYSTEM PATH (user PATH is not read by sshd)
$systemPath = [Environment]::GetEnvironmentVariable('Path', 'Machine')
$additions = @()
if ($systemPath -notlike '*AppData*npm*') { $additions += 'C:\Users\user\AppData\Roaming\npm' }
if ($systemPath -notlike '*Git\cmd*') { $additions += 'C:\Program Files\Git\cmd' }
if ($additions.Count -gt 0) {
[Environment]::SetEnvironmentVariable('Path', $systemPath + ';' + ($additions -join ';'), 'Machine')
Write-Host "Added to system PATH: $($additions -join ', ')"
}
# Set execution policy machine-wide (required for claude.ps1)
Set-ExecutionPolicy RemoteSigned -Scope LocalMachine -Force -ErrorAction SilentlyContinue
# Create system-wide PowerShell profile that rebuilds PATH from registry on login.
# Without this, interactive SSH sessions don't pick up the full system PATH.
$profileDir = Split-Path $PROFILE.AllUsersAllHosts
if (-not (Test-Path $profileDir)) { New-Item -ItemType Directory -Path $profileDir -Force }
@'
$machinePath = [Environment]::GetEnvironmentVariable('Path', 'Machine')
$userPath = [Environment]::GetEnvironmentVariable('Path', 'User')
$env:Path = "$machinePath;$userPath"
'@ | Set-Content -Path $PROFILE.AllUsersAllHosts -Force
Write-Host "PowerShell profile created"
# Restart sshd so it picks up the new PATH
Restart-Service sshd -Force
PS
Note: the connection will drop when sshd restarts — that's expected.
Clear the stale host key (new VM = new host key) and verify:
ssh-keygen -f ~/.ssh/known_hosts -R '[localhost]:2222'
sshpass -p 'password' ssh -o StrictHostKeyChecking=no -p 2222 user@localhost "claude --version"
start — Start a stopped VM
docker start windows11
stop — Stop the VM
docker stop windows11
restart — Restart the VM
docker restart windows11
status — Check VM status
docker ps -f name=windows11 --format "table {{.Status}}\t{{.Ports}}"
docker logs windows11 2>&1 | tail -5
ssh — Connect to the VM
ssh -p 2222 user@localhost
screenshot — See what's on the VM screen (for debugging)
docker exec windows11 bash -c "echo 'screendump /tmp/screen.ppm' | nc -w 2 localhost 7100" > /dev/null 2>&1
sleep 1
docker cp windows11:/tmp/screen.ppm /tmp/screen.ppm
convert /tmp/screen.ppm /tmp/screen.png
Important Notes
- ISO caching: The
/storage volume is managed by dockur and gets wiped on recreate. Store the ISO separately in $HOME/windows-vm/iso/ and mount it as /boot.iso to skip the 7.3GB download.
--cap-add NET_ADMIN is required for port forwarding to work. Without it, QEMU falls back to user-mode networking and port forwarding silently fails.
--device /dev/kvm is required for hardware acceleration.
- Boot time: Fresh install takes 20-30 min (Windows install + OpenSSH download from Microsoft). Subsequent boots from existing
data.img are fast (~2 min).
- Ports are bound to
127.0.0.1 only — not exposed to the network.
- Do NOT use
-e VERSION="win11" when mounting /boot.iso — the version is auto-detected from the ISO.
Post-install gotchas
- Node.js is not pre-installed — the Claude Code install script (
irm https://claude.ai/install.ps1 | iex) will report success but claude won't work without Node. Install Node.js via MSI first.
- npm global bin not in PATH — Node's MSI adds
C:\Program Files\nodejs to PATH but not C:\Users\user\AppData\Roaming\npm (where npm install -g puts binaries). Must add it to the system PATH (not user PATH) because OpenSSH's sshd only reads system PATH. After changing system PATH, restart sshd.
- PowerShell execution policy — Default policy is
Restricted, which blocks claude.ps1. Must set to RemoteSigned at LocalMachine scope (not CurrentUser) for it to take effect in SSH sessions.
- Escaping hell — Running PowerShell commands over SSH with nested quotes is unreliable. Pipe scripts via stdin using
powershell -ExecutionPolicy Bypass -Command - instead.
- Interactive SSH sessions don't get full PATH — Windows OpenSSH sshd doesn't properly propagate the system PATH to interactive PowerShell sessions. Fix: create a system-wide PowerShell profile (
$PROFILE.AllUsersAllHosts) that rebuilds $env:Path from the registry on every login.
- winget may not work — The Microsoft Store certificate can fail in a VM. Use direct MSI/installer downloads instead.
- Host key changes — Each recreated VM gets new SSH host keys. Run
ssh-keygen -R '[localhost]:2222' to clear the old one.
1---
2name: windows-vm
3description: Create, manage, or connect to a headless Windows 11 VM running in Docker with SSH access. Use when the user wants to spin up, stop, restart, or SSH into a Windows VM.
4argument-hint: "[create|start|stop|restart|ssh|status]"
5allowed-tools: Bash, Read, Write
6metadata:
7 source: https://skillmd.com/skills/obra/windows-vm
8---
9
10# Headless Windows 11 VM
11
12Manage a headless Windows 11 VM running via [dockur/windows](https://github.com/dockur/windows) in Docker with KVM acceleration. The VM is accessible via SSH only — no RDP or GUI required.
13
14## Host prerequisites
15
16- Docker
17- KVM support (`/dev/kvm` must exist — check with `ls /dev/kvm`)
18- `sshpass` (`sudo apt install sshpass`)
19- `imagemagick` (optional, for screenshot debugging: `sudo apt install imagemagick`)
20
21## Configuration
22
23- **Container name**: `windows11`
24- **VM directory**: `$HOME/windows-vm/`
25 - `storage/` — VM disk image (managed by dockur, wiped on recreate)
26 - `iso/win11x64.iso` — cached Windows ISO (7.3GB, persists across recreates)
27 - `oem/install.bat` — post-install script (installs OpenSSH Server)
28- **Credentials**: user / password
29- **SSH**: `localhost:2222` (bound to 127.0.0.1 only)
30- **RDP**: `localhost:3389` (bound to 127.0.0.1 only, fallback)
31- **Web console**: `localhost:8006` (VNC in browser, for debugging)
32- **Resources**: 8GB RAM, 4 CPU cores, 64GB disk
33
34## Actions
35
36### create — First-time setup or full recreate
37
381. Ensure directories exist:
39 ```bash
40 mkdir -p "$HOME/windows-vm/oem" "$HOME/windows-vm/storage" "$HOME/windows-vm/iso"
41 ```
42
432. Ensure `$HOME/windows-vm/oem/install.bat` exists with OpenSSH setup:
44 ```bat
45 @echo off
46 echo Installing OpenSSH Server...
47 powershell -Command "Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0" 2>nul
48 powershell -Command "Get-WindowsCapability -Online -Name OpenSSH.Server* | Add-WindowsCapability -Online" 2>nul
49 dism /Online /Add-Capability /CapabilityName:OpenSSH.Server~~~~0.0.1.0 2>nul
50 powershell -Command "Start-Service sshd" 2>nul
51 powershell -Command "Set-Service -Name sshd -StartupType Automatic"
52 powershell -Command "New-ItemProperty -Path 'HKLM:\SOFTWARE\OpenSSH' -Name DefaultShell -Value 'C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe' -PropertyType String -Force"
53 powershell -Command "New-NetFirewallRule -Name 'OpenSSH-Server' -DisplayName 'OpenSSH Server' -Enabled True -Direction Inbound -Protocol TCP -Action Allow -LocalPort 22"
54 powershell -Command "Get-Service sshd" 2>nul
55 echo Done.
56 ```
57
583. If recreating, remove the old container and disk:
59 ```bash
60 docker stop windows11 && docker rm windows11
61 rm -f "$HOME/windows-vm/storage/data.img"
62 ```
63
644. Launch the container. There are two cases:
65
66 **If cached ISO exists** (`$HOME/windows-vm/iso/win11x64.iso`):
67 ```bash
68 docker run -d \
69 --name windows11 \
70 -p 127.0.0.1:3389:3389 \
71 -p 127.0.0.1:2222:22 \
72 -p 127.0.0.1:8006:8006 \
73 -e RAM_SIZE="8G" \
74 -e CPU_CORES="4" \
75 -e DISK_SIZE="64G" \
76 -e USERNAME="user" \
77 -e PASSWORD="password" \
78 --cap-add NET_ADMIN \
79 --device /dev/kvm \
80 -v "$HOME/windows-vm/storage:/storage" \
81 -v "$HOME/windows-vm/oem:/oem" \
82 -v "$HOME/windows-vm/iso/win11x64.iso:/boot.iso" \
83 dockurr/windows
84 ```
85
86 **First time (no cached ISO)** — omit the `/boot.iso` mount and add `VERSION`:
87 ```bash
88 docker run -d \
89 --name windows11 \
90 -p 127.0.0.1:3389:3389 \
91 -p 127.0.0.1:2222:22 \
92 -p 127.0.0.1:8006:8006 \
93 -e RAM_SIZE="8G" \
94 -e CPU_CORES="4" \
95 -e DISK_SIZE="64G" \
96 -e VERSION="win11" \
97 -e USERNAME="user" \
98 -e PASSWORD="password" \
99 --cap-add NET_ADMIN \
100 --device /dev/kvm \
101 -v "$HOME/windows-vm/storage:/storage" \
102 -v "$HOME/windows-vm/oem:/oem" \
103 dockurr/windows
104 ```
105 After the ISO downloads and Windows boots, **immediately** copy the ISO out before
106 the container is ever stopped (dockur wipes `/storage` on recreate):
107 ```bash
108 cp "$HOME/windows-vm/storage/win11x64.iso" "$HOME/windows-vm/iso/win11x64.iso"
109 ```
110
1115. Wait for Windows install + OpenSSH setup to complete. This takes **20-30 minutes** for a
112 fresh install (the OEM install.bat runs at the end of Windows OOBE and downloads OpenSSH
113 from Microsoft, which is slow). Monitor with:
114 ```bash
115 docker logs -f windows11
116 ```
117 You can also watch the VM screen via the web console at `http://localhost:8006`.
118
119 To check if SSH is up:
120 ```bash
121 sshpass -p 'password' ssh -o StrictHostKeyChecking=no -o ConnectTimeout=5 -p 2222 user@localhost "whoami"
122 ```
123
1246. Once SSH is responding, install Node.js and Claude Code by piping a setup script via stdin
125 (avoids PowerShell escaping hell over SSH):
126 ```bash
127 cat << 'PS' | sshpass -p 'password' ssh -o StrictHostKeyChecking=no -p 2222 user@localhost "powershell -ExecutionPolicy Bypass -Command -"
128 # Download and install Node.js silently
129 Invoke-WebRequest -Uri 'https://nodejs.org/dist/v22.14.0/node-v22.14.0-x64.msi' -OutFile 'C:\Users\user\node-install.msi'
130 Start-Process msiexec.exe -ArgumentList '/i C:\Users\user\node-install.msi /qn /norestart' -Wait -Verb RunAs
131 Write-Host "Node.js installed"
132
133 # Install Claude Code globally
134 & 'C:\Program Files\nodejs\npm.cmd' install -g @anthropic-ai/claude-code
135 Write-Host "Claude Code installed"
136
137 # Add npm global bin to SYSTEM PATH (user PATH is not read by sshd)
138 $systemPath = [Environment]::GetEnvironmentVariable('Path', 'Machine')
139 $additions = @()
140 if ($systemPath -notlike '*AppData*npm*') { $additions += 'C:\Users\user\AppData\Roaming\npm' }
141 if ($systemPath -notlike '*Git\cmd*') { $additions += 'C:\Program Files\Git\cmd' }
142 if ($additions.Count -gt 0) {
143 [Environment]::SetEnvironmentVariable('Path', $systemPath + ';' + ($additions -join ';'), 'Machine')
144 Write-Host "Added to system PATH: $($additions -join ', ')"
145 }
146
147 # Set execution policy machine-wide (required for claude.ps1)
148 Set-ExecutionPolicy RemoteSigned -Scope LocalMachine -Force -ErrorAction SilentlyContinue
149
150 # Create system-wide PowerShell profile that rebuilds PATH from registry on login.
151 # Without this, interactive SSH sessions don't pick up the full system PATH.
152 $profileDir = Split-Path $PROFILE.AllUsersAllHosts
153 if (-not (Test-Path $profileDir)) { New-Item -ItemType Directory -Path $profileDir -Force }
154 @'
155 $machinePath = [Environment]::GetEnvironmentVariable('Path', 'Machine')
156 $userPath = [Environment]::GetEnvironmentVariable('Path', 'User')
157 $env:Path = "$machinePath;$userPath"
158 '@ | Set-Content -Path $PROFILE.AllUsersAllHosts -Force
159 Write-Host "PowerShell profile created"
160
161 # Restart sshd so it picks up the new PATH
162 Restart-Service sshd -Force
163 PS
164 ```
165 Note: the connection will drop when sshd restarts — that's expected.
166
1677. Clear the stale host key (new VM = new host key) and verify:
168 ```bash
169 ssh-keygen -f ~/.ssh/known_hosts -R '[localhost]:2222'
170 sshpass -p 'password' ssh -o StrictHostKeyChecking=no -p 2222 user@localhost "claude --version"
171 ```
172
173### start — Start a stopped VM
174```bash
175docker start windows11
176```
177
178### stop — Stop the VM
179```bash
180docker stop windows11
181```
182
183### restart — Restart the VM
184```bash
185docker restart windows11
186```
187
188### status — Check VM status
189```bash
190docker ps -f name=windows11 --format "table {{.Status}}\t{{.Ports}}"
191docker logs windows11 2>&1 | tail -5
192```
193
194### ssh — Connect to the VM
195```bash
196ssh -p 2222 user@localhost
197```
198
199### screenshot — See what's on the VM screen (for debugging)
200```bash
201docker exec windows11 bash -c "echo 'screendump /tmp/screen.ppm' | nc -w 2 localhost 7100" > /dev/null 2>&1
202sleep 1
203docker cp windows11:/tmp/screen.ppm /tmp/screen.ppm
204convert /tmp/screen.ppm /tmp/screen.png
205```
206
207## Important Notes
208
209- **ISO caching**: The `/storage` volume is managed by dockur and gets wiped on recreate. Store the ISO separately in `$HOME/windows-vm/iso/` and mount it as `/boot.iso` to skip the 7.3GB download.
210- **`--cap-add NET_ADMIN`** is required for port forwarding to work. Without it, QEMU falls back to user-mode networking and port forwarding silently fails.
211- **`--device /dev/kvm`** is required for hardware acceleration.
212- **Boot time**: Fresh install takes 20-30 min (Windows install + OpenSSH download from Microsoft). Subsequent boots from existing `data.img` are fast (~2 min).
213- Ports are bound to `127.0.0.1` only — not exposed to the network.
214- Do NOT use `-e VERSION="win11"` when mounting `/boot.iso` — the version is auto-detected from the ISO.
215
216## Post-install gotchas
217
218- **Node.js is not pre-installed** — the Claude Code install script (`irm https://claude.ai/install.ps1 | iex`) will report success but `claude` won't work without Node. Install Node.js via MSI first.
219- **npm global bin not in PATH** — Node's MSI adds `C:\Program Files\nodejs` to PATH but not `C:\Users\user\AppData\Roaming\npm` (where `npm install -g` puts binaries). Must add it to the **system** PATH (not user PATH) because OpenSSH's sshd only reads system PATH. After changing system PATH, restart sshd.
220- **PowerShell execution policy** — Default policy is `Restricted`, which blocks `claude.ps1`. Must set to `RemoteSigned` at **LocalMachine** scope (not CurrentUser) for it to take effect in SSH sessions.
221- **Escaping hell** — Running PowerShell commands over SSH with nested quotes is unreliable. Pipe scripts via stdin using `powershell -ExecutionPolicy Bypass -Command -` instead.
222- **Interactive SSH sessions don't get full PATH** — Windows OpenSSH sshd doesn't properly propagate the system PATH to interactive PowerShell sessions. Fix: create a system-wide PowerShell profile (`$PROFILE.AllUsersAllHosts`) that rebuilds `$env:Path` from the registry on every login.
223- **winget may not work** — The Microsoft Store certificate can fail in a VM. Use direct MSI/installer downloads instead.
224- **Host key changes** — Each recreated VM gets new SSH host keys. Run `ssh-keygen -R '[localhost]:2222'` to clear the old one.