netllm-doctor

name	netllm-doctor
description	Troubleshoot swarm-llm (netllm) misconfigurations. Use when netllm is broken, no models appear, the agent is unreachable, mDNS fails, PATH is wrong, or the user invokes /netllm-doctor. Runs netllm doctor and structured checks for providers, listen address, and global vs repo-local CLI.
version	1.0.0
license	MIT
compatibility	["cursor","codex","claude-code","copilot"]
allowed-tools	["Read","Shell","Grep"]

netllm doctor

When to use this skill

• Setup failed or agent unreachable
• No models in ./netllm models
• Swarm peers not discovered
• User says "netllm broken", "fix netllm", or /netllm-doctor

Workflow

1. Run built-in doctor

   ./netllm doctor
   

   Capture each issue title and suggested fix from output.

2. PATH check

   which netllm || true
   ./netllm --version
   

   • Repo checkout: prefer ./netllm from root
   • Global install: ~/.local/bin/netllm: run ./netllm env for PATH export if needed

3. Agent reachability

   curl -sf http://127.0.0.1:11400/health || echo "agent down"
   

   If down, start by install channel:

   • Source / dev: ./netllm serve (foreground)
   • macOS app / Homebrew: ./netllm start or menubar → Restart Agent
   • Linux deb/rpm: systemctl --user enable --now netllm: see docs/linux-install.md
   • Windows zip/winget: netllm start after install-service.ps1: see docs/windows-install.md

4. Local providers

   ./netllm discover
   

   Expected ports: Ollama 11434, LM Studio 1234, vLLM 8000; oMLX 8080 on macOS only

5. Config review, read ~/.config/netllm/config.toml (or path from user):

   • agent.listen: loopback vs 0.0.0.0
   • agent.advertise: required for gateway role
   • swarm.mdns: needs zeroconf from uv sync
   • swarm.cluster_token: empty is fine on trusted home LAN (open swarm); set only for untrusted networks

6. Platform-specific swarm checks (when ./netllm peers is empty but LAN routing is expected):

   • All platforms: ./netllm doctor now prints per-platform firewall commands (UDP 5353 mDNS in/out + TCP 11400 in) when mDNS looks blocked. LAN-bound agents auto-run a one-shot subnet scan 10s after start when mDNS finds nothing.
   • Loopback peers: ./netllm peers lists loopback-bound agents as found but unreachable — fix is menubar LAN mode, netllm init --swarm, or serve --host 0.0.0.0 on that machine
   • Token mismatches: heartbeats return 401; align tokens with netllm swarm-token + netllm join URL --token T
   • Linux: mDNS uses Avahi via python-zeroconf; install Avahi if browse fails. Fallback: swarm.peers or ./netllm peers --subnet-scan --save
   • Windows: mDNS is often blocked by firewall or missing Bonjour: prefer static swarm.peers or --subnet-scan. Allow inbound TCP on agent port (default 11400) when serve --host 0.0.0.0
   • All platforms: Guest Wi‑Fi often blocks mDNS; loopback bind (127.0.0.1) hides the agent from LAN peers

7. Inference test

   ./netllm test
   

8. Structured report, for each issue: Problem → Fix → Verify command

9. Re-run doctor after fixes:

   ./netllm doctor && scripts/agent-verify-setup.sh
   

Examples

Agent unreachable

Problem: curl /health fails
Fix: ./netllm serve in dedicated terminal
Verify: curl -sf http://127.0.0.1:11400/health

No providers online

Problem: discover shows 0/3 online
Fix: Start Ollama (ollama serve); on macOS also oMLX. Linux/Windows: Ollama, LM Studio, or vLLM, see install docs
Verify: ./netllm discover && ./netllm models

Windows swarm: no peers

Problem: ./netllm peers empty on Windows LAN
Fix: Add swarm.peers in config or ./netllm peers --subnet-scan --save; allow firewall inbound on :11400
Verify: ./netllm peers && ./netllm models --lan

mDNS unavailable

Problem: doctor reports zeroconf missing
Fix: uv sync from repo root
Verify: ./netllm peers

Edge cases

Situation	Action
Doctor passes but editor fails	Run netllm-connect-editor skill: likely model name mismatch
Model 404 with catalog list	Request used a name no backend serves — pick one from the 404 message or map it via [routing.model_aliases]
Wrong netllm on PATH	./netllm install from repo or use ./netllm only
agent-verify-setup.sh fails but ./netllm models works	Script prefers global netllm; use ./netllm models or unset global from PATH
Doctor "port in use" while testing	Expected if serve or menubar app is running
Config missing	./netllm init

Do not

• Delete config without user approval: suggest ./netllm init --force explicitly
• Commit diagnostic output containing secrets