Quick start
This page starts oonfeeWRT v0.1.8 on one host and creates the first owner account. It offers a standalone-binary path and a Docker Compose path; use only one.
Outcome: The controller answers at
http://127.0.0.1:8080,/healthzreturnsok, and you can sign in as the first owner.
Before you begin
You need:
- a supported 64-bit Linux or macOS host;
- network reachability from that host to the OpenWrt management address;
- either Docker with Compose support or the v0.1.8 release archive;
- a private place to retain the controller runtime passphrase and data.
Write impact: With a new data directory or volume, these steps write only to the controller host and do not contact a router. Reusing existing controller state resumes adopted-device polling and may resume automatic runtime 802.11k neighbour maintenance. Router access on a fresh controller begins when you explicitly inspect or adopt a device.
Option A: standalone binary
Follow Install the binary to download and checksum-verify the correct release. Then start it with a private data directory:
install -d -m 0700 "$PWD/data"
./oonfeewrtd -data-dir "$PWD/data" -listen 127.0.0.1:80802
On the first interactive start, the daemon asks twice for a new runtime passphrase. There is no recovery if it is lost.
Keep this terminal open while completing the browser setup. For unattended startup, stop the daemon with Ctrl-C and configure the mode-0600 passphrase file described in the binary installation guide.
Option B: Docker Compose
Create a private working directory, download the exact v0.1.8 Compose file, and create the runtime passphrase:
install -d -m 0700 oonfeewrt
cd oonfeewrt
umask 077
curl --fail --location \
--output docker-compose.yml \
https://raw.githubusercontent.com/aiden0rchad/oonfeeWRT/v0.1.8/deploy/docker-compose.yml
head -c 32 /dev/urandom | base64 > passphrase
sudo chown 65532:65532 passphrase
sudo chmod 600 passphrase
printf '%s\n' \
'OONFEE_VERSION=v0.1.8' \
'OONFEE_HTTP_BIND=127.0.0.1' > .env
chmod 600 .env
docker compose up -d2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
The supplied Compose file:
- publishes the controller only on
127.0.0.1:8080; - runs as UID/GID 65532;
- uses a read-only root filesystem;
- drops all Linux capabilities and disables privilege gain;
- stores controller state in the named volume
oonfee-data; - reads the runtime passphrase from
./passphrase.
Do not run docker compose down -v unless you intend to delete the named controller-data volume.
Create the first owner
- On the controller host, open http://127.0.0.1:8080.
- Enter a username. Controller usernames are 1–64 ASCII characters, must start with a letter or digit, and may contain letters, digits,
.,_, or-. - Enter a password of at least 12 characters and confirm it.
- Complete setup. The first account becomes the owner and is signed in.
The account password is not the runtime passphrase. Keep both in your password-management and recovery plan.
Verify the controller
From the controller host:
curl --fail http://127.0.0.1:8080/healthzExpected output:
okFor Docker, also check:
docker exec oonfeewrt /oonfeewrtd -version
docker compose ps
docker compose logs --tail=100 oonfeewrt2
3
The version command must print v0.1.8, and the service must report healthy.
In v0.1.8, Workspace groups Dashboard, Devices, Client Devices, Topology, Radios, Policy Engine, and Adopt a device. Insights groups Statistics, Reports, and Alerts. The sidebar places Settings, Accounts, and Logs, in that order, in a Controller group at the foot of the sidebar, followed by your compact profile shortcut to Accounts. The group remains reachable on a short screen. Open Settings → Firmware or Settings → Integrations for optional checks; opening either tab only loads stored state and does not run a check. New section bookmarks use /settings?section=firmware and /settings?section=integrations; the old standalone URLs remain supported. Accounts opens your identity, password, and sessions; owners also get a Manage accounts tab. On narrow screens, use Open navigation to reach the same workspaces with full labels. Desktop navigation can remain collapsed or expanded independently. See Accounts, roles, and sessions.
If it does not start
The daemon says no passphrase is available
An unattended process has no terminal from which to prompt. Configure -passphrase-file or OONFEE_PASSPHRASE_FILE with a regular file that is not readable by group or other users.
The passphrase file is rejected
For a standalone install:
chmod 600 /absolute/path/to/passphraseFor the supplied Compose file, it must also be readable by UID 65532:
sudo chown 65532:65532 passphrase
sudo chmod 600 passphrase2
The keyring cannot be unlocked
The runtime passphrase is wrong, or keyring.json is corrupt or truncated. Do not delete it and restart: a replacement keyring cannot decrypt the existing database. Restore the matching database, keyring, and passphrase backup.
The database exists but keyring.json does not
Startup intentionally refuses this state. Restore the matching keyring. Move the database aside only if you deliberately want a new, empty controller and accept re-adopting every device.
Port 8080 is already in use
Choose another loopback port for a standalone process, for example:
./oonfeewrtd -data-dir "$PWD/data" -listen 127.0.0.1:8081Then open http://127.0.0.1:8081. With the v0.1.8 Compose file, change published: "8080" to the desired host port and keep target: 8080.
The browser is on another computer
127.0.0.1 is reachable only on the controller host. The v0.1.8 Compose file accepts OONFEE_HTTP_BIND=<controller-LAN-IP> for a deliberate isolated management-network bind. Prefer one concrete IP; 0.0.0.0 exposes the port on every host IPv4 interface and is never the browser URL. Do not expose raw port 8080 to the Internet. Configure reverse-proxy TLS for access beyond the trusted management network. Change the value in .env and run docker compose up -d again so later lifecycle commands retain it.