feat: add Hyper-V provider for local Windows VMs

[anagnorisis2peripeteia]

Summary

A hyperv provider for running Crabbox leases on local Windows VMs via Microsoft Hyper-V and PowerShell Direct — the Windows-native counterpart to tart (macOS), with no external CLI or cloud account. The design goal is "bring a plain Windows VHDX with a known administrator password, and it just works": the provider supplies everything else. With --hyperv-init-password even that requirement drops away for auto-logon images: a stock, password-less Microsoft dev-environment VHDX works completely unmodified.

How it works

crabbox warmup --provider hyperv --hyperv-image <vhdx>:

1. Thin clone, not a copy. Each lease is backed by a differencing disk over the template (New-VHD -Differencing -ParentPath) — near-instant and space-thin (a few MB up front), so the template stays read-only and shared instead of copying tens of GB per lease.
2. (Opt-in) first-boot password for password-less templates. Microsoft's downloadable dev-environment VHDXs auto-log-on with no password, and PowerShell Direct refuses empty credentials — so stock images used to be unusable. With --hyperv-init-password the provider mounts the lease's own differencing disk offline, loads its registry hive, and writes a RunOnce command that sets the guest password to CRABBOX_HYPERV_GUEST_PASSWORD at the template's auto-logon. The template VHDX is never modified. Guard rails: requires an explicit CRABBOX_HYPERV_GUEST_PASSWORD (refuses to stamp the default password onto a guest), rejects "/% in the password and the user name (both pass through cmd.exe), and the password reaches the host-side script via env, never argv.
3. Create + place off the system drive. New-VM -Generation 2 -Path <vmDir> puts the VM config and the multi-GB .VMRS runtime files on the same (data) drive as the VHD rather than defaulting to C:\ProgramData, and automatic checkpoints are disabled (Set-VM -AutomaticCheckpointsEnabled $false) so a lease never spawns a .avhdx that would strand a disk on release.
4. Make the guest reachable. Over PowerShell Direct (authenticating with the guest admin password, passed via env — never argv) the provider installs the OpenSSH server if absent (Add-WindowsCapability, Start-Service sshd, firewall) and installs git if absent (portable MinGit, pinned to an immutable release asset and SHA-256-verified before extraction) — mirroring how the Linux cloud-init path provisions a guest. Both are no-ops when already present, so a template that pre-bakes them just skips the download. MinGit is extracted to C:\Program Files\MinGit, not C:\Program Files\Git: MinGit's etc\gitconfig deliberately includes C:/Program Files/Git/etc/gitconfig, so extracting it there makes the include self-referential and every guest git command dies with "exceeded maximum include depth" (caught live by the second proof below; fixed in this PR).
5. Inject the lease key. The SSH public key is written to the user's authorized_keys and, for admin accounts, administrators_authorized_keys with the SYSTEM+Administrators-only ACL that Windows OpenSSH requires (otherwise sshd silently ignores it).
6. Wait for readiness, then run/sync/release normally. On release the VM is removed and only the lease's own differencing disk + per-VM config dir are deleted; the template is untouched. Cleanup is scoped to the crabbox- name prefix.

Net template requirement: a Generation-2 Windows VHDX — either with an administrator password known to Crabbox (--hyperv-user / CRABBOX_HYPERV_GUEST_PASSWORD), or, for auto-logon images, none at all with --hyperv-init-password. Non-Windows targets are rejected (from CLI, YAML, or env), and ISO images are rejected.

Live proof 1 — passworded template (existing path), Windows 11 Pro host, Go 1.26.4

Captured on the latest head. Plain Windows 11 VHDX with only an admin password set; C: deliberately full so storage is redirected to D: (which also exercises the off-system-drive placement):

$ crabbox doctor --provider hyperv
ok  provider  provider=hyperv hyperv=Enabled inventory=ready api=powershell leases=0 image=… ssh_probe=unchecked

$ crabbox warmup --provider hyperv --hyperv-image D:\hyperv-templates\win11-ssh-ready.vhdx --hyperv-cpu 2 --hyperv-memory 3072
provisioned lease=cbx_e70a9aac5441 instance=crabbox-hvproofa-240c4232 state=ready
ready ssh=Administrator@172.22.155.0:22 network=public workroot=C:\crabbox

$ crabbox run --provider hyperv --id cbx_e70a9aac5441 -- cmd /c ver
sync candidate: 1 files, 27 B
sync complete in 12.056s
Microsoft Windows [Version 10.0.22621.3880]
run summary sync=12.056s command=6.513s total=21.454s sync_skipped=false exit=0

$ crabbox list --provider hyperv
crabbox-hvproofa-240c4232 ready hyperv 172.22.155.0 lease=cbx_e70a9aac5441 slug=hvproofa keep=true target=windows

$ crabbox stop --provider hyperv --id cbx_e70a9aac5441
released lease=cbx_e70a9aac5441 instance=crabbox-hvproofa-240c4232
# verify: crabbox- VMs remaining: 0   (VM, differencing disk, and config dir all removed)

Live proof 2 — broader template coverage: STOCK password-less Microsoft image + --hyperv-init-password

The template here is Microsoft's downloadable WinDev2407Eval.vhdx exactly as downloaded (file mtime 2024-07-25 before and after the run — never written): auto-logon User, no password, no OpenSSH, no git. One flag makes it a working lease:

$ crabbox warmup --provider hyperv --hyperv-image C:\Users\…\WinDev2407Eval.vhdx ^
    --hyperv-user User --hyperv-init-password --hyperv-cpu 2 --hyperv-memory 3072
provisioned lease=cbx_48ec029c0094 instance=crabbox-hvproofb-5412dc36 state=ready
ready ssh=User@172.22.145.28:22 network=public workroot=C:\crabbox
warmup complete total=9m31.274s

$ crabbox run --provider hyperv --id cbx_48ec029c0094 -- git --version
sync complete in 14.581s
git version 2.54.0.windows.1
run summary sync=14.581s command=9.902s total=27.016s sync_skipped=false exit=0

$ crabbox stop --provider hyperv --id cbx_48ec029c0094
released lease=cbx_48ec029c0094 instance=crabbox-hvproofb-5412dc36
# verify: crabbox- VMs remaining: 0; template mtime unchanged (2024-07-25)

Reaching state=ready here exercises the full chain on a guest that started with nothing — first-boot password injection, OpenSSH install, pinned + checksum-verified MinGit install (to the corrected path; git --version exiting 0 in-guest is the regression proof for the MinGit fix), ACL-correct key injection, and the Windows readiness check over SSH.

Configuration

CLI: --hyperv-image (required), --hyperv-cpu, --hyperv-memory, --hyperv-switch, --hyperv-user, --hyperv-work-root, --hyperv-init-password. YAML hyperv: and CRABBOX_HYPERV_* env equivalents, incl. CRABBOX_HYPERV_GUEST_PASSWORD and CRABBOX_HYPERV_INIT_PASSWORD.

Not included (follow-up)

• A configurable storage root (today storage follows %USERPROFILE%).
• ISO install / autounattend (templates are pre-installed VHDX).
• WSL2 mode (native Windows only).

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed June 11, 2026, 8:49 AM ET / 12:49 UTC.

Summary
The PR adds a built-in hyperv SSH-lease provider for local Windows VMs, Hyper-V CLI/YAML/env configuration, docs/tests, and a Windows-specific SSH command streaming implementation.

Reproducibility: not applicable. as a bug reproduction; this is a new provider feature, and the PR body plus maintainer comment provide live after-fix Hyper-V behavior proof instead.

Review metrics: 3 noteworthy metrics.

• Diff size: 19 files, +4,626/-25. The feature is broad enough that maintainer review should weigh provider ownership and shared SSH impact, not only unit-test coverage.
• New provider tests: 1,842 lines added. The provider has extensive mocked lifecycle coverage, but the real Hyper-V matrix still depends on maintainer-host validation.
• Shared SSH stream files: 3 files changed/added. The PR changes common SSH helper behavior on Windows hosts, which affects more than the new Hyper-V provider.

Merge readiness
Overall: 🦞 diamond lobster
Proof: 🦀 challenger crab
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Risk before merge

• [P1] Merging this branch makes Crabbox own a built-in Windows Hyper-V host matrix: Hyper-V enablement, PowerShell Direct, DHCP, nested virtualization, guest internet, OpenSSH capability install, and MinGit bootstrap can fail outside normal CI.
• [P1] The provider handles a guest administrator password and, with --hyperv-init-password, intentionally places the configured password inside the lease guest's RunOnce/net.exe path until first logon completes.
• [P1] Release and cleanup now operate on local Hyper-V VM inventory, per-user VM storage, lease claims, and stored SSH keys; scoped deletion is defensive, but host command or filesystem failures can still leave operator cleanup work.
• [P1] The PR changes shared Windows SSH command streaming, so Windows-host SSH behavior outside the new provider depends on the new file-backed stream implementation.

Maintainer options:

1. Merge with provider ownership accepted (recommended)
   Accept the documented Windows host matrix, guest bootstrap, cleanup, and shared SSH-streaming support burden based on the live proof and maintainer validation already posted.
2. Hold for release-owner signoff
   Pause merge until a maintainer explicitly signs off on the Hyper-V support boundary, the guest-password bootstrap model, and the Windows SSH stream change.
3. Defer built-in Hyper-V support
   Close or pause the PR if maintainers do not want Crabbox core to own local Windows Hyper-V lifecycle and cleanup behavior yet.

Next step before merge

• [P2] Maintainers need to decide whether to merge the built-in local Windows provider with the documented support, security, cleanup, and shared SSH-streaming risks.

Security
Cleared: The security-sensitive paths were reviewed and no concrete blocking defect was found; the remaining concerns are merge-risk ownership decisions rather than line-level vulnerabilities.

Review details

Best possible solution:

Merge this only if maintainers are ready to support provider: hyperv as a first-class local Windows provider; otherwise keep the branch open for an explicit product/support decision rather than asking for a narrow code repair.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a bug reproduction; this is a new provider feature, and the PR body plus maintainer comment provide live after-fix Hyper-V behavior proof instead.

Is this the best way to solve the issue?

Yes, if maintainers want Hyper-V in core: the implementation keeps Hyper-V lifecycle code in a provider adapter, keeps the guest password off argv, pins and verifies MinGit, and includes mocked lifecycle plus live host validation. The remaining question is product/support ownership, not a narrower code repair.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against f6ad6f84ca33.

Label changes

Label changes:

• add rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦀 challenger crab and patch quality is 🐚 platinum hermit.
• remove rating: 🐚 platinum hermit: Current PR rating is rating: 🦞 diamond lobster, so this older rating label is no longer current.

Label justifications:

• P2: This is a sizable provider feature with bounded blast radius but non-trivial local Windows runtime risk.
• merge-risk: 🚨 security-boundary: The provider provisions privileged guest access, writes SSH keys/config, handles guest administrator passwords, and bootstraps guest binaries.
• merge-risk: 🚨 availability: The new provider depends on Hyper-V, PowerShell Direct, DHCP, guest internet, OpenSSH, MinGit bootstrap, and shared Windows SSH streaming all working at runtime.
• merge-risk: 🚨 session-state: The PR creates and cleans local VM lease claims, stored SSH keys, differencing disks, VM config directories, and retained lease state.
• rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦀 challenger crab and patch quality is 🐚 platinum hermit.
• feature: ✨ showcase: ClawSweeper spotlight: unusually compelling feature idea for maintainer attention. A local Windows Hyper-V provider would unlock native Windows VM leases without a cloud account or external VM CLI.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body includes after-fix terminal output for passworded and stock password-less Hyper-V templates, and a maintainer comment adds live validation on June 11, 2026.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes after-fix terminal output for passworded and stock password-less Hyper-V templates, and a maintainer comment adds live validation on June 11, 2026.

Evidence reviewed

What I checked:

• Current main provider absence: Current main has no internal/providers/hyperv path, so the PR is not obsolete or already implemented on main. (f6ad6f84ca33)
• PR diff surface: The local diff from main to the PR head touches 19 files with 4,626 additions and 25 deletions, mostly in the new Hyper-V provider and Windows SSH stream implementation. (2b1918439958)
• Provider implementation: Acquire requires a Windows host, a VHDX image, explicit guest password, optional init-password validation, persists a provisional claim, creates a differencing-disk VM, configures guest SSH/git, and cleans up failed non-kept leases. (internal/providers/hyperv/backend.go:92, 2b1918439958)
• MinGit and SSH lockdown safeguards: The guest bootstrap pins MinGit by URL and SHA-256, writes SSH authorized keys/config, disables password auth, validates sshd config, rotates host keys, and only opens the SSH firewall after key setup. (internal/providers/hyperv/backend.go:623, 2b1918439958)
• Cleanup safeguards: Storage cleanup validates crabbox- VM names and scopes checkpoint deletion to owned name-prefixed .avhdx files in the provider VHD directory. (internal/providers/hyperv/backend.go:907, 2b1918439958)
• Shared SSH change: The PR routes SSH helpers through runCommandWithPlatformStreams and adds -n for no-input SSH paths, changing shared Windows-host SSH execution behavior beyond the new provider. (internal/cli/ssh.go:316, 2b1918439958)

Likely related people:

• steipete: Authored the later Hyper-V hardening and Windows SSH stream commits in this PR and posted maintainer live validation for the final runtime path. (role: reviewer and recent PR hardening owner; confidence: high; commits: 62dd8a36f33f, d0757519cc6b, 001bb1f74e8b; files: internal/providers/hyperv/backend.go, internal/cli/ssh_stream_windows.go, internal/cli/ssh.go)
• Vincent Koc: The current main baseline for the shared internal/cli/ssh.go helpers changed by this PR is attributed to release commit e9fa596 in local blame. (role: current-main SSH baseline contributor; confidence: medium; commits: e9fa596eac8d; files: internal/cli/ssh.go)
• Coy Geek: Recent current-main provider history includes a direct SSH-lease provider addition, making this a useful adjacent routing candidate for provider integration review. (role: adjacent SSH-provider contributor; confidence: low; commits: 836130bbcb03; files: internal/providers, internal/cli/ssh.go)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[anagnorisis2peripeteia]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/27018194271
• Updated: 2026-06-05T13:43:36.632Z

[anagnorisis2peripeteia]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/27019290052
• Updated: 2026-06-05T14:05:32.936Z

[anagnorisis2peripeteia]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/27042640690
• Updated: 2026-06-05T22:16:16.560Z

[anagnorisis2peripeteia]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/27043839025
• Updated: 2026-06-05T22:48:19.144Z

[anagnorisis2peripeteia]

@clawsweeper re-review

The provider now makes a plain Windows VHDX (just a known admin password) work end-to-end — it supplies the rest:

• Differencing-disk leases (thin clone, no multi-GB copy per lease)
• Off-system-drive placement (New-VM -Path for VM config + .VMRS; auto-checkpoints disabled to avoid disk leaks)
• Guest provisioning over PowerShell Direct: installs OpenSSH + git if absent (mirrors Linux cloud-init), key injected to administrators_authorized_keys with the SYSTEM+Administrators-only ACL Windows OpenSSH requires
• Explicit non-Windows target rejection (CLI/YAML/env)

Live proof in the body: doctor → warmup→state=ready (ssh=Administrator@…, workroot=C:\crabbox) → run (sync+command over SSH) → list → stop → cleanup (0 VMs), on a plain dev VHDX with C: full (storage redirected to D:).

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/27223766951
• Updated: 2026-06-09T17:33:56.709Z

[anagnorisis2peripeteia]

@clawsweeper re-review

Addressed the P2: registered the documented --hyperv-user and --hyperv-work-root flags (guest password stays off the CLI — only CRABBOX_HYPERV_GUEST_PASSWORD). Added a test; verified --hyperv-user parses. The documented quickstart now works as written.

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/27225220254
• Updated: 2026-06-09T18:00:10.270Z

[steipete]

Maintainer live validation on June 11, 2026:

• Provisioned a fresh nested Hyper-V Windows Server 2022 lease on an AWS Windows host: cbx_458cefeed3ee / crabbox-hv-live-91dbde19.
• Verified generated OpenSSH host-key ACLs allow only SYSTEM and Administrators, then completed SSH authentication with the per-lease key.
• Ran crabbox run --provider hyperv --id cbx_458cefeed3ee --no-sync -- whoami; output was ec2amaz-t0tblif\administrator, exit 0.
• Ran crabbox stop; verified the VM, VHDX, VM config, lease claim, and stored key were all removed.
• Reproduced and fixed Windows inbox OpenSSH hanging with Go-managed output pipes. Verified the final file-backed stream implementation on a fresh AWS Windows host, including ordered combined output, nil writers, local writer failures, 20 MiB forced spool rotation, immediate delete-pending temp files, and a real Crabbox SSH command exiting 0.

Local verification at 4c4c0d9159a70d7dea41215a2ea5c5ff4722b965:

• go test -race ./...
• go vet ./...
• Windows cross-build and Windows-only test binary
• Autoreview: no accepted/actionable findings