Linux Agent

Set up an agent on Linux (Debian/Ubuntu/etc)

Already have a Debian or Ubuntu machine, mini-PC, or VM on the target LAN? The one-line installer turns it into an agent in under a minute.

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 token and tunnel host nearby — you'll paste them into the device.
The device must already have a compatible Linux operating system installed, such as Debian, Ubuntu, or another supported Linux distribution, with internet access over Ethernet or Wi-Fi.
You must be able to open a terminal on the device, either locally or over SSH if SSH is enabled.

Starting from a bare board? Install the operating system first

This guide assumes the machine already runs Debian or Ubuntu. If you have an Orange Pi or a Raspberry Pi with a blank microSD card, write the operating system first, then come back here:

Install Debian/Ubuntu on a Raspberry Pi — Raspberry Pi Imager sets the login and SSH before first boot.
Install Debian/Ubuntu on an Orange Pi — the vendor image written with Rufus or balenaEtcher.

Any other Debian or Ubuntu machine — a mini-PC, a VM, a spare laptop — needs none of that. Carry on below.

Open a Linux terminal or connect with SSH

Open Terminal directly on the Linux machine, or connect to it from another computer using ssh. For example: ssh user@192.168.1.100.

Paste the one-line installer

Copy the command below, paste it into the Linux terminal, then press Enter. It downloads the agent, verifies its checksum, and installs a systemd service. Nothing else has to be installed first — the agent is a single self-contained program.

Linux Terminal

curl -fsSL https://mikrouter.com/installer/install-agent-linux.sh | sudo sh

Choose the version

The installer lists every published version, newest first. Press Enter to take the recommended one.

Linux Terminal

user@linux:~$ curl -fsSL https://mikrouter.com/installer/install-agent-linux.sh | sudo sh MikRouter Linux Agent SetupConnects this machine to your MikRouter dashboard. Nothing else needs installing first. Fetching the release catalogue... 1. Version selection (required)  1) 1.0.0  (29.6 MiB)  newest — recommendedSelect a version [1-1], or press Enter for 1: Version 1.0.0 selected.

Wait for the download and checksum

The installer fetches the release, checks its SHA-256 before unpacking anything, and unpacks only the build for this machine's processor.

Linux Terminal

Downloading version 1.0.0Downloading MikRouter Linux agent 1.0.0 (29.6 MiB) for amd64...######################################################################## 100.0%Verifying the package SHA-256...Package integrity verified.Extracting the selected release...Release extracted. Installing version 1.0.0Installing the MikRouter agent (amd64)…  including the bundled Wi-Fi runtime (15M)

Answer the setup questions

The installer then asks four short questions. Press Enter at any of them to take the default shown in brackets. The numbering continues from the version question above.

Linux Terminal

2. WAN (internet) selectionHow the agent reaches the internet. Ethernet is simplest; Wi-Fi is for a board with no cable to it.  1) Ethernet (eth0: 192.168.1.100)  2) Wi-Fi + Ethernet (wlan0: connect to router Wi-Fi and keep Ethernet enabled)Choose WAN [1-2]: 1Ethernet internet connected on eth0 (192.168.1.100).Turn off the MikRouter setup Wi-Fi AP? [Y/n]: MikRouter Wi-Fi management and its setup AP stay off. 3. LAN portal portThis agent's local settings page, at http://<device-ip>:<port>/. Press Enter for 80.LAN portal port [80]: LAN portal port set to 80. 4. Tunnel host (optional)The agent server address shown for this agent on the dashboard, e.g. test.mikrouter.com.Type the tunnel host, or press Enter to skip and set it later at http://192.168.1.100/.Tunnel host (optional): test.mikrouter.comTunnel host accepted. 5. Device token (optional)Get this token from the MikRouter dashboard.Paste the 48-character token, or press Enter to skip and set it later at http://192.168.1.100/.Device token (optional): 0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0xDevice token accepted.

Where the agent server and device token come from

Both are shown on the agent's page in your dashboard. You can press Enter to skip them here and paste them later on the agent's own settings page — the installer prints its address at the end.

Note the settings page address

The installer waits for the agent's own settings page to come up, prints its address, and summarises what is still missing.

Linux Terminal

Saving your answers…Registering the background service and starting it…MikRouter Agent installed and started.  service   mikrouter-agent.service  files     /opt/mikrouter-agent  settings  /var/lib/mikrouter-agent/state  log       /var/lib/mikrouter-agent/logs/agent.log Waiting for the LAN portal on port 80 to become ready…LAN portal is ready. Open http://192.168.1.100 on this network.  agent server  test.mikrouter.com  device token  configured Done. Useful commands:  mikrouter-agent status  sudo mikrouter-agent setup     # enter the agent server and device token  sudo mikrouter-agent uninstall # remove it and its settings Settings live in /var/lib/mikrouter-agent/state; the log is /var/lib/mikrouter-agent/logs/agent.log.

The IP address will vary

192.168.1.100 is only the example IP used throughout this guide. Use the actual LAN IP reported for your Linux agent; the address depends on your own network.

Open the settings page (only if something is missing)

Everything is already set if you answered the questions above — this page is where you go to change anything later, or to paste the agent server and device token if you skipped them. It asks for the portal password first.

Not Secure192.168.1.100/login

MikRouter Agent

Enter the portal password for this device.

Portal password

Show

MikRouter Agent 1.0.0

Not Secure192.168.1.100

MikRouter Agent1.0.0

Overview

This device's tunnel, its network and this settings page.

Tunnel

Connected

The agent server has accepted this device.

Connections

0 of 64

LAN address

192.168.1.100

Device

Generic PC

Wi-Fi

Not connected

Agent server

These come from the device's page on your MikRouter dashboard.

Tunnel host

test.mikrouter.com

Port

443

✓Use TLS (recommended)

Device token

0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x0x

Save

Fill in Tunnel host and Device token from the agent's page on your dashboard, then press Save. The tunnel reconnects on its own — no restart, and no need to return to the terminal.

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 machine itself reports — its hardware, LAN IP, available RAM and agent version. The Wi-Fi tiles stay as — because this example connects over Ethernet.

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

Office Linux Agent

Ubuntu 24.04 LTS (x86_64)Online

Last seen just now✎ Edit agent

Agent

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

Server Manila · test.mikrouter.com

Hardware

Ubuntu 24.04 LTS (x86_64)

Wi-Fi network

—

Wi-Fi signal

—

IP address

192.168.1.100

Firmware

v1.0.0

RAM available

2.6 GB

Active streams

0 / 64

Connected

just now

Removing the agent

Both forms need sudo, because the service is machine-wide. The difference is what happens to your settings.

Linux Terminal

sudo mikrouter-agent uninstall

Removes the systemd unit, the program files in /opt/mikrouter-agent and the command itself, and deletes your saved settings and logs — including the device token and any saved Wi-Fi passphrase. This is what you want when the machine is leaving your hands. It lists exactly which paths it removed.

Linux Terminal

sudo mikrouter-agent uninstall --keep-settings

The same, but keeps /var/lib/mikrouter-agent — your settings, the device token and the logs — so reinstalling later reconnects without retyping anything. It prints what 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 device token stays valid until you do.

Every mikrouter-agent command

The installer puts a mikrouter-agent command in /usr/local/bin, already on your PATH, so every row below works from any directory and over SSH as well as on the machine itself. Anything that only reads or changes settings talks to the running service over a loopback channel and needs no sudo — only the rows shown with sudo change machine-wide state. The full list is mikrouter-agent help.

Day to day

mikrouter-agent status

Tunnel state, agent server, streams, hardware, LAN address and the settings page address.

mikrouter-agent logs [--follow]

Print the agent's log. Timestamps are UTC. --follow keeps printing new lines.

mikrouter-agent pause

Disconnect the tunnel, leaving the service running. Remembered across reboots.

mikrouter-agent resume

Reconnect after a pause.

mikrouter-agent version

Print the installed version.

mikrouter-agent help

Every command and every setting name.

Changing settings

sudo mikrouter-agent setup

Guided prompt for the agent server host and device token.

mikrouter-agent set host <name>

Agent server host, from the agent's page in the dashboard. 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>

Tunnel port. Default 443.

mikrouter-agent set tls true|false

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

mikrouter-agent set maxStreams <1-1024>

Simultaneous tunnelled connections. Default 64 — one web page can use several.

mikrouter-agent set portalPort <1-65535>

Port for the settings page in step 7. Default 80. 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.

mikrouter-agent reset [--yes]

Clear the device token, agent server and Wi-Fi settings, keeping the agent installed. Asks first unless --yes.

Updates

mikrouter-agent update --list

List published releases for Linux, marking the one you are running.

mikrouter-agent update [--version <x.y.z>]

Install the newest release, or the version named. The service has to be running — it is what downloads the release and restarts into it.

The background service (root)

sudo mikrouter-agent start

Start the systemd service.

sudo mikrouter-agent stop

Stop it. The tunnel goes with it — use pause if you only want to disconnect.

systemctl status mikrouter-agent

What systemd itself thinks of the unit. No sudo needed to read it.

sudo mikrouter-agent uninstall

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

sudo mikrouter-agent uninstall --keep-settings

Remove the agent but keep /var/lib/mikrouter-agent, so a reinstall reconnects on its own.

This is not the same syntax as the Windows and macOS agents

Those two take set --host <name>. The Linux agent takes set host <name>, with no dashes. Everything the settings page in step 7 can change is available this way — run mikrouter-agent help for the full list of setting names.

The log timestamps are UTC

The service runs as root and inherits no time zone, so it stamps every line in UTCwhile the file's own modification time is local. On a machine eight hours ahead of UTC the last line looks eight hours old when it is a minute old. The file itself is /var/lib/mikrouter-agent/logs/agent.log.

The agent 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. That works the same for every device — the Connect ESP32 agent guide covers it.