Windows (WSL 2 + Docker Desktop)¶

MoE Sovereign runs on Windows via WSL 2 (Windows Subsystem for Linux 2) with Docker Desktop. This is the recommended path for Windows development and local testing — the full compose stack including GPU pass-through works out of the box once WSL 2 is configured correctly.

Recommended WSL 2 resource limits¶

WSL 2 uses a lightweight Hyper-V VM that shares memory with Windows. Without explicit limits it may consume all available RAM. Create or edit %USERPROFILE%\.wslconfig:

# %USERPROFILE%\.wslconfig
# Settings apply to all WSL 2 distros on this machine.

[wsl2]
# Limit the VM to a fixed amount of RAM (adjust to your hardware)
memory=16GB

# Number of virtual processors available to WSL 2
processors=12

# Swap file — keep small, MoE Sovereign data lives in volumes not swap
swap=2GB
swapfile=C:\\Windows\\Temp\\wsl-swap.vhdx

# Allow localhost forwarding (required for browser access to services)
localhostforwarding=true

Apply changes by restarting WSL:

wsl --shutdown

Installing Docker Desktop¶

Download Docker Desktop ≥ 4.30 from https://docs.docker.com/desktop/install/windows-install/.
During setup enable "Use WSL 2 based engine".
After installation: Settings → Resources → WSL Integration → enable your distro (Ubuntu recommended).

Cloning and running install.sh¶

Open your WSL terminal (e.g. Ubuntu) and run:

sudo apt-get update && sudo apt-get install -y git curl openssl
git clone https://github.com/h3rb3rn/moe-sovereign.git /opt/moe-sovereign
cd /opt/moe-sovereign
sudo bash install.sh

install.sh detects that no public domain is set and writes a minimal Caddyfile stub — Caddy starts without TLS errors and the rest of the stack comes up normally.

Common error: Caddyfile mount failure¶

Error response from daemon: failed to create task for container:
... mount src=/opt/moe-sovereign/Caddyfile ...
not a directory: Are you trying to mount a directory onto a file?

Cause: Caddyfile does not exist on the host. Docker creates a directory at the mount path instead of waiting for a file, which then fails at container start.

Fix (if install.sh was already run without generating it):

echo ':80 { respond "MoE Sovereign" 200 }' \
  > /opt/moe-sovereign/Caddyfile
sudo docker compose up -d moe-caddy

install.sh now generates this stub automatically when no domain is configured — the error should not appear on fresh installs.

Port access from Windows browser¶

With localhostforwarding=true in .wslconfig, services are accessible directly from the Windows browser:

Service	URL
Admin UI	http://localhost:8080
User Portal	http://localhost:8088
API	http://localhost:8002
Grafana	http://localhost:3000
Log Viewer	http://localhost:9080 (Dozzle)

GPU pass-through (NVIDIA)¶

WSL 2 supports CUDA via the NVIDIA CUDA on WSL driver. No separate guest driver is needed — install the Windows NVIDIA driver ≥ 525 and enable GPU in Docker Desktop:

# Verify CUDA is visible inside WSL
nvidia-smi

Then set GPU resources in the MoE Admin UI as usual under Configuration → Inference Servers.

Known limitations on WSL 2¶

Limitation	Workaround
`/opt` not bind-mountable by default on older Docker Desktop	Upgrade to Docker Desktop ≥ 4.30, or change `MOE_DATA_ROOT` to `~/moe-data`
Neo4j memory maps (`mmap`) can exhaust WSL VM memory	Add `NEO4J_server_memory_pagecache_size=512m` to `.env`
Filesystem performance slower than native Linux	Store volumes on the ext4 WSL filesystem (`/home/...`), not on Windows NTFS mounts (`/mnt/c/...`)