Windows Sandbox MCP

Windows Sandbox MCP

MCP server that lets a restricted agent run risky commands in a fresh, offline Windows Sandbox guest, without access to anything else on the host. Design and validated wsb.exe behaviour: SPEC.md. Reporting vulnerabilities: SECURITY.md.

wsb-mcp is the name of the executable, the project and the solution.

Agent host ──stdio──> wsb-mcp proxy ──named pipe──> wsb-mcp serve ──> wsb.exe

(agent account) (ACL: agent only) (your account)

Tools

The guest is also stopped when the agent disconnects, after the idle timeout, and when the broker exits.

Build and test

dotnet build

dotnet run --project tests/WsbMcp.Tests # all tests, optional name filter as argument pwsh -NoProfile -File tests/WindowsSandboxTest.Tests.ps1 # psm1 tests

The tests use a fake wsb.exe and do not need Windows Sandbox.

Installation

Two accounts are involved:

• You: the interactive user, who runs the broker.
• The agent: for example AgentSandbox, which runs Claude Code and the proxy.

Requirements: Windows 11 24H2 or later, with Windows Sandbox enabled. To enable it, run this as admin and reboot:

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

The release build is self-contained, so no .NET is needed.

Quick start

1. Install the program (admin; installs below C:\Program Files):

   winget install fmuecke.WsbMcp --scope machine

1. Set up the broker. Run this as you, in a normal terminal, not elevated:

   wsb-mcp setup --agent AgentSandbox --root C:\AgentSandbox

• --root is the folder below which the agent may map folders into the sandbox.
• setup checks the prerequisites, writes the config, and registers a logon task that starts the broker hidden in your desktop session.
• It then starts the broker and prints the next step.

1. Connect Claude Code. As the agent, in Claude Code:

   /plugin marketplace add fmuecke/windows-sandbox-mcp

/plugin install wsb-mcp@windows-sandbox-mcp

   The plugin adds the four tools plus a skill that teaches Claude how to use

them. Without plugins, use this instead: claude mcp add --scope user wsb -- wsb-mcp proxy.

Check everything with wsb-mcp diag, run as you or as the agent. If the broker isn't running, the tools say so and tell you what to run. Once it's running, the next call works without restarting Claude Code.

Commands

The config is %LOCALAPPDATA%\wsb-mcp\config.json. setup writes the first three keys; the others are optional:

{

"agentAccount": "AgentSandbox", "allowedRoot": "C:\\AgentSandbox", "pipeName": "wsb-mcp", "idleTimeoutMinutes": 30, "maxExecTimeoutSeconds": 1800, "startupTimeoutSeconds": 120, "logPath": "%LOCALAPPDATA%\\wsb-mcp\\broker.log" }

Unknown keys are rejected. `wsbPath` overrides `wsb.exe`, for tests.

Why the location matters

The broker runs with your rights. If anyone else could replace its exe, they could run code as you. So serve and setup refuse to run if anyone other than SYSTEM, Administrators, TrustedInstaller or you could do one of the following:

• change the exe;
• add files next to it;
• rename or re-permission any folder on its path.

The winget install below C:\Program Files passes by default. The broker also refuses a config or log inside allowedRoot.

Agent accounts with managed Claude Code settings

If C:\Program Files\ClaudeCode\managed-settings.json restricts MCP servers, admin changes are needed:

• strictKnownMarketplaces: add this repository's marketplace, for /plugin marketplace add.
• allowedMcpServers: add { "serverCommand": ["wsb-mcp", "proxy"] }, the command the plugin runs.
• strictPluginOnlyCustomization containing "mcp": only the plugin route works. Alternatively, define the server centrally in C:\Program Files\ClaudeCode\managed-mcp.json:

  { "mcpServers": { "wsb": { "command": "wsb-mcp", "args": ["proxy"] } } }

Symptom of a blocking policy: /mcp shows "No MCP servers configured".

Without winget

Download the zip for your architecture from the Releases page. CI builds and tests it from its tag, and GitHub signs its build provenance. Verify the zip, and extract it into a folder only admins (or you) can write:

$zip = "$env:USERPROFILE\Downloads\wsb-mcp-<version>-win-x64.zip"

gh attestation verify $zip --repo fmuecke/windows-sandbox-mcp $dir = "$env:ProgramFiles\wsb-mcp" # as admin Expand-Archive $zip -DestinationPath $dir -Force

Then run `& "$dir\wsb-mcp.exe" setup ...` as in step 2. For the Claude side,

setup prints the full exe path to use. SHA256SUMS.txt only detects a damaged download. It does not prove who built the zip; the attestation does.

From source: build a reviewed commit in a clone the agent cannot modify, for example with dotnet publish src/WsbMcp -c Release -r win-x64 -o $dir. That needs the .NET 10 SDK and NuGet access. Never build in a checkout the agent can write, such as one below C:\AgentSandbox.

Verify against the real sandbox

As the agent account, with the broker running:

pwsh -NoProfile -File tests\smoke\real-smoke.ps1 -ProxyExe (Get-Command wsb-mcp).Source -HoldForCtrlC

It runs 22 checks (19 without -HoldForCtrlC):

• folder rules
• read-only input
• no network
• exit codes
• runAs: user
• timeout
• stop on disconnect

At the end it asks you to stop the broker (wsb-mcp stop) and checks that the tools then return the offline hint. Afterwards wsb list must show no sandbox.

Update

Windows locks the exe while the broker runs, so stop it first:

wsb-mcp stop

winget upgrade fmuecke.WsbMcp # admin wsb-mcp start

Troubleshooting

Start with wsb-mcp diag. Common cases:

Uninstall

wsb-mcp uninstall                 # as you: task, config, log

winget uninstall fmuecke.WsbMcp # admin

In Claude Code, as the agent: `/plugin uninstall wsb-mcp` (or `claude mcp remove wsb`).

License

MIT - Florian Mücke, 2026