UniFi router (read-only)
The UniFi console is registered like any other host, but it is reached over its
local API instead of SSH, so hh run does not apply to it. Everything goes
through one command:
hh unifi <op> [alias] [args]
The alias can be omitted when only one console is registered, which is the
normal case. hh list shows it with platform unifi and auth apikey.
THIS IS READ-ONLY. DO NOT TRY TO CHANGE THE NETWORK.
Say it plainly to yourself before every UniFi task: you can look, you cannot touch. This is not a preference or a default that a good enough reason can override. It is the point of the integration.
- There is no command here that changes anything. No restart, no reboot, no
adopt, no firmware upgrade, no port or VLAN or SSID or firewall edit, no
client block, no config write of any kind. The broker behind
hh unifiissues HTTP GET and physically cannot issue anything else. - The API key is minted under a View Only UniFi admin, so the console refuses writes even if something got past the broker.
- Do not try to route around this. Do not look for another path to the router:
not SSH to the gateway, not the UniFi mobile app, not
curlagainst the API yourself, not a script that "just" restarts one access point. If you catch yourself planning any of that, stop. The answer is to tell the user what to change, not to change it. - If the user asks you to change a UniFi setting, do not refuse flatly and do not quietly do nothing. Say that HomelabHero's UniFi access is read-only on purpose, then give the operator the exact steps to do it themselves in the UniFi app: which screen, which setting, which value, and what they should expect to see afterwards. Offer to re-read the state once they have done it and confirm it took effect. That is the whole workflow, and it is a good one.
Why it is built this way: the router is the one device whose failure takes away the access you would need to fix it. A bad firewall rule, a mistaken VLAN change, or an ill-timed reboot can cut off every host, the command center, and your own way in, all at once, with no way back except physically standing in front of the hardware. Nothing an agent could usefully automate here is worth that risk. So the router is treated as a source of truth to read and reason about, and changes stay with the person.
Read capabilities/unifi.md for the full read surface and the exact ops. It is
not loaded up front.
What you can read
hh unifi summary the one-screen picture: WAN, internet, LAN, WiFi, device counts, pending firmware, client count hh unifi health WAN / internet / LAN / WiFi subsystem status hh unifi devices adopted gear: name, model, state, IP, firmware hh unifi clients connected clients: name, IP, MAC, type hh unifi networks configured networks and VLANs hh unifi info console and Network application version hh unifi sites sites on the console (usually just one) hh unifi device <id> full JSON for one device hh unifi stats <id> latest statistics for one device hh unifi ping connectivity check
Start with summary. It answers most questions on its own, and it tells you
whether to go deeper into devices, clients, or health.
For anything the named ops do not cover, there is a raw GET escape hatch. It is
still read-only, and {site} / {siteName} are substituted for you:
hh unifi get '/proxy/network/integration/v1/sites/{site}/firewall/policies' hh unifi get '/proxy/network/api/s/{siteName}/stat/event?_limit=20' hh unifi get '/proxy/network/api/s/{siteName}/rest/portforward' hh unifi get '/proxy/network/api/s/{siteName}/rest/wlanconf'
Two APIs sit under /proxy/network/: the documented integration API at
/integration/v1/..., and the older private API at /api/s/{siteName}/...
which still holds things the new one has no equivalent for. Prefer the former;
reach for the latter when it is the only source.
Reading the output
summary and health report four subsystems. What each one failing means:
- WAN not ok: the internet link itself. Check
wan_ipis present and plausible. No IP means the connection to the ISP is down, which is upstream of everything and not something in the homelab to fix. - Internet (www) not ok: the link is up but quality is poor. Latency and throughput numbers are in the same line; compare them against what the user pays for before calling it a fault.
- LAN not ok: usually a switch offline or a port down. Cross-check with
hh unifi devicesfor anything notONLINE. - WiFi (wlan) not ok: an access point is offline or disconnected. Again,
devicesnames which one.
An OFFLINE device in devices is the single most useful signal here. If a
host is unreachable and the access point or switch it hangs off is offline, the
network is the cause and there is no point troubleshooting the host.
How this fits the rest of the ladder
The escalation ladder in CLAUDE.md ends at the network layer, and this is the
top of it. When several unrelated things are broken at once, check here early:
one offline switch explains a dozen unreachable services, and it takes one
command to rule in or out.
Pair it with netbird-ops for the mesh, cloudflare-ops for ingress, and
network-diag for DNS resolution and per-host interfaces. UniFi tells you
about the fabric and the gear; network-diag tells you about the overlay and
the hosts on it.
Useful pairing in practice:
hh unifi summaryto see whether the fabric is healthy at all.hh unifi devicesto find anything offline.hh unifi clientsto confirm a specific machine is actually on the network, and on which network or VLAN.- Then
hh test <alias>and thenetwork-diagskill for the hosts themselves.
Recording what you learn
The topology notes in infra/network.md are the place for anything durable you
discover here: subnets and VLANs, which access point covers which area, the
normal client count, what the internet numbers usually look like. Reading the
live console is how you learn it; writing it down is how it stays learned. When
an incident is resolved, the runbook entry belongs in runbooks/ as usual.
