MikroDash

MikroDash can run on the MikroTik it monitors, using RouterOS’s own container support:

/container/add remote-image=ghcr.io/secops-7/mikrodash:latest \
  interface=veth_mikrodash root-dir=usb1/mikrodash \
  mountlists=mikrodash_data start-on-boot=yes comment="MikroDash"

Follow docs/routeros-container-install.md for the full walkthrough: enabling container mode, the veth and bridge, the input chain firewall rule (its absence is the usual cause of a bare “timed out” when adding the router) and the /data mount, without which every repull discards your database.

The RouterOS Apps menu installs MikroDash from MikroTik’s own copy of the catalogue, which they refresh on their own schedule and which can lag behind the current release. Adding it as an ordinary container, as above, always pulls the latest release.

Only Docker is needed on the host:

git clone https://github.com/SecOps-7/MikroDash.git
cd MikroDash
docker build -t mikrodash:local .
docker run -d --name mikrodash --restart unless-stopped \
  -p 3081:3081 -v mikrodash-data:/data mikrodash:local

The multi-stage build bundles the frontend with esbuild through its Go API (cmd/webbuild, so no Node runtime is involved), compiles a static Go binary with CGO_ENABLED=0, and copies both into an Alpine runtime with /data as its only mount. For a multi-arch build:

docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t mikrodash:local --load .

A worked deployment on a separate Docker host is in docs/deploy-r5s.md.

• Lockout guards. Changing or removing the address, interface, service, route, firewall rule, certificate or account MikroDash itself connects through is refused or raises a warning first, because nothing in the app could undo it.
• Secrets are never read back. WiFi passphrases, PPP and OpenVPN passwords, IPsec pre-shared keys and SNMP passwords are not requested from the router at all, so no page can display one. A blank password field means “keep the current one”.
• One deliberate exception, and it is audited. A WireGuard peer’s client configuration contains that peer’s private key, which is the point of it. It is fetched by a one-shot request rather than carried on the socket, needs write access to the WireGuard page on that router, is refused outright when sign-in is off or no audit database exists, and writes a row naming who revealed it before the router is asked. The key itself never enters that row.
• Code is for global administrators. What a script, scheduler task, VRRP script or container image runs is RouterOS code, so changing it needs a global administrator.
• Reboots ask for the router’s name. Rebooting, applying package changes, upgrading RouterOS or restoring a backup requires the router’s name typed back.
• Files that would act are refused. A file created or downloaded to the router may not be named to run on arrival (*.auto.*) or to install at the next reboot (.npk). A file’s contents are read only when you ask, capped, with credential values hidden.
• Config Management deploys carefully. A syntax check before anything runs, a restore point per router, a canary router whose name you type before the rest, an automatic revert if a change cuts MikroDash off, and a fresh login to prove it did not.
• No sign-in, no writes. With sign-in turned off, every configuration page is read-only.

Off by default. Nothing is sent anywhere until you switch it on and configure an endpoint.

• Any OpenAI-compatible endpoint: a hosted provider, a gateway, or a model on your own hardware (Ollama, LM Studio, vLLM, LiteLLM). Configure it under Settings, AI Agent, and use Test Connection; an endpoint with a self-signed certificate is trusted by pinning it from there, never by turning checking off. A hosted endpoint receives router names, addresses and network shape; a local one sends nothing outside your network.
• Reads what you can read. It answers from the router’s current data and can look up any table your role permits, never a page your role denies.
• Changes go through the forms’ own path: one row at a time, or several as a plan you approve once, with the same permission checks, lockout guards, undo history and audit entry. It can undo its own most recent change, and run the pages’ own actions (reboot, upgrade, sign a certificate, run a script, download a file), each confirmed.
• Only the router you selected. It reads the others’ status from MikroDash’s records and cannot reach them. It reads files and configuration exports with credentials hidden, and a WireGuard client configuration opens in your browser, never in the conversation.
• Raw RouterOS commands are off unless a global administrator switches them on (Settings, AI Agent). Even then they are offered only to global administrators, and every command, reads included, runs only when you type the router’s name.
• Asks before changing anything by default. Deletes, and changes that could cut MikroDash off from the router, always ask.
• Keeps the conversation per user and per router, so follow-up questions work. Clear deletes it, and it expires after the retention period you set.
• Agent Overview card: an optional dashboard card with a one-line router status written by the assistant.

docs/mikromcp-parity.md maps what the assistant can reach.

Off by default. Switch it on under Settings, Provisioning, and give the public name or address routers will dial.

• Add device on the Devices page asks where the router will be. Remote routers dial this MikroDash over WireGuard, so they can be anywhere with internet access; Local routers call home over your LAN and need no tunnel. Name it, optionally give its serial number (only that router can then use the script), pick its sites and a template, and download the script.
• Run the script on the router: upload it and run /import, or paste it into a terminal. It sets up the tunnel and an API user limited to MikroDash’s address, then calls home every minute until MikroDash answers, and removes itself.
• On arrival the router is added to the fleet and its template is previewed on it and deployed through Config Management, with a restore point and the auto-revert, as the person who added it.
• A generic script (Settings, Provisioning) serves a whole rollout. Each router that runs it waits on the Devices page as Not yet provisioned, with its serial, model and RouterOS version, until you Onboard it (name, sites, template) or Reject it. Nothing connects to it before then.
• Only your instance. Every script carries this MikroDash’s WireGuard key and instance ID. Scripts are shown once and expire; making a new one stops the old one working. The router’s API password is made on the router (remote) and sent only inside the tunnel.
• One UDP port, 13231 by default, must be published and forwarded to MikroDash. The WireGuard server runs in userspace, so the container needs no extra privileges.

Pages that change the router need more than read:

ftp governs reading and writing files on the router, which /export file= and /system/backup/save need; it does not enable the FTP service. policy governs user management, so an account holding it can create router users. Grant it deliberately, not by default.

/user group set [find name=mikrodash] policy=read,write,policy,api,test,!local,!telnet,!ssh,!ftp,!reboot,!winbox,!web,!sniff,!sensitive,!romon,!rest-api

Without these nothing breaks: a page that is refused drops to read-only and shows the command it needs. MikroDash never lets you edit the account it signs in with, or that account’s group.

Credential profiles need the same two policies, for the same reason: a profile (Config Management -> Credentials) creates a RouterOS account on every device you link it to, which is user management. Each profile creates its own group with the policies you choose, so it never shares a group with MikroDash’s own account, and that account can never be taken by a profile - the same guard refuses it per device. See SECURITY.md on what a fleet-wide password is worth.

The MikroDash login is the one exception, and it is deliberate. The pinned “MikroDash login” row on the same tab keeps the password of the mikrodash account MikroDash itself signs in with, in one place. Linking a device creates that account in a mikrodash group, or adopts the one you made by hand, and MikroDash then signs in through the profile. Changing the password changes it on every linked device or on none: each device must be online, each is confirmed with a fresh sign-in, and any failure puts the old password back everywhere.

The Terminal page is the exception to that whole table, because it does not know what your line will do. It sends what you type to the router’s own console and shows the reply, so the policies above are not a list it consults - they are the limit the router enforces on it. On the read-only account at the top of this section it can read and nothing else, because RouterOS refuses the rest.

Who may use it is a permission, per device: grant a role write access to the Terminal page in Settings -> Authentication -> Access Management. Administrators have it already; nobody else does until you say so, and a grant on one device does not carry to another. Every line is recorded in the Audit Trail whether it worked or not. There is no guard, no read-back and no undo on this page, which is the point of it and the reason the permission is worth granting deliberately.

A self-signed certificate is enough:

/certificate add name=local-ca common-name=local-ca days-valid=3650 key-size=2048 key-usage=key-cert-sign,crl-sign
/certificate sign local-ca
/certificate add name=api-ssl-cert common-name=mikrodash days-valid=3650 key-size=2048 key-usage=digital-signature,key-encipherment,tls-server
/certificate sign api-ssl-cert ca=local-ca
/ip/service set api-ssl certificate=api-ssl-cert disabled=no port=8729

Then edit the router in MikroDash, enable TLS and Allow self-signed cert, and set the port to 8729.

Or let MikroDash do all of the above: Auto Switch to API-SSL in the device’s edit dialog creates the certificates, enables the service, and moves the connection across once the device answers on 8729. The plain API is left on.

The Dashboard’s Top Talkers card reads per-device rates from RouterOS Kid Control. RouterOS only tracks devices there once at least one Kid Control profile exists, so on a router without one the card says “No devices”.

Create one profile that allows everything:

/ip kid-control add name=monitor mon=0s-1d tue=0s-1d wed=0s-1d thu=0s-1d fri=0s-1d sat=0s-1d sun=0s-1d

Within a few seconds RouterOS starts listing the devices it sees on your LAN. Kid Control only restricts devices assigned to a profile, and none are, so this blocks nothing. The all-day schedule is there in case a device is ever assigned to it: without it, RouterOS defaults to 7h-21h.

Devices found this way have no name. To name them from your DHCP leases (the lease comment if it has one, otherwise the client’s hostname), wait about ten seconds and paste:

:foreach l in=[/ip dhcp-server lease find] do={
  :local mac [/ip dhcp-server lease get $l mac-address]
  :local nm [/ip dhcp-server lease get $l comment]
  :if ($nm = "") do={ :set nm [/ip dhcp-server lease get $l host-name] }
  :local d [/ip kid-control device find where mac-address=$mac]
  :if ($nm != "" && [:len $d] > 0) do={
    :if ([/ip kid-control device get $d name] = "") do={
      :do { /ip kid-control device set $d name=$nm } on-error={
        /ip kid-control device set $d name=($nm . " (" . [:pick $mac 9 17] . ")")
      }
    }
  }
}

• Naming a device does not assign it to the profile, so it stays unrestricted.
• Names must be unique, so a duplicate gets the end of its MAC added, e.g. Living Room TV (E2:57:BE).
• Only devices that are online now get named. The script only names devices that have no name yet, so it is safe to run again, or on a schedule: save it as a script called kc-names, then /system scheduler add name=kc-names interval=1h on-event=kc-names.

The image passes these as its CMD; give the container its own command: to override them.

The four feature switches are off in the bare binary and on in the image, because each is unsafe to run twice against the same routers: two instances would take every backup twice and send every alert twice. If you run a second instance against the same fleet, turn them off there.

MikroDash refuses a WebSocket whose Origin does not match the Host it sees, which is what stops a hostile page opening an authenticated socket to a MikroDash you are signed in to. Behind a proxy the two differ, so the UI loads and then stays empty, with this in the log:

[ws] accept: failed to accept WebSocket connection: request Origin "dash.example.com" is not authorized for Host "..."

Name the host the browser uses, including the port when it is not the default:

environment:
  - MIKRODASH_ORIGINS=dash.example.com
  - MIKRODASH_TRUSTED_PROXIES=172.18.0.0/16   # your proxy's address or network

Alternatively, have the proxy preserve the original Host header (proxy_set_header Host $host; in Nginx). X-Forwarded-Host is deliberately not trusted, since any client can send one.

MikroDash does not ship cloudflared, but it runs well beside Cloudflare’s own container. This puts the login page on the internet, so first make sure sign-in is required, put Cloudflare Access in front of the hostname, and use strong passwords.

1. In the Cloudflare dashboard (Zero Trust, Networks, Tunnels), create a tunnel and copy its token. Add one public hostname, for example dash.example.com, pointing at http://mikrodash:3081.
2. Add the sidecar and put the token in .env as TUNNEL_TOKEN=...:

services:
  mikrodash:
    # ... your existing service ...
    environment:
      - MIKRODASH_ORIGINS=dash.example.com
      - MIKRODASH_TRUSTED_PROXIES=172.18.0.0/16   # the network the two containers share
      - FORCE_HTTPS=true

  cloudflared:
    image: cloudflare/cloudflared:latest
    command: tunnel --no-autoupdate run
    environment:
      - TUNNEL_TOKEN=${TUNNEL_TOKEN}
    restart: unless-stopped
    depends_on:
      - mikrodash

3. Find the shared network’s range with docker network inspect <project>_default --format '{{(index .IPAM.Config 0).Subnet}}'. MikroDash refuses to start if MIKRODASH_TRUSTED_PROXIES does not parse.

FORCE_HTTPS=true means plain http:// sign-in on the LAN stops working; use the tunnel hostname everywhere, or leave it off. The official cloudflared image covers linux/amd64 and linux/arm64 only.