Unifi

# UniFi Network Monitoring Skill

Monitor and query your UniFi network via the local UniFi OS gateway API (tested on Cloud Gateway Max).

## Purpose

This skill provides **read-only** access to your UniFi network's operational data: - Devices (APs, switches, gateway) status and health - Active clients (who's connected where) - Network health overview - Traffic insights (top applications via DPI) - Recent alarms and events

All operations are **GET-only** and safe for monitoring/reporting.

## Setup

Create the credentials file: `~/.clawdbot/credentials/unifi/config.json`

```json { "url": "https://10.1.0.1", "username": "api", "password": "YOUR_PASSWORD", "site": "default" } ```

- `url`: Your UniFi OS gateway IP/hostname (HTTPS) - `username`: Local UniFi OS admin username - `password`: Local UniFi OS admin password - `site`: Site name (usually `default`)

## Commands

All commands support optional `json` argument for raw JSON output (default is human-readable table).

### Network Dashboard

Comprehensive view of all network stats (Health, Devices, Clients, Networks, DPI, etc.):

```bash bash scripts/dashboard.sh bash scripts/dashboard.sh json # Raw JSON for all sections ```

**Output:** Full ASCII dashboard with all metrics.

### List Devices

Shows all UniFi devices (APs, switches, gateway):

```bash bash scripts/devices.sh bash scripts/devices.sh json # Raw JSON ```

**Output:** Device name, model, IP, state, uptime, connected clients

### List Active Clients

Shows who's currently connected:

```bash bash scripts/clients.sh bash scripts/clients.sh json # Raw JSON ```

**Output:** Hostname, IP, MAC, AP, signal strength, RX/TX rates

### Health Summary

Site-wide health status:

```bash bash scripts/health.sh bash scripts/health.sh json # Raw JSON ```

**Output:** Subsystem status (WAN, LAN, WLAN), counts (up/adopted/disconnected)

### Top Applications (DPI)

Top bandwidth consumers by application:

```bash bash scripts/top-apps.sh bash scripts/top-apps.sh 15 # Show top 15 (default: 10) ```

**Output:** App name, category, RX/TX/total traffic in GB

### Recent Alerts

Recent alarms and events:

```bash bash scripts/alerts.sh bash scripts/alerts.sh 50 # Show last 50 (default: 20) ```

**Output:** Timestamp, alarm key, message, affected device

## Workflow

When the user asks about UniFi:

1. **"What's on my network?"** → Run `bash scripts/devices.sh` + `bash scripts/clients.sh` 2. **"Is everything healthy?"** → Run `bash scripts/health.sh` 3. **"Any problems?"** → Run `bash scripts/alerts.sh` 4. **"What's using bandwidth?"** → Run `bash scripts/top-apps.sh` 5. **"Show me a dashboard"** or general checkup → Run `bash scripts/dashboard.sh`

Always confirm the output looks reasonable before presenting it to the user (check for auth failures, empty data, etc.).

## Notes

- Requires network access to your UniFi gateway - Uses UniFi OS login + `/proxy/network` API path - All calls are **read-only GET requests** - Tested endpoints are documented in `references/unifi-readonly-endpoints.md`

## Reference

- [Tested Endpoints](references/unifi-readonly-endpoints.md) — Full catalog of verified read-only API calls on your Cloud Gateway Max