sandbox-mcp

Fresh, throwaway Windows machines for testing your apps. One command (or one MCP tool call) boots a clean Windows 11 in Windows Sandbox, copies your build in, runs it, drives its UI, screenshots it, checks for crashes, copies the results out and deletes the machine. About 35 seconds, start to finish.

> sbx run .\samples\HelloSandbox\bin --test .\samples\HelloSandbox\test.ps1

[sbx] booting a fresh Windows Sandbox (network on)
[sbx] started 4ebd5e89-0df5-457e-b15e-70f48dce0591
[sbx] ip 172.25.229.32
[sbx] folders shared
[sbx] user session ready
[sbx] agent up as 6CB5E6E5-FD41-4\WDAGUtilityAccount
[sbx] copying D:\github\sandbox-mcp\samples\HelloSandbox\bin to C:\apps\HelloSandbox
[sbx] running HelloSandbox.exe
[sbx] running test test.ps1
[sbx] destroying the sandbox
PASS  HelloSandbox.exe on a fresh Windows Sandbox (37.4s)
  sandbox  network on, booted in 14.9s
  process  still running, window "Hello Sandbox"
  crashes  none
  test     test.ps1 passed
  shots    3 screenshot(s)
  report   C:\Users\you\AppData\Local\sandbox-mcp\runs\20261106-190012\out\report.md

The test script typed a name into the app with UI Automation, clicked Greet and waited for the answer. This is the screenshot it brought back from inside the sandbox:

It's both:

• an MCP server so AI agents (GitHub Copilot, Claude, Cursor, VS Code, ...) can test the apps they just built on a machine that isn't yours, and

• a CLI (sbx) for you, your scripts and your CI.

They share state, so you can sbx start, let an agent poke at the app, then sbx stop.

Why

"It works on my machine" is usually true: your machine has every runtime, SDK, redistributable, font, registry key and PATH entry you ever installed. Your users' machines don't. Windows Sandbox is a pristine Windows that boots in seconds and is deleted when it closes, which makes it the perfect "brand-new customer PC". But it has no API: it was built for a person clicking around. sandbox-mcp makes it scriptable.

If you need many machines, persistence, or Linux, use a VM or a cloud box. If you want to know "does my Windows app install, launch and work on a clean PC, and what does it look like?" as quickly and cheaply as possible, this is it.

Related MCP server: Hyper-V Sandbox MCP Server

What you can do

• Clean-machine smoke tests: does the exe even start without the VC++ runtime / .NET runtime / WebView2 you forgot to bundle? sbx run tells you, with a screenshot and the crash events.

• Test installers and uninstallers: sbx install-test setup.msi installs on a clean machine, uninstalls, and reports every file, registry key, service, scheduled task and autorun the installer added and the uninstaller forgot. Hung installers waiting on a hidden dialog get screenshotted instead of hanging your CI.

• Drive the UI with UI Automation, not pixels: read the control tree (Button "Save" #SaveButton {invoke}), set text, click, toggle, select, wait for results. Works for WinForms, WPF, Win32 and WinUI apps, and things like File Explorer. Screenshots, mouse and keyboard are there for everything else.

• Let an agent close the loop: "build it, test it on a clean machine, look at the screenshot, fix it, repeat", without the agent touching your real desktop.

• Run things with no network at all: --network off boots the sandbox with no network adapter. Control still works (through a shared folder), so you can watch an app's offline behavior or open something you don't trust.

• See what a file you don't trust actually does: sbx detonate invoice.js runs it in a sandbox with no network and reports every process it started (with command lines), the names it looked up, the addresses it tried, and the autoruns, scheduled tasks, services and files it planted. Then the whole machine is deleted.

• Collect evidence: every run keeps screenshots, copied-out files, a markdown report and an audit log on the host after the sandbox is gone.

Requirements

• Windows 11 24H2 or later, Pro / Enterprise / Education (Windows Sandbox isn't available on Home).

• Windows Sandbox enabled: Enable-WindowsOptionalFeature -Online -FeatureName Containers-DisposableClientVM (as admin, then reboot), or Turn Windows features on or off > Windows Sandbox.

• Launch Windows Sandbox from the Start menu once. That updates it to the Store version, which includes the wsb command-line tool this project drives. Check with wsb --version.

• Node.js 20+.

Quick start

git clone https://github.com/shanselman/sandbox-mcp
cd sandbox-mcp
npm install
npm link            # puts `sbx` and `sandbox-mcp` on your PATH (or use `node src/cli.js`)

sbx run C:\Windows\System32\charmap.exe --open     # try it on something that exists everywhere

Try the included sample (needs nothing but Windows; it compiles with the .NET Framework's csc.exe):

.\samples\HelloSandbox\build.ps1
sbx run .\samples\HelloSandbox\bin --test .\samples\HelloSandbox\test.ps1   # passes
sbx run .\samples\HelloSandbox\bin --args --crash                            # fails, and shows the crash
sbx install-test .\samples\LeakyApp\install.ps1                              # an installer whose uninstaller forgets things
sbx detonate .\samples\Suspicious\suspicious.ps1                             # a harmless script that acts like malware

Use it from an agent (MCP)

Add the server to your MCP client. For example VS Code (.vscode/mcp.json) or GitHub Copilot CLI (~/.copilot/mcp-config.json):

{
  "servers": {
    "windows-sandbox": {
      "type": "stdio",
      "command": "node",
      "args": ["C:\\path\\to\\sandbox-mcp\\src\\server.js"]
    }
  }
}

(Claude Desktop and others use "mcpServers" instead of "servers". After npm link you can use "command": "sandbox-mcp" with no args.)

Then ask: "Build the app, run it in a fresh Windows Sandbox, type my name in the box, click Greet and show me a screenshot."

There's also an agent skill in skills/windows-sandbox-app-test that teaches agents the workflow; copy it into your agent's skills folder (for example ~/.copilot/skills/).

MCP tools

CLI

sbx run <app.exe|folder> [--exe <name>] [--args "<args>"] [--console] [--wait <sec>]
                         [--test <script.ps1>] [--collect <sandbox path>]... [--keep] [--open]
sbx install-test <setup.msi|.exe|.ps1|.cmd> [--args "/S"] [--uninstall auto|none|"<cmd>"]
                         [--uninstall-args "/S"] [--test <script.ps1>] [--fail-on-leftovers] [--exclude <path>]...
sbx detonate <file> [--args "<args>"] [--network off|firewall|on] [--duration <sec>] [--full] [--every <sec>]

sbx start [--network on|firewall|off] [--memory <MB>] [--no-gpu] [--minimized]
sbx push <host path> [sandbox path]          sbx pull <sandbox path> [name]
sbx exec [--cmd] [--cwd <dir>] <command...>  sbx launch <exe> [--args "..."]
sbx shot [--window <title>|--pid <pid>]      sbx windows   sbx proc <pid>
sbx ui [tree] [--pid <pid>]                  sbx ui click --name Save
sbx ui set --id NameBox --value Scott        sbx ui wait --name "Saved" --timeout 10
sbx snapshot <name> [--exclude <path>]...    sbx diff <from> <to>
sbx click <x> <y>   sbx type "text" [--keys] sbx errors   sbx status   sbx stop
sbx mcp                                      # run the MCP server

Add --json to any command for machine-readable output. sbx exec and sbx run exit with meaningful codes, so they drop straight into scripts. sbx help has the details.

Test scripts

sbx run --test smoke.ps1 (or sandbox_run with testScript) runs your script inside the sandbox after the app starts, with:

• $env:SBX_APP_PID, $env:SBX_APP_DIR, $env:SBX_OUT (anything you write to SBX_OUT comes back to the host),

• these commands already imported:

Get-SbxUiTree [-ProcessId <pid>] [-WindowTitle <title>] [-Depth <n>]     # objects: type, name, automationId, value, actions...
Invoke-SbxUi  -Action <click|setvalue|toggle|select|expand|read|...> [-Name <text>] [-AutomationId <id>]
              [-ControlType <Button|Edit|...>] [-Index <n>] [-Value <text>] [-ProcessId <pid>]
Wait-SbxUi    [-Name <text>] [-AutomationId <id>] [-ControlType <type>] [-TimeoutSec <n>] [-ProcessId <pid>]

Throw, or exit non-zero, to fail the run. Example (samples/HelloSandbox/test.ps1):

$app = [int]$env:SBX_APP_PID
Invoke-SbxUi -ProcessId $app -AutomationId NameBox -Action setvalue -Value 'Sandbox'
Invoke-SbxUi -ProcessId $app -Name Greet -Action click
Wait-SbxUi   -ProcessId $app -Name 'Hello, Sandbox!' -TimeoutSec 5 | Out-Null

Installer testing

Installers are the part of an app that only ever runs on clean machines, so they're the part you test least. sbx install-test takes a system snapshot of a fresh sandbox, runs your installer silently, snapshots again, uninstalls it the way Add/Remove Programs would, snapshots a third time and diffs them:

> sbx install-test .\7z2501-x64.msi --offline

PASS  7z2501-x64.msi on a fresh Windows Sandbox (117.5s)
  install    exit 0 in 2.5s
  added      7-Zip 25.01 (x64 edition); 111 files, 18 registry keys, 0 services, 0 autorun/env values
  uninstall  7-Zip 25.01 (x64 edition): exit 0 in 2.3s
  leftovers  none, clean uninstall

The report lists what was added (here: C:\Program Files\7-Zip, the Start menu folder, the shell extension CLSIDs and context-menu handlers, App Paths and the uninstall entry) and what's left behind. Try the included deliberately sloppy installer, whose uninstaller only deletes its program folder:

> sbx install-test .\samples\LeakyApp\install.ps1

## Left behind after uninstall
Services:  added service LeakyUpdater "Leaky App Updater", automatic: "C:\Program Files\LeakyApp\updater.exe"
Autoruns:  added HKCU\Software\Microsoft\Windows\CurrentVersion\Run\LeakyUpdater
Files:     C:\ProgramData\LeakyApp\   C:\Users\WDAGUtilityAccount\AppData\Roaming\LeakyApp\
           C:\Windows\System32\Tasks\LeakyApp Daily Check
Registry:  HKLM\SOFTWARE\LeakyApp

• .msi files get msiexec /i /qn /norestart with a verbose log (brought back, with its errors in the report). For .exe installers pass the silent switch: --args /S (NSIS), /VERYSILENT (Inno), --silent (Squirrel).

• The uninstall uses what the installer registered: msiexec /x {ProductCode}, else QuietUninstallString, else UninstallString plus --uninstall-args. The run fails if the program is still in Add/Remove Programs afterwards.

• An installer that doesn't exit within --timeout is screenshotted (and its new windows' UI Automation tree recorded) before it's killed. That's usually a "silent" install that's waiting for someone to click a dialog.

• Processes the installer leaves running (tray apps, updaters) are listed and stopped before uninstalling.

• --test smoke.ps1 runs between install and uninstall with $env:SBX_INSTALL_DIR and $env:SBX_PROGRAM.

• --fail-on-leftovers turns leftovers into a failure, for CI.

• The snapshots skip the things Windows changes on its own (caches, telemetry, Defender, Windows Update, Start menu and Explorer bookkeeping, Windows Installer's internal database), so a 30-second idle sandbox diffs to "No changes". --exclude adds more.

The same snapshots are available step by step: sbx snapshot before, do anything, sbx snapshot after, sbx diff before after (or the sandbox_snapshot / sandbox_diff tools).

Detonate: what does this file actually do?

Someone sent you invoice.js, a "driver update", a script from a forum. sbx detonate runs it the way a double-click would, in a fresh sandbox with no network adapter, with Windows' own auditing switched on, and tells you what it did:

> sbx detonate .\samples\Suspicious\suspicious.ps1 --network firewall

suspicious.ps1: 3 red flag(s) (watched 40s, network firewall)
  findings   🔴 starts itself with Windows: added HKCU\Software\Microsoft\Windows\CurrentVersion\Run\ContosoUpdater =
                powershell.exe -WindowStyle Hidden -ExecutionPolicy Bypass -File "C:\Users\...\ContosoUpdater\updater.ps1"
             🔴 created a scheduled task: ContosoUpdate
             🔴 put something in a Startup folder: C:\Users\...\Start Menu\Programs\Startup\contoso.cmd
             🟠 wrote 2 runnable file(s): C:\Users\...\ContosoUpdater\updater.ps1, ...\Startup\contoso.cmd
             🟠 ran built-in Windows tools that malware often uses: schtasks.exe, whoami.exe, ipconfig.exe, net.exe, net1.exe
             🟠 looked up 1 internet name(s): c2.contoso-updates.example
             🟠 tried to connect to 2 address(es): 198.51.100.7:4444, 203.0.113.10:80
  processes  7 (powershell.exe → conhost.exe → schtasks.exe → whoami.exe → ipconfig.exe …)
  network    1 name lookup(s), 2 connection attempt(s)
  changed    4 files added, 0 changed, 2 registry keys, 1 autorun/env values, 0 services

(samples/Suspicious/suspicious.ps1 is harmless; it just behaves like something that isn't.) The report also has a timeline:

  +0.0s  start    powershell.exe (pid 8180)  ... -File "C:\Users\WDAGUtilityAccount\Downloads\suspicious.ps1"
  +1.5s  start    schtasks.exe (pid 7848)  /Create /F /TN ContosoUpdate /SC ONLOGON /TR "powershell.exe -WindowStyle Hidden ..."
  +1.6s  start    whoami.exe (pid 7616)  /all
  +1.7s  start    net.exe (pid 9064)  user
  +1.7s  start    net1.exe (pid 8096)  C:\Windows\system32\net1 user
 +15.0s  lookup   c2.contoso-updates.example (failed)
 +15.1s  connect  203.0.113.10:80/TCP blocked (powershell.exe)
 +15.2s  connect  198.51.100.7:4444/TCP blocked (powershell.exe)

plus the process tree, a before/after diff of files, registry, services and autoruns, the windows it opened, screenshots, and "everything else that happened" (usually Windows itself, kept separate rather than hidden).

• How: process creation auditing with command lines (Security 4688), Windows Filtering Platform connection auditing (5156/5157) and the DNS client log, collected from inside the guest, plus the same snapshots as install-test. Activity is attributed to the file's own process tree, so the agent's own work isn't mixed in.

• Network: off (default) has no adapter at all. Name lookups are still recorded, but nothing leaves the machine. --network firewall also shows the IP addresses and ports it tries, blocked by the guest firewall. on gives it the internet; only use that for things you're prepared to let talk to the world.

• Runs: .exe, .msi (silently), .ps1, .cmd, .bat, .js/.jse/.vbs/.vbe/.wsf (with wscript) and .hta (with mshta), from the user's Downloads folder.

• Watching: up to --duration seconds (60), stopping early once everything it started has exited, unless --full. A screenshot every --every seconds (15).

• Findings are heuristics, not a verdict. Installers add autoruns and services too. Exit code 0 means "it was observed", not "it's safe". This is a quick first look on your own PC, not a malware lab: something that checks whether it's in a sandbox can just behave nicely.

Network modes

In firewall and off mode, sandbox-mcp also switches off Smart App Control in the guest. It ships in evaluation mode and asks the cloud about every new exe and msi; with no internet each of those lookups hangs for about two minutes (a 2 MB MSI took 125 s to install instead of 1 s).

Security notes

• Each sandbox is a separate Hyper-V-isolated kernel. It's thrown away on stop, together with everything that ran in it.

• Hardened defaults: clipboard, printer, microphone and camera redirection are off, and Protected Client mode is on.

• The host shares exactly three folders: the guest agent (read-only), a staging folder for files you copy in (read-only) and an output folder (read-write). Nothing else from your disk is visible.

• The control channel needs a random per-sandbox token. In on/firewall mode it's TCP to the sandbox's private NAT address; in off mode it's the shared folder.

• SANDBOX_MCP_ALLOWED_ROOTS limits which host folders can be copied in (handy when an agent is driving).

• Every operation is appended to audit.jsonl in the run folder.

• When the MCP client disconnects, the sandbox is destroyed. An idle watchdog inside the guest shuts it down after 30 minutes with no calls.

• With network: on the guest has internet access like any other machine on your network's NAT. Use off for anything you don't trust.

• The out folder is writable from inside the sandbox, so treat what comes back (screenshots, pulled files, logs) as untrusted, especially after detonate. sandbox-mcp reads data from it but never runs anything from it.

• Windows Sandbox is strong isolation, but not a guarantee: a hypervisor or Windows Sandbox escape would be a zero-day. For real malware analysis use a dedicated, disposable analysis machine.

Configuration

How it works

Windows Sandbox has no COM or WMI API. Since Windows 11 24H2 its Store version ships wsb.exe (start / stop / list / ip / exec / share / connect), but wsb exec returns only an exit code: no output, no screenshots, no UI. So:

1. The host creates a run folder and calls wsb start with a hardened config (and <Networking>Disable in off mode).

2. It shares the guest agent folder and starts agent/agent.ps1 inside with wsb exec, in the interactive user session (it needs a desktop for windows and screenshots).

3. The agent is a small PowerShell server: exec with real output, file copy, process launch, screenshots, mouse and keyboard, window list, event log, and UI Automation through agent/uia.cs. That uses native UI Automation (the managed System.Windows.Automation can't see inside WinForms apps), with an interop assembly generated on the fly from the OS type library, so nothing needs installing.

4. With the network on, the host talks to it over TCP. In off mode it uses a mailbox in the shared folders. (The guest caches "file not found" for ~5 s, so the host bumps a sequence file the guest polls, bringing a round trip from 5 s down to ~100 ms.)

5. wsb stop destroys the VM. The run folder stays on the host.

Limits

• One sandbox at a time. That's a Windows Sandbox rule. sbx run calls queue nothing; they fail fast if one is running.

• Every boot is pristine, so prerequisites get installed every time (that's the point, but it costs time).

• No Microsoft Store apps, winget, Notepad, Calculator or Windows Terminal inside. Windows PowerShell 5.1 and .NET Framework 4.8 are there.

• The first UI Automation call in a sandbox takes ~4 s (it generates the interop); later calls are fast.

• A system snapshot takes 10-20 s (about 11k files, 340k registry keys, 700 services), so install-test takes roughly two minutes plus your installer's own time.

• The guest desktop gets a plain background so screenshots stay around 100 KB instead of 16 MB.

• Needs a logged-in Windows session on the host (Windows Sandbox is a desktop feature).

Related projects

• fmuecke/windows-sandbox-mcp is another MCP server for Windows Sandbox, focused on running agent-generated code safely and with Networking Disable by default. Its ideas (true offline by default, stop on disconnect, an idle watchdog, an audit log, allowed folders) shaped this project. sandbox-mcp leans the other way: testing your app on a clean machine, with UI Automation, screenshots and one-shot reports.

• devvm.dev: disposable cloud dev machines for agents. The inspiration for "just give the agent a fresh box".

License

MIT