UniFi network management for AI agents: safe keys, playbooks, backups

A UniFi console holds everything that makes a small network work: the SSIDs, which are the Wi-Fi names your devices see, the VLANs that split one physical network into separate segments, the firewall rules between them, and the firmware on every device. An agent that can read all of that is a patient troubleshooter. An agent that can write all of that is one wrong guess from an outage, and the worst outage is the one where it reboots the gateway its own connection rides on and nobody is left to undo it.

UniFi AI Network Management is the package I built so that the reading could be generous and the writing stingy. It bundles a SKILL.md runbook with safety tiers, a Python API helper that uses only the standard library, owner-only tools for setup, status and a break-glass switch, meaning the emergency off, a timestamped backup, and a restore that stays a dry run until you type the exact words. It installs into OpenClaw or Hermes Agent, two frameworks that read skills from the filesystem, and adapts to any framework that does the same. It is MIT licensed, created in May 2026, last pushed in October 2026.

Three UniFi APIs, kept apart

UniFi has three APIs, not one, and the helper separates them deliberately. The Site Manager API lives in Ubiquiti's cloud at api.ui.com/v1, authenticates with an X-API-Key header, and gives a fleet overview across consoles and sites. The local Network Integration API is the official one on your own console, at https://<controller>/proxy/network/integration/v1, also keyed, and it is where sites, devices and clients come from. The third is the legacy private Network Application API, which wants a username, a password and a session cookie; it is version-dependent, so use it sparingly. The rule is official first, legacy only when no official route exists.

The helper is one Python file with generic commands rather than a wrapper per endpoint, and every write command refuses to run without the flag --yes-I-understand. One trap is worth knowing first: some controller revisions use the plural integrations in the local path, so if every local endpoint returns 404 while host and key are right, set UNIFI_NETWORK_PREFIX=/proxy/network/integrations/v1 in the env file and try again.

Installing it, and where the key goes

You need a Linux or WSL-style shell, Bash and Python 3.10 or newer. Clone it where the agent runs and point the installer at your framework:

Code, shellgit clone https://github.com/AEON-7/unifi-ai-network-management.git
cd unifi-ai-network-management
./setup.sh --target openclaw
source ~/.bashrc
unifi-setup-openclaw
unifi-status-openclaw

For Hermes Agent, replace openclaw with hermes throughout and finish with hermes doctor. The installer copies the whole skill/unifi-api directory, SKILL.md with the helper and four reference pages, into the framework's skill path and puts six commands per target in ~/.local/bin: status, setup, off, on, backup and restore.

Local API keys come from the console at Network > Settings > Control Plane > Integrations. Copy the key once and hand it to unifi-setup-openclaw. The tool hides what you type, backs up the previous env file, and writes the new one with mode 0600, readable only by your user. The file lands at ~/.openclaw/unifi.env or ~/.hermes/unifi.env, outside the repository, which ships an env.example and never a real one.

The README's safety baseline is ten rules, and two carry most of the weight. Split access: a read-only key for daily monitoring, a write-capable key with the narrowest scope UniFi offers for explicit maintenance windows, and the legacy service account disabled unless a task needs it. Keep write-capable keys out of chat history. UNIFI_INSECURE_TLS=1, which turns off certificate verification, is for a self-signed local controller only, never for the cloud API.

The playbooks

The skill carries ten task recipes. Most are diagnostic: a network health summary, bad Wi-Fi for one client, a firmware audit, an audit of how SSIDs map to VLANs, a review of guest access, and a switch port or PoE issue, where PoE is the power a switch sends to an access point over its Ethernet cable. One is a narrow repair, reconnecting a single client. One is paperwork, the change record with before, after and rollback. The last two are the backup before a major change and the restore from one.

AGENTS.md adds a behavior contract of eleven rules, and every write follows seven steps: read the current state, identify the exact site and object, back up if the change is major, explain the intended action, make the smallest possible write, verify afterward, and report before and after with the rollback. Reboots, firmware upgrades, VLAN, DHCP, DNS and firewall changes, SSID changes, PoE cycling, factory resets and blocking a client of uncertain identity never happen on the agent's own initiative. They need explicit intent from the person and, in nearly every case, a backup first; only a single verified client reconnect may skip it.

Backups, and a restore that refuses to guess

unifi-backup-openclaw writes a timestamped backup-YYYYMMDD-HHMMSS folder under ~/.openclaw/unifi-backups/, with a latest symlink and a log of every restore. Directories are 0700 and files 0600, because a backup may hold SSIDs, firewall rules, VLANs, port profiles and possibly Wi-Fi credentials. It never goes into chat either.

Restore is a dry run by default: it prints the plan and changes nothing. Applying needs --apply with the exact phrase RESTORE UNIFI CONFIG, and even then objects that exist now but are absent from the backup are kept unless you also pass --delete-extra, meant only for an intentional full rollback.

Code, shellunifi-backup-openclaw
unifi-restore-openclaw --backup ~/.openclaw/unifi-backups/backup-YYYYMMDD-HHMMSS
unifi-restore-openclaw --backup ~/.openclaw/unifi-backups/backup-YYYYMMDD-HHMMSS --apply --confirm 'RESTORE UNIFI CONFIG'

Backup and restore live inside the skill on purpose. The agent may back up on demand and run a dry run when asked, but it starts a restore only when the person asks, and when several backup dates exist it must ask which. The SKILL.md puts it in three words: do not guess.

Break glass, and the rules I wrote down

Setup, status and the kill switch are owner commands, kept out of the skill workflow so the agent never runs them on itself. unifi-off-openclaw renames unifi.env to unifi.env.disabled and restarts the agent's gateway process if one is running; unifi-on-openclaw puts it back. What matters is what the switch does not do: it is local, and it does not revoke the real key. If a key may be compromised, delete it in the console under Settings > Control Plane > Integrations and disable or rotate any legacy service user. Then preserve the logs and inspect recent controller changes before you re-enable anything.

Handing an agent API access to a network is like handing a junior network admin a constrained service account and a very detailed runbook, and most of the runbook is about identity and self-preservation. Verify every object by name plus MAC address, IP or model before writing to it, and never confuse a site ID with a device, client or network ID; default is not necessarily the only site. Do not reboot the gateway that carries the agent's own SSH or API path, and do not change Wi-Fi security or VLANs during a voice or text session unless a second management path exists, a rule that matters when the agent on the line is the Matrix VoIP agent or wears one of the agentic personas. Everything else I publish is listed in the Aeon Forge catalog.

Sources

• Repository: AEON-7/unifi-ai-network-management (README, AGENTS.md, SKILL.md, docs)
• Ubiquiti: Getting started with the UniFi API
• Ubiquiti: Site Manager API and the developer portal
• Maker account: AEON-7 on GitHub