███████╗ █████╗ ███╗   ██╗██████╗ ██████╗  ██████╗ ██╗  ██╗
██╔════╝██╔══██╗████╗  ██║██╔══██╗██╔══██╗██╔═══██╗╚██╗██╔╝
███████╗███████║██╔██╗ ██║██║  ██║██████╔╝██║   ██║ ╚███╔╝
╚════██║██╔══██║██║╚██╗██║██║  ██║██╔══██╗██║   ██║ ██╔██╗
███████║██║  ██║██║ ╚████║██████╔╝██████╔╝╚██████╔╝██╔╝ ██╗
╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝╚═════╝ ╚═════╝  ╚═════╝ ╚═╝  ╚═╝

WSL Ubuntu Sandbox Guide

Focus: Standing up a disposable, isolated Ubuntu on Windows for experiments — spin-up, snapshot, blast-radius containment, and a one-command nuke — so a risky install or a customer repro never lands in your real dev distro.

Overview

The wsl/ guide covers WSL as your primary dev environment. This one covers the opposite posture: a distro you expect to break. The whole workflow is four verbs on the same wsl.exe binary you already have — no extra tooling, no VM images to download.

The important thing to internalise before you trust it with anything dangerous: all WSL 2 distros run inside one shared lightweight utility VM. Per Microsoft's own architecture note, distros "share the same network namespace, device tree (other than /dev/pts), CPU/Kernel/Memory/Swap, /init binary, but have their own PID namespace, Mount namespace, User namespace, Cgroup namespace, and init process." The hard wall is the Hyper-V boundary between the VM and Windows — not the boundary between two distros.

Which tier do you actually need?

Official Documentation

Quickstart — a throwaway Ubuntu in 60 seconds

# Stand up a SECOND Ubuntu named "lab" — --name is what makes a second
# copy of an already-installed distro possible.
wsl.exe --install Ubuntu-24.04 --name lab --no-launch

# Enter it
wsl.exe -d lab

# ...break things...

# Nuke it. Instant. Unrecoverable. That's the point.
wsl.exe --unregister lab

From PowerShell, drop the .exe. Everything below uses wsl (PowerShell form) except where a Linux-side command is being run.

Confirm what's installed and which VM version each distro is on:

wsl.exe --list --verbose
wsl.exe --version          # verify your WSL build supports the flags below
wsl.exe --list --online    # real, current distro names for --install

--list --online today includes Ubuntu-26.04, Ubuntu-24.04, Ubuntu-22.04, Debian, kali-linux, archlinux, FedoraLinux-44, and the AlmaLinux / openSUSE / SUSE / Oracle families. Use the NAME column verbatim.

Placing and sizing the sandbox

Put the sandbox VHDX somewhere you don't mind filling up, and cap it:

wsl --install Ubuntu-24.04 `
  --name lab `
  --location D:\wsl\lab `
  --vhd-size 40GB `
  --no-launch

Snapshot and restore

This is the part that turns a second distro into a sandbox. Get the environment to a known-good state, export it, and from then on every experiment starts from that file.

Take the golden snapshot

# Terminate first so the filesystem is quiescent
wsl --terminate lab

# tar is the portable format; tar.gz / tar.xz trade CPU for size
wsl --export lab D:\wsl\snapshots\lab-clean.tar.gz --format tar.gz

--format accepts tar, tar.gz, tar.xz, and vhd. The older --vhd switch is still accepted and is equivalent to --format vhd. A .vhdx export restores fastest (no untar) but is far larger and only meaningful for WSL 2.

<FileName> can be - for stdout (and - for stdin on import), so an export can be streamed into another tool. Do this from cmd or a POSIX shell, not PowerShell — PowerShell's object pipeline mangles binary streams:

# Git Bash / WSL — stream a snapshot straight to a compressor or a remote host
WSL_UTF8=1 wsl.exe --export lab - | zstd -T0 -19 -o /d/wsl/snapshots/lab-clean.tar.zst

Restore into a fresh distro

wsl --import lab-2 D:\wsl\lab-2 D:\wsl\snapshots\lab-clean.tar.gz --version 2
wsl -d lab-2

For a .vhdx you want to attach without copying (fast, but the file becomes the live disk):

wsl --import-in-place lab-3 D:\wsl\images\lab.vhdx

The VHD must be formatted ext4.

The reset loop

# One experiment, start to finish
wsl --unregister lab
wsl --import lab D:\wsl\lab D:\wsl\snapshots\lab-clean.tar.gz --version 2
wsl -d lab -- bash -lc './experiment.sh'

Because --unregister deletes the root filesystem outright, this loop is genuinely a few seconds. Treat lab-clean.tar.gz as immutable and never export over it from a dirty distro.

Post-import housekeeping

An imported distro has no launcher executable, which breaks the usual ubuntu config --default-user trick. Use wsl --manage instead:

wsl --manage lab --set-default-user amani     # imported distros boot as root otherwise
wsl --manage lab --set-sparse true            # auto-reclaim freed disk space
wsl --manage lab --resize 60GB                # grow (or shrink) the VHDX
wsl --manage lab --move E:\wsl\lab            # relocate the distro's disk

Or set it inside the distro before you snapshot, in /etc/wsl.conf:

[user]
default=amani

Containing the blast radius

A fresh distro is not contained by default: it automounts your Windows drives and can launch Windows binaries as you. Harden it in /etc/wsl.conf before you take the golden snapshot.

# Inside the sandbox distro
sudo tee /etc/wsl.conf >/dev/null <<'EOF'
# Do not mount C:\ (and friends) into the sandbox at all.
[automount]
enabled = false
mountFsTab = false

# Do not let Linux processes launch Windows binaries, and keep the
# Windows PATH out of $PATH.
[interop]
enabled = false
appendWindowsPath = false

[network]
hostname = lab
generateResolvConf = true

[user]
default = amani

[boot]
systemd = true
EOF

Then, from Windows:

wsl --terminate lab   # settings only apply after the distro fully stops

What each switch buys you:

Microsoft's enterprise guidance is explicit about why automount matters: when a Linux binary in WSL touches a Windows file, it does so with the permissions of the Windows user who ran wsl.exe. Root inside the sandbox is not root on Windows — but it is you on Windows, for every file you can reach.

What you still don't get

Be honest with yourself about the boundary, especially before running anything you'd call malware:

• Shared kernel. Every distro runs on the one microsoft-standard-WSL2 kernel. A kernel-level exploit escapes the distro boundary into the VM. It does not escape the Hyper-V boundary into Windows — that's the wall that counts.
• Shared network namespace. Distros share it. A listener bound in the sandbox collides with your dev distro's :3000, and a process in the sandbox can reach services your dev distro is serving on localhost.
• Shared /mnt/wsl. A tmpfs visible from every running distro. Anything written there is cross-distro.
• .wslconfig is VM-global. There is no per-distro memory or CPU cap. memory=8GB caps the entire VM shared by dev and sandbox.
• wsl --debug-shell opens a root shell in the utility VM itself. It's a diagnostic tool; it's also a reminder of where the real boundary sits.
• Docker Desktop registers its own docker-desktop distro in the same VM.

For anything genuinely hostile: a full Hyper-V VM (or Windows Sandbox, or a disposable cloud box) — not a WSL distro.

Resource limits with .wslconfig

.wslconfig lives on the Windows side at %UserProfile%\.wslconfig and governs the whole WSL 2 VM. Keeping a runaway make -j$(nproc) in the sandbox from freezing Windows is exactly what it's for.

# %UserProfile%\.wslconfig   —  applies to the VM shared by ALL WSL 2 distros
[wsl2]
memory=8GB              # default: 50% of host RAM
processors=4            # default: all logical processors
swap=4GB                # default: 25% of memory, rounded up to the nearest GB
swapFile=D:\\wsl\\swap.vhdx
defaultVhdSize=64GB     # cap new distro disks (default 1 TB)
vmIdleTimeout=60000     # ms of idle before the VM shuts down (Windows 11)
nestedVirtualization=true
localhostForwarding=true

[experimental]
autoMemoryReclaim=gradual   # reclaim cache slowly instead of dropCache
sparseVhd=true              # every new VHDX is sparse — disk comes back on delete

Notes that will save you an hour:

• Paths need escaped backslashes (D:\\wsl\\swap.vhdx). Sizes take GB/MB suffixes; bare numbers are bytes.
• Nothing applies until the VM restarts. Run wsl --shutdown — a --terminate of one distro is not enough. Give it ~8 seconds before relaunching.
• A malformed file is silently ignored. WSL boots with defaults and tells you nothing. Verify with free -h and nproc inside a distro after the shutdown.
• Windows 11 ships a WSL Settings GUI app that edits this file; it's the recommended path over hand-editing.

Per-experiment limits

Since .wslconfig can't cap a single distro, cap the workload instead — systemd-run inside the sandbox:

# Needs [boot] systemd=true in the sandbox's wsl.conf
sudo systemd-run --scope \
  -p MemoryMax=2G -p CPUQuota=200% -p TasksMax=512 \
  ./experiment.sh

(--user scopes work too, but only where systemd has delegated the memory and pids controllers to the user slice — sudo is the version that always applies.)

...or run the experiment in a container, which is the next section.

Networking isolation

WSL's network knobs are all in [wsl2], and all global:

[wsl2]
networkingMode=mirrored   # nat (default) | mirrored | virtioproxy | none
firewall=true             # Windows Firewall + Hyper-V rules filter WSL traffic (default)
dnsTunneling=true         # DNS via virtualization rather than packets — VPN-friendly
autoProxy=true            # inherit the Windows HTTP proxy

• networkingMode=none disconnects WSL networking entirely — a genuine air-gap, but for every distro at once. Practical as a deliberate "offline experiment" mode: set it, wsl --shutdown, run the experiment, revert.
• firewall=true (the default since WSL 2.0.9 on Windows 11 22H2+) means your Windows Firewall rules already apply to WSL. Per-distro rules are possible via Hyper-V Firewall.
• For per-sandbox network isolation that doesn't disturb your dev distro, don't fight .wslconfig — use a container with --network none, or iptables/nftables inside the sandbox distro itself.

Docker containers — the lighter sandbox

When the experiment is one process rather than a whole environment, a container is faster, tighter, and self-cleaning. Run this from inside your normal distro (or Docker Desktop's WSL integration):

# Ephemeral, network-isolated Ubuntu shell. Gone the moment you exit.
docker run --rm -it --network none ubuntu:24.04 bash

A hardened version for running something you actively distrust:

docker run --rm -it \
  --network none \
  --memory 2g --cpus 2 --pids-limit 512 \
  --cap-drop ALL \
  --security-opt no-new-privileges \
  --read-only --tmpfs /tmp:rw,noexec,nosuid,size=256m \
  --user 1000:1000 \
  -v "$PWD/artifacts:/out:rw" \
  -w /out \
  ubuntu:24.04 bash

Container vs. distro, decided in one line: if you need systemctl, a persistent home directory, or a multi-day environment, use a distro. If you need "run this and forget it", use a container.

The nuke-and-rebuild script

Keep this next to the golden snapshot. It's the whole workflow in one file.

# D:\wsl\reset-lab.ps1
param(
  # No default for $Name: --unregister has no undo, so the caller must say it out loud.
  [Parameter(Mandatory)][string]$Name,
  [string]$Root     = "D:\wsl\lab",
  [string]$Snapshot = "D:\wsl\snapshots\lab-clean.tar.gz"
)

$env:WSL_UTF8 = 1   # otherwise wsl.exe output is UTF-16 and every match fails

if (-not (Test-Path $Snapshot)) { throw "No snapshot at $Snapshot" }
if ($Name -eq "Ubuntu")         { throw "Refusing to nuke the default distro" }

# Only tear down if it is actually registered.
if ((wsl --list --quiet) -contains $Name) {
  wsl --terminate  $Name
  wsl --unregister $Name
  if ($LASTEXITCODE -ne 0) { throw "unregister failed for $Name" }
}

New-Item -ItemType Directory -Force -Path $Root | Out-Null
wsl --import $Name $Root $Snapshot --version 2
if ($LASTEXITCODE -ne 0) { throw "import failed from $Snapshot" }

wsl --manage $Name --set-sparse true

Write-Host "Sandbox '$Name' rebuilt from $Snapshot"
wsl --list --verbose

And the one-way door, spelled out because it deserves it:

wsl --unregister lab

--unregister deletes the distro's root filesystem. There is no recycle bin, no undo, and no prompt. Type the distro name carefully — wsl --unregister Ubuntu and wsl --unregister lab are one character apart in muscle memory.

Scripting wsl.exe from agents and CI

wsl.exe emits UTF-16LE with no BOM by default, which turns into interleaved NUL bytes in any pipeline that assumes UTF-8 — the classic "why is my output U b u n t u". Set WSL_UTF8=1:

WSL_UTF8=1 wsl.exe --list --verbose

$env:WSL_UTF8 = 1
wsl --list --verbose

Two more scripting notes:

• From Git Bash / MSYS, Windows paths in wsl.exe arguments get path-mangled. Prefix with MSYS_NO_PATHCONV=1, or run those commands from PowerShell.
• wsl.exe returns -1 (255) on failure with an Wsl/Service/... error code on stderr. Check the exit code; don't parse the message.

codeAmani notes

A sandbox is where risky things go, not where secrets go.

• Never seed a sandbox distro with real credentials. Hazina bindings, .env.local, ~/.ssh, ~/.aws, and cloud CLI tokens stay in the dev distro. With [automount] enabled=false and [interop] enabled=false in the sandbox's wsl.conf, they're not reachable from it — which is the entire point. If an experiment needs a credential, mint a scoped test key for it and revoke it when the distro is unregistered.
• Pairs with the security guide's isolated-lab requirement. Scanners, exploit PoCs, dependency-confusion checks, and gitleaks runs against untrusted repos belong here, one snapshot-restore per run so results are never contaminated by the previous one.
• Customer-bug repros. Import the golden snapshot, install exactly the reported versions, reproduce, capture the diff, unregister. No "it works on my machine" because the machine was clean an hour ago.
• Vetting a new dependency before it enters the catalog. libraries/ build-vs-buy calls often hinge on running an unfamiliar package's install script. Run it in lab with the network off (--network none container, or networkingMode=none for the run) and watch what it tries to do.
• Supply-chain posture. The sandbox is where you observe; it doesn't substitute for the real controls. SLSA provenance, npm audit signatures, dependency review, and secret scanning still gate anything codeAmani ships (see supply-chain/CLAUDE_CODE_INTEGRATION.md).
• Low-bandwidth reality for the Kenya-targeted builds. Snapshot-and-restore is the bandwidth win here: one Ubuntu-24.04 download, then every rebuild is a local tarball. Export as tar.xz if a teammate on a metered connection has to pull the golden image; keep --format tar for local speed. Testing a duka-order-bot or boda-dispatch webhook path against a throttled interface is also easiest in a sandbox — tc qdisc there can't wreck your working network stack.
• Don't run production-adjacent work in a sandbox you plan to nuke. Anything worth keeping goes back to git before --unregister. The sandbox has no backup, by design.

Related guides

• wsl/CLAUDE_CODE_INTEGRATION.md — WSL as your primary dev environment: filesystem performance, /mnt/c rules, Claude Code inside WSL, networking modes, systemd. Read that one first; this guide assumes it.
• security/CLAUDE_CODE_INTEGRATION.md — the isolated-lab requirement this guide satisfies.
• supply-chain/CLAUDE_CODE_INTEGRATION.md — SLSA provenance for anything that leaves the lab.