windows-vm

Files (1)

• SKILL.md

SKILL.md (first lines)

# Headless Windows 11 VM

Manage 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.

## 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

1. Ensure directories exist:
   ```bash
   mkdir -p "$HOME/windows-vm/oem" "$HOME/windows-vm/storage" "$HOME/windows-vm/iso"
   ```

2. Ensure `$HOME/windows-vm/oem/install.bat` exists with OpenSSH setup:
   ```bat
   @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.
   ```

3. If recreating, remove the old container and disk:
   ```bash
   docker stop windows11 && docker rm windows11
   rm -f "$HOME/windows-vm/storage/data.img"
   ```

4. Launch the container. There are two cases:

   **If cached ISO exists** (`$HOME/windows-vm/iso/win11x64.iso`):
   ```bash
   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`:
   ```bash
   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):
   ```bash
   cp "$HOME/windows-vm/storage/win11x64.iso" "$HOME/windows-vm/iso/win11x64.iso"
   ```

5. 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:
   ```bash
   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:
   ```bash
   sshpass -p 'password' ssh -o StrictHostKeyChecking=no -o ConnectTimeout=5 -p 2222 user@localhost "whoami"
   ```

6. Once SSH is responding, install Node.js and Claude Code by piping a setup script via stdin
   (avoids PowerShell escaping hell over SSH):
   ```bash
   cat << 'PS' | sshpass -p 'password' ssh -o StrictHostKeyChecking=no -p 2222 user@localhost "powershell -ExecutionPolicy Bypass -Command -"
   # Download and install Node.js silently

From obra/superpowers-lab, MIT.

More from obra/superpowers-lab