How do I run Claude Code safely on Windows with WSL2?

01Steps

1. Check that your distribution runs WSL2, not WSL1. In PowerShell, wsl -l -v lists each distribution and its WSL version. Convert a WSL1 distribution with wsl --set-version, or install one with wsl --install, which Microsoft's docs say sets new installs to WSL2.

   PowerShell

   wsl -l -v
   wsl --set-version Ubuntu 2

2. Install Claude Code inside WSL. Open the WSL terminal and run the Linux installer there, not from PowerShell. WSL setups do not need Git for Windows.

   WSL terminal

   curl -fsSL https://claude.ai/install.sh | bash

3. Install the sandbox's dependencies. On Linux and WSL2 the sandbox relies on bubblewrap for filesystem isolation and socat to relay network traffic through its proxy. On Ubuntu 24.04 and later, Anthropic's docs also describe an AppArmor profile for bwrap.

   WSL terminal

   sudo apt-get install bubblewrap socat

4. Turn the sandbox on and make it fail closed. Run /sandbox inside a session, or pass settings for one session. failIfUnavailable makes Claude Code exit instead of running unsandboxed when the sandbox cannot start, and allowUnsandboxedCommands: false stops the unsandboxed retry.

   WSL terminal

   claude --settings '{"sandbox": {"enabled": true, "failIfUnavailable": true, "allowUnsandboxedCommands": false}}'

5. For a VM boundary, install kosa8 and set up its WSL2 engine. Install kosa8 from PowerShell (no administrator rights needed), then run kosa8 wsl setup once. It checks WSL2 and nested virtualization, installs kosa8's Linux engine into an Ubuntu distribution, starts it and connects the Windows CLI to it. kosa8 wsl status shows the connection, and the last command proves a sandbox boots.

   PowerShell

   irm https://kosa8.com/install.ps1 | iex
   kosa8 wsl setup
   kosa8 wsl status
   kosa8 run alpine echo hi

6. Run Claude Code in its own microVM. Set your API key on the Windows side only, read the plan with --dry-run, then run the claude kit from your project folder. The sandbox sees one folder, reaches only the hosts the kit lists, and holds a placeholder instead of your key. kosa8's docs do not yet describe how a Windows folder is shared through the WSL2 engine, so check the workspace line the dry run prints and try it first on a copy of a project.

   PowerShell

   $env:ANTHROPIC_API_KEY = "sk-ant-..."
   kosa8 agent run --dry-run claude
   kosa8 agent run claude

7. Review what it did. Every brokered request and every tool call is in a hash-chained audit log. Risky calls such as a force push wait for a person in kosa8 mcp asks.

   PowerShell

   kosa8 audit ls
   kosa8 audit verify
   kosa8 mcp asks

02Does Claude Code's sandbox work on native Windows or WSL1?

No. Anthropic's documentation says the sandbox runs on macOS, Linux and WSL2, and that on native Windows Claude Code runs commands unsandboxed. WSL1 is not supported either: if Claude Code reports "Sandboxing requires WSL2", the distribution is running WSL1 and needs converting with wsl --set-version.

Anthropic's setup page sums it up in one table: native Windows (sandboxing not supported), WSL 2 (supported), WSL 1 (not supported). By default, if the sandbox cannot start because a dependency is missing or the platform is unsupported, Claude Code runs commands without it. Set sandbox.failIfUnavailable to true so a missing sandbox stops the session instead of passing silently.

Inside WSL2 the sandbox uses bubblewrap, the same as on Linux, and a sandboxed command runs in a separate network namespace that reaches the network only through Claude Code's proxy. Your Windows drives are normally mounted under /mnt/c in WSL, so if the agent should not read them, add those paths to sandbox.filesystem.denyRead.

03What does kosa8 wsl setup do?

It checks for WSL2 and nested virtualization, installs kosa8's Linux engine into a Debian or Ubuntu distribution, starts it and connects the Windows kosa8 command to it. It needs Windows 11 on an x86-64 PC; Windows 10 and Windows on ARM connect to an Apple silicon Mac or a Linux machine that runs the sandboxes instead.

• WSL version. A WSL1 distribution is refused with the wsl --set-version command to convert it. --distro picks a distribution other than WSL's default.
• Nested virtualization. If WSL2 has no /dev/kvm, it turns on nestedVirtualization in %USERPROFILE%\.wslconfig and asks you to run wsl --shutdown; it never stops your distributions itself.
• The engine. It installs virtiofsd and Cloud Hypervisor v53.0, checked against a pinned SHA-256 digest, then the same kosa8 release, and starts the daemon on 127.0.0.1:7440 with a token only your user can read.

This is a preview. kosa8 lists Windows 11 on x86-64 as running sandboxes through WSL2 (preview); Apple silicon Macs and x86-64 Linux are the platforms without that label.

04What does a microVM add over Claude Code's sandbox in WSL2?

Bubblewrap isolates commands with namespaces on the WSL2 kernel that the rest of your distribution also uses, and it wraps Bash commands rather than every tool. A kosa8 microVM gives Claude Code a Linux kernel of its own, one shared folder, a network closed except for the hosts its kit names, and a placeholder instead of your Anthropic API key.

• Every tool, not only Bash. Claude Code's own file tools and any MCP server it starts run inside the VM too.
• The key stays outside. A broker on your side adds the real key to requests to api.anthropic.com.
• Checked tool calls. With the claude kit, a download piped into a shell is refused and a force push waits for kosa8 mcp approve.
• The shared folder is still shared. Claude Code can change anything in it, including .git. Commit first.

05Other options

• Claude Code's /sandbox in WSL2 fits most day-to-day work, with failIfUnavailable and denyRead set as above.
• A dev container fits teams that already use one; Anthropic documents a dev container setup for Claude Code with an example egress firewall, and Docker Desktop on Windows can run on a WSL2 backend.
• Docker Sandboxes runs coding agents in isolated microVM sandboxes from Docker's tooling.
• A full VM in Hyper-V or another hypervisor fits when you want a long-lived Linux workstation and are happy to manage it.
• Hosted sandboxes such as E2B, Daytona or Modal fit when the agent should run in the cloud rather than on your PC.

Related guides

• How do I run Claude Code safely on a Mac?
• How to run Claude Code safely on Linux
• Is it safe to use claude --dangerously-skip-permissions?
• Docker containers vs microVMs: which isolates an AI agent better?
• How do I give an AI agent API keys without exposing them?
• How do I restrict an AI agent's network access to an allow-list?
• How do I undo what an AI coding agent did?