NemoClaw on WSL2: The Complete Workaround Guide

NemoClaw is NVIDIA’s enterprise security wrapper for OpenClaw — the open-source AI agent framework that combines kernel-level sandboxing (OpenShell), a YAML policy engine for per-action authorization, and a privacy router for local inference routing. NVIDIA launched NemoClaw at GTC 2026 as an alpha release targeting native Linux as the primary deployment platform. WSL2 is not an officially supported target, and the gap between “it runs on Linux” and “it runs on Linux inside Windows” creates a specific set of failures that require manual intervention.

This guide documents every WSL2-specific issue, its root cause, and the workaround we have tested on production Windows workstations. If you are a developer running NemoClaw on a Windows machine for local development or evaluation, this is the guide that will save you the two-day setup struggle described on r/vibecoding and r/LocalLLaMA.

Before you begin, read our NemoClaw Implementation Guide for the general setup process. This post assumes you understand the basic NemoClaw architecture. If an issue listed here also appears in our Troubleshooting Guide, we link to the relevant section rather than duplicating content.

NemoClaw on WSL2 requires a specific environment configuration. Missing any of these prerequisites will cause failures that are difficult to diagnose because error messages reference Linux-native concepts that behave differently under WSL2.

# Create or edit: C:\Users\YourName\.wslconfig
[wsl2]
memory=12GB
swap=8GB
processors=4
localhostForwarding=true

# Enable systemd (required for cgroup delegation)
# In WSL2, run: sudo tee /etc/wsl.conf
[boot]
systemd=true

# Enable systemd in WSL2 (if not already)
$ sudo tee /etc/wsl.conf <<'EOF'
[boot]
systemd=true
EOF

# Restart WSL2 from PowerShell
# PS C:\> wsl --shutdown
# Then reopen your WSL2 terminal

# Verify systemd is running
$ systemctl --version
$ ps -p 1 -o comm=
# Should show "systemd", not "init"

The NemoClaw onboarding wizard detects NVIDIA GPU support through WSL2’s GPU passthrough layer and automatically enables GPU mode. Specifically, the onboard process runs nvidia-smi inside WSL2, sees a valid GPU, and forces --gpu mode. Critically, no --no-gpu flag exists in the current alpha build (GitHub #208). GPU passthrough in WSL2 does not work the same way as native Linux GPU access. The k3s cluster inside the gateway container cannot access the GPU through WSL2’s virtualization layer, causing the sandbox initialization to fail completely.

# Method 1: Environment variable override
$ export NEMOCLAW_GPU_MODE=disabled
$ nemoclaw onboard

# Method 2: Mask the GPU from NemoClaw's detection
$ export NVIDIA_VISIBLE_DEVICES=""
$ export CUDA_VISIBLE_DEVICES=""
$ nemoclaw onboard

# Method 3: Start gateway WITHOUT --gpu, then create provider
# This workaround bypasses the onboard wizard entirely
$ openshell gateway start --name nemoclaw
# Create the provider BEFORE sandbox — avoids GPU auto-detection

# After onboarding, verify CPU-only mode
$ nemoclaw status | grep -i gpu
# GPU: disabled (CPU-only mode)

WSL2 runs as a lightweight VM with its own virtual network adapter. Docker Desktop on WSL2 adds another network layer. NemoClaw’s gateway container adds a third. The result is triple-NAT: your agent inside the NemoClaw sandbox is three network hops away from the Windows host. This breaks several assumptions that NemoClaw makes about network connectivity.

When your sandboxed agent tries to reach localhost:11434 for Ollama inference, it hits the k3s pod’s localhost — which has nothing listening on 11434. The request never leaves the sandbox network. This is the root cause of GitHub #336 and #385.

# From WSL2: what is the Windows host IP?
$ WIN_HOST=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}')
$ echo "Windows host: $WIN_HOST"

# From WSL2: can you reach Ollama on Windows?
$ curl -s http://$WIN_HOST:11434/api/tags
# Should return JSON with model list

# From NemoClaw sandbox: can the agent reach anything?
$ nemoclaw sandbox exec -- curl -s http://host.docker.internal:11434/api/tags
# If this fails, the sandbox-to-host route is broken

# Check Docker's host.docker.internal resolution
$ nemoclaw sandbox exec -- getent hosts host.docker.internal
# Should resolve to the Docker host IP

This is the most common WSL2 issue reported on r/LocalLLaMA: NemoClaw’s sandbox cannot connect to Ollama running on the Windows host. The agent times out waiting for inference responses. Logs show connection refused or network unreachable errors. The root cause is the triple-NAT problem described above, combined with Ollama’s default binding to 127.0.0.1 (localhost only).

Step-by-Step Fix

1. 1
   Bind Ollama to all interfaces on Windows. Open System Environment Variables and add OLLAMA_HOST=0.0.0.0:11434. Restart the Ollama service. Alternatively, if running Ollama in WSL2 directly: OLLAMA_HOST=0.0.0.0:11434 ollama serve.
2. 2
   Add Windows Firewall exception. Open PowerShell as administrator: New-NetFirewallRule -DisplayName "Ollama WSL2" -Direction Inbound -Protocol TCP -LocalPort 11434 -Action Allow. This allows WSL2 to reach the Ollama port through the Windows firewall.
3. 3
   Get the Windows host IP from inside WSL2. Run cat /etc/resolv.conf | grep nameserver | awk '{print $2}'. This IP changes on each WSL2 restart, so this step may need to be repeated.
4. 4
   Configure NemoClaw to use that IP. Run nemoclaw config set inference.endpoint http://<WINDOWS_IP>:11434. Replace <WINDOWS_IP> with the IP from step 3.
5. 5
   Add the IP to your YAML policy’s network allowlist. The policy engine must permit outbound connections to the Ollama endpoint. Add the Windows host IP and port 11434 to your network.destinations list.

#!/bin/bash
# wsl2-ollama-fix.sh — Run inside WSL2 after each restart

# Get Windows host IP
WIN_IP=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}')
echo "Windows host IP: $WIN_IP"

# Test connectivity to Ollama
if curl -s --connect-timeout 3 http://$WIN_IP:11434/api/tags > /dev/null 2>&1; then
    echo "Ollama reachable at $WIN_IP:11434"
else
    echo "ERROR: Cannot reach Ollama at $WIN_IP:11434"
    echo "Check: 1) Ollama running on Windows with OLLAMA_HOST=0.0.0.0"
    echo "       2) Windows Firewall allows port 11434"
    exit 1
fi

# Configure NemoClaw
nemoclaw config set inference.endpoint http://$WIN_IP:11434
echo "NemoClaw configured for Ollama at $WIN_IP:11434"

# Restart NemoClaw to apply
nemoclaw restart
echo "NemoClaw restarted. Verifying..."

# Verify from sandbox
sleep 5
nemoclaw sandbox exec -- curl -s http://$WIN_IP:11434/api/tags
echo "Done."

NemoClaw uses k3s (lightweight Kubernetes) inside the gateway container to manage sandbox pods. On native Linux, k3s starts cleanly and manages pod networking through the host kernel’s network namespaces. On WSL2, k3s runs inside a Docker container that runs inside a WSL2 VM that runs inside Windows. This nesting creates issues with storage drivers, network overlays, and container runtime socket access. GitHub #305 tracks these nested container networking issues — k3s inside OpenShell cannot reliably reach container registries from within WSL2, causing image pull failures during sandbox creation.

Storage Driver Conflicts

# Check if k3s is running inside the gateway
$ docker exec nemoclaw-gateway kubectl get nodes
# If this returns "connection refused", k3s failed to start

# Check k3s logs for storage driver errors
$ docker exec nemoclaw-gateway journalctl -u k3s | grep -i "overlay\|storage\|mount"

# Common error: "overlay mount failed" — WSL2's filesystem
# does not always support overlay2 in nested containers

# Fix: switch k3s to vfs storage driver
$ nemoclaw config set sandbox.storage_driver vfs
$ nemoclaw restart

DNS Resolution Inside Sandbox

WSL2 uses a custom DNS resolver that maps to the Windows host’s DNS settings. When NemoClaw’s sandbox creates its own network namespace, DNS resolution can break because the sandbox’s /etc/resolv.conf points to a nameserver that is unreachable from the sandbox network.

# Test DNS from inside the sandbox
$ nemoclaw sandbox exec -- nslookup api.openai.com
# If this fails, DNS is broken inside the sandbox

# Fix: configure sandbox to use public DNS
$ nemoclaw config set sandbox.dns "8.8.8.8,8.8.4.4"
$ nemoclaw restart

# Verify DNS works
$ nemoclaw sandbox exec -- nslookup api.openai.com
# Should resolve successfully

The NemoClaw WSL2 experience has generated significant discussion in developer communities. The recurring themes match the issues documented above, with community members contributing additional workarounds and edge cases.

Community consensus aligns with our recommendation: WSL2 for development and evaluation, native Linux for production. The workarounds in this guide reduce the setup time from “two days” to approximately one hour, but the underlying architecture limitations remain.

Experimental: GPU Passthrough on WSL2

For teams that need GPU passthrough on WSL2, the thenewguardai/tng-nemoclaw-quickstart repository provides an experimental wsl2-gpu-deploy.sh script that patches the CDI (Container Device Interface) pipeline for GPU passthrough within the NemoClaw sandbox. The repo’s tagline: “Ship your first secure AI agent in under 30 minutes.” The script is community-maintained and not endorsed by NVIDIA, but it addresses the GPU passthrough gap that the official onboarding wizard cannot handle on WSL2.