claude-unifi-skill
leipold-us/claude-unifi-skill
Claude Code skill to check on your UniFi gateway (Dream Machine Pro & family) over SSH — health, clients, WAN/public-IP history, IDS threats, AP/switch inventory, VPN/port-forwards. Read-only.
Instalação
npx convez-ai leipold-us/claude-unifi-skill1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
UniFi Gateway skill for Claude Code
A Claude Code skill that lets you ask Claude to check on your UniFi gateway — Dream Machine Pro (UDM Pro), UDM, UDR, UXG, or similar — over SSH. Ask things like "how's the gateway?", "who are my top bandwidth users?", "has my public IP changed?", "any threats blocked today?", or "list my access points and their firmware."
Everything is read-only by default — the skill never reboots, updates, or changes config without you explicitly confirming.
What it covers
- Connecting — first-time SSH key setup so Claude can reach the gateway passwordless
- Health — CPU/load, memory, temperature, disk, top processes
- Clients — connected devices (IP / hostname / MAC)
- WAN / internet — public IP, speed-test history, and how long your IP has held (from the device's own DHCP log, often months)
- Security — IDS/IPS threats: top attackers, most-targeted hosts, categories
- Infrastructure — every adopted AP and switch with model + firmware (via the controller's MongoDB)
- Device management — SSH into adopted switches/APs (the right way, via Device Authentication key push), PoE/link diagnostics, and a safe down-AP recovery flow (find → diagnose → power-cycle/reboot)
- VPN / port forwards / firewall — WireGuard/IPsec tunnels, NAT forwards with labels, firewall summary
- Logs — a full catalog of every log on the device and how to read it
Examples
Real interactions (IPs/names sanitized). You just ask in plain language; Claude runs the read-only checks over SSH and summarizes.
"How long have I had my current public IP?"
You: has my WAN IP ever changed? how long have I had it?
Claude: Your public IP is
203.0.113.45, and it has never changed in the device's retained history — every one of the 3,700+ DHCP renewals logged since Jan 3 is the same address. That's ~5 months, which is as far back as the logs go; it's almost certainly been stable longer. Typical for ISPs that tie the lease to your modem/ONT — it renews the same IP every couple of hours rather than handing out a new one.
It reads this from the gateway's own wan-diag-dhcp.log, which usually goes back months — no external lookups, no guessing.
"Review my WiFi health — any problem APs?"
You: can you review the WiFi health? any problem APs?
Claude: 8 access points adopted · 5 up · 3 down.
🔴 Offline:
AP Model Last seen Notes Office U7PRO ~10 days ago Was healthy, dropped off recently — check PoE/cable first Bedroom U7PG2 none recorded Down long enough to have no last-seen; stuck on old firmware Patio U7PG2 none recorded Same pattern — likely unplugged/retired 🟢 Healthy: Living Room, Garage, Kitchen, Hall, Basement — all current firmware, seen seconds ago.
The recently-dropped one is the most actionable; the two with no last-seen and old firmware look long-dead. Want me to check which switch ports they hang off, to tell a PoE problem from an AP problem?
Cross-checks the controller's device records (last_seen, firmware) against a live ping of each AP, so "down" means actually unreachable — not just stale UI state.
"Bring that dead AP back"
A full recovery, end to end — diagnose, act (with confirmation), verify:
You: the Studio AP is down — can you fix it?
Claude: Confirmed down: its MAC isn't in the gateway's neighbor table at any IP, and the controller logged it disconnecting ~10 days ago. It hangs off port 4 of the
Studioswitch (last-known uplink). Two options:
- A — power-cycle just PoE port 4 (recommended): drops power to that one AP for a few seconds.
- B — reboot the whole switch: takes every device on it offline ~1–2 min.
Which do you want? Both change live state, so I'll wait for your call.
You: reboot the switch
Claude: Rebooting
Studioswitch… it dropped at t+15s, back up at t+75s. The AP needs a couple more minutes to boot — watching…✅ AP recovered:
192.168.1.xanswering (0% loss), controllerlast_seen1 min ago. Bonus: it pulled a pending firmware update on the way up, so it's now current. Port 4 PoE reads healthy (8.8 W, Class 4).
What made this work: it found the AP by MAC (not a stale IP), identified the exact switch + port from the controller's uplink record, used swctrl to read PoE/link, asked before the disruptive action, and knew an AP takes longer to boot than the switch — so it waited instead of declaring failure. Device SSH uses the key pushed via Device Authentication (works on switches/APs, survives reboots).
Other things to ask
- "how's the gateway?" — load, memory, temp, top processes
- "who are my top bandwidth users?" — top talkers by total bytes
- "any threats blocked today?" — IDS/IPS: top attackers, most-targeted hosts
- "list my APs and switches with firmware versions"
- "show my port forwards" / "are any VPN tunnels up?"
- "check the logs for anything around 3am"
Requirements
- Claude Code installed
- A UniFi gateway you administer, with SSH enabled (UniFi console → Settings → System → Console/Advanced → SSH)
ssh/ssh-keygen/ssh-copy-idon your machine
The gateway already ships with jq, mca-dump, and mongo, which the skill's commands use.
Install
git clone https://github.com/leipold-us/claude-unifi-skill.git
cd claude-unifi-skill
./install.sh
install.sh copies the unifi/ skill into ~/.claude/skills/unifi/. Restart Claude Code (or start a new session) and the skill is discoverable.
First-time connection
The skill's SKILL.md walks Claude (and you) through it, but in short:
- Enable SSH + set a password in the UniFi console.
- Generate a key:
ssh-keygen -t ed25519 -f ~/.ssh/udm-pro -N "" -C "claude-$(hostname -s)" - Install it (prompts for the SSH password once):
ssh-copy-id -i ~/.ssh/udm-pro.pub root@<GATEWAY_IP> - Add an SSH alias named
udm(snippet inSKILL.md). - Verify:
ssh udm 'uname -a'
Note: the key is stored in
/root/.ssh/authorized_keyson the gateway, which a firmware update or full reboot can wipe. If passwordless access stops working, just re-run step 3.
Portability
Written and verified against a Dream Machine Pro on UniFi OS 5.1.x. Other UniFi gateways are similar; the skill discovers model, firmware, WAN interface, and LAN bridges at runtime rather than hardcoding them, so it adapts. A few paths may still differ on older/newer firmware — PRs welcome.
Safety
Read-only by design. Any command that would reboot, update firmware, change configuration, or kill a process requires your explicit confirmation. The skill contains no credentials and no network-specific data — it discovers everything live from your own gateway.
License
MIT — see LICENSE.