sandbox-mcp — Claude Code plugin: Windows Sandbox testing
This plugin for Claude Code and GitHub Copilot lets an agent run Windows apps in a disposable Sandbox and control their UI. It’s for checking installers, app behavior, or untrusted files in a clean guest.
MIT ★ 494 updated 2026-11-15
/plugin marketplace add shanselman/sandbox-mcp
/plugin install sandbox-mcp@sandbox-mcpWhat sandbox-mcp does
The plugin runs Windows apps in a separate Windows Sandbox, drives their interfaces, and captures test results. An agent can inspect UI Automation elements, type, click, toggle controls, and record process state, exit codes, and crashes.
The same engine is available through the sbx CLI and an optional MCP adapter. Screenshots, recordings, and reports stay on the host after the guest session ends. Windows Sandbox and a Windows app or package are required; Node.js does not need a separate installation. Guest networking can be disabled, and dependency installation happens only when explicitly requested.
What it helps with
- test an app on a clean Windows guest
- control desktop UI elements
- identify a missing app dependency
- capture a crash and keep test evidence
- inspect an installer or untrusted file
Example prompts for the agent
- Test
app.exein a clean Windows Sandbox and save a report. - Open the app in Sandbox, click its launch button, and save a screenshot.
- Run the installer in a separate Sandbox and record its changes.
How to install sandbox-mcp
Plugin marketplace
/plugin marketplace add shanselman/sandbox-mcp/plugin install sandbox-mcp@sandbox-mcpCommand from the source
copilot plugin install sandbox-mcp@awesome-copilotStep by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own
Questions about sandbox-mcp
How do I install sandbox-mcp in Claude Code?
Run these commands in order: /plugin marketplace add shanselman/sandbox-mcp, then /plugin install sandbox-mcp@sandbox-mcp.
What does sandbox-mcp do?
It runs Windows apps and installers in a disposable Windows Sandbox. An agent can control the UI, diagnose dependencies, and preserve test results.
What does sandbox-mcp need to run?
It requires Windows Sandbox and a Windows app or package to test. Node.js is bundled with the CLI, so a separate Node.js installation is unnecessary.
Source text
SKILL.md · MIT
# sandbox-mcp
## Give your AI agent a brand-new Windows PC. Then throw it away.
Not your desktop. Not a container pretending to be Windows. **A real, disposable Windows 11 machine**:
boot it, deploy your app, drive the controls, catch the crash, keep the evidence, delete the PC.
Run it directly with `sbx`; the optional MCP adapter exposes discoverable tools and inline images for clients that want them.
Both interfaces use the same engine. The measured GUI samples take roughly **40-50 seconds** end to end.
See the [website](https://shanselman.github.io/sandbox-mcp/).

*Real app, real guest: Haptics Everywhere's self-contained WPF/WinForms desktop app in a fresh, network-off Sandbox.
UIA selects the Inspector, the guest switches light to dark, the app relaunches and exits, then the guest is destroyed.
10-second, 183 KB edited footage: light Inspector slowed for readability, repeated dark frames trimmed.
Boot/teardown title cards summarize actual logs, not filmed boot/shutdown.
No guest runtime installation or haptic-hardware claim. [Fresh dark lab screenshot](docs/haptics-teaser.png) ·
[Earlier light-theme inspector](docs/haptics-inspector.png).*
### 🤖 Let your agent set it up
Give this to your bot. It checks the PC, verifies the download and asks before admin changes or a restart.
The CLI works on its own; configure MCP only if your agent needs that interface:
```text
Set up the sandbox-mcp CLI by following:
https://raw.githubusercontent.com/shanselman/sandbox-mcp/main/docs/agent-setup.md
Install the latest verified release. The CLI must work without MCP; configure the optional MCP adapter only if my agent needs it. Ask before admin changes or a restart.
```
**[Download v1.2.0](https://github.com/shanselman/sandbox-mcp/releases/tag/v1.2.0)**: portable CLI + optional MCP server,
bundled Node.js, guest agent and setup instructions. No Node/npm installation needed.
### “Works on my machine.” Caught in 30 seconds.
The dev box had Visual C++ installed. The fresh, **network-off** customer PC did not:
```text
FAIL NativeProof.exe on a fresh Windows Sandbox (29.8s)
why exited with code -1073741515; Missing dependency: VC++ redistributable.
```
Opt in to the verified runtime install, then repeat on another fresh guest:
```text
PASS NativeProof.exe on a fresh Windows Sandbox (30.9s)
baseline PROVISIONED (not a clean-machine pass): VC++ redistributable x64
process exited with code 0
```
Those are [actual measured results](docs/compatibility.md#combined-feature-verification), not illustrative output.
The installer was Microsoft-signed **14.51.36247.0**, downloaded and verified on the host. Guest networking stayed
off. `sbx deps app.exe` diagnoses; `sbx run app.exe --provision auto` installs **only when explicitly requested**.
### What your agent gets
| A clean customer PC | A real desktop to drive | Evidence that survives |
|---|---|---|
| Fresh on every boot; no implicit app-runtime installs | Native UIA: inspect, type, click, toggle, wait | PNGs, bounded recordings, self-contained HTML, optional MP4 |
| Dependency diagnosis; explicit verified provisioning | WinUI, WPF, WinForms, Win32; MSIX/AUMID activation | Process state, exit codes, crash events, reports |
| Network **off / firewall / on** | CLI + MCP share state; verified warm incremental deploy | Installer/uninstaller diffs; detonation observations |
Same clean-machine loop, different frameworks:
| WinUI 3, packaged | WPF, self-contained | Native Win32, packaged |
|---|---|---|
|  |  |  |
These are real offline-guest screenshots, not host mockups. WinUI/WPF were refreshed against the final integrated
source; the full matrix covers seven configurations. Exact builds, timings, startup defects
found and remaining coverage gaps are in the [compatibility evidence](docs/compatibility.md).
[Download/setup](#download-and-try-it-no-nodejs-install) · [Agent setup guide](docs/agent-setup.md) ·
[Measured compatibility and honest limits](docs/compatibility.md) · [CLI and MCP interfaces](#one-engine-two-interfaces)
<details>
<summary>See a fresh, recorded UI Automation session</summary>

This 138 KB animation comes from a new 74-frame guest recording: UIA changes the text, invokes buttons and
increments the counter. The guest was stopped afterward; the HTML viewer, MP4 and frames remained on the host.
No synthetic screenshots. This small fixture proves the automation path; the rich app above shows the real-app use case.
</details>
## Why
**A Windows Sandbox showcase, not a framework gate.** WinUI 3 is welcome, but the entry point is a Windows
executable or package, not a particular UI framework. Bring an app that can run in Sandbox and its prerequisites:
Win32, WinForms, WPF, WinUI, console, PyInstaller or Electron builds use the same clean-machine workflow.
Installers and untrusted files have their own audit/detonation workflows. This is not a promise that every
Windows app or hardware-dependent workload works in Sandbox. See the [measured compatibility matrix](docs/compatibility.md)
and [small source samples](samples/README.md) in this matching checkout for the configurations actually exercised.
[winapp CLI's Sandbox execution](https://github.com/microsoft/winappCli/blob/5f379fb55517b7a47f9aad11885a7c1676dcca2e/docs/sandbox-execution.md)
also supports packaged and unpackaged apps: its `--on sandbox` offers a warm, identity-aware developer loop,
runtime preparation and WinUI diagnostics. sandbox-mcp emphasizes **fresh-by-default clean-machine reports**,
network-off shared-folder mailbox transport, installer/uninstaller diffs and detonation. The tools have
overlapping app support but different defaults and goals; sandbox-mcp never implicitly installs app prerequisites.
Inbox Framework/CBS components can exist, but are not proof that an app's requested runtime is available.
"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". Its supported `wsb`
CLI provides automation; sandbox-mcp adds orchestrated app deployment, UI Automation, clean-machine checks and
durable test evidence around it.
| | sandbox-mcp (Windows Sandbox) | Hyper-V / VMware VM | Windows containers | Cloud dev VMs (devvm, Codespaces, Dev Box) |
|------------------------------|-------------------------------------|----------------------------|------------------------------|--------------------------------------------|
| Real Windows desktop + GUI | ✅ | ✅ | ❌ no desktop | Linux mostly / ✅ (Dev Box) |
| Clean state every run | ✅ always, by design | snapshots to manage | ✅ | ❌ persistent |
| Startup | ~15 s | minutes | seconds | minutes |
| Images to build or download | none (uses your installed Windows) | a 20+ GB VHD | multi-GB base images | none, but it's someone else's computer |
| Cost | free with Windows Pro/Enterprise | free-ish + disk | free | 💸 |
| Runs offline / local | ✅ | ✅ | ✅ | ❌ |
| Parallel instances | ❌ one at a time | ✅ | ✅ | ✅ |
| Persistent environment | ❌ | ✅ | via volumes | ✅ |
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.
## What you can do
`sbx deps <app.exe|folder>` (MCP: `sandbox_deps`) inspects dependencies on the host without running or installing
anything: PE architecture/imports, app-local VC++ DLLs, .NET runtime configs, .NET Framework configs, package
dependencies and script interpreters. `sbx run` includes this diagnosis in its report and names likely missing
runtimes after a failed launch. This is a conservative static scan, not proof that every dynamic dependency is
present. Optional guest components such as WebView2 must be checked in the actual guest.
The default never installs dependencies. To **explicitly opt in**, use `sbx run <app> --provision auto`
(`sandbox_run` parameter `provision: "auto"`), or specify a comma-separated list such as
`--provision desktop:10.0:x64,vcredist:x64`. Supported components: `dotnet:<version>:<arch>`,
`desktop:<version>:<arch>`, `aspnetcore:<version>:<arch>`, `vcredist:<arch>` and
`windows-app-runtime:<major.minor>:<arch>`. Architecture is `x86`, `x64` or `arm64` (explicit lists default
to x64). `sbx provision <host app path> --provision <auto|list>` / `sandbox_provision` does the same in
an already-started sandbox; it never starts or adopts a guest. Unknown versions/architectures or unsupported
auto-provision requests fail explicitly; Java and Python require application-specific setup.
Downloads happen on the **host**, are cached under the sandbox-mcp home `cache\redistributables` folder,
verified with published SHA-512 hashes for .NET and a valid Microsoft Authenticode signature for every
installer, then copied in and installed silently. Guest networking can stay **off**. A cached installer
is reverified before reuse; remove its specific cache file to refresh a mutable VC++/Windows App Runtime
download. Reports record the requested provisioning, completed installs, source and verification details
and say **PROVISIONED (not a clean-machine test)**. A provisioned pass never means the original clean machine
had those runtimes. .NET resolution conservatively stays within the requested major/minor channel and
honors exact-version requests (`rollForward: Disable` / `applyPatches: false`) rather than silently changing
the app configuration. A reboot-required installer result fails the run.
Step-by-step provisioning also writes `provisioning.json` in the run folder and marks `sbx status` /
`sandbox_status`, so switching clients does not lose the non-clean-machine provenance. This records explicit
provisioning only, not arbitrary installers a user runs with `exec`. For a live regression, publish a small
framework-dependent .NET desktop app and run `node test\deps-offline.js <publish folder>` with exclusive use
of Windows Sandbox. The observed optional-component baseline for build 26100.9882 is recorded in
`test\fixtures\sandbox-26100.9882.json`; it is evidence for that build, not a promise about future guest images.
- **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.
## Download and try it (no Node.js install)
Download the **Windows x64 portable ZIP** from the [latest GitHub release](https://github.com/shanselman/sandbox-mcp/releases/latest)
and extract it into its own folder. The standard ZIP bundles Node.js; releases that also offer a `-bun.zip` bundle
the runtime into `sbx.exe`. **Either runtime ZIP is all you need**; the `-bun-relink-source.zip` is only for
rebuilding or relinking. Both include the CLI, MCP server, guest agent and skills. You do not need to clone the repo,
install Node, npm or Bun, or add anything to PATH. Keep the extracted files together and use `sbx.cmd` directly
for CLI-only operation; you do not need an MCP client, server configuration or plugin. The packages are built and
tested on native Windows x64; ARM64 is not currently packaged.
Verify the ZIP against its adjacent `.sha256` file before extracting; the [agent setup guide](docs/agent-setup.md)
does that automatically and preserves existing client configuration.
Open PowerShell in the extracted folder and start with the read-only readiness check:
```powershell
.\sbx.cmd doctor
```
`doctor` explains what is missing and how to fix it. It never enables Windows features, elevates, changes PATH, or
restarts the PC for you. Windows Sandbox is only available on Windows Pro, Enterprise or Education; Windows Home
and Windows Server cannot run it.
If the Sandbox feature is off, open **an administrator PowerShell**, run the command below, then restart Windows:
```powershell
Enable-WindowsOptionalFeature -Online -FeatureName Containers-DisposableClientVM -All
```
After restarting, open **Windows Sandbox from the Start menu once**, then close it. This updates Sandbox and installs
the `wsb` command-line tool that `sbx` uses. Run the check again and try a built-in Windows app:
```powershell
.\sbx.cmd doctor
.\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>` (`out` contains the report and media), even after teardown.
`--open` opens the report. Add `--record` for a self-contained viewer under
`out\recordings\<recordingId>\recording.html` and MP4 when host ffmpeg is available. `SANDBOX_MCP_HOME`
changes the artifact root. No ffmpeg or app runtime is silently installed.
For an MCP client using the standard ZIP, configure its stdio server with the full paths to the bundled runtime and
server. Replace the example folder with the location where you extracted the ZIP:
```json
{
"servers": {
"windows-sandbox": {
"type": "stdio",
"command": "C:\\Users\\you\\Downloads\\sandbox-mcp\\node.exe",
"args": ["C:\\Users\\you\\Downloads\\sandbox-mcp\\src\\server.js"]
}
}
}
```
That is the VS Code `.vscode\mcp.json` shape. For GitHub Copilot CLI's
`%USERPROFILE%\.copilot\mcp-config.json`, use:
```json
{
"mcpServers": {
"windows-sandbox": {
"type": "local",
"command": "C:\\Users\\you\\Downloads\\sandbox-mcp\\node.exe",
"args": ["C:\\Users\\you\\Downloads\\sandbox-mcp\\src\\server.js"],
"tools": ["*"]
}
}
}
```
For the Bun ZIP, replace the `command` and `args` in either example with:
```json
{
"command": "C:\\Users\\you\\Downloads\\sandbox-mcp\\sbx.exe",
"args": ["mcp"]
}
```
For Claude Desktop, use `"mcpServers"` with the same command/args and omit `type` and `tools`.
Restart or reload the client's server configuration, then ask it to run Character Map in a fresh offline Sandbox
and return the report and screenshot. The server writes logs to stderr; stdout is reserved for MCP messages.
## Turn on Windows Sandbox
If you have Windows Pro, Enterprise or Education, you already own one of the best tools in Windows and it's probably
switched off. [Windows Sandbox](https://learn.microsoft.com/windows/security/application-security/application-isolation/windows-sandbox/windows-sandbox-overview)
is a whole, real Windows desktop that:
- **comes with Windows:** nothing to download, no VHD, no license key. It's built from the Windows you're running.
- **is brand new every time:** it boots as clean as the day Windows was installed, in about 15 seconds.
- **is thrown away when you close it:** guest files, registry keys and installed apps are deleted.
Explicitly shared output folders remain on the host as test evidence.
- **is properly isolated:** it runs on its own kernel behind the Microsoft hypervisor (the same hardware
virtualization as Hyper-V), not just a separate user account.
- **is light:** it shares memory and files with your PC where it safely can, and uses your GPU.
Turn it on with one line in an **admin** PowerShell, then restart:
```powershell
Enable-WindowsOptionalFeature -Online -FeatureName Containers-DisposableClientVM -All
```
(Or *Turn Windows features on or off* > tick *Windows Sandbox*.) After the restart, **open Windows Sandbox from the
Start menu once**. That updates it to the Store version, which includes the `wsb` command-line tool this project
drives. Then check everything with:
```powershell
sbx doctor
```
```text
✅ Windows 11 Pro, build 26100
✅ Windows Sandbox feature is on
✅ Virtualization is on
✅ wsb command-line tool: C:\Users\you\AppData\Local\Microsoft\WindowsApps\wsb.exe (Windows Sandbox 0.8.107.0)
✅ Node.js 22.11.0
Ready. Try: sbx run C:\Windows\System32\charmap.exe --open
```
If something's missing, `sbx doctor` says what and how to fix it, and every other command tells you the same thing
if it can't reach Windows Sandbox. The full list of what you need:
- Windows 11 24H2 (build 26100) or later, Pro / Enterprise / Education. Windows Sandbox isn't available on Home or Windows Server.
- Virtualization turned on in your PC's UEFI/BIOS (Intel VT-x or AMD-V). Most PCs ship with it on.
- At least 4 GB of RAM (8 GB recommended), 2 CPU cores and 1 GB of free disk.
- Running inside a VM? Turn on nested virtualization on the host first:
`Set-VMProcessor -VMName <name> -ExposeVirtualizationExtensions $true`.
- Either portable ZIP includes its runtime for Windows x64. If installing from source, use Node.js 20+ (`winget install OpenJS.NodeJS.LTS`).
## Install from source
The clone command below retrieves the public default branch. Check out `v1.2.0` to reproduce that release's
source and WinUI/WPF samples exactly. Samples are not included in the portable ZIP.
```powershell
git clone https://github.com/shanselman/sandbox-mcp
cd sandbox-mcp
npm ci --omit=dev
npm link # puts `sbx` and `sandbox-mcp` on your PATH (or use `node src/cli.js`)
sbx doctor # is Windows Sandbox ready? (see above)
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`):
```powershell
.\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 (optional MCP)
The `sbx` CLI is fully usable without an MCP server. If your agent can run shell commands, use `sbx` (or
`.\sbx.cmd` from the portable ZIP) directly. Configure the MCP adapter only when the client benefits from
discoverable tool schemas, structured tool results and inline screenshot images.
For source installs, use the same client-specific shapes above, replacing the bundled command with your
installed Node executable. For example, VS Code (`.vscode\mcp.json`):
```json
{
"servers": {
"windows-sandbox": {
"type": "stdio",
"command": "node",
"args": ["C:\\path\\to\\sandbox-mcp\\src\\server.js"]
}
}
}
```
Use the Copilot CLI or Claude shape above for those clients; their top-level keys differ from VS Code.
An absolute Node path avoids differences between your terminal PATH and the MCP client's environment.
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 are also agent skills in [`skills/`](skills) that teach agents each workflow: setup, clean-machine runs,
interactive UI testing, installer testing and detonating untrusted files. Copy the ones you want into your agent's
skills folder (for example `~/.copilot/skills/`), or install the plugin below to get them all with the optional MCP adapter.
### Install the agent plugin
The [agent plugin](docs/agent-plugin.md) bundles the MCP adapter and skills, so you don't need to clone anything
or edit MCP configuration. It needs Node.js 20 or later. The plugin is optional if you use the CLI directly.
With GitHub Copilot CLI:
```powershell
copilot plugin marketplace add shanselman/sandbox-mcp
copilot plugin install sandbox-mcp@sandbox-mcp
```
In VS Code, add `shanselman/sandbox-mcp` as a marketplace in **Chat: Open Customizations**, or run
**Chat: Install Plugin from Source**. See the [plugin guide](docs/agent-plugin.md) for details.
## Fast inner loop
Start once, then build and deploy repeatedly into that **warm** sandbox (any framework, no guest prerequisites
installed implicitly):
```powershell
sbx start --network off
powershell -File .\samples\HelloSandbox\build.ps1
sbx deploy .\samples\HelloSandbox\bin C:\apps\HelloSandbox --launch HelloSandbox.exe --restart
sbx shot --window "Hello Sandbox"
# Edit, build, deploy --restart, screenshot again; when done:
sbx stop
```
`deploy` transfers only added/changed files through a fresh shared staging folder, removes deleted files, and verifies
the entire destination using SHA256. Its report includes added/changed/removed/unchanged counts, bytes transferred,
elapsed milliseconds and `verified: true`. `--restart` stops processes whose executable is under the destination before
applying and requires `--launch` to relaunch the app; `--launch` alone launches after verification. Arguments use
`--args "..."`. TCP and network-off shared-folder transport both work.
Use a dedicated destination: **extra guest files there are deleted**. Links, junctions and reparse points are rejected.
If a build changes while staging, deployment fails with `build output changed during deploy; rerun` before touching the
destination. Apply/verification failures restore the previous touched files where possible; rollback failures explicitly
identify the retained guest backup. Stopped processes are not automatically restarted after a failed apply.
`push` / `sandbox_copy_in` still perform a full replacement. `run`, `install-test` and `detonate` still start fresh;
incremental deployment never adopts an unrelated sandbox.
## One engine, two interfaces
The `sbx` CLI and MCP server are two interfaces to the same implementation: both import and use `src/core.js`,
and the higher-level run, installer and detonation workflows are shared too. The CLI is the complete standalone
interface; MCP is an optional adapter for agents that benefit from discoverable tool schemas, structured results
and inline screenshot images. They are not separate engines, and their names or output formats are not meant to
be identical.
For example, both forms run Character Map on a fresh offline guest, capture evidence and destroy the guest:
```powershell
sbx run C:\Windows\System32\charmap.exe --network off
```
Or call MCP tool `sandbox_run` with these arguments:
```json
{
"app": "C:\\Windows\\System32\\charmap.exe",
"network": "off"
}
```
The supported workflows map across the interfaces:
| Workflow | CLI | MCP adapter |
|---|---|---|
| Fresh app test | `sbx run` | `sandbox_run` |
| Guest lifecycle and shared state | `sbx start`, `status`, `stop`, `desktop-release` | `sandbox_start`, `sandbox_status`, `sandbox_stop`, `sandbox_desktop_release` |
| Commands, processes and files | `sbx exec`, `launch`, `proc`, `push`, `pull`, `deploy`, `errors` | `sandbox_exec`, `sandbox_launch`, `sandbox_process`, `sandbox_copy_in`, `sandbox_copy_out`, `sandbox_deploy`, `sandbox_app_errors` |
| UI automation and capture | `sbx ui`, `ui wait`, `shot`, `windows`, `click`, `type` | `sandbox_ui_tree`, `sandbox_ui_action`, `sandbox_ui_wait`, `sandbox_screenshot`, `sandbox_windows`, `sandbox_click`, `sandbox_type` |
| Recording | `sbx record start`, `record stop` | `sandbox_record_start`, `sandbox_record_stop` |
| Dependencies and provisioning | `sbx deps`, `provision` | `sandbox_deps`, `sandbox_provision` |
| Installer and untrusted-file tests | `sbx install-test`, `detonate` | `sandbox_install_test`, `sandbox_detonate` |
| System snapshots | `sbx snapshot`, `diff` | `sandbox_snapshot`, `sandbox_diff` |
Use the CLI's human-readable output and process exit codes in a shell; add `--json` for machine-readable output.
The MCP adapter presents schemas and structured results to compatible clients and can return screenshots inline.
## MCP tools
| Tool | What it does |
|---|---|
| `sandbox_deps` | Host-only conservative dependency diagnosis; does not execute or install the app. |
| `sandbox_provision` | Explicit opt-in verified runtime installation into the current owned guest; persists non-clean provenance. |
| `sandbox_run` | The whole loop in one call: boot, copy/install, launch or run, observe, test script, collect, destroy, report. |
| `sandbox_start` | Boot a fresh sandbox (`network`: on / firewall / off, `memoryMB`, `vGpu`). Waits for the agent and an interactive desktop; reports readiness timings. |
| `sandbox_status` | Is one running, its id/IP/network mode, agent health and current interactive-desktop facts. |
| `sandbox_desktop_release` | End this workflow's desktop turn immediately. |
| `sandbox_stop` | Destroy it. Lists the artifacts left on the host. |
| `sandbox_copy_in` | Copy a host file or folder in (default `C:\apps\<name>`). |
| `sandbox_deploy` | Deploy a host directory into an already running sandbox, transfer only changes and verify hashes; optional launch/restart. |
| `sandbox_copy_out` | Copy a sandbox file or folder out to the run's `out\files`. |
| `sandbox_exec` | Run a PowerShell (or `cmd`) command; returns stdout, stderr, exit code. |
| `sandbox_launch` | Start an EXE or installed package AUMID; returns the app pid and main window. |
| `sandbox_process` | Running? Exit code? Window title? |
| `sandbox_windows` | Visible top-level windows with titles, pids and bounds. |
| `sandbox_screenshot` | PNG of the desktop or one window, returned inline (and saved on the host), with its own `captureId`, bounds and scale. |
| `sandbox_record_start` / `sandbox_record_stop` | Bounded desktop recording: frames stream straight to the host share; stop publishes a self-contained HTML flipbook and MP4 if host ffmpeg is available. |
| `sandbox_click` / `sandbox_type` | Mouse and keyboard, in screenshot coordinates / SendKeys syntax. Click accepts `captureId` (default latest); out-of-image points and moved/resized captured windows are rejected. |
| `sandbox_ui_tree` | The UI Automation tree of a window: type, name, automation id, value, state, supported actions. |
| `sandbox_ui_action` | Find a control by name / automation id / type and click, set a value, toggle, select, expand, read... |
| `sandbox_ui_wait` | Wait for a control (a result, a dialog) to appear. |
| `sandbox_app_errors` | Application event log errors: crashes, hangs, .NET unhandled exceptions. |
| `sandbox_install_test` | The installer loop in one call: snapshot, install, snapshot, optional test, uninstall, snapshot, report what was added and left behind. |
| `sandbox_detonate` | Run an untrusted file (no network by default) and report its processes, lookups, connections, persistence and changes. |
| `sandbox_snapshot` | Record files, registry, services, autoruns and installed programs under a name. |
| `sandbox_diff` | Compare two snapshots: what changed in between. |
## CLI
```text
sbx run <app.exe|folder|app.msix> [--exe <name>] [--args "<args>"] [--console] [--wait <sec>]
[--cert <file.cer>] [--deps <folder>] [--app-id <id>]
[--record] [--provision <auto|list>]
[--test <script.ps1>] [--collect <sandbox path>]... [--keep] [--open]
sbx install-test <setup.msi|.exe|.ps1|.cmd> [--args "/S"] [--uninstall auto|none|"<cmd>"]...
© Scott Hanselman · MIT · shanselman/sandbox-mcp