Install Orb on MikroTik RouterOS

Introduction

This guide will walk you through the process of setting up the Orb sensor on your MikroTik RouterOS device. Installing the Orb sensor allows you to monitor the responsiveness and reliability of your network from anywhere in the world using your mobile device or computer.

With the Orb sensor running on your MikroTik device, you can:

• Monitor your internet experience from your MikroTik routers, switches, and access points to determine where a network issue exists.
• Track network reliability and responsiveness over time without impacting other services.
• Receive push notifications on your Android or iOS device when your MikroTik device experiences connectivity issues.

Compatibility

Orb on MikroTik leverages the RouterOS Container package, which requires RouterOS v7.x and is supported on ARM, ARM64, and AMD64 architectures. We recommend devices with at least 128MB of built-in flash storage or expanded USB/SD-Card storage.

The following table shows MikroTik device compatibility:

Device	Supported	Validated	Notes
RouterOS on AMD64	✓
hEX refresh	✓	✓	ARMv5 (EN7562CT CPU) — Apps menu unavailable, see Manual /container setup¹
hEX S (2025)	✓	✓	ARMv5 (EN7562CT CPU) — Apps menu unavailable, see Manual /container setup¹
L009UiGS-RM	✓		Consider disabling bandwidth tests¹
RB4011iGS+RM	✓		ARM 32-bit — Apps menu unavailable, see Manual /container setup
RB5009UG+S+IN	✓	✓
RB5009UPr+S+IN	✓	✓
RB5009UPr+S+OUT	✓	✓
RB1100AHx4	✓		ARM 32-bit — Apps menu unavailable, see Manual /container setup
RB1100AHx4 Dude Edition	✓		ARM 32-bit — Apps menu unavailable, see Manual /container setup
CCR2004-16G-2S+PC	✓
CCR2004-16G-2S+	✓
CCR2004-1G-12S+2XS	✓
CCR2004-1G-2XS-PCIe	✓
CCR2116-12G-4S+	✓
ROSE Data server (RDS)	✓
CCR2216-1G-12XS-2XQ	✓
CRS520-4XS-16XQ-RM	✓
CRS418-8P-8G-2S+RM	✓
CRS418-8P-8G-2S+5axQ2axQ-RM	✓
CRS812 DDQ	✓
CRS804 DDQ	✓
SXTsq 5 ax	✓		ARM 32-bit — Apps menu unavailable, see Manual /container setup
LHG-5axD	✓		ARM 32-bit — Apps menu unavailable, see Manual /container setup
NetBox 5 ax	✓		ARM 32-bit — Apps menu unavailable, see Manual /container setup
LHG XL 5 ax	✓		ARM 32-bit — Apps menu unavailable, see Manual /container setup
NetMetal ax	✓		ARM 32-bit — Apps menu unavailable, see Manual /container setup
mANTBox ax 15s	✓		ARM 32-bit — Apps menu unavailable, see Manual /container setup
hAP ax lite	✓		ARM 32-bit — Apps menu unavailable, see Manual /container setup
wAP ax	✓		ARM 32-bit — Apps menu unavailable, see Manual /container setup
hAP ax²	✓
hAP ax lite LTE6	✓		ARM 32-bit — Apps menu unavailable, see Manual /container setup
hAP ac³	✓		ARM 32-bit — Apps menu unavailable, see Manual /container setup
cAP ax	✓
L009UiGS-2HaxD-IN	✓		ARM 32-bit — Apps menu unavailable, see Manual /container setup
hAP ax³	✓
hAP be³ Media	✓
Chateau LTE6	✓		Requires USB storage; ARM 32-bit — Apps menu unavailable, see Manual /container setup
Audience	✓		ARM 32-bit — Apps menu unavailable, see Manual /container setup
Chateau PRO ax	✓
RB4011iGS+5HacQ2HnD-IN	✓		ARM 32-bit — Apps menu unavailable, see Manual /container setup
L11UG-5HaxD	✓		ARM 32-bit — Apps menu unavailable, see Manual /container setup
L23UGSR-5HaxD2HaxD	✓		ARM 32-bit — Apps menu unavailable, see Manual /container setup
RB450Gx4	✓		ARM 32-bit — Apps menu unavailable, see Manual /container setup
Chateau LTE6 ax	✓
Chateau LTE7 ax	✓
cAP LTE12 ax	✓
Chateau LTE18 ax	✓
Chateau 5G R17 ax	✓
Chateau 5G R16	✓		Requires USB storage; ARM 32-bit — Apps menu unavailable, see Manual /container setup

¹ ARMv5 devices have limited CPU performance. If using these devices for routing without hardware offload, disable bandwidth tests using ORB_BANDWIDTH_DISABLED=1 to prevent CPU spikes.

Recommended: Install via the Apps menu

Starting with RouterOS v7.22, the /app menu provides a catalog-based way to deploy containerized apps in a couple of clicks, with networking, storage, and firewall rules configured automatically. This is now the easiest way to get Orb running on a supported MikroTik device — no manual bridge, veth, or NAT configuration required.

Requirements

• A MikroTik device with arm64 or x86 architecture, running RouterOS v7.22+
• Physical access to your device (required once, for the device-mode confirmation when enabling containers)
• The container package installed

Step 1: Enable container support

1. Connect to your device via WebFig.

2. Select the Advanced tab in the top-right.

3. Navigate to System > Packages.

4. Click Check for Updates, and update RouterOS if a newer version is available (recommended — v7.22+ is required).

5. Once on v7.22+, install the container package if it isn't already installed, then Apply Changes.

6. Select the Terminal tab and run:

   /system/device-mode/update container=yes

7. Press the physical reset or mode button on your device within the 5-minute countdown as instructed, or power-cycle the device. If nothing happens within 5 minutes, the change is cancelled and you'll need to re-run the command.

Step 2: Configure app storage

If your device has an external USB/NVMe/SATA drive attached, RouterOS will detect it automatically — select it under System > Disks and format it with ext4 or btrfs if needed.

If you don't have external storage, you can create small file-backed virtual disks directly on internal flash. We recommend two disks: one for the app itself, and one dedicated scratch disk used only during image download/extraction. Separating these matters — image extraction briefly needs more space than the final installed app, and giving that transient overhead its own disk lets the main app disk be sized much closer to the app's real footprint:

/disk/add type=file file-path=orb-appdisk file-size=64M smb-sharing=no media-sharing=no
/disk/format file-orb-appdisk file-system=ext4

/disk/add type=file file-path=orb-scratch file-size=20M smb-sharing=no media-sharing=no
/disk/format file-orb-scratch file-system=ext4

Point the Apps system at the app disk, and point the container extraction directory (tmpdir) at the scratch disk:

/app/settings/set disk=file-orb-appdisk
/container/config/set tmpdir=file-orb-scratch/tmp

Step 3: Add the Orb app store

Add the Orb custom app store:

/app/settings/set app-store-urls=https://orb.net/docs/scripts/mikrotik/orb-app-store.yml

Then open Apps and you should see orb-sensor available in the catalog alongside MikroTik's official apps.

Step 4: Install and configure Orb

1. Select orb-sensor from the catalog and click Install.
2. Before enabling, set the Network to lan if appropriate for your network topology so the sensor gets a real address on your LAN (rather than being NATed behind the router), matching how a normal Orb sensor would see your network. With lan, the sensor gets its address from the DHCP server on the router's LAN bridge (lan-bridge in /app/settings). If that bridge has no DHCP server, leave Network on its default.
3. Add your deployment token as an environment variable so the sensor links to your account automatically on first boot — under the app's Environment settings, add:
   • ORB_DEPLOYMENT_TOKEN = your deployment token (see Configuration for how to generate one)
4. If this device is also routing traffic (rather than just observing it), consider also adding:
   • ORB_FIRSTHOP_DISABLED=1 — disables first-hop monitoring, appropriate for router deployments.
5. Since use-https defaults to on and expects the app to expose a web UI (Orb doesn't), disable it so the app doesn't stall waiting on a reverse-proxy certificate.
6. Leave Auto Update off. Each RouterOS app update leaves the previous image on the app disk, so automatic updates eventually fill it and the sensor stops. Use the update script instead.
7. Click Enable. The app will download and extract the image, then start automatically.

Once running, your MikroTik device should appear in your Orb dashboard within a minute or two.

Finally, add the update script so it's ready when you want to update.

Equivalent via terminal

Steps 2–7 above can also be done from the Terminal tab. Note that environment values must be prefixed with the service name (orb:, matching the services.orb key in the app's YAML):

/app/set [find name=orb-sensor] network=lan use-https=no environment="orb:ORB_EPHEMERAL_MODE=1,orb:ORB_DEPLOYMENT_TOKEN=your-deployment-token"
/app/enable [find name=orb-sensor]

Manual /container setup

Prerequisites

Before you begin, make sure you have:

• A compatible MikroTik device running RouterOS v7.x
• Physical access to your MikroTik device (required for device mode update)
• Access to your MikroTik device via WebFig
• Basic familiarity with RouterOS configuration

Step 1: Enable Container Support

First, you need to install and enable the container package:

1. Connect to your device via WebFig.
2. Select the Advanced tab in the top-right.
3. Navigate to System > Packages.
4. Click Check for Updates.
5. Update RouterOS if available (recommended).
6. Once completed, click Check for Updates again.
7. Select the container package and click Enable, then Apply Changes.

Next, update the device mode to enable container support:

1. Select the Terminal tab in the top-right.

2. Enter the following command:

   /system/device-mode/update container=yes

3. Press the physical reset or mode button on your device within the 5-minute countdown as instructed.

Step 2: Configure Container Networking

Create a dedicated network for the Orb container:

Create Container Bridge

Navigate to Bridge > New.

• Name: containers
• Click OK.

Create Virtual Ethernet Interface

Navigate to Interfaces > New > VETH.

• Name: veth-orb
• Click the + next to Address.
• Enter IP: 172.19.0.2/24 (or alternate if this network is in use).
• Gateway: 172.19.0.1.
• Click OK.

Add Interface to Bridge

Navigate to Bridge > Ports > New.

• Interface: veth-orb.
• Bridge: containers.
• Click OK.

Step 3: Configure Container Storage and Environment

Create Data Mount

Navigate to Container > Mounts > New.

• Name: MOUNT_ORB_DATA.
• Src: /orb-data.
• Dst: /root/.config/orb.
• Click OK.

Configure Environment Variables

Enable ephemeral mode to prevent writing to flash:

Navigate to Container > Envs > New.

• Name: ENV_ORB.
• Key: ORB_EPHEMERAL_MODE.
• Value: 1.
• Click OK.

For router deployments, disable first-hop monitoring:

Navigate to Container > Envs > New.

• Name: ENV_ORB.
• Key: ORB_FIRSTHOP_DISABLED.
• Value: 1.
• Click OK.

For devices with limited CPU (ARMv5), also disable bandwidth tests:

Navigate to Container > Envs > New.

• Name: ENV_ORB.
• Key: ORB_BANDWIDTH_DISABLED.
• Value: 1.
• Click OK.

Step 4: Deploy the Orb Container

Add Container

1. Navigate to Container > Container > New.

2. Click the + next to Remote Image and enter:

   registry.hub.docker.com/orbforge/orb-busybox:latest

3. Configure the following settings:

   • Interface: veth-orb.
   • Envlist: ENV_ORB.
   • Workdir: /app.
   • Mounts: MOUNT_ORB_DATA.
   • Logging: enabled.
   • Start On Boot: enabled.

4. Click Apply.

5. Click Start.

Configure NAT for Outbound Traffic

1. Select the Terminal tab.

2. Enter the following command:

   /ip/firewall/nat/add chain=srcnat action=masquerade src-address=172.19.0.0/24

Step 5: Link Your Orb to Your Account

The final step is to link your new Orb sensor to your account:

1. In the RouterOS terminal, connect to the container:

   /container shell [find where name~"orb-busybox:latest"]

2. Run the link command:

   /app/orb link

3. Follow the instructions provided to complete the linking process.

4. Once linked, your MikroTik Orb will appear in your Orb dashboard.

Troubleshooting

orb-sensor Doesn't Appear in the Apps Catalog

If you've set app-store-urls but don't see orb-sensor in the Apps list:

• The catalog may not have refreshed yet. Open Apps > Settings in WinBox and click Apply, or reboot the device once.
• Confirm the setting was saved: Apps > Configuration > Settings, check the App Store Urls field.
• Check the view filter next to the item count (top-right of the Apps list) — it may be set to a specific view that hides store-sourced entries.

App Won't Enable / Stuck Waiting

If an app installed via the Apps menu shows a status like "wait for reverse proxy" and never progresses to downloading:

• Orb doesn't expose a web UI, so the default use-https=yes reverse-proxy/certificate step will stall indefinitely. Disable it: /app/set [find name=orb-sensor] use-https=no.

Container Not Starting

If the Orb container fails to start:

• Check container status in Container > Container (or Apps, if installed via the Apps menu).
• View logs in Terminal: /log/print (ensure logging is enabled in container settings).
• Verify the veth interface has the correct IP configuration.
• Ensure the NAT rule is properly configured (manual /container setup only — the Apps menu handles this automatically).

"Not Enough Disk Space" During Download/Extract, or App Crashes Right After Starting

These usually mean the app disk is too small:

• not enough disk space to download/extract on a first install: set a separate tmpdir on a dedicated scratch disk and use a 64MB app disk (see Step 2 above).
• App extracts fine but exits immediately (exited with status 1): the app disk is just barely big enough to extract into, but leaves too little room for the app to actually write config and certs on first run. Increase the disk size.
• The errors start after an update: see the next section.

Updates Fail With "No Space Left on Device" or "Extract Layer Failed" Errors

RouterOS keeps every previous Orb image on the app disk when it updates the app, so after one or more updates with the Update button or Auto Update the disk fills and the new image can't be extracted. The app retries in a loop and the sensor stays offline.

If you installed Orb with the current app store YAML, run the update script. It frees the disk and reinstalls the latest image with the same Orb identity. To check whether your install keeps its identity in a volume, run:

/file/print where name~"apps/orb-sensor/config/private.key"

If that prints a file, the update script will work. Turn off Auto Update afterwards (/app/set orb-sensor auto-update=no).

If it prints nothing, Orb was installed before its identity was moved into a volume. That identity lives inside the old image and can't be carried over, so reinstall Orb on a 64MB disk. It will appear in your dashboard as a new Orb, and you can remove the old one.

1. Remove the old app and its disk. When /app/cleanup asks App data will be lost, continue?, answer y:

   /app/disable orb-sensor
   /app/cleanup orb-sensor
   /disk/remove file-orb-appdisk
   /file/remove orb-appdisk

2. Recreate the app disk at 64MB and point the Apps system at it, as in Step 2:

   /disk/add type=file file-path=orb-appdisk file-size=64M smb-sharing=no media-sharing=no
   /disk/format file-orb-appdisk file-system=ext4
   /app/settings/set disk=file-orb-appdisk
   /disk/set file-orb-scratch smb-sharing=no media-sharing=no

3. Reload the Orb app store so RouterOS picks up the current YAML: open Apps > Settings in WinBox and click Apply, or reboot. Then follow Step 4 again, including your deployment token.

Network Connectivity Issues

If the container cannot reach the internet:

• Verify the NAT rule source address matches your container network (manual /container setup only).
• Check firewall rules aren't blocking container traffic.
• Ensure DNS is properly configured for the container.

Updating the Container

For /app-based installs, update Orb with the orb-update script below instead of the Update button or Auto Update. RouterOS keeps every previous image on the app disk when it updates an app, so the built-in update fills the disk after a few releases and the sensor stops (see the troubleshooting entry). The script moves your Orb's identity out of the app, removes the app with /app/cleanup (which frees all of its images), moves the identity back, restores your environment settings, and reinstalls the latest image. Your Orb keeps its ID and history.

Add the script once by pasting this into the Terminal:

/system/script/add name=orb-update source={
:local app "orb-sensor"
:local disk [/app/settings get disk]
:local dir ($disk . "/apps/" . $app)
:local vol ($dir . "/config")
:local keep ($disk . "/orb-identity")
:local envfile ($disk . "/orb-environment.txt")
:if ([:len [/file find name=($vol . "/private.key")]] > 0) do={
  /file remove [find name=$keep]
  /file remove [find name=$envfile]
  :local env ""
  :foreach e in=[/app get $app environment] do={ :if ($env != "") do={ :set env ($env . ",") }; :set env ($env . $e) }
  /file add name=$envfile contents=$env
  /file set [find name=$vol] name=$keep
}
:if ([:len [/file find name=($keep . "/private.key")]] = 0) do={ :error "orb-update: no Orb identity found, nothing changed" }
/app disable $app
:execute ("/app cleanup " . $app)
:local i 0
:while ([:len [/file find name=$dir]] > 0 && $i < 120) do={ :delay 1s; :set i ($i + 1) }
:if ([:len [/file find name=$dir]] > 0) do={ :error "orb-update: cleanup did not finish, run the script again" }
:delay 5s
/file add name=$dir type=directory
/file set [find name=$keep] name=$vol
:if ([:len [/file find name=$envfile]] > 0) do={ /app set $app environment=[/file get $envfile contents] }
/app enable $app
:log info "orb-update: reinstalled $app with its saved identity"
}

Then, whenever you want to update Orb, run:

/system/script/run orb-update

The sensor goes offline for about a minute while the latest image downloads. While the update runs, the script keeps your Orb's identity in an orb-identity folder and your environment settings in orb-environment.txt on the app disk, so if an update is interrupted (for example by a power cut), run the script again. If the script stops with no Orb identity found, your install predates the identity volume — see the troubleshooting entry.

For /container-based installs (manual /container setup only), RouterOS does not support a mechanism for easily updating to the latest version of the Orb image — this is specific to raw /container, the /app system above has its own update commands. The solution is to delete the container and recreate it with the same configuration, which will pull the :latest tagged image from Docker Hub. As we set up persistent storage, you will not need to re-link, and your history will be preserved.

Container Shell Access Issues

If you cannot access the container shell:

• Ensure the container is running.
• Try using the container ID instead of the name pattern.
• Restart the container and try again.

Additional Resources

• For more details on the Apps menu, see MikroTik's Apps documentation.
• For more details on RouterOS containers, see MikroTik's Container documentation.
• To find compatible devices, use MikroTik's hardware catalog.
• For alternative installation methods, see Install Orb on Docker.
• For general Orb troubleshooting, see the Orb documentation.