Set up an agent on a Mac
A Mac mini, or any Mac that stays on at the site, can be the agent. Download the app and click through it, or paste one line into Terminal — both end up at the same place.
Before You Start
- You need a MikRouter account with at least one agent created under Agents.
- Open the agent's detail page and keep its
tokenandtunnel hostnearby — you'll paste them into the app. - A Mac running macOS 11 Big Sur or newer, on the same network as the devices you want to reach.
- You need to be able to enter an administrator password on it once, if you set up the background service — the Terminal route always does, and the app route offers it as an optional last step.
What you are installing
One program — no Homebrew, no Python and no other runtime. It connects on its own as soon as it has your tunnel host and device token.
Separately, it can register a background service that starts with the Mac and keeps running after you log out, so nobody has to stay signed in. Downloading the app leaves that up to you (it is the last step, and optional); the Terminal route sets it up for you as part of the install, along with the menu bar item and the mikrouter-agent command in /usr/local/bin.
Download and unzip it
Downloads to unpack, which gives you MikRouter Agent.app. You do not have to move it into Applications yourself — installing does that for you in step 4.Open it — right-click, then Open
MikRouter Agent.app, choose Open, then confirm. You only do this once.If macOS still refuses
curl is never quarantined.Enter the tunnel host and device token
443 and Use TLS (wss) ticked unless your dashboard shows different values.Not set up yet
Fill in the tunnel host and the device token, then choose Start Tunnel. Installing the background service is optional, and is what keeps the tunnel up after you log out.
TUNNEL CONNECTION
1–1024 simultaneous tunnelled connections (default 64). One web page can use several. Raising this uses more memory and sockets; it does not add mappings or make the connection faster.
STARTUP
BACKGROUND SERVICE
Not installed
The tunnel can run without any of this — Start Tunnel connects straight away, for as long as this app is open. The background service is what keeps it up when the app is closed: it starts with this Mac, before anyone signs in, and keeps running after you log out. Installing it needs administrator rights.
ABOUT
Version 1.0.0 (macos agent)
macOS 15.5 Mac mini (arm64)
Settings: /Users/you/Library/Application Support/MikRouter Agent/config.json
Log: /Users/you/Library/Application Support/MikRouter Agent/agent.log
For more info visit https://mikrouter.com
| 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.
Confirm the agent is Online in the dashboard
Front Desk Mac
macOS 15.5 Mac mini (arm64)OnlineAgent
Live status reported by the agent — only while it's online.
Hardware
macOS 15.5 Mac mini (arm64)
Wi-Fi network
—
Wi-Fi signal
—
IP address
192.168.1.100
Firmware
v1.0.0
RAM available
9.4 GB
Active streams
0 / 64
Connected
just now
It is already working at this point
Install it as a background service — optional
You can stop here. The agent is connected and you can start adding mappings. This step is worth doing when the Mac is meant to stay reachable on its own — and you can come back to it at any time.
What the background service actually is
Right now the tunnel is running inside the app. That means it lives and dies with the app: quit it, log out, or restart the Mac, and the tunnel goes with it. Nothing is broken about that — it just needs somebody signed in with the app open.
The background service moves the tunnel out of the app and into macOS itself, as a LaunchDaemon — a program macOS starts at boot, before anyone logs in, and keeps running after everyone logs out. The window then stops being the thing that holds the tunnel up and becomes just a remote control for it: you can close it, quit it, or sign out entirely and the tunnel carries on.
So do you need it?
Install it for anything you are leaving in place — a Mac mini at the site, or any machine that has to come back on its own after a power cut or a restart. Without it, a reboot leaves the agent offline until someone signs in and opens the app.
Skip it if you are trying MikRouter out, or using a Mac you are sitting at anyway and do not mind restarting the tunnel yourself.
To install it: in the STARTUP section choose Install as a Background Service and enter your administrator password when macOS asks — it needs one because a program that starts before login is a system-wide change. Your saved settings are carried over, so nothing is retyped. Afterwards the row reads Installed — the tunnel starts with this Mac, the app is copied into Applications, and a MikRouter item appears in the menu bar.
Connected to test.mikrouter.com:443
0 of 64 streams in use · LAN address 192.168.1.100
TUNNEL CONNECTION
1–1024 simultaneous tunnelled connections (default 64). One web page can use several. Raising this uses more memory and sockets; it does not add mappings or make the connection faster.
STARTUP
BACKGROUND SERVICE
Installed — the tunnel starts with this Mac
The tunnel can run without any of this — Start Tunnel connects straight away, for as long as this app is open. The background service is what keeps it up when the app is closed: it starts with this Mac, before anyone signs in, and keeps running after you log out. Installing it needs administrator rights.
ABOUT
Version 1.0.0 (macos agent)
macOS 15.5 Mac mini (arm64)
Settings: /Library/Application Support/MikRouter Agent/config.json
Log: /Library/Application Support/MikRouter Agent/logs/agent.log
For more info visit https://mikrouter.com
Installed. The tunnel now starts with this Mac and keeps running after you log out.
When to use this instead
curl is never quarantined — and it always installs the newest published version without you picking one.Paste the one-line installer
Return. It asks for your Mac password, because registering a service that starts at boot needs one. The installer resolves the newest published version, then checks its exact size and SHA-256 fingerprint before installing anything.curl -fsSL https://mikrouter.com/installer/install-agent-macos.sh | sudo sh
you@mac ~ % curl -fsSL https://mikrouter.com/installer/install-agent-macos.sh | sudo shPassword:MikRouter macOS Agent SetupFetching the release catalogue…Downloading MikRouter macOS agent 1.0.0…################################################################# 100.0%Verifying package size and SHA-256…Package integrity verified.Extracting the release…Release extracted.Installing the background service…MikRouter Agent 1.0.0 is installed and running. Service MikRouter Agent (starts with the computer, keeps running when signed out) Settings /Library/Application Support/MikRouter Agent Log /Library/Application Support/MikRouter Agent/logs/agent.log MikRouter macOS agent 1.0.0 is installed and running. Next, point it at your agent server and paste the device token from theMikRouter dashboard: mikrouter-agent setup Then check it with: mikrouter-agent status A signed-in Mac also gets a menu bar item; it appears at the next login, orimmediately by opening "MikRouter Agent" from Applications.you@mac ~ %Enter the tunnel host and device token
mikrouter-agent setup
you@mac ~ % mikrouter-agent setupMikRouter Agent setup. Press Enter to keep the value in brackets. Tunnel host (from the MikRouter dashboard): test.mikrouter.comTunnel port [443]:Use TLS (yes/no) [yes]:Device token (48 hexadecimal characters) [not set]: 0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x Saved. The tunnel is connecting; check it with `mikrouter-agent status`.Press Enter to accept anything already in brackets — that is how the port stays 443 and TLS stays on.
To set them in one go instead — handy in a provisioning script — mikrouter-agent set --host <tunnel host> --token <device token>. The port stays 443 with TLS on unless you pass --port or --no-tls.
| 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.
Confirm it is connected
mikrouter-agent status
you@mac ~ % mikrouter-agent statusMikRouter Agent 1.0.0 (macos) Hardware macOS 15.5 Mac mini (arm64) Tunnel connected Agent server test.mikrouter.com:443 (tls true) Device token set Streams 0 of 64 LAN address 192.168.1.100 Settings /Library/Application Support/MikRouter Agent/config.json Log /Library/Application Support/MikRouter Agent/logs/agent.logyou@mac ~ %The dashboard agrees within a few seconds — open Agents and the badge turns Online.
Front Desk Mac
macOS 15.5 Mac mini (arm64)OnlineAgent
Live status reported by the agent — only while it's online.
Hardware
macOS 15.5 Mac mini (arm64)
Wi-Fi network
—
Wi-Fi signal
—
IP address
192.168.1.100
Firmware
v1.0.0
RAM available
9.4 GB
Active streams
0 / 64
Connected
just now
The window is still there if you want it
mikrouter-agent gui opens the same settings window shown in the other tab, and it edits the same saved settings.Removing the agent
Both forms need an administrator password, because the background service is machine-wide. The difference is what happens to your settings.
sudo mikrouter-agent uninstall
Removes the background service, the menu bar item and the installed files, and deletes your saved settings and logs — including the device token. This is what you want when the Mac is leaving your hands. It lists exactly which directories it removed.
sudo mikrouter-agent uninstall --keep-settings
The same, but keeps your settings and logs, including the device token, so reinstalling later reconnects without retyping anything. It prints the directories it kept.
Either way the agent and its mappings stay in your dashboard — uninstalling here does not delete them. Remove them under Agents if you no longer need them, and remember the token is still valid until you do.
Every mikrouter-agent command
The full list is mikrouter-agent help. Anything that reads or changes settings talks to the background service over a loopback channel on this Mac and needs no password; only the four marked sudo below change machine-wide state and ask for an administrator password.
“command not found” means the background service is not installed
Day to day
mikrouter-agent statusShow the tunnel state and this agent's settings.
mikrouter-agent pauseDisconnect the tunnel, leaving the service running. Remembered across restarts.
mikrouter-agent resumeReconnect after a pause.
mikrouter-agent logsPrint where the log file lives.
mikrouter-agent guiOpen the menu bar item and the settings window.
Changing settings
mikrouter-agent setupGuided prompt for the tunnel host and device token — asks for each value in turn.
mikrouter-agent set --host <name>Tunnel host, from the agent's page in the dashboard.
mikrouter-agent set --token <48 hex>Device token, from the same page.
mikrouter-agent set --port <1-65535>Tunnel port. Default 443.
mikrouter-agent set --tls | --no-tlsUse TLS for the tunnel. On by default; leave it on.
mikrouter-agent set --max-streams <1-1024>Simultaneous tunnelled connections. Default 64 — one web page can use several.
mikrouter-agent resetClear the tunnel settings, keeping the agent installed.
Updates
mikrouter-agent update --listList published releases for macOS.
mikrouter-agent update --version <x.y.z>Install one. The tunnel does not have to be connected. With the background service stopped, run it with sudo — it installs and runs the next time you start the service.
The background service (administrator)
sudo mikrouter-agent startStart the background service itself.
sudo mikrouter-agent stopStop the background service. The tunnel goes with it.
sudo mikrouter-agent set-startup --service=on|offTurn the service on or off without removing anything — a pause, not an uninstall.
sudo mikrouter-agent set-startup --tray=on|offShow or hide the menu bar item at login. Never starts or stops the tunnel.
logs prints the location of the service log rather than the log itself. To follow it as it is written:
sudo tail -f "/Library/Application Support/MikRouter Agent/logs/agent.log"
The log timestamps are UTC
root and inherits no time zone, so it stamps every line in UTCwhile Finder shows the file's own time as local. On a Mac eight hours ahead of UTC the last line looks eight hours old when it is a minute old.