agentic-windows-bootstrap

A Claude Code skill that wipes and reinstalls Windows 11 on any target PC via a fully-automated USB build, then takes the new install over remotely on a Tailscale tailnet. ~30 minutes wall-clock; ~60 seconds physical hands-on.

Claude Code skill. Sister to optiplex-bootstrap for Ubuntu nodes — same procedural shape, different OS.

What it does

You point an LLM agent at this skill, hand it a <hostname> / <username> / <license-key> triple, and it runs the entire 8-phase pipeline for you:

1. PROBE        — USB plugged in? ISO present? Tailnet reachable?
2. SCOPE        — collect inputs from the user
3. ISO          — pull official Win 11 ISO via Microsoft's Fido.ps1
4. AUTH-KEY     — generate a Tailscale pre-auth key via CDP-driven Chrome
                  (or accept paste-in)
5. BUILD-MEDIA  — render templates -> wipe USB -> copy ISO
                  -> split install.wim -> drop autounattend + $OEM$ scripts
6. HANDOFF      — user plugs USB into target, hits boot key, walks away
7. JOIN         — poll tailnet for the new node (~25-30 min)
8. RECORD       — append to fleet credentials registry, ssh alias, smoke-test

Phases 1-5 and 7-8 are agentic. Phase 6 is the only physical step (the user plugs the USB in and selects it from the boot menu).

What it solves

• Disk wipe + clean install without sitting through Microsoft's OOBE
• No-Microsoft-account dance (HideOnlineAccountScreens in autounattend, baked-in local admin)
• Hardware-check bypass for unsupported CPUs (registry tweaks via LabConfig + truncated appraiserres.dll)
• FAT32 USB compatibility for ISOs whose install.wim exceeds 4 GB (DISM split-image into .swm chunks)
• Headless Tailscale enrollment on first boot via CDP-generated pre-auth key
• Remote takeover — once the node is on the tailnet, OpenSSH server is up and you can tailscale ssh <hostname>@<hostname> from anywhere

Repo layout

SKILL.md         — entry point (frontmatter + 8-step procedure overview)
CHECKLIST.md     — phase-by-phase walkthrough
PITFALLS.md      — 14 documented gotchas and their mitigations
recover.ps1      — standalone safety net (one-line iwr|iex from the target)
templates/
  autounattend.xml.tmpl       Setup answer file (disk wipe, account, OOBE skip)
  post-install.ps1.tmpl       First-boot: Tailscale + OpenSSH + beacon
  SetupComplete.cmd.tmpl      SYSTEM-context shim
  build-usb.ps1.tmpl          USB writer (PowerShell storage cmdlets, no diskpart)
  build-usb-runner.ps1.tmpl   UAC + zombie-cleanup wrapper, done-flag pattern
  generate-tailscale-key.py.tmpl  CDP-driven preauth generator

13 placeholders across the templates: {{HOSTNAME}}, {{USERNAME}}, {{PASSWORD_ENCODED}}, {{LICENSE_KEY}}, {{TIMEZONE}}, {{BUILD_DATE}}, {{TARGET_HW_MODEL}}, {{ISO_PATH}}, {{PROJECT_ROOT}}, {{LIFE_ROOT}}, {{USB_DISK_NUMBER}}, {{USB_MODEL_HINT}}, {{BOOT_KEY}}. The password placeholder is base64-encoded UTF-16LE of (plain-password + "Password") -- see CHECKLIST.md Phase 5 for the render snippet. (PlainText=true is documented but unreliable -- PITFALLS #12.)

Recovery (if the unattend post-install didn't fire)

If the target boots fine but C:\Windows\Setup\Scripts\ is empty / Tailscale isn't installed (the canonical PITFALLS #13 mode), don't rebuild the USB. From an elevated PowerShell on the target:

$env:TS_AUTH_KEY = 'tskey-auth-...'
iwr https://raw.githubusercontent.com/RayyanZahid/agentic-windows-bootstrap/master/recover.ps1 -UseBasicParsing | iex

Single paste, ~30 sec. Installs OpenSSH + Tailscale, joins tailnet, writes a beacon. Operator picks up via tailscale ssh <user>@<hostname>.

Install as a Claude Code skill

Clone into your Claude skills folder:

cd ~/.claude/skills/
git clone https://github.com/RayyanZahid/agentic-windows-bootstrap.git windows-bootstrap

Then in any Claude Code session: bootstrap <hostname> (or one of the other triggers in SKILL.md).

Prerequisites

Operator machine (where the USB gets built):

• Windows 10/11
• PowerShell 5.1+ (built-in)
• Admin access (UAC prompt during USB write — one click)
• ≥ 10 GB free on C: (ISO download + working space)
• USB stick ≥ 8 GB (will be wiped)
• Internet (~7-8 GB ISO download)

For headless Tailscale auth (optional — interactive fallback works without):

• A Tailscale tailnet you administer
• A CDP-instrumented Chrome, with you logged into Tailscale admin (typically Google SSO)
• A CDP helper module importable from {{LIFE_ROOT}} (the template uses from browser.cdp_capture import CDP, open_tab, find_tab_by_host — you can replace this import with any minimal CDP-over-WebSocket client)

Target PC:

• UEFI firmware, x64 CPU
• ≥ 4 GB RAM, ≥ 64 GB storage
• Boot key reachable (F12 on Dell, F9 on HP, F12 on Lenovo, F8 on ASUS, F11 on MSI)
• License key (Win 10 Pro keys activate Win 11 Pro; Win 11 Pro keys also work)

Status: alpha — known issues

The first-run validation (Dell XPS 15 9550/9560, P82G, 7th gen Intel, 2026-05-07) revealed multiple silent autounattend failure modes that prevented the unattended path from completing. Final bring-up required manual recovery via WinRE → utilman swap → built-in Administrator. The bugs and fixes are documented in PITFALLS.md (#12 through #16); v4 of the templates incorporates fallbacks that should make the unattended path actually work, but end-to-end re-validation has not been done.

Until a clean second run lands, treat this skill as "USB-burner with documented gotchas" rather than "USB-plug-and-walk-away." Every release is a hypothesis until the next bring-up confirms it.

If your bring-up works the first time, please file an issue saying so -- positive evidence is rarer than negative and worth more.

Recovery if the unattended path stalls

Both safety nets are baked into the USB by build-usb.ps1:

1. Built-in Administrator is enabled in autounattend (v4+) with a known password. If the LocalAccount creation silently fails (PITFALLS #15), you can still log in as Administrator.
2. RECOVER.cmd + recover.ps1 at the USB root. Plug the USB into the running install, double-click RECOVER.cmd, click Yes on UAC. Idempotent: installs OpenSSH (portable build), brings Tailscale up, joins tailnet, configures firewall + RDP.

Worst case (no admin, no recovery USB): WinRE → swap utilman.exe with cmd.exe → reboot → click Ease of Access at lock screen → SYSTEM cmd → enable Administrator manually. Documented in PITFALLS.md but should never be needed with v4.

How it differs from Rufus

Rufus is a great GUI tool for one-off USB builds. This skill is scripted end-to-end for use by an LLM agent or in a CI/repeatable pipeline:

• No GUI clicks. One UAC prompt total (Win 11 default secure desktop blocks UI Automation, so this is the irreducible minimum).
• autounattend.xml is rendered from a template per build (different hostname/user/key per target).
• First-boot bootstrap is baked in via $OEM$\$$\Setup\Scripts\ (Tailscale install, OpenSSH, beacon).
• Remote takeover via tailnet is the explicit endpoint.

If you want a one-off USB built by hand, use Rufus. If you want every Windows install in your fleet to come up identically and SSH-reachable on first boot, use this.

License

MIT. See LICENSE.

Contributing

Found a new pitfall on your Windows bring-up? Open an issue or PR with:

• Target PC make/model + CPU generation
• Which phase failed
• The actual error message + log excerpt
• How you worked around it

The goal is for PITFALLS.md to grow with every weird vendor / firmware / Windows version combo encountered.