ComfyUI Hardened Setup — Architecture & Privilege Map

How every hardening layer connects, where it lives, and what breaks if you skip a step.

Windows OS layer
WSL2 / Linux layer
Docker / network layer
Container / ComfyUI layer
Common failure point
hover chips for details
① Windows 11 — outermost layer
3 isolated accounts
admin (installs only), daily (browsing), comfyui (Docker only). Blast radius stays small if something escapes the container.
docker-users group
Membership lets comfyui run Docker without elevation. Missing this = docker command not found or permission denied.
Hyper-V Admins group
Required for wsl --mount to work. Without it the VHD auto-mount silently fails and /mnt/models never appears.
VHD NTFS perms
icacls grants comfyui Modify rights on comfyui-models.vhdx. Without this WSL throws Access Denied at mount time.
Task Scheduler (as comfyui)
Auto-mounts VHD at comfyui login. Security principal must be set to comfyui — if left as admin it mounts into a hidden admin WSL session invisible to comfyui's Docker containers.
ext4 VHD on model disk
Models live on a native ext4 virtual disk, bypassing the slow Windows↔WSL2 NTFS bridge. Easy to backup or wipe independently.
WSL2 runs inside Windows
② WSL2 / Ubuntu — Linux boundary
networkingMode=nat
In .wslconfig. Windows 11 defaults to Mirrored mode which routes container traffic through the Windows stack, silently bypassing all iptables rules. nat forces proper isolation.
C: mounted read-only
Set via options="ro" in /etc/wsl.conf. Anything inside WSL2 or the container cannot write to your Windows system drive.
memory + swap caps
In .wslconfig. Prevents WSL2 from consuming all host RAM if a runaway process or malicious node tries to exhaust resources.
/mnt/models (ext4)
The VHD is mounted here. Models are read directly without crossing the NTFS bridge. Container bind-mounts this path.
no CUDA toolkit in WSL2
Windows NVIDIA driver exposes GPU passthrough automatically. Installing the Linux CUDA toolkit causes library conflicts that break --gpus all.
Docker runs inside WSL2
③ Docker / network — isolation layer
airlock_net bridge
Custom bridge with enable_ip_masquerade=false. Disables Source NAT so containers on this network can't reach external IPs, while still allowing -p port publishing inward.
iptables FORWARD DROP
Second layer of enforcement. Rules live in the FORWARD chain (not DOCKER-USER, which doesn't reliably intercept custom bridge traffic). ESTABLISHED,RELATED exception lets your browser reach the UI.
-p 127.0.0.1:8188:8188
Binds port only to loopback. The UI is invisible to your router and LAN — only reachable from localhost.
manual lifecycle
No --restart unless-stopped. Container never auto-boots before comfy_secure reapplies iptables rules. Rules reset on every WSL2 shutdown.
--shm-size=8g
Replaces --ipc=host. Provides tensor-passing shared memory without exposing the host IPC namespace to the container.
ComfyUI runs inside container
④ Container / ComfyUI — innermost layer
WANTED_UID/GID
Container drops to comfyui's host UID/GID. Output files are owned by you, not root. Prevents privilege escalation through file ownership.
NETWORK_MODE=offline
Tells ComfyUI-Manager not to attempt any network calls. Prevents restart loops and stops Manager from phoning home in production.
DISABLE_UPGRADES=true
Stops git pull / pip upgrade on every start. Required for offline mode to not crash, and prevents nodes from silently self-updating to malicious versions.
TORCH_LOCK
Pins exact PyTorch/torchvision/torchaudio versions. Prevents accidental CUDA stack upgrade that could break GPU passthrough.
.local cache :ro
~/comfyui-dotlocal mapped to cache Python packages offline. uv binary mounted read-only in production — prevents unauthorized self-updates of the package manager.
postvenv + user scripts
Two-tier bootstrap: postvenv_script.bash handles pip packages, user_script.bash handles OS binaries. Both cache results so comfy_secure runs fully offline. New packages need comfy_update to cache first.
ephemeral sandbox
comfy_sandbox: CPU-only, --network none, no real models, temp dotlocal. Entire environment wiped on exit. Use before installing any unvetted node.
Privilege structure
hands off after setup ↓
ComfyUI account ↓
Group membership unlocks
docker-users
→ docker commands work
→ WSL2 sees Docker daemon

Hyper-V Admins
→ wsl --mount works
→ /mnt/models appears
→ Task Scheduler succeeds
⚠️

Common failure: "Ubuntu not visible in comfyui account"

WSL2 distros are installed per Windows user. If you run wsl --install while logged in as admin, the distro is bound to that profile and completely invisible to comfyui. Being in the Administrators group or running with privileges does not change this — distro visibility is per-profile, not per-privilege level. Fix: export from admin with wsl --export Ubuntu-24.04, then import under comfyui with wsl --import.

⚠️

Common failure: "docker command not found / permission denied" in comfyui account

comfyui is missing from the docker-users group. Run as admin: net localgroup "docker-users" "comfyui" /add — then log comfyui out and back in. Group changes don't take effect in an existing session.

⚠️

Common failure: "/mnt/models missing" after login

comfyui is missing from Hyper-V Administrators, or the Task Scheduler entry was created with the wrong security principal (runs as admin instead of comfyui). In Task Scheduler → General tab → Change User or Group → set to comfyui. Also add the group: net localgroup "Hyper-V Administrators" "comfyui" /add.

💡

Silent failure: network isolation broken by Mirrored networking

If networkingMode=nat is missing from C:\Users\comfyui\.wslconfig, Windows 11 may use Mirrored mode, routing container traffic through the Windows host stack and bypassing all iptables FORWARD rules. The outbound check in comfy_secure will report BLOCKED but traffic may still escape. Always include networkingMode=nat explicitly.

Network flow in comfy_secure mode
ComfyUI
container
origin
→
outbound
BLOCKED
(iptables DROP)
airlock_net
bridge
NAT disabled
→
FORWARD
chain DROP
WSL2
network
nat mode
✕
never
reaches
Internet
external
↕
separate
flow
Browser
(Windows)
your machine
→
127.0.0.1
:8188
ALLOWED
ComfyUI
UI port
loopback only
Setup sequence — account context at each step
01
as: admin
Create 3 accounts. Add comfyui to docker-users + Hyper-V Administrators. Log comfyui out/in.
02
bios
Enable Intel VT-x or AMD-V. Required for WSL2 hardware virtualisation.
03
as: admin
Enable WSL2 + Virtual Machine Platform via dism.exe. Reboot.
04
⚠ switch to: comfyui
After reboot, log into comfyui. All remaining steps run here. Do NOT install Ubuntu or Docker from admin.
05
as: comfyui
wsl --install -d Ubuntu-24.04. Distro is now bound to comfyui's profile.
06
as: admin
Install NVIDIA driver (Windows only). Do not touch CUDA inside WSL2.
07
as: admin
Install Docker Desktop (WSL2 backend). Enable WSL Integration for Ubuntu. Move data off C:.
08
as: comfyui
Create .wslconfig with memory caps + networkingMode=nat. Set /etc/wsl.conf C: read-only.
09
as: admin
Create VHD. Grant comfyui Modify perms on .vhdx. Set Task Scheduler entry — principal = comfyui.
10
as: comfyui (WSL2)
Format VHD as ext4. Identify disk in lsblk — never format sda.
11
as: comfyui (WSL2)
Create bootstrap scripts, offline Manager config, folder structure.
12
as: comfyui (WSL2)
Run bootstrap docker command (online). Install trusted nodes. Switch to comfy_secure.
Companion to the ComfyUI Hardened Docker Guide · hover chips for layer details