Skip to content

aboylabs/ai-agent-skills / skills/mlops/windows-local-ai-services

windows-local-ai-services

Unverified

Run local AI services on Windows — port binding, firewall, WSL2 networking, and common pitfalls.

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
    
  2. Ensure Windows service listens on 0.0.0.0 (not 127.0.0.1):

    # Check listening address
    netstat -ano | findstr :8430
    
    # Should show 0.0.0.0:8430, not 127.0.0.1:8430
    
  3. Configure Windows Firewall:

    # Allow inbound on the service port
    New-NetFirewallRule -DisplayName "AI Service Port 8430" -Direction Inbound -LocalPort 8430 -Protocol TCP -Action Allow
    

3. Process Already Running

Symptom: Service says "port already in use" but Get-Process shows nothing.

Diagnosis:

# Find what's using the port
netstat -ano | findstr :8430

# Get process details (replace 1234 with PID from netstat)
Get-Process -Id 1234 | Select-Object Name, Id, Path

Fix:

  • If it's your service from a previous run: kill it and restart
  • If it's svchost or another system service: change your service's port

4. Service Crashes Silently

Always check logs first:

# Common log locations
Get-Content ~\.service-name\service.log -Tail 50
Get-Content $env:APPDATA\service-name\logs\latest.log -Tail 50

Common causes:

  • Missing dependencies (Python, CUDA/ROCm, Visual C++ Redistributable)
  • Config file syntax errors
  • Permission issues (try running PowerShell as Administrator)

Setup Checklist

When setting up a new local AI service on Windows:

  1. Choose a safe port (8000-9000 range recommended)
  2. Configure to listen on 0.0.0.0 (not 127.0.0.1) if WSL2 access needed
  3. Add Windows Firewall rule for the port
  4. Test from Windows first: curl http://localhost:PORT/health
  5. Test from WSL2: curl http://$(ip route show default | awk '{print $3}'):PORT/health
  6. Save the gateway IP or add to WSL2 ~/.bashrc:
    export WINDOWS_HOST=$(ip route show default | awk '{print $3}')
    export AI_SERVICE_URL="http://$WINDOWS_HOST:8430/v1"
    

Verification

After setup, verify cross-OS connectivity:

# From WSL2
GATEWAY_IP=$(ip route show default | awk '{print $3}')
echo "Windows host IP: $GATEWAY_IP"

# Test connection
curl -s http://$GATEWAY_IP:8430/v1/models | jq .

# If it works, save to config
echo "export AI_SERVICE_URL=http://$GATEWAY_IP:8430/v1" >> ~/.bashrc

Rules

  1. Always check logs before guessing — most errors are explicit
  2. Never kill system processes (svchost, System, services.exe)
  3. Use gateway IP for WSL2 → Windows — never localhost
  4. Verify firewall rules before blaming the service
  5. Document the port — save it in config files, not just command-line flags
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall