How to Connect a MikroTik Router via WireGuard

Connect your MikroTik router to ISP-OS over a WireGuard tunnel so the platform can manage PPPoE users, monitor the router, and review brownfield data before import.

Prerequisites

• A MikroTik router running RouterOS 7.x or later
• Winbox or SSH access to the router
• Internet access from the router to the ISP-OS endpoint
• A desktop browser. On mobile, ISP-OS only shows a copy-link helper for onboarding; the actual inspect and install flow is desktop-only.

Steps

1. Add the router in ISP-OS

Navigate to Routers and click Add router. Enter a friendly name, for example Brgy. San Jose POP, then submit.

ISP-OS creates a Pending router and opens /routers/onboarding/{id} in the inspect phase. At this point there is no steady-state management tunnel yet. ISP-OS has only issued a time-boxed inspect token and prepared the read-only inspect command.

2. Run the inspect one-liner

The first command is a read-only inspect script. It scans the router's existing address claims, WireGuard state, and RouterOS details, then posts that summary back to ISP-OS. Nothing is provisioned yet.

Copy the command and paste it into the MikroTik terminal in Winbox or SSH. The scan usually finishes in a few seconds.

3. Review the bridge screen

Once the inspect script reports in, ISP-OS moves the router to the bridge phase and shows:

• the selected WireGuard /29
• the router's reported model and RouterOS version
• any detected network claims that influenced the subnet choice
• the next action: Continue to final setup

This is the intentional checkpoint between inspection and installation. If everything looks right, click Continue to final setup. ISP-OS rotates the inspect token into a fresh install token and advances to the install phase.

You can close the tab during inspect or bridge. Progress is saved, and the router can be resumed later from the Routers list while the onboarding window is still active.

4. Paste the install one-liner

Copy the install command from the onboarding page and paste it into the MikroTik terminal. This is the step that actually provisions the router:

1. Creates a WireGuard interface (wg-ispos) on the router
2. Generates a key pair and keeps the private key on the router
3. Adds a WireGuard peer pointing back to ISP-OS
4. Assigns a tunnel IP address for management traffic
5. Adds firewall rules for ISP-OS management traffic
6. Sends a registration callback to ISP-OS with the router's public key

Before the router fetches the install script, you can still cancel the onboarding. After the first successful fetch, Cancel onboarding is hidden and blocked server-side. At that point the router may already have partial wg-ispos state, so ISP-OS treats the setup as an in-progress install rather than something safe to delete silently.

The install run usually takes 5-10 seconds.

5. Wait for connection

The onboarding page shows a live stepper and status copy while the router finishes registration. The key moments are:

• Install pending: waiting for the install command to run
• Registering: ISP-OS saw the install token fetch and is waiting for the router to claim
• Connected: the WireGuard handshake succeeded and the router is reachable

This usually takes 15-30 seconds. If the router stays stuck in registering for more than 90 seconds, the page surfaces retry affordances and any captured setup error message.

When the router is connected, ISP-OS captures the first router snapshot and automatically sends you to the canonical review page at /routers/{router}/snapshots/{snapshot}.

6. Review or defer the snapshot

Connection is only the first half of onboarding. After the first snapshot lands, review what ISP-OS found on the router:

• detected plans and subscriber candidates
• manual-mapping items that need operator judgement
• enforcement hooks such as unpaid PPPoE profiles or suspension address lists
• any subnet-conflict or partial-scan warnings

For a clean router, you can click Skip for now and come back later. For a brownfield router, continue with Review a Router Snapshot before importing subscribers into ISP-OS.

Troubleshooting

Token expired before you finished

• Use Regenerate setup token if you want a fresh token for the current phase.
• Use Restart preflight if you want to go back to the inspect phase and clear the current onboarding state.

Router stays in "Registering" for more than 90 seconds

• Check whether the page shows a specific setup error from the router script.
• Verify the router can reach the ISP-OS WireGuard endpoint and that UDP 51820 is not blocked.
• Run /interface wireguard print and confirm wg-ispos exists and is enabled.
• If the router fetched the install script but never completed registration, regenerate the install token or restart preflight from the onboarding page.

Bridge screen shows unexpected claims or a wrong subnet

• Stop at the bridge screen and review before continuing.
• If you want to abandon the current attempt cleanly, restart preflight.
• If the router later reports a blocking conflict during snapshot review, pick one of the suggested replacement /29 ranges and follow the re-provision flow from the review page.

RouterOS version is too old

WireGuard requires RouterOS 7.x or later. Check the version with /system resource print and upgrade before onboarding if the router is still on RouterOS 6.x.

Result

The router now shows as connected in Routers and has a canonical snapshot-review URL. ISP-OS can manage the router immediately, and you can choose whether to import brownfield data now or defer it until later.

Was this helpful?