Self-hosted, UniFi-inspired management for stock OpenWrt.
oonfeeWRT is a controller, not firmware. It runs on your server, NAS, mini-PC, or Mac and manages OpenWrt devices through their existing interfaces. Your routers stay on stock OpenWrt and continue to work with LuCI.
Docker is optional. Run the standalone binary directly on a supported 64-bit Linux or macOS host, or use the container/Compose setup. The controller does not need a dedicated machine and is not installed on the managed routers.
Live Internet health, controller-host speed tests, and fleet status.
Live radio inventory and evidence-aware channel planning.
- A fleet dashboard with WAN reachability, throughput, topology, clients, radios, events, and controller-host speed tests.
- Reviewed site configuration for networks, VLANs, DHCP, firewall zones, and WLANs, with OpenWrt's rollback timer protecting every Apply.
- Device adoption, health monitoring, telemetry, logs, RF tools, and explicit source-coverage gaps instead of guessed data.
- Local owner, administrator, operator, and read-only accounts with session management and revocation.
- Downloadable, redacted diagnostics bundles containing controller evidence and stored router model, firmware, and capability data.
- Encrypted controller backup and staged restore with compatibility checks, controlled restart, and a persistent router-write gate.
- Optional LLDP using the official OpenWrt
lldpdpackage, with an exact plan, separate consent, durable ownership records, and rollback.
oonfeeWRT does not build or replace OpenWrt, run controller-authored software on routers, broker cloud access, or silently install packages.
Adoption can create only one scoped oonfeewrt login and one rpcd ACL JSON
file after you approve the displayed plan. The router administrator credential
used for that one-time action is not stored. Optional packages and
configuration changes have separate review and consent flows.
The controller changes only UCI sections it owns. Existing human-managed sections remain visible but are not silently rewritten.
oonfeeWRT supports two equivalent ways to run the controller:
| Method | Supported controller hosts | Notes |
|---|---|---|
| Standalone binary | linux/amd64, linux/arm64, darwin/amd64, darwin/arm64 |
No Docker required; the UI is embedded in the binary |
| Container / Docker Compose | linux/amd64, linux/arm64 images |
Convenient for an existing NAS, mini-PC, SBC, or Docker Desktop host |
A controller host must be able to reach each router's management address. Remote sites need an existing routed management network or VPN; oonfeeWRT does not provide cloud brokering or automatic NAT traversal.
Managed routers require OpenWrt 21.02 or newer with SSH, rpcd, and the
uhttpd ubus handler. Hardware and driver capabilities still vary, so begin
with one non-critical device and review the detected capability gaps.
A 64-bit host with 1 GB of RAM and 2 GB of free storage is a practical starting point. The controller's engineering envelope is at most 256 MB steady-state RSS at 25 devices, 2% of one modern CPU core for an idle fleet, and 2 GB of disk at the full 13-month retention depth.
oonfeeWRT is not memory-only. Raw telemetry is held in RAM temporarily;
completed rollups, configuration, accounts, events, and audit history are
stored in SQLite. Preserve the data directory and its matching keyring.json
and passphrase when running either installation method.
Download and checksum-verify the archive for your platform by following the binary installation guide, then run:
install -d -m 0700 "$PWD/data"
./oonfeewrtd -data-dir "$PWD/data" -listen 127.0.0.1:8080The first interactive start asks you to create the controller passphrase. Open
http://127.0.0.1:8080 and create the first owner
account. For unattended startup, use -passphrase-file with a mode-0600
file as described in the installation guide.
Requirements:
- Docker with Compose support.
Create a private working directory and download the release Compose file:
mkdir -p oonfeewrt
cd oonfeewrt
curl --fail --location \
--output docker-compose.yml \
https://raw.githubusercontent.com/aiden0rchad/oonfeeWRT/v0.1.1/deploy/docker-compose.yml
umask 077
head -c 32 /dev/urandom | base64 > passphrase
sudo chown 65532:65532 passphrase
sudo chmod 600 passphrase
OONFEE_VERSION=v0.1.1 docker compose up -dOpen http://127.0.0.1:8080 and create the first owner
account. The default Compose configuration publishes HTTP only on host
loopback, runs as UID 65532, drops all capabilities, uses a read-only root
filesystem, and stores controller state in a named volume. It pulls
ghcr.io/aiden0rchad/oonfeewrt:v0.1.1 for linux/amd64 or linux/arm64.
The passphrase file unlocks the controller keyring and is not your owner
account password. Back it up with the controller state and keep both private.
docker compose down -v deletes the named data volume.
Bridge networking works on Linux and Docker Desktop. Layer-2 discovery does not cross the bridge, so add routers by address. Linux host networking is an explicit opt-in described in the Compose file.
For checksummed binaries, signature verification, reverse-proxy TLS, persistence, upgrades, and rollback, follow the installation guide.
No. Docker Compose is one quick-start option. The release also includes standalone 64-bit Linux and macOS binaries with the web UI embedded.
No. It runs separately on a computer, NAS, SBC, or server and manages stock OpenWrt devices. This keeps controller storage and upgrades away from the routers' limited flash, RAM, and firmware lifecycle.
SSH is a bounded bootstrap, cleanup, and separately approved optional-package path, not the steady-state management transport. Stock rpcd cannot create the scoped login and ACL through ubus, even when logged in as root. The administrator credential is used for the approved action and is not stored. Normal polling and configuration use rpcd/ubus.
Every Apply is previewed and uses OpenWrt's rollback window. The controller confirms only after reconnecting and reading the expected state. If the router becomes unreachable or the operation is interrupted, OpenWrt rolls the change back. The controller also limits cleanup and writes to UCI sections it owns.
-
Set a router root password if it does not already have one:
ROUTER_ADDRESS=192.0.2.1 ssh -t root@"$ROUTER_ADDRESS" passwdThe controller warns rather than blocking an explicitly trusted, passwordless lab router. Do not rely on that outside isolated testing.
-
In Devices, add the router by address or run the on-demand discovery scan.
-
Review the controller-access payload. Approving it creates the scoped login and ACL; cancelling changes nothing.
-
Inspect discovered capabilities and source gaps.
-
Preview configuration before Apply. Router changes never happen merely because a device was discovered or listed.
- Apply uses
uci.applywith a rollback window, then confirms only after the controller can read the expected state. An interrupted or unhealthy Apply reverts on the router. - Ownership tags restrict changes and cleanup to controller-created sections.
- RF scans, speed tests, capability installation, and other disruptive actions require explicit acknowledgement.
- Un-adoption restores or removes controller-owned configuration, then removes the scoped login and ACL. It is blocked while an optional LLDP installation still has a rollback record.
- Restoring a controller never automatically applies restored desired configuration. Router writes remain suppressed until an owner reviews and explicitly resumes them.
- The HTTP listener has no native TLS. Keep it on loopback or an isolated management network, and use a trusted reverse proxy for remote access.
Owners can use Settings → Backup & Restore to export an encrypted
.oowrtbak file. Export requires recent account reauthentication and a
separate passphrase that the controller does not retain. Restore decrypts and
validates in disposable staging, shows a compatibility preview, creates a
safety backup, and completes through a controlled restart.
For filesystem-level recovery, oonfeewrt.db and keyring.json are one
unit. The runtime passphrase cannot recreate a lost keyring. See the
installation guide before copying live
state.
Diagnostics bundles are bounded, redacted ZIP files generated from stored controller evidence. They make no router management call and exclude credentials, WLAN keys, private keys, session material, and controller passphrases.
- Hardware validation covers a Linksys WRT3200ACM and TP-Link Archer C6 v2 on OpenWrt 25.12.5. Three-or-more-AP fan-out, real mesh backhaul, wireless uplink, MT7621, and MT7981/Filogic remain unverified.
- The speed test runs from the controller host or container through Cloudflare, not from a router. It uses approximately 15 MiB, is bounded to 30 seconds, and can temporarily saturate the WAN. Loaded latency and jitter are not measured.
- Native controller TLS, cloud remote access, and gateway-run speed tests are not included in v0.1.1.
- Optional LLDP may install official-feed packages. Adoption itself never installs a package, daemon, service, firmware, or executable.
Detailed hardware evidence and known gaps are in the fresh-start validation record and parity matrix.
Go 1.26.6 and Node.js 22 are the release toolchain.
make check
make build
./oonfeewrtd -data-dir "$PWD/.run" -listen 127.0.0.1:8080For unattended startup, use -passphrase-file with a mode-0600 file.
oonfeeWRT rejects passphrases supplied through environment variables.
- Install, upgrade, TLS, and recovery
- v0.1.1 release notes
- v0.1.0 release notes
- Architecture and security boundaries
- Hardware validation
- Feature parity and evidence
- Roadmap
- Risk register
Apache License 2.0. See LICENSE, NOTICE, and THIRD_PARTY_LICENSES. Every release archive and container image includes the same notices.
AI coding tools have been used substantially during development to help draft and iterate on implementation code, tests, debugging, and documentation. The maintainer supplies the product direction, networking architecture, security boundaries, hardware knowledge, review, and final decisions, and remains responsible for what the project ships.
AI output is not treated as evidence that the software is correct or secure.
CI runs Go tests, go vet, the race detector, govulncheck, UI unit and browser
tests, npm audit, release smoke tests, and repository/history secret scans.
Hardware behavior is checked separately against physical OpenWrt devices and
the known coverage gaps are published above.
oonfeeWRT has not received an independent security audit or third-party penetration test. It is a new project: start with non-critical hardware, keep backups, review every proposed router change, and report unexpected behavior.