OpenWrt Router

Set up an agent on an OpenWrt router

Already running OpenWrt? Put the agent on the router itself — no extra box to buy or power, and everything on your network becomes reachable.

Before You Start

A MikRouter account with an agent created under Agents.
That agent's token and tunnel host, from its detail page. You'll paste them into the router.
A router already running OpenWrt (18.06 or newer), reachable over ssh as root — we don't install OpenWrt for you.
About 600 KB free on the router — df -h /overlay tells you. Step 2 checks this before anything is downloaded.
Internet access on the router. The agent dials out, so you don't open a port and don't need a public IP.

Your router carries on being a router

The agent changes nothing about how your router works. Wi-Fi, DHCP, DNS, routing and the firewall all stay where they are, in LuCI. The agent just opens one connection out to MikRouter and passes traffic back down it to devices on your network.

Nothing connects in, so this works behind CGNAT and on a changing IP — no port forwarding, no public address.

Connect to the router over SSH

Open a terminal on your computer and log in to the router as root. Use the router's own address — 192.168.1.1 on a fresh OpenWrt install.

Terminal

ssh root@192.168.1.1

If SSH is switched off, turn it on in LuCI under System›Administration›SSH Access first. Everything below is typed on the router.

Check there is room on the router

The agent needs about 600 KB of free space. Check that before downloading anything:

OpenWrt (SSH)

df -h /overlay

OpenWrt (SSH)

root@OpenWrt:~# df -h /overlayFilesystem                Size      Used Available Use% Mounted on/dev/ubi0_1               1.1M    524.0K    628.0K  46% /overlay

Look at the Available column. This router has 628 KB free, which is enough.

Not enough room? There is a second route

Small routers — 4 MB of flash, often with only ~320 KB of space in total — can't fit the agent, and deleting things won't help. You'll see this:

OpenWrt (SSH)

 * verify_pkg_installable: Only have 84kb available on filesystem /overlay,   pkg mikrouter-agent needs 480

If that's your router, stop here and use Set up an agent on a small-flash OpenWrt router instead. It keeps a few kilobytes on the router and loads the agent into memory at every boot.

Paste the one-line installer

Paste this into the router's terminal and press Enter.

It asks which version — press Enter for the newest — then for the settings page port, the agent server and the device token. The last two are on the agent's page in your dashboard. Enter keeps whatever is shown in brackets.

That is all: the agent is installed, starts at boot, and is already connected.

OpenWrt (SSH)

wget -qO- https://mikrouter.com/installer/install-agent-openwrt.sh | sh

OpenWrt (SSH)

root@OpenWrt:~# wget -qO- https://mikrouter.com/installer/install-agent-openwrt.sh | sh MikRouter agent installer  router     OpenWrt 25.12.5 (mips_24kc)  packages   apk (.apk) Finding the newest version ... Downloading mikrouter-agent_1.0.0_mips_24kc.apk ...  checksum verifiedInstalling ...(1/1) Installing mikrouter-agent (1.0.0-r0)  Executing mikrouter-agent-1.0.0-r0.post-installOK: 12.0 MiB in 147 packages MikRouter agent setupPress Enter at any of them to leave it for the settings page later.    Its page will be at http://192.168.1.1:<port>/1. Settings page port [8080]:    The agent server on this agent's dashboard page.2. Tunnel host [not set]: test.mikrouter.com   The 48-character token on that same page.3. Device token [not set]: 0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x InstalledOpen http://192.168.1.1:8080 on this network.  agent server   test.mikrouter.com  device token   configured   mikrouter-agent status     what is configured, and is it running  mikrouter-agent setup      change these settings from a terminal  logread -e mikrouter       watch its log

Check that it connected

There is nothing to start by hand — the installer already did it. mikrouter-agent status shows the settings and whether the agent is running:

OpenWrt (SSH)

root@OpenWrt:~# mikrouter-agent statusMikRouter OpenWrt agent 1.0.0   agent server   test.mikrouter.com  device token   set  settings page  port 8080  settings file  /etc/mikrouter-agent/config.json   service        running  tunnel         connected as Branch Router  (2 open streams)  log            logread -e mikrouter

Confirm the router is Online in the dashboard

Open Agents in the dashboard and pick your agent. Within a few seconds the badge turns Online and the Agent section fills in with what the router reports.

https://mikrouter.com/user/agents/…

Branch Router

OpenWrt 25.12.5Online

Last seen just now✎ Edit agent

Agent

Live status reported by the agent — only while it's online.

Server Manila · test.mikrouter.com

Hardware

OpenWrt 25.12.5 TP-Link EAP225-Outdoor v3

Wi-Fi network

—

Wi-Fi signal

—

IP address

192.168.1.1

Firmware

v1.0.0

RAM available

41 MB

Active streams

0 / 64

Connected

just now

Why the Wi-Fi tiles are empty

They show — on every router, even when Wi-Fi is working perfectly. The agent doesn't manage the radio, so it reports nothing about it — that stays in LuCI. The Hardware tile starts with OpenWrt, which is how MikRouter knows this is a router.

The settings page (only if you need to change something)

Everything is already set up. Use this page to change the agent server or the device token later without SSH. It is on port 8080 — http://192.168.1.1:8080. The password starts as mikrouter; change it in the Password card, which asks for the current one first. Sign out at the bottom ends the session on this browser.

Not Secure192.168.1.1:8080

MikRouter Agent

Relaying connections to this network

Status

Tunnelconnected

Active streams0 / 64

Agent servertest.mikrouter.com

Device tokenset

Connection

Agent server

test.mikrouter.com

Device token

0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x

Both are on the agent's page in the MikRouter dashboard. Emptying either one disconnects the tunnel.

Save

Settings page

Port

8080

This page moves as soon as you save, and the tunnel is not touched. Port 80 is normally LuCI's.

Change port

Password

Current password

••••••••

New password

at least four characters

Changing it signs this browser out.

Change password

Sign out

Wi-Fi, DHCP and firewall stay with OpenWrt — configure them in LuCI. This agent only relays connections.

Saving applies it straight away — the agent reconnects with the new settings. There is nothing to restart.

Both boxes arrive holding what the router is using now, so emptying one clears it rather than leaving it alone — an empty agent server or device token disconnects the tunnel.

Port 8080, not 80 — and it is not a mistake

Port 80 is LuCI, your router's own admin page, so the agent takes 8080 instead. Do not free up port 80 for it.

You can move it in the Settings page card if 8080 clashes with something. It moves as soon as you save and links you to the new address. If the port cannot be used, nothing changes and the page says why.

If the page does not open, the tunnel still works — a settings page that can't start is skipped rather than stopping the agent.

Removing the agent

Use the helper. It removes the package and your settings, which the package manager leaves behind.

OpenWrt (SSH)

mikrouter-agent uninstall

Removes the agent and its settings, including your device token. Use this when the router is leaving your hands.

OpenWrt (SSH)

mikrouter-agent uninstall --keep-settings

The same, but keeps your settings, so reinstalling later reconnects on its own.

Every mikrouter-agent command

You are already root over SSH, so nothing here needs sudo. The full list is mikrouter-agent help.

Day to day

mikrouter-agent status

The settings, the tunnel state, and whether the agent is running.

mikrouter-agent setup

Asks for the agent server, device token and settings page port.

mikrouter-agent version

Print the installed version.

logread -e mikrouter

The agent's log. Add -f to follow it.

Changing one setting

mikrouter-agent set host <name>

Agent server, from the agent's page. Note the syntax: a name and a value, no dashes.

mikrouter-agent set token <48 hex>

Device token, from the same page.

mikrouter-agent set port <1-65535>

Agent server port. Default 443.

mikrouter-agent set tls true|false

Use TLS for the tunnel. On by default — leave it on.

mikrouter-agent set portalPort <1-65535>

Port for the settings page. Default 8080, because 80 is LuCI's. A port browsers refuse to open — 1, 21, 22, 23, 25, 53 and about seventy more — is rejected, because the page would be unreachable from a browser.

mikrouter-agent set webpass <password>

Password for the settings page. Starts as “mikrouter”.

mikrouter-agent set tunnelEnabled true|false

Turn the tunnel off without stopping the agent. The settings page stays up.

mikrouter-agent set maxStreams <1-64>

How many connections at once. Default 64.

The service (procd)

/etc/init.d/mikrouter-agent restart

Apply changed settings.

/etc/init.d/mikrouter-agent stop

Stop the agent. It comes back at the next boot.

/etc/init.d/mikrouter-agent disable

Stop it starting at boot.

mikrouter-agent uninstall

Remove the agent and its settings, including your device token.

mikrouter-agent uninstall --keep-settings

Remove the agent but keep the settings, so a reinstall reconnects on its own.

What is different about running the agent on a router

Field	Value	Note
Wi-Fi	`not managed`	OpenWrt keeps the radios. The agent has no Wi-Fi code at all.
DHCP / DNS	`not managed`	OpenWrt keeps both. The agent runs neither.
Settings	`/etc/mikrouter-agent`	Not /var — that is wiped at every reboot.
Service	`procd`	/etc/init.d/mikrouter-agent, not systemd.
Updates	`package manager`	No self-update on a router.
Settings page	`port 8080`	LuCI has port 80.
Connections	`64`	The same as a computer agent, not the ESP32's handful.

The agent is connected — what's next

The router is online, but nothing is reachable from the internet yet. Add a mapping on the agent's detail page for each device you want to reach — LuCI itself, a camera, an OLT, a NAS. It works the same for every agent, and the Connect ESP32 agent guide covers it.