Run Hermes in WSL2 with Clean Filesystem Boundaries

WSL2 gives Hermes a real Linux environment on Windows, but it creates a boundary between the Linux VM and the Windows host. Most failures come from forgetting which side owns a file, process, port, or credential.

Operating checklist

Install WSL2 and confirm the distro reports version 2.
Prefer current Ubuntu LTS.
Enable systemd for a managed gateway.
Install Hermes from inside the WSL shell.
Keep repos, virtual environments, and ~/.hermes on Linux storage.
Plan every Windows-to-WSL network hop.

How the workflow works

Use wsl --list --verbose to confirm WSL2, then run the official Linux installer inside the distro. Repositories under ~/code use Linux storage; repositories under /mnt/c cross a slower bridge with weaker permission and watcher behavior. Use wslpath, explorer.exe, or wslview to cross the boundary intentionally. Remember that localhost inside WSL and on Windows may identify different hosts unless mirrored networking is configured.

Common pitfalls

Cloning active projects under /mnt/c.
Using WSL1.
Mixing native Windows and WSL Hermes homes.
Assuming a Windows-hosted model is reachable on WSL localhost.
Editing shell scripts with CRLF line endings.

Verification steps

Confirm PID 1 is systemd when required.
Run hermes doctor and a normal chat.
Check Git performance in a Linux-side repo.
Test required file transfers in both directions.
Probe each Windows-hosted service from the WSL shell.

Use the official Hermes documentation for the current source of truth.