windows-sandbox-setup — Claude Code skill: setup guide
The windows-sandbox-setup Claude Code skill checks and prepares Windows Sandbox for CLI or MCP workflows. It runs before first use, after a readiness error, or when an active sandbox blocks another one.
MIT ★ 494 updated 2026-11-15
npx skills add shanselman/sandbox-mcp --skill windows-sandbox-setup -a claude-codeWhat windows-sandbox-setup does
The skill runs sbx doctor, explains any reported problems, and presents fixes in order. The check is read-only: it does not enable Windows features, request admin access, or restart the PC. To confirm the setup, the skill can run charmap.exe in the sandbox with networking disabled.
Windows Sandbox requires Windows 11 24H2 or later, in Pro, Enterprise, or Education edition, and the agent must run on that PC. Home and Server editions cannot run it. Enabling the feature or changing virtualization settings usually calls for administrator access and a restart. Windows allows one sandbox at a time, so an existing guest must be checked before it is stopped.
What it helps with
- check Windows Sandbox before its first launch
- find out why
sbxreports that Sandbox is not ready - identify a running guest that blocks another sandbox
- test a program inside the sandbox with networking off
Example prompts for the agent
- Check whether Windows Sandbox is ready for its first run.
- Find out why
sbxsays Windows Sandbox is not ready. - Check which sandbox is running and how to free the slot.
How to install windows-sandbox-setup
1Skills CLI (Vercel)
npx skills add shanselman/sandbox-mcp --skill windows-sandbox-setup -a claude-code2Manually: put the files in place
~/.claude/skills/windows-sandbox-setup/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/windows-sandbox-setup/
1Skills CLI (Vercel)
npx skills add shanselman/sandbox-mcp --skill windows-sandbox-setup -a codex2Manually: put the files in place
.agents/skills/windows-sandbox-setup/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add shanselman/sandbox-mcp --skill windows-sandbox-setup -a cursor2Manually: put the files in place
.cursor/skills/windows-sandbox-setup/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1Command from the source
copilot plugin install sandbox-mcp@awesome-copilot2GitHub CLI
gh skill install shanselman/sandbox-mcp skills/windows-sandbox-setup3Manually: put the files in place
.github/skills/windows-sandbox-setup/SKILL.md1Skills CLI (Vercel)
npx skills add shanselman/sandbox-mcp --skill windows-sandbox-setup -a gemini-cli2Platform CLI
gemini skills install https://github.com/shanselman/sandbox-mcp --path skills/windows-sandbox-setupManually: put the files in place
.devin/skills/windows-sandbox-setup/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about windows-sandbox-setup
How do I install windows-sandbox-setup in Claude Code?
Run npx skills add shanselman/sandbox-mcp --skill windows-sandbox-setup -a claude-code. The skill file is at ~/.claude/skills/windows-sandbox-setup/SKILL.md.
What does windows-sandbox-setup do?
It checks Windows Sandbox readiness, explains reported issues, and can test the setup by launching a program in the sandbox.
What does windows-sandbox-setup need to run?
It needs a PC running Windows 11 24H2 or later, in Pro, Enterprise, or Education edition; the agent must run on that PC. The optional MCP interface needs Node.js 20 or later on PATH and network access for its first download. The CLI does not require the MCP adapter.
Source text
SKILL.md · MIT
--- name: windows-sandbox-setup description: Get Windows Sandbox ready for sandbox-mcp CLI or MCP workflows. Use when sbx or a sandbox tool says "Windows Sandbox isn't ready", when a sandbox is already running and blocks a new one, or before first use. --- # Set up Windows Sandbox Windows Sandbox runs only on **Windows 11 24H2 or later, Pro, Enterprise or Education**. Home and Server editions can't run it, and neither can macOS or Linux hosts. The agent must run on that Windows PC itself. If shell access is available, use the `sbx` CLI; the optional MCP adapter uses the same engine and is not required. ## Check the PC Run the read-only check. It never enables features, elevates or restarts anything. ```powershell sbx doctor ``` If `sbx` isn't on PATH, use the portable ZIP's `.\sbx.cmd` (no Node.js install required). With Node.js and npm, you can also run the one-off check without installing the plugin: ```powershell npx --yes --package=github:shanselman/sandbox-mcp sbx doctor ``` To install the portable package with its bundled Node.js and verified download, follow [the agent setup guide](https://raw.githubusercontent.com/shanselman/sandbox-mcp/main/docs/agent-setup.md). It asks before admin changes or a restart. Exit code 0 means ready. Exit code 1 lists each problem with its `Fix:` line; add `--json` for structured output. `sbx start` and `sbx run` report the same readiness checks as `sandbox_start` and the one-shot MCP tools. ## Fix what it reports Pass the fixes to the user, in order. They usually need an administrator and a restart, so don't run them yourself or try to work around them. - **Sandbox feature off:** in an administrator PowerShell, run `Enable-WindowsOptionalFeature -Online -FeatureName Containers-DisposableClientVM -All`, then restart Windows. - **`wsb` tool missing:** open Windows Sandbox from the Start menu once, then close it. It updates itself from the Microsoft Store, which adds `wsb`. - **Virtualization off:** turn on Intel VT-x or AMD-V in UEFI/BIOS. Inside a VM, the host must enable nested virtualization. - **Node.js too old:** `winget install OpenJS.NodeJS.LTS --source winget`, then restart the agent so it sees the new PATH. - **Home or Server edition:** there is no fix short of a different Windows edition. Tell the user and stop. ## Confirm it works With shell access, run `sbx run C:\Windows\System32\charmap.exe --network off`. Otherwise, call `sandbox_run` with `app: "C:\\Windows\\System32\\charmap.exe"` and `network: "off"`. It should report PASS in under a minute. ## If you chose MCP and its tools don't appear This only affects the optional MCP interface; the CLI remains usable. The plugin starts the server with `cmd /d /c npx --yes github:shanselman/sandbox-mcp#<version>`, which needs Node.js 20 or later on PATH and network access for the first download. Run that command in a terminal to see the error; a working server logs `ready` to stderr and then waits on stdin. Press Ctrl+C to stop it. ## If a sandbox is already running Windows allows one sandbox at a time. Check with `sbx status` or `sandbox_status`. Stop only a guest you own, with `sbx stop` or `sandbox_stop`. If you don't own it, it may hold someone's work, so ask its owner or the user rather than interrupting it. Only with their approval, use the force option. ## Settings Set these in the shell environment for `sbx`, or in the MCP server environment when using that adapter: | Variable | Default | Purpose | |---|---|---| | `SANDBOX_MCP_HOME` | `%LOCALAPPDATA%\sandbox-mcp` | Where runs, screenshots and reports are kept | | `SANDBOX_MCP_ALLOWED_ROOTS` | any folder | `;`-separated host folders that may be copied in | | `SANDBOX_MCP_IDLE_MINUTES` | `30` | Guest shuts down after this long idle; `0` disables | | `SANDBOX_MCP_KEEP_ON_EXIT` | unset | `1` leaves the sandbox running when the client disconnects |
© Scott Hanselman · MIT · shanselman/sandbox-mcp