Skip to main content
skill CX Codex

windows-vm — Claude Code skill: Windows 11 VM in Docker with SSH

windows-vm is a Claude Code skill for running and managing a headless Windows 11 VM in Docker over SSH. Run Windows commands directly from your agent.

MIT 285 installs ★ 441 updated 2026-06-01

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add obra/superpowers-lab --skill windows-vm -a claude-code
Open on GitHub

What windows-vm does

This skill runs Windows 11 inside a Docker container with KVM acceleration and exposes SSH on port 2222. OpenSSH Server is automatically installed during setup, so you can execute PowerShell or Bash commands via sshpass immediately. All VM data lives in $HOME/windows-vm/: the disk image, a cached Windows ISO (7.3GB, persists across recreates), and an OEM install script.

You'll need Docker, KVM support (check for /dev/kvm), and sshpass. The first run takes 20–30 minutes: the VM downloads the ISO, installs Windows 11, and runs the OEM setup script. The skill provides create (initial setup or full rebuild), start, stop, restart, ssh, and status commands. The VM is configured with 8GB RAM, 4 CPU cores, and 64GB disk; a web console at localhost:8006 offers VNC debugging if needed.

What it helps with

  • set up a Windows environment to test Windows-specific code
  • run PowerShell scripts and Windows commands from an agent without RDP
  • install and execute Windows-dependent tools like MSBuild, .NET, or MSSQL
  • access Windows files and registry via SSH
  • reuse a pre-installed VM by caching the ISO between runs

Example prompts for the agent

  • Create a new Windows VM: windows-vm create
  • Connect to the VM and install Node.js: windows-vm ssh then run a PowerShell script
  • Check VM status and SSH availability: windows-vm status

How to install windows-vm

1Skills CLI (Vercel)

npx skills add obra/superpowers-lab --skill windows-vm -a claude-code

2Manually: put the files in place

~/.claude/skills/windows-vm/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/windows-vm/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about windows-vm

How do I install windows-vm in Claude Code?

Run npx skills add obra/superpowers-lab --skill windows-vm -a claude-code. The skill will be available at ~/.claude/skills/windows-vm/SKILL.md.

What does windows-vm do?

It launches Windows 11 in a Docker container with SSH access. You can create VMs, connect to them, run PowerShell commands, and install Windows applications without opening RDP or a desktop environment.

What are the prerequisites?

Docker, KVM support (the /dev/kvm device must exist), and the sshpass utility. The first run takes ~30 minutes and requires 7.3GB to download the Windows ISO; subsequent runs use the cached image.

Source text

SKILL.md · MIT
---
name: windows-vm
description: 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.
argument-hint: "[create|start|stop|restart|ssh|status]"
allowed-tools: Bash, Read, Write
---

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

7. Clear the stale host key (new VM = new host key) and verify:
   ```bash
   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
```bash
docker start windows11
```

### stop — Stop the VM
```bash
docker stop windows11
```

### restart — Restart the VM
```bash
docker restart windows11
```

### status — Check VM status
```bash
docker ps -f name=windows11 --format "table {{.Status}}\t{{.Ports}}"
docker logs windows11 2>&1 | tail -5
```

### ssh — Connect to the VM
```bash
ssh -p 2222 user@localhost
```

### screenshot — See what's on the VM screen (for debugging)
```bash
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.

© obra · MIT · obra/superpowers-lab

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set4

Project sponsors

Companies that keep this analytics open