# Install methods

The ways to put the mikroscope agent on a MikroTik router — the CLI with a registry pull, the image tar or a checkout, a RouterOS script, the generator, or by hand — and what each needs.

Source: https://docs.jmrp.io/mikroscope/install/routes/

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](https://docs.jmrp.io/mikroscope/install/prerequisites/) first, device mode included.

## Compare methods

| Method                                                                   | Needs                                                              | Use it when                                                     |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------ | --------------------------------------------------------------- |
| **[Registry pull](https://docs.jmrp.io/mikroscope/install/routes/#a-registry-pull)** with the CLI                       | ssh to the router; the router reaches Docker Hub or GHCR           | the default: one command, nothing uploaded                      |
| [Offline install](https://docs.jmrp.io/mikroscope/install/offline/)                          | ssh and `scp`; the image tar for the router's architecture         | the router cannot reach a registry                              |
| [From source](https://docs.jmrp.io/mikroscope/install/routes/#a-checkout-with-go)                                       | Go 1.27 and a checkout; ssh and `scp`                              | you are changing the agent and want it from your tree           |
| [RouterOS script](https://docs.jmrp.io/mikroscope/install/script/)                           | the CLI on any computer; a terminal on the router                  | you reach the router through Winbox or WebFig, not over ssh     |
| [Script generator](https://docs.jmrp.io/mikroscope/install/generator/)                       | a browser; a terminal on the router                                | you have no CLI at all                                          |
| [Manual install: terminal](https://docs.jmrp.io/mikroscope/install/manual-cli/)              | a terminal on the router                                           | you want to type or adapt every command                         |
| [Manual install: WebFig and Winbox](https://docs.jmrp.io/mikroscope/install/manual-gui/)     | 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](https://docs.jmrp.io/mikroscope/install/offline/) has the table.

## Registry pull

```sh
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](https://download.mikrotik.com/routeros/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](https://docs.jmrp.io/mikroscope/about/status/#verified-remote-image-host)).
- No registry login is needed: the published image is public on both registries
  ([tested](https://docs.jmrp.io/mikroscope/about/status/#install-routes-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](https://docs.jmrp.io/mikroscope/reference/troubleshooting/#one-credential-for-every-registry) 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](https://docs.docker.com/docker-hub/usage/pulls/)). 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](https://docs.jmrp.io/mikroscope/install/script/).

## From source

```sh
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](https://docs.jmrp.io/mikroscope/install/offline/).

## See also

- [Requirements](https://docs.jmrp.io/mikroscope/install/prerequisites/): what every method needs on the router.
- [Install with the CLI](https://docs.jmrp.io/mikroscope/install/): what `install` does once the image source is
  decided.
- [Upgrade and uninstall](https://docs.jmrp.io/mikroscope/install/upgrade/): upgrading and removing an install, by any
  method.
- [Storage and container settings](https://docs.jmrp.io/mikroscope/install/layout/): the disk the tar and the root use.