Install the CLI

Two programs are released together and they run on two different machines:

• mikroscope, the CLI and collector, runs on your computer — the laptop or server you type commands on. This page is about that one.
• mikroscope-agent runs on the router, inside a container. mikroscope install puts it there for you; you never run it yourself, and the only time you download it by hand is the --agent-tar route.

So the archive you want here is picked by your operating system and CPU, not by the router’s. The router’s architecture decides something else, and Requirements has that table.

Install script

curl -fsSL https://raw.githubusercontent.com/jmrplens/mikroscope/main/install.sh | bash

or, in PowerShell on Windows:

irm https://raw.githubusercontent.com/jmrplens/mikroscope/main/install.ps1 | iex

Either script, install.sh or install.ps1, does by itself everything the rest of this page does by hand: work out your platform, resolve the newest version, download that archive and the release’s checksums.txt, and refuse to install anything whose SHA-256 is not the one the release published. There is no flag to skip that check. A script piped into a shell is the least inspectable way to install anything, so the one thing it must not do is trust what it just downloaded. Where cosign is already on the machine it also verifies that checksums.txt came from the release workflow; where it is not, the checksum is still enforced.

It installs into /usr/local/bin when that is writable and ~/.local/bin otherwise, and if the directory is not on your PATH it prints the line to add and the file to add it to. It will not reach for sudo on its own: a script read off the network should not be the thing that decides to become root.

It offers the other half, and does not do it quietly

On a terminal it then asks whether to put the agent on a router. Saying yes runs mikroscope doctor — read-only — and then mikroscope install, which prints every RouterOS command it is about to run and waits for your answer. Nothing is passed that would skip that prompt. Piped into a shell with no terminal it prints the two commands instead of asking, because there is nobody there to answer.

Two arguments, which are also the VERSION and BIN_DIR variables so they can be set through a pipe:

curl -fsSL .../install.sh | VERSION=1.6.1 BIN_DIR=~/bin bash
./install.sh --version 1.6.1 --dir ~/bin      # the same, with the file downloaded first

The rest of this page is what those scripts do, one platform at a time, for anyone who would rather read the archive’s checksum themselves — or who is on a machine where curl | bash is not something to type.

Choose an archive

Your machine	Download
Linux, ordinary PC or server	mikroscope_<version>_linux_x86_64.tar.gz
Linux on ARM (Raspberry Pi 4/5, …)	mikroscope_<version>_linux_arm64.tar.gz
macOS, Apple silicon (M1 and later)	mikroscope_<version>_darwin_arm64.tar.gz
macOS, Intel	mikroscope_<version>_darwin_x86_64.tar.gz
Windows	mikroscope_<version>_windows_x86_64.zip

They are on the latest release. Anything whose name starts with mikroscope-agent is the other program.

Manual install

Linux

1. Download the archive and the checksums:

   VERSION=1.6.1
   curl -fsSLO https://github.com/jmrplens/mikroscope/releases/download/v$VERSION/mikroscope_${VERSION}_linux_x86_64.tar.gz
   curl -fsSLO https://github.com/jmrplens/mikroscope/releases/download/v$VERSION/checksums.txt

2. Check it against the list before unpacking it:

   sha256sum --ignore-missing -c checksums.txt

3. Unpack and put it where the shell looks:

   tar xzf mikroscope_${VERSION}_linux_x86_64.tar.gz mikroscope
   sudo install -m 0755 mikroscope /usr/local/bin/mikroscope

   Without sudo, mkdir -p ~/.local/bin && install -m 0755 mikroscope ~/.local/bin/ works as well, as long as ~/.local/bin is on your PATH.

macOS

1. Download the archive for your CPU — darwin_arm64 for Apple silicon, darwin_x86_64 for Intel — and the checksums:

   VERSION=1.6.1
   curl -fsSLO https://github.com/jmrplens/mikroscope/releases/download/v$VERSION/mikroscope_${VERSION}_darwin_arm64.tar.gz
   curl -fsSLO https://github.com/jmrplens/mikroscope/releases/download/v$VERSION/checksums.txt

2. Check it:

   shasum -a 256 --ignore-missing -c checksums.txt

3. Unpack, clear the quarantine flag the download put on it, and install it:

   tar xzf mikroscope_${VERSION}_darwin_arm64.tar.gz mikroscope
   xattr -d com.apple.quarantine mikroscope 2>/dev/null || true
   sudo install -m 0755 mikroscope /usr/local/bin/mikroscope

   The binary is not signed or notarized, so without that xattr line macOS refuses to run it and says it “cannot be opened because the developer cannot be verified”.

Windows

1. Download mikroscope_<version>_windows_x86_64.zip and checksums.txt from the release page.

2. Check it in PowerShell, against the line for your file in checksums.txt:

   Get-FileHash .\mikroscope_1.6.1_windows_x86_64.zip -Algorithm SHA256

3. Unpack it somewhere permanent and put that folder on your PATH:

   Expand-Archive .\mikroscope_1.6.1_windows_x86_64.zip -DestinationPath $HOME\mikroscope
   $env:PATH += ";$HOME\mikroscope"

   That line lasts for the session. To keep it, add the folder in Settings → System → About → Advanced system settings → Environment Variables, or:

   [Environment]::SetEnvironmentVariable("PATH", "$env:PATH;$HOME\mikroscope", "User")

ssh on Windows

The CLI reaches the router over ssh, with the ssh and scp on your PATH. Windows 10 and 11 ship OpenSSH: Get-Command ssh should find it, and Settings → System → Optional features installs it if not. A RouterOS script needs no ssh at all.

With Go

If you have Go 1.27 or later and would rather build it:

go install github.com/jmrplens/mikroscope/cmd/mikroscope@latest

That puts mikroscope in $(go env GOPATH)/bin, which is ~/go/bin unless you moved it, and that directory has to be on your PATH. A binary built this way reports the module version rather than a release stamp.

A checkout builds either program, which is the contributor’s route:

git clone https://github.com/jmrplens/mikroscope
cd mikroscope
make build          # leaves bin/mikroscope
make build-agent    # leaves bin/mikroscope-agent-<goarch>

Verify the install

mikroscope version

It prints the version, the commit and the build date:

mikroscope 1.6.1 (commit <commit>, built <time>)

Then, with a router to point at:

mikroscope doctor --router admin@192.168.88.1

doctor writes nothing. It reads the device, prints what it is, and marks each prerequisite ok or MISSING, and an advisory check that finds something WARN, with the command that fixes it — including the one nobody can do remotely — then reports what an agent already running shows (Health checks). Run it first, before any install method.

The flags have environment variables

--router, --ssh-port, --ssh-key, --arch and the other connection and naming flags read a default from a MIKROSCOPE_* variable, so a shell that exports them turns the command above into mikroscope doctor. --rate, --buffer, --port and the other agent settings do not, and must be passed each time. Environment variables is the list, and the repository’s .env.example is a template.

See also

• Requirements: the prerequisites on the device, and the architecture table for the router.
• Install with the CLI: what install does once you have the CLI.
• Install methods: the other ways to put the agent on the router.
• CLI: every verb and every flag.