Four ways to install

The agent is a container image, and the four routes below differ in one thing only: how that image reaches the router. Everything else install writes — the veth, the address, the two list memberships, the envlist, the container and its tag — is the same whichever route you take, and so are the prerequisites: What the router needs comes first in all four, because device-mode container=yes needs a hand on the device and no route works around it.

Which one

Route	Needs	Prefer it when
A registry pull — start here	the router can reach Docker Hub; nothing else	almost always: one command, nothing to choose, nothing uploaded
A RouterOS script	a terminal on the router; --remote-image	you reach the router through WinBox or WebFig and not over ssh
A checkout, with Go	Go 1.27 and the repository; ssh to the router	you are working on mikroscope and want the agent from your tree
The published tar	the release assets, the right one for the board; ssh to the router	the router cannot reach a registry

Take the first one unless something stops you. A registry pull is a single command with nothing to pick: the published image index carries every platform a MikroTik container can be, so the router matches its own and no one has to know whether the board is 64-bit ARM or one of the two 32-bit kinds. Nothing lands on the flash, and uninstall has no file to account for.

The tar is last on purpose. It is the right route for a router with no way out to a registry, and it is the only one where you pick the architecture — the way that goes wrong is an image that installs, starts and dies with exec format error in the container log. If you take it, read which tar before downloading.

A registry pull

The recommended route, and the shortest. One command, nothing to download, nothing uploaded:

mikroscope install --router user@192.168.88.1 \
  --remote-image jmrplens/mikroscope-agent:1.0.4

Nothing is uploaded, no tar lands on the device, and uninstall has no file to account for: the container step becomes /container/add remote-image="jmrplens/mikroscope-agent:1.0.4" … and the plan prints the router pulls … (nothing is uploaded) where the upload line would be. The release publishes the image twice, as jmrplens/mikroscope-agent:1.0.4 on Docker Hub and as ghcr.io/jmrplens/mikroscope-agent:1.0.4 on GHCR. Both carry linux/amd64, linux/arm64, linux/arm/v7 and linux/arm/v5, and RouterOS picks the one its architecture needs — which is why this route asks nothing about the board: the two kinds of 32-bit ARM MikroTik ships are both in the index.

The reference above is the Docker Hub one, and it carries no registry host: the router pulls it from whatever /container/config registry-url already names, and RouterOS ships that setting as https://registry-1.docker.io. On a router where nobody has changed it, the command above needs nothing set first — on the RB5009 this project is measured on, that setting reads https://registry-1.docker.io. The GHCR reference is the alternative, and it needs /container/config/set registry-url=https://ghcr.io on the device first, which is a change to every container on it.

It needs two things the other routes do not: the router has to reach the registry, and it has to have room in RAM for the layers while it extracts them.

The registry host is a global router setting

RouterOS takes the registry host from /container/config registry-url, which is global to the device and shared with every other container on it, and only the rest of the reference goes into remote-image=. mikroscope never writes that setting — pointing your router’s registry somewhere else to install a probe would be a change to somebody else’s containers. doctor reads it instead, and when the reference names a host the setting does not match it names the one command to run — /container/config/set registry-url=https://ghcr.io for the GHCR reference. Install with --agent-tar if you would rather not change it.

A reference with no host — jmrplens/mikroscope-agent:1.0.4 — leaves the registry to whatever the router is already configured for, and doctor then checks nothing about it. --remote-image reads its default from MIKROSCOPE_REMOTE_IMAGE, and upgrade takes it too; image refuses it, because there is no tar to write.

A RouterOS script

For a router you reach through WinBox or WebFig, or where you do not want ssh from another machine at all:

mikroscope plan --rsc \
  --remote-image jmrplens/mikroscope-agent:1.0.4 \
  --out install.rsc

The file holds the same commands install runs, in the same order, each object tagged the same way, so status and uninstall from the CLI recognise them afterwards. Read it, then paste it into the router’s terminal, or upload it and /import it. Without --out it goes to standard output. It carries its own header: the tag it writes, what to check before running it, and, at the end, /container/print where name~"mikroscope" and the /healthz URL the agent answers on.

Two caveats, both stated in the script itself:

• It cannot upload anything. A script running on the router has no way to put the image there, so pair it with --remote-image. Without one, the header says instead which filename to put on the device first — the name the container step expects — and how to regenerate the script for a registry pull.
• With --token, the file is a credential. The envlist line carries the token in clear, because the router needs it in clear. The CLI writes the file 0600; what you do with it afterwards is the exposure.

Nothing in the script checks anything. There is no doctor, no question about what the objects it creates would collide with, and no confirmation prompt: it writes. Run mikroscope doctor from a machine that can, or read What the router needs and check the three prerequisites by hand, before you paste it.

All four routes were run end to end against the reference RB5009UG+S+ (RouterOS 7.24.2, arm64) on 2026-09-17, one after another, each installing under its own name, veth and /30 so that nothing already on the device was touched, and each removed again before the next. In every one the agent answered /healthz from the collector host: the checkout build and the published mikroscope-agent-arm64.tar at a 2 ms round trip, the router’s own pull of jmrplens/mikroscope-agent:1.0.4 from Docker Hub at 2 ms, and the plan --rsc script — uploaded and /imported, with no CLI involved in the install itself — at 15 ms on its first samples. uninstall then verified by ownership count in each case, and the router’s /export after all four was byte-identical to the one taken before them.

Untested

--remote-image against GHCR. /container/config registry-url is a single global RouterOS setting that mikroscope reads and never writes, and the reference router points at Docker Hub; pointing it at ghcr.io to test that path would change the registry for every other container on the device. The image is published to both registries and CI starts it from GHCR on all three architectures, but no router has pulled it from there. Nor has any route been run on arm or on x86_64 hardware.

A checkout, with Go

git clone https://github.com/jmrplens/mikroscope
cd mikroscope
make build
bin/mikroscope install --router user@192.168.88.1

plan, install, upgrade and image build the agent themselves: go build ./cmd/mikroscope-agent for linux/<arch> (--arch, default arm64) with CGO_ENABLED=0, packed into an image tar without Docker. The build path is relative, so run the CLI from the checkout. This is the only route that installs an agent built from your own tree, which is why it is the one to use while changing the agent.

make build leaves the CLI in bin/mikroscope. With no Go toolchain on PATH, the verb stops before anything is written and names the other two routes and the Go version it wanted.

The published tar

The route for a router that cannot reach a registry. Two assets: the CLI archive for the machine you run it from — which is Getting the CLI, and has nothing to do with the router — and one agent image tar, for the router’s architecture. No Go toolchain, no checkout.

Which tar

Your MikroTik	architecture-name	Agent image tar
RB5009, CCR2004, hAP ax³, other 64-bit ARM	arm64	mikroscope-agent-arm64.tar
hEX Refresh / hEX S (2025), any EN7562CT board	arm	mikroscope-agent-armv5.tar
Other 32-bit ARM (hAP ac², hAP ax², …)	arm	mikroscope-agent-armv7.tar, or the v5 one
CHR, x86 RouterOS	x86_64	mikroscope-agent-amd64.tar

mikroscope doctor --router … prints the architecture off the device, so run it first and let it tell you. If you are not sure which 32-bit ARM board you have, take the v5 tar: MikroTik’s container documentation says EN7562CT boards “support only arm32v5 container images”, and an ARMv5 image runs on every 32-bit ARM MikroTik ships, while an ARMv7 one does not run on those.

1. Download mikroscope_1.0.4_<os>_<arch>.tar.gz (.zip on Windows) and the agent image tar from the table above, together with checksums.txt and checksums.txt.sigstore.json.

2. Verify them, below, before unpacking anything.

3. Unpack the CLI and install:

   tar xzf mikroscope_1.0.4_linux_x86_64.tar.gz
   ./mikroscope install --router user@192.168.88.1 \
     --arch arm64 --agent-tar mikroscope-agent-arm64.tar

The CLI reads the tar before it uploads it, which is what catches the wrong download: it prints what it read, as using mikroscope-agent-arm64.tar: linux/arm64, agent <size> KiB, and on the ARMv7 image it adds the note that an EN7562CT board needs the v5 one instead.

It wants a one-image manifest.json, the config that manifest names, one layer, and /mikroscope-agent as the entrypoint; anything else fails as this is not a mikroscope agent image. Then the image’s architecture has to be the one --arch says, or the verb fails naming the asset to download instead — an amd64 image on an arm64 board would otherwise install, start, and die with exec format error in the container log. On a tar it accepts it prints what it read, as using mikroscope-agent-arm64.tar: linux/arm64, agent <size> KiB.

--agent-tar reads its default from MIKROSCOPE_AGENT_TAR, and upgrade and image take it too. From here on the install is the upload route: the tar goes up with scp, RouterOS extracts it at add time, and install deletes it.

Two assets have similar names

mikroscope-agent-arm64.tar is the side-loadable container image, the one --agent-tar wants. mikroscope-agent_1.0.4_linux_arm64.tar.gz is an archive of the bare agent binary, for reading or running it outside a container; --agent-tar rejects it.

Verifying the download

checksums.txt covers every archive and every agent image tar, and it is the one file the signature vouches for. The signature is keyless: the identity is the workflow run that produced it, recorded in a public transparency log, so there is no key to fetch.

cosign verify-blob \
  --certificate-identity-regexp 'https://github.com/jmrplens/mikroscope/.github/workflows/release.yml@refs/tags/.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --bundle checksums.txt.sigstore.json \
  checksums.txt
sha256sum --ignore-missing -c checksums.txt

--ignore-missing is what lets you check the two files you downloaded against a list that covers the whole release. Each archive also ships an SPDX SBOM (<archive>.spdx.json) with a signature bundle of its own, verified the same way.

See also

• What the router needs: the three prerequisites every route shares, and what doctor checks.
• Installing the agent: what install does once the image is decided.
• Where things go: the disk the tar and the container root use, and what --remote-image leaves off it.
• Reaching the agent: the probe that runs afterwards.