Overview

sandbox-mcp gives developers and AI agents a real, disposable Windows 11 machine for testing Windows apps. It boots a fresh Windows Sandbox, deploys and launches your executable, drives native UI Automation, captures screenshots or recordings, then destroys the guest. The same engine powers a standalone sbx CLI and an optional MCP server, so agents can call structured tools when they need discoverable schemas and inline images source:5.

Beyond running an app, it diagnoses host dependencies without executing anything, can explicitly provision verified runtimes, tests installers by diffing system snapshots, and detonates untrusted files in an offline guest source:29.

Quick start

Prerequisites: Windows 11 Pro, Enterprise or Education with virtualization enabled and a logged-in desktop session. Windows Sandbox must be on and the wsb CLI available.

1. Download the Windows x64 portable ZIP from the latest release, verify it against the adjacent .sha256, and extract it. The ZIP bundles Node.js, so no Node/npm install is required source:30.
2. Open PowerShell in the extracted folder and run the readiness check:

.\sbx.cmd doctor

3. If the Sandbox feature is off, run in an administrator PowerShell and restart:

Enable-WindowsOptionalFeature -Online -FeatureName Containers-DisposableClientVM -All

Then open Windows Sandbox once from the Start menu to install the wsb command-line tool, and rerun doctor source:37. 4. Try a built-in app:

.\sbx.cmd run C:\Windows\System32\charmap.exe --open

A passing run leaves report.md, report.json, screenshots and audit.jsonl under %LOCALAPPDATA%\sandbox-mcp\runs\<timestamp>. Add --record for a self-contained HTML viewer and MP4 when host ffmpeg exists.

For agent use, configure the MCP client's stdio command to the bundled node.exe and src\server.js with absolute paths; VS Code, Copilot CLI and Claude Desktop use different top-level keys, shown in the README source:35.

Constraints

• One sandbox runs at a time, a Windows Sandbox rule; concurrent sbx run calls fail fast rather than queue source:3.
• Every boot is pristine. App prerequisites are never installed implicitly; opt in with --provision auto or an explicit component list, and note reports mark provisioned runs as non-clean.
• No Microsoft Store apps, winget, Notepad, Calculator or Windows Terminal inside the guest; Windows PowerShell 5.1 and .NET Framework 4.8 are present.
• The first UI Automation call takes about 4 seconds while the interop assembly is generated; system snapshots take 10–20 seconds, so install-test runs around two minutes plus installer time.
• Network mode off has no network adapter and communicates through a shared-folder mailbox; use it for untrusted files. The out folder is writable from the guest and must be treated as untrusted, and Windows Sandbox is not a substitute for dedicated malware analysis.
• The project is MIT licensed. The portable package targets native Windows x64; ARM64 is not currently packaged.

HotRepo's take

sandbox-mcp is a young repository that recorded 108 stars and 3 forks in its first tracked window on the JavaScript new-project list. That single snapshot shows early interest but is not enough to infer a trend. What stands out in the material is the separation of concerns: a complete CLI that works without any MCP client, a shared core behind the optional adapter, and reports with real logs and measured timings, plus a compatibility matrix for multiple UI frameworks source:16. For developers testing Windows desktop apps or agents that need a disposable Windows target, that design is the relevant signal; the star count adds little to it.