A single Pane of Glass orchestration for OpenWRT Networks
- Python 52.8%
- Go 23.9%
- Vue 17.8%
- Shell 2.6%
- TypeScript 2.5%
- Other 0.3%
| agent | ||
| broker | ||
| Completed | ||
| controller | ||
| db/init | ||
| deploy | ||
| docs | ||
| packaging | ||
| scripts | ||
| services/mdns-relay | ||
| tests | ||
| Updates_to_make | ||
| Upgrades_to_make | ||
| .env.example | ||
| .gitignore | ||
| AGENTS.md | ||
| code_reviewed_notes.md | ||
| docker-compose.yml | ||
| product_specification.md | ||
| README.md | ||
| refined_product_speicifcation.md | ||
| requirements.md | ||
| REVIEW_WORK_PLAN.md | ||
| TODO.md | ||
GlassWRT
Centralized, multi-tenant, state-synchronized OpenWRT management platform.
See
docs/PLAN.mdfor the full phased build plan andrefined_product_speicifcation.mdfor the specification source of truth.
Architecture
- Controller backend: Python 3.11+ / FastAPI (async) — controller/backend/
- Controller frontend: Vue 3 + Ant Design Vue + Xterm.js — controller/frontend/
- Database: PostgreSQL 16+
- MQTT broker: Eclipse Mosquitto (TLS 1.3 on port 8883)
- Agent: Go 1.22+ binary installed on each OpenWRT device — agent/
- Packaging: OpenWRT Makefile +
.ipk— packaging/
Features
- Multi-tenant RBAC — organizations, projects, role-based access with SuperAdmin/OrgAdmin/ProjectNetworkAdmin/ProjectObserver
- Agent management — mDNS auto-discovery, zero-touch adoption, MQTT TLS 1.3 heartbeats with LWT, over-the-air enrollment
- Network configuration — VLAN, mwan3, WireGuard, DHCP, DNS, WiFi, timezone, backup via transactional rollback engine
- Observability — real-time SSH shell, system/kernel log streaming, topology graph, process management, bandwidth charts
- Dashboard — customizable widget system with donut charts, event log, speed test trends, device health, top talkers, firmware distribution, 24h bandwidth comparison
- Lifecycle — package management (opkg), firmware upgrades, attended sysupgrade via ASU, firewall config (fw4)
- Security — TOTP MFA, WebAuthn passkeys, OIDC provider management, signed CSR-based enrollment
- Notifications — SMTP/Webhook/HomeAssistant delivery, new device/offline/data usage/bandwidth saturation rules
Quick start (Phase 0)
# 1. Copy environment template (already done in dev; idempotent)
cp -n .env.example .env
# 2. Bring the whole stack up
docker compose up -d --build
# 3. Verify the stack
bash tests/verify_deployment.sh
The verify script waits up to 45 s for all four services (postgres, mosquitto, backend, frontend) to report healthy and confirms /healthz returns 200 via both the frontend (port 80) and backend (port 8000).
Supported hardware
Deployed and verified on:
| Device | SoC | Arch | OpenWRT | Package |
|---|---|---|---|---|
| x86-64 (dev) | — | x86_64 |
24.10 | glassagent_0.2.0-1_x86_64.ipk |
| Zyxel GS1900-8HP v1 | RTL8380 (MIPS32r2) | mips_4kec |
24.10.0 | glassagent_0.2.0-1_mips_4kec.ipk |
Zero-touch adoption
The agent supports zero-touch adoption via mDNS + HTTP config server:
- Install the
.ipkon the device — agent starts, broadcasts_glasswrt._tcpvia mDNS - Relay (
scripts/mdns_relay.py) on the Docker host discovers the device and POSTs to the controller - Admin clicks Adopt in the Web UI — controller pushes MQTT/TLS config to the agent's HTTP adopt server
- Agent writes
agent.yaml, restarts, connects via MQTT
See the Admin Guide for full setup.
Phased delivery
| Phase | Title | Status | |
|---|---|---|---|
| 0 | Foundation | complete | |
| 1 | Core Orchestration & Multi-Tenancy | complete | |
| 2 | Agent Development & Enrollment | complete | |
| 3 | Network Configuration Engine + extras | complete | |
| 4 | Observability & Visual Intelligence + extras | complete | |
| 5 | Lifecycle & Maintenance | complete | |
| — | Zero-Touch Adoption & Real Hardware | complete | |
| — | Post-Phase 5: Bandwidth Charts, Multi-WAN, DHCP/DNS, Floorplans, Snapshots | complete | |
| — | Post-Phase 5: OIDC Provider Management, WebAuthn MFA, Config File Editor | complete | |
| — | Post-Phase 5: Dashboard Overhaul (widgets, donuts, event log, 5 new endpoints) | complete | |
| — | Post-Phase 5: Speed Tests, Port/DHCP Counts, Device List Fields, Notifications | complete | |
| — | Post-Phase 5: WiFi Interface Management, Multi-WAN Enhancements | complete |
- AGENTS.md — live build progress and per-step checklists.
Ports
| Service | Port (host) | Notes |
|---|---|---|
| Frontend (nginx) | 80 | SPA + reverse-proxies /api/* + /ipk/* to backend |
| Backend (FastAPI) | 8000 | /healthz, /api/v1/*, /ipk/*, OpenAPI at /docs |
| PostgreSQL | 5432 | Internal; mapped on host for psql access |
| Mosquitto MQTT (TLS 1.3) | 8883 | mTLS-capable; allow_anonymous=false |
| Reverse proxy (TCP) | 9090 | Agent reverse connection for shell/logs/process (Phase 4) |
Replacing the dev MQTT certs
cert-init generates a self-signed CA and server cert in the shared mosq_certs volume the first time the stack is brought up. For production, replace the contents of mosq_certs (ca.crt, server.crt, server.key) with your real certs and restart the mosquitto and backend services.