claudecode-wsl2

A sandboxed AI workspace running Claude Code on Windows. One script to install, PowerShell commands to control it.

How It Works

graph TB
    subgraph win [Your Windows PC]
        terminal[Windows Terminal]
        workspace["%USERPROFILE%\claudecode-workspace\ Your files live here"]
        explorer[Windows Explorer]
    end

    subgraph wsl [Sandbox WSL2 Distro - Ubuntu]
        claude[Claude Code AI assistant]
        sandbox[Filesystem sandbox]
    end

    terminal -->|connects to| claude
    sandbox -->|shared folders| workspace
    explorer -->|browse files| workspace

The key idea: Your AI runs in a sandbox (a mini Linux computer inside your Windows PC). Your files stay on your Windows machine in your user profile at %USERPROFILE%\claudecode-workspace\ (e.g., C:\Users\YourName\claudecode-workspace\). The AI can read and write to those files, but it can't touch anything else on your PC.

What You Need

Windows 10 (build 19041 or later) or Windows 11
WSL2 enabled (the installer will enable it if needed)
An Anthropic account (free to create)
About 10 minutes for the first install

Quick Start

Step 1: Install

Open PowerShell as Administrator (right-click the Start button, choose "Terminal (Admin)" or "PowerShell (Admin)") and paste these three lines:

git clone https://github.com/jaredstanko/claudecode-wsl2.git
cd claudecode-wsl2
powershell -ExecutionPolicy Bypass -File install.ps1

The installer will download and set up everything automatically. You'll see a lot of output scrolling by -- ignore it all until you see the final instructions.

Note: If WSL2 wasn't already enabled, the installer will enable it and ask you to restart your PC. After restarting, run install.ps1 again and it will pick up where it left off.

Step 2: Open a Session

When the install finishes, open Windows Terminal and run:

.\scripts\launch.ps1

A new tab will open connected to your AI workspace.

Step 3: Sign In

Claude Code will ask you to sign in. It opens a browser -- log in with your Anthropic account.

When it asks "Do you trust /home/claude/.claude?" say yes.

Step 4: You're Done

Look for the ClaudeCode-Status icon in your system tray (bottom right, near the clock). From now on, just click New Claude Code Session in the tray menu, or run .\scripts\launch.ps1 in PowerShell.

What You Get

Sandboxed AI -- Claude Code runs inside an isolated WSL2 distro, not directly on your Windows machine
System tray app -- start sessions, stop the distro, open the web portal from one icon
Session resume -- pick up previous conversations where you left off
Shared folders -- %USERPROFILE%\claudecode-workspace\ on Windows is shared with the AI
Health check -- run doctor.ps1 or use the tray menu to check system health
Audio -- WSLg passthrough on Windows 11 (automatic, no config needed)

The System Tray App

After install, ClaudeCode-Status lives in your system tray (bottom right, near the clock). It shows a small icon with a colored dot (green = running, red = stopped).

ClaudeCode-Status tray menu:
  Distro: Running
  Start Distro / Stop Distro
  ------------------
  New Claude Code Session  <- opens a new AI workspace
  Resume Session           <- pick up where you left off
  ------------------
  Open Portal              <- opens the web portal
  Open a Terminal          <- plain shell (no AI)
  ------------------
  Health Check             <- runs doctor.ps1
  Launch at Login
  Quit ClaudeCode-Status

The tray app is compiled from C# source at install time using the .NET Framework compiler (csc.exe) that ships with every Windows 10/11 machine. No build tools or SDKs needed.

Shared Files

Your Windows PC and the AI share files through %USERPROFILE%\claudecode-workspace\:

%USERPROFILE%\claudecode-workspace\
  exchange\    Drop files here -- the AI can read them
  work\        AI outputs and projects
  data\        Datasets and databases
  portal\      Web portal content
  upstream\    Reference repos

AI settings and memory live inside the WSL2 distro at /home/claude/.claude (on the fast ext4 filesystem). Your workspace files live on Windows. You can browse them in Explorer like any other folder on your PC.

Sharing Additional Folders

The quickest way to get files into the distro is the exchange\ folder -- just drop files there.

To give the AI permanent access to a project folder on your Windows machine:

.\scripts\mount.ps1 C:\Projects\my-repo

This adds the folder to the distro's mount table and restarts the distro briefly (~2 seconds). Your directory then appears at /home/claude/my-repo inside the distro with live two-way access.

.\scripts\mount.ps1 -List                                          # See what's shared
.\scripts\mount.ps1 C:\Projects\my-repo -WslMountPath /home/claude/code  # Choose where it appears

Copying Files

To copy individual files in or out, just use the shared claudecode-workspace folder. Drop files into %USERPROFILE%\claudecode-workspace\exchange\ on Windows and they appear at /home/claude/exchange/ inside the distro (and vice versa). There's a "Claude Code Workspace" shortcut on your Desktop for quick access.

You can also copy from the Windows side using the \\wsl$\ path:

# Copy a file from the distro to your Desktop
copy \\wsl$\claudecode\home\claude\work\output.pdf $env:USERPROFILE\Desktop\

Filesystem Isolation

By default, WSL2 mounts the Windows C: drive at /mnt/c/ and allows running Windows executables from Linux. This project blocks both with three layers:

Layer 1: Disable automount (/etc/wsl.conf)

[automount]
enabled=false

Windows drives are never mounted. Claude Code cannot see your files.

Layer 2: Disable interop (/etc/wsl.conf)

[interop]
enabled=false
appendWindowsPath=false

Windows executables (like cmd.exe, powershell.exe) cannot be called from inside the sandbox.

Layer 3: Claude Code sandbox (~/.claude/settings.json)

{
  "permissions": { "deny": ["Read(//mnt/**)", "Edit(//mnt/**)"] },
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~", "//tmp"],
      "denyRead": ["//mnt"],
      "denyWrite": ["//mnt"]
    }
  }
}

Even if the other layers were bypassed, Claude Code's own sandbox rules deny access to /mnt/.

Note: All three layers live inside the VM. An agent with root shell access could theoretically modify these configs. These are defense-in-depth measures against accidental access, not a hard boundary against a compromised agent.

Advanced

Everything below is for power users who want to customize or troubleshoot.

Install Options

.\install.ps1                                  # Normal install
.\install.ps1 -Name v2                         # Parallel install as a separate instance
.\install.ps1 -Name v2 -Port 8082             # Parallel install with specific portal port

Parallel Installs

Use -Name to run multiple instances side by side. Each gets its own WSL2 distro, workspace, and portal port:

.\install.ps1 -Name v2

# Creates:
#   Distro:    claudecode-v2
#   Workspace: %USERPROFILE%\claudecode-workspace-v2\
#   Portal:    http://localhost:8081 (auto-assigned)

All scripts accept -Name to target a specific instance:

.\scripts\launch.ps1 -Name v2
.\scripts\verify.ps1 -Name v2
.\scripts\upgrade.ps1 -Name v2
.\scripts\uninstall.ps1 -Name v2

CLI Commands

.\scripts\launch.ps1                 # New Claude Code session
.\scripts\launch.ps1 -Resume         # Resume a previous session
.\scripts\launch.ps1 -Shell          # Plain shell in the distro (no AI)

Health Check

.\scripts\doctor.ps1                 # Full diagnostic -- checks WSL2, distro, network,
                                     # disk, services, and reports PASS/WARN/FAIL

Verification

.\scripts\verify.ps1                 # Check system health (PASS/FAIL for each component)

Upgrading

cd claudecode-wsl2
git pull
.\scripts\upgrade.ps1

Your workspace, authentication, and sessions are preserved.

Backup & Restore

.\scripts\backup-restore.ps1 backup           # Back up distro + workspace
.\scripts\backup-restore.ps1 restore           # Restore from a backup

Uninstall

.\scripts\uninstall.ps1

Removes the WSL2 distro and launch scripts. Asks before deleting workspace data.

WSL2 Distro Specs

Setting	Default
Runtime	WSL2 (Hyper-V backed)
OS	Ubuntu 24.04 x86_64
CPUs	4
Memory	4 GB
Disk	50 GB (virtual hard disk)
Audio	WSLg (Win 11, automatic)
Display	WSLg Wayland/X11 (Win 11 only)

To resize, create or edit %UserProfile%\.wslconfig:

[wsl2]
processors=6
memory=6GB
swap=8GB

Then restart the distro:

wsl.exe --shutdown
.\scripts\launch.ps1

Audio

Windows 11 (WSLg)

Audio works automatically via WSLg. No configuration needed.

# Inside the distro:
aplay -l
speaker-test -t sine -f 440 -l 1 -p 2

Windows 10

Audio passthrough is not available on Windows 10 (requires WSLg on Windows 11). All text features work fully without audio.

Troubleshooting

Install fails at "Importing distro" -- Run wsl.exe --unregister claudecode then .\install.ps1 again.

WSL2 not available -- Make sure virtualization is enabled in your BIOS/UEFI settings. Run wsl.exe --install from an admin PowerShell to enable WSL2.

No audio -- On Windows 11, audio uses WSLg automatically. Run wsl.exe -d claudecode -- pactl info to check PulseAudio. If it fails, restart WSL with wsl.exe --shutdown and try again. On Windows 10, audio is not available.

Distro shows as "Stopped" -- Run wsl.exe -d claudecode to start it, or .\scripts\launch.ps1.

Slow file access in shared folders -- This is normal for cross-OS file access in WSL2. For best performance on large projects, clone repos inside the distro (/home/claude/) rather than in the shared workspace.

DNS resolution fails -- Add to /etc/wsl.conf:

[network]
generateResolvConf=false

Then: echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

Differences from claudecode-lima (macOS)

Feature	claudecode-lima (macOS)	claudecode-wsl2 (Windows)
VM layer	Lima + VZ framework	WSL2 + Hyper-V
Architecture	ARM64 (Apple Silicon)	x86_64 (typically)
Audio	VirtIO sound device	WSLg (Win 11)
Shared folder	Lima named mounts	fstab + drvfs
Port forwarding	Manual (VM IP)	Automatic (localhost)
VM config	`claudecode.yaml`	`.wslconfig`
Host isolation	VM boundary only	automount + interop disabled + Claude sandbox

Credits

WSL2 -- Windows Subsystem for Linux
WSLg -- GUI and audio support for WSL
Claude Code -- Anthropic's CLI for Claude
Windows Terminal -- Modern terminal for Windows
claudecode-lima -- macOS version

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
config		config
scripts		scripts
trayapp		trayapp
README.md		README.md
install.ps1		install.ps1

Folders and files

Latest commit

History

Repository files navigation

claudecode-wsl2

How It Works

What You Need

Quick Start

Step 1: Install

Step 2: Open a Session

Step 3: Sign In

Step 4: You're Done

What You Get

The System Tray App

Shared Files

Sharing Additional Folders

Copying Files

Filesystem Isolation

Advanced

Install Options

Parallel Installs

CLI Commands

Health Check

Verification

Upgrading

Backup & Restore

Uninstall

WSL2 Distro Specs

Audio

Windows 11 (WSLg)

Windows 10

Troubleshooting

Differences from claudecode-lima (macOS)

Credits

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages