16 KiB
A copy of the boilerplate's
documentation/Install WSL.mdat commit 09e144d, unedited below this line; the fix lands upstream first.
Abstract
The sandbox is a WSL distro. Claude Code runs inside it from the desktop app with all permissions, because the distro cannot reach anything on Windows. Interops is turned off, no drives are mounted, and to keep it this way admin permissions are not granted.
Root is reached only from Windows, with wsl -d claudebox -u root. That is how you install and update packages later.
The repos live inside the distro in /home/claude/cboxcode. Working from Windows covers working with them from Windows.
Install
1. Check that WSL 2 runs
PS> wsl --status
It should say Default Version: 2 and nothing about virtualisation.
If it says virtualisation is not enabled, run wsl.exe --install --no-distribution once in an admin PowerShell and reboot. If it still complains, switch on Intel VT-x or AMD-V in the BIOS. This is the only step that can need admin rights.
If a claudebox from an earlier attempt exists, wsl -l -v lists it. wsl --unregister claudebox deletes it with everything inside.
2. Install Ubuntu as claudebox
PS> wsl --install Ubuntu-24.04 --name claudebox --no-launch --web-download
--name claudeboxnames the distro, so it does not collide with an ordinary Ubuntu.--no-launchskips Ubuntu's first-start wizard, which would create a user with sudo. We create our own user in step 5.--web-downloaddownloads it directly instead of through the Microsoft Store.
3. Open a root shell
PS> wsl -d claudebox -u root
The prompt changes to something like root@PC:/mnt/c/...#. You are now inside Linux as root. C: is still visible at this point; step 7 takes it away.
4. Update and install packages
# apt update
# apt upgrade -y
# apt install -y build-essential git curl ripgrep sqlite3 jq unzip
apt update fetches the package lists, apt upgrade installs updates, and apt install adds the tools: compilers for Python packages that build from source, git, curl, ripgrep for Claude's searches, sqlite3 to look into the databases, jq for JSON, unzip.
5. Create the user claude, without sudo
# useradd --create-home --shell /bin/bash claude
# groups claude
useradd creates the user with a home directory and bash. It gets no password and no groups. groups claude must print only claude : claude. If sudo appears there, the user can become root, and gpasswd -d claude sudo removes it.
# passwd -l root
This locks root's password, so su cannot become root from inside either. Ubuntu ships it locked, so this only makes sure.
6. Install uv and Claude Code as claude
Switch to the user. Root can do that without a password:
# su - claude
The prompt ends in $ now. Install the two tools into ~/.local/bin, which belongs to claude, so they update without root:
$ curl -LsSf https://astral.sh/uv/install.sh | sh
$ curl -fsSL https://claude.ai/install.sh | bash
$ echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
The third line puts ~/.local/bin on the path for every new shell.
Set the git identity, with your own name and email, and create the folder for the repos:
$ git config --global user.name "Your Name"
$ git config --global user.email "you@example.com"
$ git config --global init.defaultBranch main
$ mkdir ~/cboxcode
Back to root:
$ exit
7. Cut the distro off from Windows
/etc/wsl.conf is the file WSL reads when the distro starts. Open it in the editor:
# nano /etc/wsl.conf
Delete what is there and type this:
[boot]
systemd=true
[user]
default=claude
[automount]
enabled=false
mountFsTab=false
[interop]
enabled=false
appendWindowsPath=false
[user] default=claudemakes every normal start log in asclaude, not root.[automount] enabled=falsestops WSL from mountingC:and the other drives under/mnt.mountFsTab=falsealso ignores/etc/fstab, so no other way of mounting them applies.[interop] enabled=falsestops Linux from starting Windows programs. That includeswsl.exe, which would otherwise be a way back to root.appendWindowsPath=falsekeeps the Windows folders off the Linux path.[boot] systemd=trueis Ubuntu's default and stays.
Save with Ctrl+O then Enter, quit with Ctrl+X.
The first start in step 3 left an empty folder per Windows drive under /mnt. Nothing will be mounted on them any more, so remove them to avoid confusion. rmdir only removes empty folders, so it cannot delete anything:
# rmdir /mnt/c /mnt/d
Name every drive letter that ls /mnt shows. wsl and wslg belong to WSL and stay. Leave the distro:
# exit
WSL only reads the file on a fresh start, so stop the distro:
PS> wsl --terminate claudebox
8. Check the isolation
Start it the normal way, which now logs in as claude:
PS> wsl -d claudebox
Each check and what it must answer:
$ whoami
claude
$ groups
claude
$ passwd -S claude
claude L ...
$ sudo -n true
sudo: a password is required
$ ls /mnt
wsl wslg
$ uv --version
$ claude --version
groupsshowing onlyclaudemeans no admin group, so sudo refuses even with a password.Linpasswd -Smeans the password is locked: no password exists, so nothing can be typed at a sudo or su prompt that works. A plainsudostill asks for one, and any answer fails.ls /mntshowing no drive letters means no Windows drive is there.mount | grep -i drvfsprinting nothing confirms it.- The last two print version numbers.
The real test that Windows programs cannot start needs one. In a second PowerShell window, copy a harmless one in from Windows, run it inside, and delete it again:
PS> Copy-Item C:\Windows\System32\whoami.exe \\wsl.localhost\claudebox\tmp\
PS> wsl -d claudebox -- /tmp/whoami.exe
PS> Remove-Item \\wsl.localhost\claudebox\tmp\whoami.exe
With interop off it prints no Windows user name, only a WSL error after a few seconds. If it prints your Windows name, step 7 did not take.
If any check answers differently, the step it belongs to did not take: 5 for groups and passwd, 7 for /mnt and whoami.exe.
$ exit
PowerShell 7
Our scripts are running on powershell 7, which needs to be installed.
Then, set it to the default profile in the terminal app.
PS> winget install Microsoft.PowerShell
The execution policy
Running commands in the WSL need extra permissions:
PS> pwsh -ExecutionPolicy Bypass -File <command>
This is one reason why we add all important commands into the profile
PyCharm
Remote execution agent failure
PyCharm on Windows is not able to read folders on the cut-off WSL. Its bundled plugin Remote Execution Agent copies a helper called IJent into the distro from /mnt/c/Program Files/JetBrains/... and reads files and runs Git through it. With the drives unmounted the copy fails: opening a file reports "unable to locate", Git reports execvpe(.../ttyfix) failed, and idea.log shows cp: cannot stat '/mnt/c/...ijent...'.
So you need to disable the plugin: Settings > Plugins > Installed, search for Remote Execution Agent, untick it, restart PyCharm.
Git
Set Settings > Version Control > Git > Path to Git executable to C:\Program Files\Git\cmd\git.exe, so it uses Windows Git instead of trying to start the distro's.
Run configurations
We currently don't use them.
Maintenance
Update
Packages, as root from Windows:
PS> wsl -d claudebox -u root -- apt update
PS> wsl -d claudebox -u root -- apt upgrade -y
Claude Code updates itself. uv updates with the line below. The full path is needed because a command passed from PowerShell does not load ~/.bashrc:
PS> wsl -d claudebox -- /home/claude/.local/bin/uv self update
Remove WSL
Remove the distro with all repos in it, after pushing what matters:
PS> wsl --unregister claudebox
Getting it ready for use
Git
Tell Windows Git to trust that folder, since its files belong to the Linux user:
PS> git config --global --add safe.directory '%(prefix)///wsl.localhost/claudebox/home/claude/cboxcode/news'
git config core.autocrlf false stops Git from converting line endings in this repo. git checkout -- . rewrites the files Windows Git checked out with Windows line endings, so Linux Git does not report every line as changed.
Working from Windows
The only direction that works is Windows into WSL: Windows reads and writes the checkout through \\wsl.localhost\<distro>\... and starts processes with wsl.exe. The distro never reaches back. Editing and the Git UI happen on Windows; the agents, the tests, serve, the jobs, uv sync, release step 1 and db.sh run in the distro, typed from Windows through the profile commands below; release steps 2 and 3 run on Windows with wslc, since the distro must not hold a container socket.
A .venv belongs to one OS: bin/python on Linux, Scripts\python.exe on Windows. The .venv in the checkout is the distro's. A Windows uv sync or uv run in that folder would replace it with a Windows one, and the distro's next uv run would swap it back, so run uv in the distro (<folder>-sh opens a shell there). A Windows interpreter for an editor's code insight belongs outside the checkout.
Run the app in the distro, not from Windows. Only one side may open a SQLite file at a time, since locking through the share is unreliable, and file change notifications through the share are unreliable too, so --reload started from Windows can miss edits.
WSL Containers for the image
We don't need Docker Desktop but build images directly on WSL with wslc. It needs WSL 2.9.3 or later:
PS> wsl --update
PS> wsl --version
PS> wslc version
Log it in to the registry once, with a token that has package-write access, typed at its password prompt:
PS> wslc login git.rittershofer.org -u wolf
Env files
Once per checkout, including every new repo, and again when DISTRO or CHECKOUT changes:
- Copy
deploy/release.env.exampletodeploy/release.envin the checkout (cpin the distro, or Explorer) and fill inDISTRO(claudebox),CHECKOUT(the path in the distro,/home/claude/cboxcode/news) andIMAGE. The file is gitignored.
PS Profile commands
We want a simple way to run and deploy the app, cd into the repo. So we have script adding the relevant commands to the PS profile:
PS> pwsh -ExecutionPolicy Bypass -File \\wsl.localhost\claudebox\home\claude\cboxcode\news\deploy\wsl-setup.ps1
It creates commands into the profie
The prefix is the checkout folder's name, news- for news and boilerplate- for boilerplate; -Name on the .ps1 sets another. The setup writes one block between # >>> news (deploy/wsl-setup.ps1) >>> and # <<< news (deploy/wsl-setup.ps1) <<< into $PROFILE and replaces it when run again. Blocks written by older versions of the setup, newsdesk (deploy/wsl-setup.ps1) and wsl shared (deploy/wsl-setup.ps1), call scripts that no longer exist; delete them with notepad $PROFILE.
| Command | Runs | Does |
|---|---|---|
news-cd |
Set-Location |
PowerShell into the checkout's folder |
news-sh |
wsl.exe |
a shell in claudebox, in the checkout |
news-backend [-v] |
bin/backend.sh in claudebox |
uv run app serve on :8787, until Ctrl-C |
news-frontend |
bin/frontend.sh in claudebox |
Vite with hot reload on :5173, until Ctrl-C |
news-check |
bin/check.sh in claudebox |
the gate on the working tree, without promoting |
news-1test [--push-branch] [--no-tests] |
deploy/1-test-and-promote.sh in claudebox |
test local main, fast-forward production, export it |
news-2build |
deploy\2-build-image.ps1 on Windows |
build the exported tree with wslc, tags <sha> and latest |
news-3push |
deploy\3-push-image.ps1 on Windows |
push both tags with wslc |
news-0release [--push-branch] [--no-tests] |
the three above | 1test, 2build, 3push, stopping at the first that fails |
<folder>-db pull|push |
deploy/db.sh in claudebox |
only where deploy/db.sh exists, as in the boilerplate |
If the setup does not run, paste the block by hand. New-Item -Force $PROFILE creates the file if Test-Path $PROFILE says it is missing; notepad $PROFILE opens it. For news, with DISTRO=claudebox and CHECKOUT=/home/claude/cboxcode/news, the setup writes exactly this:
# >>> news (deploy/wsl-setup.ps1) >>>
function news-cd { Set-Location '\\wsl.localhost\claudebox\home\claude\cboxcode\news' }
function news-sh { wsl.exe -d claudebox --cd /home/claude/cboxcode/news }
function news-backend { wsl.exe -d claudebox --cd /home/claude/cboxcode/news -- bash bin/backend.sh @args }
function news-frontend { wsl.exe -d claudebox --cd /home/claude/cboxcode/news -- bash bin/frontend.sh @args }
function news-check { wsl.exe -d claudebox --cd /home/claude/cboxcode/news -- bash bin/check.sh @args }
function news-1test { wsl.exe -d claudebox --cd /home/claude/cboxcode/news -- bash deploy/1-test-and-promote.sh @args }
function news-2build { & (Get-Process -Id $PID).Path -NoProfile -ExecutionPolicy Bypass -File '\\wsl.localhost\claudebox\home\claude\cboxcode\news\deploy\2-build-image.ps1' }
function news-3push { & (Get-Process -Id $PID).Path -NoProfile -ExecutionPolicy Bypass -File '\\wsl.localhost\claudebox\home\claude\cboxcode\news\deploy\3-push-image.ps1' }
function news-0release { news-1test @args; if ($LASTEXITCODE -ne 0) { return }; news-2build; if ($LASTEXITCODE -ne 0) { return }; news-3push }
# <<< news (deploy/wsl-setup.ps1) <<<
For another checkout, replace news and the path.
When a command fails
wsl -l -vlists the distros.DISTROmust be one of the names exactly.Test-Path \\wsl.localhost\claudebox\home\claude\cboxcode\newsmust sayTrue.\\wsl$\claudebox\...is the older spelling of the same share; if only that one answers, use it in the block.$PROFILEprints the profile file this PowerShell loads, andGet-Command news-*lists the commands it defined. Commands missing in one PowerShell and present in another means the setup ran in the other one.Get-ExecutionPolicy -Listshows the policy per scope.RestrictedorAllSignedwhere it applies means the profile does not load; aMachinePolicyorUserPolicyentry is group policy and overridesCurrentUser.wslc versionfailing means WSL is older than 2.9.3:wsl --update.news-2buildsaying there is noproductionfile means step 1 has not exported yet: runnews-1test.- If
wslc buildrefuses the\\wsl.localhostfolder as its context, which Microsoft's documentation neither promises nor rules out, copy the tree to Windows and build there:Copy-Item -Recurse \\wsl.localhost\claudebox\home\claude\cboxcode\release\news\<sha> $env:TEMP\release-<sha>, then thewslc buildline of2-build-image.ps1with that folder.
Kill and restart
Run everything in an admin PowerShell on Windows.
Normal shutdown
wsl --shutdown
Killing it
If normal shutdown hangs:
taskkill /f /im wsl.exe
taskkill /f /im wslhost.exe
taskkill /f /im wslrelay.exe
Check the service
sc queryex WslService
If it says STOP_PENDING or START_PENDING, take the PID from the output and run taskkill /PID <PID> /F.
If it says STOPPED, start it with sc start WslService, then run wsl.
Kill a lingering VM
IF it still does not work check the VM
hcsdiag list
hcsdiag kill <ID>
If the old WSL VM is still listed, kill it with the ID shown. This was reported as the only fix short of a reboot in a complete-freeze case.
Restart the Hyper-V Host Compute Service
Restart-Service vmcompute
A wedged vmcompute service is a common reason WSL stops working after it ran fine earlier in the same Windows session.
If it still hangs after all four, a reboot is the reliable fix.
Once it’s back up, running wsl --update is worth doing, since hangs like this are often fixed in newer versions.
Pitfalls
- Only open the distro from a normal PowerShell. Opened from an admin one, WSL mounts the Windows drives despite
automountbeing off (microsoft/WSL#12443).wsl --terminate claudeboxand a normal shell undo it. - Changes to
/etc/wsl.confapply only afterwsl --terminate claudebox.