Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add shanselman/sandbox-mcp --skill windows-sandbox-setup -a claude-code
Open on GitHub

What 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 sbx reports 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 sbx says 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-code

2Manually: put the files in place

~/.claude/skills/windows-sandbox-setup/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/windows-sandbox-setup/

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

Similar skills

All skills for Security →

From the same set6

Project sponsors

Companies that keep this analytics open