Connect

Connect ESP32 agent

The step after flashing: join the board's setup Wi-Fi, give it your Wi-Fi network and your agent token, and watch the tunnel come up — until this is done the agent stays offline in the dashboard.

Before You Start

Your ESP32 is already flashed with the MikRouter agent firmware. If it isn't, do that first — see Flash an ESP32.
You need a MikRouter account with at least one agent created under Agents.
Open the agent's detail page and keep its token and tunnel host nearby — you'll paste them into the device.
The name and password of the site's 2.4 GHz Wi-Fi network — ESP32 boards cannot see or join 5 GHz networks.

A flashed ESP32, ESP32-S3, ESP32-C6 or ESP32-C3 knows nothing yet — not your Wi-Fi, not which agent it is. You tell it both through its own setup portal: the board broadcasts a Wi-Fi network, you join it from a phone or laptop, and fill in one form. It takes a couple of minutes and you only do it once per board.

Copy the agent token from the dashboard

Open Agents›your agent›Edit and press Regenerate token if you don't already have the token saved. The new token is shown only once — copy it now, or press Show QR code and Download QR to save it as an image you can upload later.

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

New token — save it now

Copy this token now — it is shown only once and cannot be retrieved later. If you lose it, regenerate a new one (which disconnects the old agent).

0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x

▣ Hide QR code

⤓ Download QR

I've saved it

Photographing the screen is unreliable

The QR is dense. Reading it off a second screen with a phone camera often fails — download the image and upload it in the portal, or just paste the token text.

Power the board and join its setup Wi-Fi

Plug the ESP32 into USB power near the site's router. Within a few seconds it broadcasts an open Wi-Fi network named MikrouterAgent-XXXXXX — the last six characters are this board's own MAC address, so yours will differ from the one shown here. Join it from your phone or laptop.

Wi-Fi

Wi-Fi networks

MikrouterAgent-XXXXXX

Open network — no password

Join

TP-Link_XXXX

Neighbour_2G

OfficeGuest

No such network?

Give it 10–15 seconds after power-up, then refresh the Wi-Fi list. If it never appears, the board may not be flashed, or it may already be configured with the setup Wi-Fi turned off. Holding the board's BOOT button for 5 seconds factory-resets it and brings the setup network back — it also erases the Wi-Fi and token already on the board.

Open the portal and log in

Your phone will usually pop up the portal by itself ("Sign in to Wi-Fi network"). If it doesn't, open a browser and go to http://192.168.4.1/. The default portal password is mikrouter.

No internet connection

192.168.4.1/login

MikRouter Agent

Enter the portal password to continue

Password

••••••••Show

Your phone will say No internet connection the whole time you are on this network. That is expected — the board's setup network is not an internet connection, it only serves this page.

Check the status — a fresh board is not configured

The first section is Status. On a board you have never set up, it reads AP (setup), Wi-Fi not configured, tunnel server (not set) and device token NOT set. That is exactly what the next step fills in.

No internet connection

192.168.4.1

MikRouter Agent

Reverse-tunnel agent — local setup portal

Log out

Status

Firmware

1.0.0

Mode

AP (setup)

Wi-Fi

not configured

Setup Wi-Fi

MikrouterAgent-XXXXXX (open) @ 192.168.4.1

IP address

192.168.4.1

Signal

Tunnel server

(not set)

Tunnel status

disconnected

Active streams

0 / 10

RAM available

191 KB

Device token

NOT set

Fill in Wi-Fi, tunnel host and token

Scroll down to Configuration and press Scan Wifi. Pick the site's 2.4 GHz network from the list and type its password, then enter the tunnel values from your agent's detail page. Paste the token, or press Scan / upload QR and choose the QR image you downloaded in step 1.

Field	Value	Note
host	`test.mikrouter.com`	Example only — see below
port	`443`	TLS port
tls	`true`	Always on
token	`<your agent token>`	From the agent detail page

test.mikrouter.com is not a real address — it's a stand-in for this guide. Your agent's real tunnel host depends on the agent server you picked when you created the agent, so copy the exact value from the agent's detail page rather than typing the one shown here.

No internet connection

192.168.4.1

Configuration

Wi-Fi networkScan Wifi

MyHomeWiFi

MyHomeWiFi-64 dBm

Neighbour_2G-86 dBm

OfficeGuest-89 dBm

Wi-Fi password

••••••••Show

Tunnel server host

test.mikrouter.com

Tunnel server port

443

Use TLS (wss)

Device token (48 hex chars)Scan / upload QR

0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x

Save & reboot

2.4 GHz only

ESP32 boards cannot see 5 GHz networks. If your Wi-Fi name appears twice with a _5G variant, pick the one without it — and if it never shows up in the scan, check the router isn't broadcasting that name on 5 GHz only.

Press Save & reboot. The board restarts, joins your Wi-Fi and dials the tunnel — this takes about 10–20 seconds.

Confirm the tunnel is connected

Rejoin MikrouterAgent-XXXXXX (the setup network stays up after the board connects) and reload http://192.168.4.1/. The status section should now read AP + STA (connected), show the IP address your router handed the board, and Tunnel status: CONNECTED.

No internet connection

192.168.4.1

MikRouter Agent

Reverse-tunnel agent — local setup portal

Log out

Status

Firmware

1.0.0

Mode

AP + STA (connected)

Wi-Fi

connected: MyHomeWiFi

Setup Wi-Fi

MikrouterAgent-XXXXXX (open) @ 192.168.4.1

IP address

192.168.1.100

Signal

-67 dBm

Tunnel server

test.mikrouter.com:443 (wss)

Tunnel status

CONNECTED

Active streams

0 / 10

Device name

Front Desk Agent

RAM available

191 KB

Device token

set

If it doesn't connect — or says it did

Wi-Fi shows "incorrect password" — retype the Wi-Fi password. Wi-Fi connects but the tunnel stays disconnected — the tunnel host or token is wrong. The host is your agent server's address from the agent detail page, not the example in this guide, and the token must be the full 48 characters of the one you copied last. The board says CONNECTED but the agent stays Offline in the dashboard — and nothing you map ever loads. The tunnel host saved on the board is not the agent server this agent belongs to, so that server turns the board away and it keeps retrying. Copy the host from the agent's detail page again, exactly as shown there, save, and power-cycle the board. A board can show CONNECTED while it is being turned away like this, so the Online badge in the next step — not this tile — is the confirmation that counts.

Confirm the agent is Online in the dashboard

Open Agents in the dashboard and pick the agent. Within a few seconds its badge turns to Online and the Agent section fills in with what the board itself reports — its hardware, the Wi-Fi it joined, its signal, LAN IP and firmware version.

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

Front Desk Agent

ESP32-S3Online

Last seen just now✎ Edit agent

Agent

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

Server Manila · test.mikrouter.com

Hardware

ESP32-S3

Wi-Fi network

MyHomeWiFi

Wi-Fi signal

-67 dBm

Good

IP address

192.168.1.100

Firmware

v1.0.0

RAM available

191 KB

Active streams

0 / 10

Connected

26m

The board is connected — what's next

The agent is online and ready. Nothing is reachable from the internet yet: that happens when you add mappings on the agent's detail page, one per LAN service you want to reach.

Protect what you expose

Anything you map becomes reachable from the internet through the tunnel. Set an access password on your account and mark sensitive web mappings as protected, and use strong logins on the LAN devices themselves.