agent-sandbox-vm

A fully scripted Hyper-V sandbox for running agent tools on Windows with a native MSVC toolchain. The agent runs inside an isolated VM, builds real Windows binaries, and artifacts are extracted back to the host. Also ships an Apple Silicon path via Virtualization.framework and Parallels.

PowerShell Windows / macOS GPL-3.0 · v3.0.0 Hyper-V Parallels

Architecture

host
PowerShell scripts — PowerShell Direct (VMBus) → Hyper-V Gen2 VM
MSVC · Rust · Claude Code · Codex → artifacts
extracted to host

Install-Windows.ps1 — instead of booting from DVD (which can fail on Gen2 VMs), it mounts the ISO on the host, partitions the VHDX, and applies the image via DISM. Bootstrap can also build an ISO from UUP dump.

Start-Session.ps1 — copies your project into the VM over PowerShell Direct, optionally enables internet, and connects the console. -Restore gives a clean-room build from the base snapshot.

Lifecycle

Every script is idempotent and targets a named VM. Host scripts take -VMName; omit it to use the current default from the last Bootstrap.

BootstrapNew-AgentVM · Install-Windows (DISM) · New-UUPDumpISO

ProvisionVS Build Tools · Rust (MSVC) · Node · Python + uv · Git / gh · Claude Code · Codex CLI

SnapshotSave-BaseSnapshot → CleanProvisionedBase

SessionStart-Session · -Internet · -Restore · -ExtractOnExit

ExtractCopy-Artifacts · -WaitForShutdown · -ExtraPatterns

Kernel debugSetup-KernelDebugger · Setup-KernelDebuggee — KDNET over the Default Switch

Setup

Run everything as Administrator on Windows 10/11 Pro or Enterprise (Hyper-V required). One-time bootstrap and provision, then daily sessions.

> .\Bootstrap.ps1

> .\scripts\Start-Provision.ps1 -VMName AgentDevSandbox

> .\Start-Session.ps1 -VMName AgentDevSandbox -ProjectPath C:\Projects\myapp -Internet

Needs a Claude Pro subscription (for Claude Code) and/or an OpenAI API key (for Codex CLI) — at least one. Supply your own Windows ISO or let Bootstrap build one from UUP dump.

Workflows

Isolated builds

No internet by default — a full sandbox. The native MSVC toolchain builds real Windows binaries; add -Internet only when a session needs cargo fetch or npm install.

Clean-room from snapshot

-Restore rolls back to CleanProvisionedBase before every run, so each build starts from an identical, known-good machine.

Kernel debugging over KDNET

WinDbg on the debugger machine, BCD / test-signing on the debuggee. The setup scripts own the KDNET key, firewall port, and Secure Boot toggle end to end.

Apple Silicon

An experimental Virtualization.framework path for macOS guests, plus a near-parity Parallels workflow for a full Windows 11 ARM64 sandbox with agentless prlctl exec control.

← all projects github.com/glslang/agent-sandbox-vm ↗