windows-local-ai-services

Windows Local AI Services

Running local AI services (enowxai, Ollama, LM Studio, vLLM, llama.cpp servers) on Windows has specific networking and port binding pitfalls. This skill covers setup, troubleshooting, and WSL2 cross-OS access.

References

• references/windows-port-restrictions.md — Windows reserved port ranges and binding errors
• references/headless-gui-apps.md — Running GUI apps in headless WSL2 with Xvfb

Common Pitfalls

1. Port Binding Failures

Symptom: Service crashes immediately with:

ERROR failed to start error="listen tcp4 127.0.0.1:1430: bind: An attempt was made to access a socket in a way forbidden by its access permissions."

Root Cause: Windows reserves certain port ranges for system services (Hyper-V, WinNAT, dynamic port allocation). Ports in these ranges cannot be bound by user applications.

Fix:

1. Change the port (easiest):

   # Use a port outside reserved ranges (8000-9000 is usually safe)
   service start --port 8430
   

2. Check reserved ranges:

   netsh int ipv4 show dynamicport tcp
   netsh int ipv4 show excludedportrange protocol=tcp
   

3. Exclude a specific port (risky, can conflict with system services):

   netsh int ipv4 add excludedportrange protocol=tcp startport=1430 numberofports=1
   

Never kill svchost.exe — it's a Windows system service host. If netstat shows svchost using your target port, the port is reserved by Windows.

2. WSL2 Cross-OS Networking

Symptom: Service runs on Windows but WSL2 cannot connect via localhost.

Root Cause: WSL2 uses a virtualized network. localhost in WSL2 points to the WSL2 VM, not the Windows host.

Fix:

1. Use Windows host gateway IP from WSL2:

   # Get Windows host IP (usually 172.17.16.1, but can change on reboot)
   ip route show default | awk '{print $3}'
   
   # Test connection
   curl http://172.17.16.1:8430/v1/models