Install methods

Every method creates the same objects on the router: the veth, the router’s address, the list memberships you keep, the envlist, the container and the install manifest, each carrying the same tag. So mikroscope status and uninstall recognise an install whichever method made it. They differ in where they run and in how the agent image reaches the router. Every method needs the Requirements first, device mode included.

Compare methods

Method	Needs	Use it when
Registry pull with the CLI	ssh to the router; the router reaches Docker Hub or GHCR	the default: one command, nothing uploaded
Offline install	ssh and scp; the image tar for the router’s architecture	the router cannot reach a registry
From source	Go 1.27 and a checkout; ssh and scp	you are changing the agent and want it from your tree
RouterOS script	the CLI on any computer; a terminal on the router	you reach the router through Winbox or WebFig, not over ssh
Script generator	a browser; a terminal on the router	you have no CLI at all
Manual install: terminal	a terminal on the router	you want to type or adapt every command
Manual install: WebFig and Winbox	WebFig or Winbox	you prefer menus to commands

Take the registry pull unless something stops you. It is one command with nothing to pick and nothing to set on the router: the published image index carries every platform a MikroTik container can be, so the router matches its own. No tar lands on the flash.

The image tar is the one route where you pick the architecture, and a wrong pick installs, starts and dies with exec format error in the container log. Offline install has the table.

Registry pull

mikroscope install --router admin@192.168.88.1 --remote-image jmrplens/mikroscope-agent:1.6.1

The container step becomes /container/add remote-image="registry-1.docker.io/jmrplens/mikroscope-agent:1.6.1" …, and the plan prints the router pulls registry-1.docker.io/jmrplens/mikroscope-agent:1.6.1 (nothing is uploaded) where an upload would be. Each release publishes the image twice, as jmrplens/mikroscope-agent:1.6.1 on Docker Hub and as ghcr.io/jmrplens/mikroscope-agent:1.6.1 on GHCR. Both carry linux/amd64, linux/arm64, linux/arm/v7 and linux/arm/v5, and RouterOS picks the one its architecture needs.

The route needs two things the others do not: the router has to reach the registry, and it needs free RAM for the layers while it extracts them. doctor warns when free memory is short of --memory-max plus 16 MiB.

--remote-image reads its default from MIKROSCOPE_REMOTE_IMAGE. upgrade takes it too, and takes its image from its own flags only, so pass it again with the new version. image refuses it, because there is no tar to write.

Registry settings

mikroscope hands RouterOS the whole reference, registry host included. A reference with no host, or one that starts with docker.io/, index.docker.io/ or registry.hub.docker.com/, goes out as registry-1.docker.io/jmrplens/mikroscope-agent:1.6.1, the host Docker Hub’s registry answers on; any other host is kept as given. RouterOS 7.18 and later take a registry host there (7.18 changelog: “container - allow specifying registry using remote-image property”), and mikroscope needs 7.24.

So you set nothing on the router:

• /container/config registry-url, one value for the whole device, does not decide this pull. install, upgrade and the RouterOS script never write it (verified).
• No registry login is needed: the published image is public on both registries (tested).
• doctor, and upgrade before it removes anything, read registry-url and whether a username is set, for one warning.

One registry username for the whole device

/container/config holds one registry username and password for every container on the router, and a login meant for one registry and sent to another can end a pull of a public image in auth error. doctor warns, as WARN no registry credential meant for another registry, when a username is set and the host registry-url names is not the host the image is pulled from. Troubleshooting has the three ways out.

To pull through a mirror or a pull-through cache, name its host in the reference: --remote-image <mirror-host>/jmrplens/mikroscope-agent:1.6.1. mikroscope sends it as given, and upgrade prints a note when registry-url names a host other than the one the pull goes to.

Docker Hub allows an anonymous client 100 pulls per 6 hours per IPv4 address or IPv6 /64 (Docker Hub pull limits). Docker counts a multi-architecture image as one pull per architecture pulled, and a router pulls only its own. The limit is per public address, so routers behind one NAT share it, which matters for a fleet installing at once.

A RouterOS script with the same install, for a router you reach without ssh, is on RouterOS script.

From source

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

plan, install, upgrade and image build the agent themselves when given neither --remote-image nor --agent-tar: go build ./cmd/mikroscope-agent for linux/<arch> with CGO_ENABLED=0, packed into an image tar without Docker. install and upgrade build for the architecture they read from the router; plan and image connect to nothing and build arm64 unless --arch says otherwise. 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.

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 wants.

The published image tar, which one a board takes, and how to verify the download are on Offline install.

See also

• Requirements: what every method needs on the router.
• Install with the CLI: what install does once the image source is decided.
• Upgrade and uninstall: upgrading and removing an install, by any method.
• Storage and container settings: the disk the tar and the root use.