Set Up Loss Prevention on Windows 11 with WSL2#

This guide takes a clean Windows 11 machine to a working Loss Prevention environment under WSL2. It is written for someone who has never used WSL before.

Before make benchmark, also complete the hardware metrics prerequisites. Windows GPU counters, optional GPU power sensors, and native Windows Performance Counter Monitor (PCM) need separate host-side setup. Collection then starts and stops automatically with the benchmark; no separate collector command is needed during a run. See WSL benchmark metrics for outputs and limitations. The Makefile detects WSL2 automatically from the Microsoft kernel; no flag is needed.

Follow the steps in order. Several of them fail in confusing ways if done out of sequence — particularly the proxy configuration, which must come before any download.


Contents#

  1. Elevation and virtualization

  2. Install WSL2 and Ubuntu 24.04

  3. Proxy configuration

  4. Base packages

  5. Enable systemd

  6. Install Docker Engine

  7. Docker daemon proxy

  8. Docker build-time proxy

  9. Memory and CPU tuning

  10. Clone the repository

  11. GPU and NPU verification

  12. Smoke test

  13. Troubleshooting


Conventions#

Commands are labeled by where they run:

Label

Where

PowerShell

Windows PowerShell or Terminal, on the Windows side

Ubuntu

Inside the WSL2 Ubuntu distribution

Getting these mixed up is the single most common early mistake.


Values you must change for your site#

Most URLs in this guide are public upstream endpoints and are identical on every machine. A small number are site-specific and are the most likely reason the guide fails somewhere else. Every occurrence below is marked with a ⚙️ note.

Placeholder used here

What it is

How to find yours

http://proxy.example.com:PORT

Example proxy URL; replace the host and port with your site’s values

netsh winhttp show proxy or ProxyServer (Windows), echo $HTTP_PROXY (Ubuntu)

.example.com, 192.0.2.0/24

Reserved example values for the NO_PROXY internal domain and network range

Your own internal DNS suffix and network ranges

PAC URL

Proxy auto-configuration file

AutoConfigURL (Windows), echo $WSL_PAC_URL (Ubuntu)

C:\Users\<YourName>

Windows profile path

Use $env:USERPROFILE, which resolves itself

Discover everything at once. In PowerShell:

netsh winhttp show proxy
Get-ItemProperty "HKCU:\Software\Microsoft\Windows\CurrentVersion\Internet Settings" |
  Select-Object ProxyServer, AutoConfigURL

In Ubuntu, once a distribution exists:

echo "$HTTP_PROXY"
echo "$WSL_PAC_URL"

These are constant everywhere — never edit them: api.github.com, download.docker.com, archive.ubuntu.com, github.com/intel-retail/loss-prevention, openvino/ubuntu24_dev. The service names rabbitmq, minio-service, rtsp-streamer, ovms-vlm, and model-downloader in every NO_PROXY are Docker Compose service names from src/docker-compose.yml and must be kept as-is.


1. Elevation and virtualization#

WSL2 is a lightweight virtual machine. Getting it installed means satisfying three independent requirements, in this order:

Layer

What it is

How to enable

Reboot

VT-x

CPU feature, a firmware setting

BIOS/UEFI only

Yes, into BIOS

Windows features

VirtualMachinePlatform, Microsoft-Windows-Subsystem-Linux

dism or wsl --install

Yes, normal reboot

WSL package

the wsl.exe runtime itself

wsl --install download, or the MSI

No

These are not alternatives. dism cannot switch on VT-x, and enabling the Windows features while VT-x is off leaves you with a WSL that installs cleanly and then refuses to boot a distribution.

1a. Open an elevated PowerShell#

Everything in this section fails with Error: 740 — Elevated permissions are required from a normal shell.

Select Windows Start menu, type powershell, right-click Windows PowerShell, and Run as administrator. Or from an existing window:

Start-Process powershell -Verb RunAs

To confirm it worked:

whoami /groups | findstr /i "High Mandatory"

The result must print a line containing High Mandatory Level. Nothing printed means the window is not elevated.

Caution

Remote machines: an SSH session (MobaXterm, OpenSSH) cannot elevate — UAC needs an interactive desktop to draw the consent dialog, and there is no CLI workaround. Use RDP, which creates a real interactive session and supports UAC normally. If the account is not listed by net localgroup Administrators, stop here.

1b. Point WinHTTP at the proxy#

An elevated shell uses the machine’s WinHTTP proxy configuration, not your browser’s, and by default that is empty. Skip this on a corporate network and the WSL downloader fails with The certificate authority is invalid or incorrect:

netsh winhttp import proxy source=ie
netsh winhttp show proxy

If it still reports Direct access (no proxy server), set it explicitly:

netsh winhttp set proxy proxy-server="http=proxy.example.com:PORT;https=proxy.example.com:PORT" bypass-list="*.example.com;localhost;127.0.0.1;<local>"

Note

⚙️ Site-specific. Replace proxy.example.com:PORT and the bypass list with your own. Find them with:

Get-ItemProperty "HKCU:\Software\Microsoft\Windows\CurrentVersion\Internet Settings" |
  Select-Object ProxyServer, AutoConfigURL

If only AutoConfigURL is set, open that PAC URL in a browser and read the proxy host and port out of the JavaScript.

Check the proxy actually reaches the download host before going further:

curl.exe -sS -o NUL -w "%{http_code}`n" -x http://proxy.example.com:PORT https://github.com

Replace the example host and PORT with the proxy host and port reported by your settings or PAC file. A 200 confirms the proxy reaches the destination; a 403 means it refuses that destination.

1c. Check firmware virtualization#

Run this to check virtualization:

systeminfo | findstr /i "Hyper-V"

Output

Meaning

Action

A hypervisor has been detected.

VT-x is on and a hypervisor is running

Continue to 1d

A list ending Virtualization Enabled In Firmware: No

VT-x is off

Reboot into BIOS/UEFI, enable Intel Virtualization Technology (VT-x), then resume here

If virtualization is off, you have to enable it in BIOS — there is no Windows command for it.

1d. Enable the Windows features and install the WSL package#

One command normally does both:

wsl.exe --install --no-distribution

On a corporate network this often fails at the download half with The certificate authority is invalid or incorrect or Forbidden (403). The WSL downloader performs its own strict certificate validation and rejects the TLS-inspected chain, even when the corporate CA is trusted machine-wide. Retrying will not help.

Split the two jobs instead. The Deployment Image Servicing and Management (DISM) tool enables the features and needs no network:

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Then fetch the package with curl.exe, which ships with Windows and validates against the Windows certificate store — the same store your browser uses, so the inspected chain is accepted:

$json = curl.exe -sS -x http://proxy.example.com:PORT https://api.github.com/repos/microsoft/WSL/releases/latest | ConvertFrom-Json
$url  = ($json.assets | Where-Object { $_.name -like '*x64.msi' }).browser_download_url
$url
curl.exe -L -x http://proxy.example.com:PORT -o "$env:TEMP\wsl.msi" $url
(Get-Item "$env:TEMP\wsl.msi").Length
msiexec /i "$env:TEMP\wsl.msi" /qn /norestart

Expect roughly a 100–150 MB download. A few kilobytes means you downloaded the proxy’s block page rather than the installer.

Note

⚙️ Site-specific. Replace http://proxy.example.com:PORT with the proxy URL confirmed in step 1b. The api.github.com URL is universal, and the MSI URL is deliberately not hardcoded: the API query resolves the current version’s browser_download_url, so it stays correct as WSL releases change. Do not replace it with a literal filename.


winget install --id Microsoft.WSL is a third option. It uses yet another HTTP stack and sometimes succeeds where both others fail.

1e. Reboot#

The feature changes do not take effect until you do:

shutdown /r /t 0

1f. Verify#

In an elevated shell (this query also needs it):

dism /online /get-featureinfo /featurename:VirtualMachinePlatform

Expected: State : Enabled.

Then ask WSL itself:

wsl --version
wsl --status

wsl --status output

Meaning

Action

Default Version: 2

Step 1 complete

Go to step 2

The Windows Subsystem for Linux is not installed

The step 1d download half did not succeed

Install the MSI

WSL2 is unable to start since virtualization is not enabled on this machine

The package is installed but the Windows features are not

Run the command below, then reboot

WSL2 is not supported with your current machine configuration

VT-x is off in firmware

See step 1c, enable in BIOS

The third row is the common one after installing via MSI. wsl.exe is now present and reporting on its own environment. Its full message is:

WSL1 is not supported with your current machine configuration.
Please enable the "Windows Subsystem for Linux" optional component to use WSL1.
WSL2 is unable to start since virtualization is not enabled on this machine.
Please ensure the "Virtual Machine Platform" optional component is enabled and
virtualization is turned on in your computer's firmware settings.

Because the package is already local, this command no longer needs to download anything — it only flips the two optional components, so it succeeds even on a network where 1d failed:

wsl.exe --install --no-distribution
shutdown /r /t 0

Re-run wsl --status after the reboot. It should now report Default Version: 2.


2. Install WSL2 and Ubuntu 24.04#

PowerShell:

wsl --set-default-version 2
wsl --list --online
wsl --install -d Ubuntu-24.04

The installer prompts for a Linux username and password. These are independent of your Windows account. Remember the password — it is your sudo password.

Record your version baseline:

wsl --version
wsl -l -v

Example output:

WSL version: 2.7.12.0
Kernel version: 6.18.33.2-2
WSLg version: 1.0.73.2
Direct3D version: 1.611.1-81528511
Windows version: 10.0.26200.9168

Ubuntu — confirm the distribution launched and identifies itself:

lsb_release -a
uname -r

Expected: Ubuntu 24.04 LTS (codename noble).

Important

Do not run apt update or apt upgrade yet. On a corporate network those will partially fail in ways that are hard to interpret. Configure the proxy first — the system update is the last part of step 3.

Type exit to return to PowerShell.


3. Proxy configuration#

Do this before anything else that touches the network. On a corporate network, skipping it produces misleading failures much later.

Why this trips people up#

On some networks, plain HTTP may work directly while HTTPS is blocked. Ubuntu’s own package repositories may use plain HTTP, so sudo apt update can appear to succeed:

Hit:1 http://archive.ubuntu.com/ubuntu noble InRelease        <-- HTTP repository succeeds
Err:6 https://download.docker.com/linux/ubuntu noble InRelease <-- HTTPS repository times out
  Could not connect to download.docker.com:443, connection timed out

A successful apt update does not prove your network is configured.

If you are not behind a proxy, skip to step 4.

3a. Windows side — .wslconfig#

By default WSL2 uses NAT, and corporate endpoint-security agents frequently drop that traffic. Mirrored networking makes WSL share the Windows network stack directly.

Note

Mirrored networking requires WSL 2.0.0+ and Windows build 22621+. Check with wsl --version and [System.Environment]::OSVersion.Version if unsure. On older builds, omit networkingMode, dnsTunneling, and firewall, and set the proxy manually in step 3b.

Create or edit C:\Users\<YourName>\.wslconfig:

[wsl2]
networkingMode=mirrored
dnsTunneling=true
autoProxy=true
firewall=true

Note

⚙️ Machine-specific path. Rather than typing your username, let PowerShell resolve it — this writes the same file on any machine:

@"
[wsl2]
networkingMode=mirrored
dnsTunneling=true
autoProxy=true
firewall=true
"@ | Set-Content -Path "$env:USERPROFILE\.wslconfig" -Encoding ASCII

Get-Content "$env:USERPROFILE\.wslconfig"

On a remote machine this must be the profile of the account running WSL, not the one you connect from.

PowerShell — apply:

wsl --shutdown

Ubuntu — verify. The address should now match your Windows IPv4, not 172.x.x.x:

ip addr show eth0 | grep 'inet '

3b. Ubuntu shell — ~/.bashrc#

autoProxy=true injects HTTP_PROXY but not HTTPS_PROXY. Tools like curl read HTTPS_PROXY for TLS connections, so without it they connect directly to port 443 and hang. Mirror the value:

cat >> ~/.bashrc <<'EOF'

# WSL autoProxy sets HTTP_PROXY but not HTTPS_PROXY - mirror it
if [ -n "$HTTP_PROXY" ]; then
    export HTTPS_PROXY="${HTTPS_PROXY:-$HTTP_PROXY}"
    export http_proxy="$HTTP_PROXY"
    export https_proxy="$HTTPS_PROXY"
    export NO_PROXY="localhost,127.0.0.1,::1,.example.com,192.0.2.0/24,rabbitmq,minio-service,rtsp-streamer,ovms-vlm,model-downloader"
    export no_proxy="$NO_PROXY"
fi
EOF

source ~/.bashrc

Verify:

env | grep -i proxy
curl -sI --max-time 15 https://download.docker.com/linux/ubuntu/gpg | head -1

The curl must return HTTP/1.1 200 or HTTP/2 200. A hang means HTTPS is still going direct.

Note

Find your proxy URL from echo $HTTP_PROXY, or inspect the PAC file WSL exposes as $WSL_PAC_URL. On Windows, netsh winhttp show proxy and the Internet Settings ProxyServer and AutoConfigURL values show the configured proxy or PAC URL. If only a PAC URL is available, inspect its script to find the proxy host and port.


⚙️ Site-specific. The NO_PROXY list above mixes two kinds of entry. Replace .example.com and 192.0.2.0/24 with your own internal domain and network ranges. Keep rabbitmq, minio-service, rtsp-streamer, ovms-vlm, and model-downloader — those are Compose service names from src/docker-compose.yml, identical on every machine, and routing them through a proxy breaks inter-container traffic. Check your current values with:

echo "$HTTP_PROXY"
echo "$WSL_PAC_URL"

3c. apt — its own configuration file#

apt does not read shell environment variables. It needs its own file. This is separate from step 3b and both are required:

sudo tee /etc/apt/apt.conf.d/95proxies > /dev/null <<'EOF'
Acquire::http::Proxy "http://proxy.example.com:PORT";
Acquire::https::Proxy "http://proxy.example.com:PORT";
EOF

Note

⚙️ Site-specific. Substitute your own proxy. Because the heredoc is quoted (<<'EOF'), $HTTP_PROXY would be written literally rather than expanded — so if you want it filled in from the environment, drop the quotes:

sudo tee /etc/apt/apt.conf.d/95proxies > /dev/null <<EOF
Acquire::http::Proxy "$HTTP_PROXY";
Acquire::https::Proxy "$HTTPS_PROXY";
EOF

Always cat the file afterwards to confirm real values landed, not empty strings.

3d. Force IPv4#

WSL2 has no IPv6 route, so every apt download wastes around 30 seconds failing over eight IPv6 addresses before trying IPv4. Force IPv4 with:

sudo tee /etc/apt/apt.conf.d/99force-ipv4 > /dev/null <<'EOF'
Acquire::ForceIPv4 "true";
EOF

Verify both files:

cat /etc/apt/apt.conf.d/95proxies /etc/apt/apt.conf.d/99force-ipv4

3e. Update the base system#

Only now is it safe to run this — every download path is configured:

sudo apt update
sudo apt upgrade -y

apt update must complete with no Err: lines. Warnings about missing repositories you have not added yet are fine; connection timeouts are not.

The four proxy contexts#

Proxy settings live in four unrelated places. Configuring one tells you nothing about the others:

Context

Consumer

Location

Step

Shell

curl, git, pip, wget

~/.bashrc

step 3b

apt

sudo apt

/etc/apt/apt.conf.d/95proxies

step 3c

Daemon

docker pull

/etc/systemd/system/docker.service.d/proxy.conf

step 7

Build

docker build RUN steps

~/.docker/config.json

step 8

Steps 7 and 8 come later because those paths do not exist until Docker is installed.

Caution

sudo strips proxy environment variables. Use sudo -E for any command that needs network access.


4. Base packages#

sudo apt install -y \
  build-essential make git curl wget unzip \
  jq python3 python3-pip python3-venv \
  ca-certificates gnupg lsb-release x11-xserver-utils

Package

Used by

make

every workflow command (make run-lp, make benchmark)

jq

model-downloader.sh and check-device-env parse configs/*.json

python3 + venv

download-video.py, configuration validators, benchmark scripts

curl / wget

model and video downloads

git

the repository and the performance-tools submodule

x11-xserver-utils

xhost, required by make run-render-mode for X11 display access

Verify:

make --version && jq --version && python3 --version && git --version

5. Enable systemd#

Docker Engine runs as a systemd service. WSL2 does not enable systemd by default, so enable it in /etc/wsl.conf:

sudo tee /etc/wsl.conf > /dev/null <<'EOF'
[boot]
systemd=true

[interop]
appendWindowsPath=true
EOF

PowerShell — a full shutdown is required; closing the terminal is not enough:

wsl --shutdown

Reopen Ubuntu and verify:

ps -p 1 -o comm=
systemctl list-units --type=service | head

ps -p 1 -o comm= must print systemd. If you see System has not been booted with systemd, the shutdown did not take effect.


6. Install Docker Engine#

Why Docker Engine and not Docker Desktop#

Docker Desktop runs its daemon in a separate hidden distribution (docker-desktop), not in your Ubuntu. For the GPU work in step 11 you will bind-mount /usr/lib/wsl/lib and pass --device=/dev/dxg; cross-distribution path translation makes failures much harder to diagnose. With Docker Engine installed inside Ubuntu-24.04, the daemon sees exactly the same devices and filesystem you do.

Caution

Do not install both. Two daemons will conflict.

Add Docker’s GPG key#

sudo install -m 0755 -d /etc/apt/keyrings
sudo -E curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

Verify before continuing. A timed-out curl leaves an empty file, and the resulting apt error is misleading:

head -1 /etc/apt/keyrings/docker.asc

Must print -----BEGIN PGP PUBLIC KEY BLOCK-----.

Add the repository and install#

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \
https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

Enable non-root access#

sudo usermod -aG docker $USER
sudo systemctl enable --now docker

Group membership is only read at login. PowerShell:

wsl --shutdown

Reopen Ubuntu and confirm the group and the service. These are local checks and need no network:

id -nG | tr ' ' '\n' | grep docker
systemctl is-active docker

Expect docker and active. If the group is missing, the shutdown did not take effect.

Caution

Do not work around permission errors with sudo docker. Running as root creates root-owned files in models/ and results/, which breaks later steps.

The full end-to-end check comes at the end of step 8 — docker run hello-world has to pull an image, which cannot work until the daemon proxy is configured.


7. Docker daemon proxy#

Required for docker pull. The daemon is a system service and does not inherit your shell environment:

sudo mkdir -p /etc/systemd/system/docker.service.d
sudo tee /etc/systemd/system/docker.service.d/proxy.conf > /dev/null <<'EOF'
[Service]
Environment="HTTP_PROXY=http://proxy.example.com:PORT"
Environment="HTTPS_PROXY=http://proxy.example.com:PORT"
Environment="NO_PROXY=localhost,127.0.0.1,.example.com,rabbitmq,minio-service,rtsp-streamer,ovms-vlm,model-downloader"
EOF

sudo systemctl daemon-reload
sudo systemctl restart docker

Note

⚙️ Site-specific. Replace http://proxy.example.com:PORT and the .example.com entry with your own; keep the Compose service names. Confirm the values you are about to write first with echo "$HTTP_PROXY".

Verify:

docker info | grep -i proxy

You should see HTTP Proxy, HTTPS Proxy, and No Proxy lines. If they are absent, the drop-in did not load.


8. Docker build-time proxy#

Each RUN instruction in a Dockerfile executes in a throwaway container with a clean environment. It does not inherit your shell’s proxy settings.

The Makefile and Compose file already pass HTTP_PROXY/HTTPS_PROXY as build arguments for the project’s own images, but coverage has gaps:

  • With WSL2=false REGISTRY=false, make build-benchmark delegates to the performance-tools submodule’s Makefile, which is outside this repository’s proxy plumbing. On WSL2, it instead uses the Windows Python executable configured by WINDOWS_PYTHON in the root Makefile and installs its Python dependencies; Windows Python needs its own working network/proxy configuration. Docker proxy settings do not configure Windows pip.

  • Only rtsp-streamer passes the lowercase http_proxy/https_proxy variants; curl reads lowercase http_proxy only, so RUN curl http://... in the other images would bypass the proxy.

  • NO_PROXY is not passed as a build argument anywhere.

Setting the CLI-level configuration covers all of these uniformly:

mkdir -p ~/.docker
cat > ~/.docker/config.json <<'EOF'
{
  "proxies": {
    "default": {
      "httpProxy": "http://proxy.example.com:PORT",
      "httpsProxy": "http://proxy.example.com:PORT",
      "noProxy": "localhost,127.0.0.1,.example.com,rabbitmq,minio-service,rtsp-streamer,ovms-vlm,model-downloader"
    }
  }
}
EOF

Note

⚙️ Site-specific. Same substitution as step 7 — proxy host, port, and .example.com. This file is JSON, so a trailing comma or an unescaped value breaks every docker command, not just builds. Validate it after writing:

jq . ~/.docker/config.json

Verify Docker end to end#

Only now can Docker actually reach a registry. Run these in order:

id -nG | tr ' ' '\n' | grep docker
docker run hello-world
docker compose version
docker buildx version

docker run hello-world is the real test — it pulls from Docker Hub, so it exercises the daemon proxy from step 7. A hang or TLS handshake timeout means that drop-in is wrong or did not load; re-check docker info | grep -i proxy.

docker compose version must report v2.24.4 or newer — the Makefile uses docker compose (space, not hyphen) throughout, and src/docker-compose-wsl2.yml relies on the include top-level element and the !override merge tag, which earlier v2 releases reject. If your version is older, upgrade docker-compose-plugin from the Docker apt repository configured in step 6.


9. Memory and CPU tuning#

The Vision Language Model (VLM) workload loads a 7B parameter model. Defaults are not sufficient.

Edit C:\Users\<YourName>\.wslconfig on the Windows side, merging with the networking settings from step 3a:

[wsl2]
memory=48GB
processors=12
swap=16GB
networkingMode=mirrored
dnsTunneling=true
autoProxy=true
firewall=true

Note

localhostForwarding is unnecessary when networkingMode=mirrored is set.


⚙️ Machine-specific. Use $env:USERPROFILE\.wslconfig for the path. The memory, processors, and swap values must suit your hardware: check with Get-CimInstance Win32_ComputerSystem | Select TotalPhysicalMemory and $env:NUMBER_OF_PROCESSORS, then leave headroom for Windows — roughly 75% of RAM and total cores is a safe ceiling.

PowerShell:

wsl --shutdown

Ubuntu — verify:

free -h
nproc
df -h /

The repository plus models needs roughly 300 GB. df -h / reports free space inside the WSL filesystem, not free space on the Windows drive storing its virtual disk. Check that host drive separately in PowerShell (for example, Get-PSDrive C if the distribution is stored on C:). Both the WSL filesystem and its Windows host drive need sufficient space.


10. Clone the repository#

cd ~
git clone https://github.com/intel-retail/loss-prevention.git
cd loss-prevention
git submodule update --init --recursive

Important

  1. Never clone into /mnt/c/.... Windows drives are reached through a slow translation layer. Always use ~, which is the native Linux filesystem.

  2. The submodule is mandatory. performance-tools/ holds every benchmark script.

Verify the submodule checked out:

ls performance-tools/benchmark-scripts | head

You should see benchmark.py and format_avc_mp4.sh. An empty directory means the submodule did not initialize.

Record your baseline:

git rev-parse --short HEAD
git submodule status

Optional: repository-scoped environment#

The Makefile reads an optional .env file. Proxy variables do not need to go here — make already imports them from your shell environment. Use .env only for values that should not be global, such as secrets and optional WSL2 host configuration:

# .env  (do not commit)
HUGGINGFACE_TOKEN=hf_xxxxxxxx

The Makefile detects WSL2 automatically and selects src/docker-compose-wsl2.yml instead of the native src/docker-compose.yml. The WSL2 Compose file replaces native Linux /dev/dri device mappings with WSL2’s /dev/dxg and mounts the WSL graphics libraries and driver helper libraries. OpenCL configuration and userspace runtimes come from the container images, not host OpenCL bind mounts. CPU workloads remain CPU workloads because the device is selected by the workload JSON.


11. GPU and NPU verification#

This is the decisive check for the whole adaptation of Loss Prevention to WSL2.

Windows drivers and container userspace runtimes#

WSL GPU access uses the Windows graphics driver and /dev/dxg, not a native Linux GPU kernel driver. WSL exposes graphics libraries under /usr/lib/wsl/lib and driver helpers under /usr/lib/wsl/drivers. Keep the Windows graphics driver up to date; do not install a native Linux kernel driver to replace it.

OpenCL and Level Zero userspace runtimes are separate from that kernel driver. The container images must provide compatible runtimes and ICD configuration. The WSL Compose override retains the image’s /etc/OpenCL and /usr/lib/x86_64-linux-gnu/intel-opencl contents instead of mounting host copies over them. These host directories are not prerequisites and should not be created just to satisfy Docker mounts. Host userspace packages do not provision container runtimes.

For lp-pipeline-runner, the WSL startup wrapper prepends both WSL library directories to the image’s existing LD_LIBRARY_PATH before running the normal pipeline script. The other GPU services also include the WSL library paths. GPU enumeration in the actual deployment images remains a required host check; Compose parsing alone does not establish runtime compatibility.

If the Windows-provided WSL libraries or /dev/dxg are missing, update the Intel graphics driver on Windows, then run wsl --shutdown. If the device exists but OpenVINO™ Toolkit (OpenVINO™) cannot enumerate a GPU, inspect the container’s runtime and ICD files.

Note

NPU workloads remain unsupported by this WSL setup.

11a. Host device check#

ls -l /dev/dxg
ls -l /usr/lib/wsl/lib/
ls -l /usr/lib/wsl/drivers/
ls /dev/dri 2>&1
ls /dev/accel 2>&1

Expected results:

Path

Expected

Meaning

/dev/dxg

exists

the WSL GPU device — replaces /dev/dri

/usr/lib/wsl/lib/

populated

WSL graphics bridge libraries such as libd3d12.so and libdxcore.so; not a substitute for the container’s OpenCL runtime

/usr/lib/wsl/drivers/

populated

WSL GPU driver helpers such as libwsl_compute_helper.so

/dev/dri

absent

expected; this is why the Compose device mappings need changing

/dev/accel

likely absent

the NPU finding

If /dev/dxg is missing, stop here and update the Windows graphics driver.

11b. OpenVINO™ device enumeration#

docker run --rm \
  --device=/dev/dxg \
  -v /usr/lib/wsl/lib:/usr/lib/wsl/lib:ro \
  -v /usr/lib/wsl/drivers:/usr/lib/wsl/drivers:ro \
  intel/dlstreamer:2026.2.0-ubuntu24 \
  bash -lc '. /opt/intel/openvino/setupvars.sh 2>/dev/null || true; \
    export LD_LIBRARY_PATH=/usr/lib/wsl/lib:/usr/lib/wsl/drivers:/usr/lib/openvino-2026.2.0${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}; \
    python3 -c "import openvino as ov; print(ov.Core().available_devices)"'

Want: ['CPU', 'GPU']

If only ['CPU'] appears, do not run GPU workloads. Inspect the plugin and driver runtime with:

docker run --rm \
  --device=/dev/dxg \
  -v /usr/lib/wsl/lib:/usr/lib/wsl/lib:ro \
  -v /usr/lib/wsl/drivers:/usr/lib/wsl/drivers:ro \
  intel/dlstreamer:2026.2.0-ubuntu24 \
  bash -lc 'export LD_LIBRARY_PATH=/usr/lib/wsl/lib:/usr/lib/wsl/drivers:/usr/lib/openvino-2026.2.0${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}; \
    ldd /usr/lib/openvino-2026.2.0/libopenvino_intel_gpu_plugin.so | grep "not found" || true; \
    python3 -c "import openvino as ov; print(ov.Core().available_devices)"'

11c. NPU#

ls /dev/accel 2>&1
lsmod | grep -i vpu

If NPU does not appear in the OpenVINO™ device list, that is the expected result on current WSL2 builds, not a mistake on your part. Intel NPU passthrough uses a different mechanism from GPU passthrough and may not be available for your driver and kernel combination. A documented “not supported” is a valid outcome.

11d. Record the baseline#

{
  echo "=== /dev/dxg ==="   ; ls -l /dev/dxg   2>&1
  echo "=== /dev/dri ==="   ; ls -l /dev/dri   2>&1
  echo "=== /dev/accel ===" ; ls -l /dev/accel 2>&1
  echo "=== /usr/lib/wsl/lib ==="; ls /usr/lib/wsl/lib/
  echo "=== kernel ==="     ; uname -r
} | tee ~/wsl-accel-baseline.txt

12. Smoke test#

Run in order, stopping at the first failure:

cd ~/loss-prevention

# 1. Docker works
docker run hello-world

# 2. The Makefile parses and resolves variables
make -n run-lp | head -20

# 3. Config validators work (proves python3 and jq are fine)
make validate-all-configs

# 4. What devices does the repo think you have?
make check-device-env

# 5. Sample videos - small download, fast feedback
make download-sample-videos

Optional: render mode#

WSLg can display the annotated stream for CPU workloads. xhost is provided by x11-xserver-utils, which is installed in step 4. Confirm that WSLg set a display:

echo "$DISPLAY"
xhost +local:docker

Run the CPU object-detection workload with rendering enabled:

RENDER_MODE=1 DISPLAY=:0 make run-lp \
  CAMERA_STREAM=camera_to_workload_asc_object_detection.json \
  WORKLOAD_DIST=workload_to_pipeline_asc_object_detection_cpu.json

When testing a change to src/gst-pipeline-generator.py, use REGISTRY=false so Docker rebuilds lp-pipeline-runner from the current checkout. The registry image does not contain uncommitted or newly pulled local source changes:

make down-lp

REGISTRY=false RENDER_MODE=1 DISPLAY=:0 make run-lp \
  CAMERA_STREAM=camera_to_workload_asc_object_detection.json \
  WORKLOAD_DIST=workload_to_pipeline_asc_object_detection_cpu.json

For the WSLg display path, the generated pipeline must include videoconvert before the automatic video sink. Verify it in the running container:

docker compose -f src/docker-compose-wsl2.yml exec lp-pipeline-runner \
  grep -n 'gvawatermark.*videoconvert.*ximagesink' \
  /home/pipeline-server/pipelines/pipeline.sh

Troubleshooting#

MinIO restarts after the image update: backend write permission denied#

After switching from the previous MinIO image to the Chainguard image, an existing data volume may still be owned by the previous container user. make run-lp can then fail with dependency failed to start: container src-minio-service-1 is unhealthy. The MinIO logs identify this case with:

Error: unable to rename (/data/.minio.sys/tmp -> /data/.minio.sys/tmp-old/...) file access denied
FATAL Unable to initialize backend: Unable to write to the backend

This is a storage-permissions failure, not a /dev/tcp health-check failure. MinIO exits because it cannot write to /data, and its restart policy restarts the container. Changing the health check will not fix that startup error. The same issue can occur on native Linux; it depends on volume ownership, not WSL2 detection.

Run the following commands in Ubuntu, on the affected machine. The examples use the default container name src-minio-service-1 and volume src_minio_data. If your Compose project uses another name, substitute the actual names.

  1. Confirm the error, the mounted volume, and the image’s runtime UID/GID:

    docker logs --tail 100 src-minio-service-1
    docker inspect src-minio-service-1 --format 'User={{.Config.User}} Mounts={{json .Mounts}}'
    MINIO_IMAGE=$(docker inspect src-minio-service-1 --format '{{.Image}}')
    docker run --rm --network none --entrypoint /bin/sh "$MINIO_IMAGE" -c 'id'
    

    For the pinned Chainguard image, the verified values are User=65532, uid=65532(nonroot) gid=65532(nonroot), and the named volume mounted at /data is src_minio_data with RW=true. The temporary container used for id does not mount your data. Do not use the repair command unchanged if these values differ; use the actual volume name and the UID/GID that the service runs as.

  2. Stop MinIO before modifying its storage. Back up the volume first if it contains important data:

    docker stop src-minio-service-1
    
  3. Repair ownership and owner permissions without deleting stored data:

    docker run --rm --user 0:0 --network none \
      --mount type=volume,source=src_minio_data,target=/data \
      alpine:3.22 \
      sh -c 'chown -R 65532:65532 /data && chmod -R u+rwX /data'
    

    Docker may need to pull alpine:3.22; its daemon proxy must already be configured. Root is used only in this temporary repair container. MinIO continues to run as non-root. Stop here if the repair command fails.

  4. Start MinIO and inspect recent startup logs:

    docker start src-minio-service-1
    docker logs --since 1m --tail 50 src-minio-service-1
    

    Allow approximately 30 seconds for the health check, then inspect its result:

    docker inspect src-minio-service-1 --format '{{json .State.Health}}'
    

    Once it reports healthy, rerun your original make run-lp command to start the services that were blocked by MinIO. If it remains unhealthy, inspect the new server logs and health-check output before making further changes.

This is a one-time repair for the affected volume, not a step required on every run. Ownership persists across container restarts, recreation, and normal Compose down/up operations. Restored data with different ownership or a future runtime UID change may require another migration. Keep the current health check unchanged; do not use down -v, delete the volume, apply chmod 777, or permanently run MinIO as root to resolve this error.