Files
jobboard/docs/Install WSL.md
T

16 KiB
Raw Blame History

A copy of the boilerplate's documentation/Install WSL.md at 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 claudebox names the distro, so it does not collide with an ordinary Ubuntu.
  • --no-launch skips Ubuntu's first-start wizard, which would create a user with sudo. We create our own user in step 5.
  • --web-download downloads 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=claude makes every normal start log in as claude, not root.
  • [automount] enabled=false stops WSL from mounting C: and the other drives under /mnt. mountFsTab=false also ignores /etc/fstab, so no other way of mounting them applies.
  • [interop] enabled=false stops Linux from starting Windows programs. That includes wsl.exe, which would otherwise be a way back to root. appendWindowsPath=false keeps the Windows folders off the Linux path.
  • [boot] systemd=true is 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
  • groups showing only claude means no admin group, so sudo refuses even with a password.
  • L in passwd -S means the password is locked: no password exists, so nothing can be typed at a sudo or su prompt that works. A plain sudo still asks for one, and any answer fails.
  • ls /mnt showing no drive letters means no Windows drive is there. mount | grep -i drvfs printing 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:

  1. Copy deploy/release.env.example to deploy/release.env in the checkout (cp in the distro, or Explorer) and fill in DISTRO (claudebox), CHECKOUT (the path in the distro, /home/claude/cboxcode/news) and IMAGE. 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 -v lists the distros. DISTRO must be one of the names exactly.
  • Test-Path \\wsl.localhost\claudebox\home\claude\cboxcode\news must say True. \\wsl$\claudebox\... is the older spelling of the same share; if only that one answers, use it in the block.
  • $PROFILE prints the profile file this PowerShell loads, and Get-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 -List shows the policy per scope. Restricted or AllSigned where it applies means the profile does not load; a MachinePolicy or UserPolicy entry is group policy and overrides CurrentUser.
  • wslc version failing means WSL is older than 2.9.3: wsl --update.
  • news-2build saying there is no production file means step 1 has not exported yet: run news-1test.
  • If wslc build refuses the \\wsl.localhost folder 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 the wslc build line of 2-build-image.ps1 with 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 automount being off (microsoft/WSL#12443). wsl --terminate claudebox and a normal shell undo it.
  • Changes to /etc/wsl.conf apply only after wsl --terminate claudebox.