Why Router Onboarding Is Two-Phase
Router onboarding in ISP-OS is deliberately split into inspect, bridge, install, and then snapshot review. That is more ceremony than a single "paste this script and hope" flow, but it removes several real failure modes that matter in live ISP networks.
Inspect comes first because subnet choice depends on reality
The first command is read-only. ISP-OS uses it to learn what the router already has:
- existing address ranges
- current WireGuard state
- router model and RouterOS version
- brownfield hints that influence later review
Without that inspect pass, ISP-OS would have to guess a management subnet up front. That is acceptable for toy demos and dangerous for real brownfield routers. The inspect step lets ISP-OS pick a safe /29 from what the router actually reports instead of asking the operator to reason about overlap manually.
The bridge exists so there is a human checkpoint before real changes
After inspection, ISP-OS pauses on the bridge screen instead of immediately provisioning the router. That pause is intentional.
It gives the operator a chance to confirm:
- the chosen
/29 - the router model and version that were detected
- whether the reported claims make sense
- whether this is still the router they want to continue with
This also keeps the install token separate from the inspect token. ISP-OS only issues the install token when the operator clicks Continue to final setup, which narrows the window where a token can cause real router-side change.
Mobile is blocked because this workflow is command-heavy and failure-sensitive
Onboarding uses long RouterOS commands and several pages of stateful UI. On a phone, that quickly becomes unreliable:
- copying long commands is error-prone
- bridge warnings and conflict details are easy to miss
- install retries are hard to reason about from a narrow viewport
Instead of pretending the experience is fine, ISP-OS intentionally falls back to a copy-link helper on mobile and expects the real workflow to happen on desktop.
Cancel disappears after the install script fetch because the router may already be mutated
Before the router fetches the install script, ISP-OS can still safely delete the Pending row and abandon the setup. After the fetch boundary, that is no longer true.
By then the router may already have:
- created
wg-ispos - generated keys
- added firewall rules
- started claiming back to ISP-OS
If ISP-OS allowed a silent delete after that point, the platform could forget the router while the router still carries partial management state. That is why Cancel onboarding disappears in the UI and is also blocked server-side once setup_script_fetched_at is stamped.
Connection and snapshot review are separate because "connected" is not the same as "imported"
WireGuard connectivity solves the control-plane problem. Brownfield import is a different problem.
A router can be fully connected while ISP-OS still needs operator judgement about:
- which RouterOS profiles should become plans
- which subscriber candidates are safe to import
- which items need manual mapping
- how existing enforcement hooks should map into ISP-OS
Keeping snapshot review on its own page makes that distinction explicit:
- the router can become manageable immediately
- the operator can defer import with Skip for now
- brownfield review has a canonical URL and can be revisited later
That separation is especially important for clean installs. A brand-new router should not be forced through an empty brownfield import ceremony just because it is now connected.
The result
The two-phase design trades one opaque bootstrap for a flow that is easier to reason about:
- inspect before mutation
- pause before installation
- block unsafe cancellation once the router has fetched the real script
- treat brownfield review as a first-class workflow, not a side effect
The happy path is still fast, but the failure modes are much more legible.