Router Onboarding Reference

This page is the canonical reference for router onboarding after the inspect -> bridge -> install refactor.

Canonical routes

Web routes

Route	Purpose
/routers/create	Generate state for creating a new Pending router
/routers/onboarding/{router}	Phase-aware onboarding page for an existing Pending router
/routers/{router}/snapshots/{snapshot}	Canonical snapshot review page
/onboarding/devices/{device}/status	Session-authenticated onboarding poll endpoint

Operator action routes

Route	Purpose
POST /routers	Create a Pending router and issue the first inspect token
POST /routers/{router}/regenerate-token	Issue a fresh token for the current onboarding phase
POST /routers/{router}/restart-preflight	Reset the router back to inspect
POST /routers/{router}/advance-to-install	Rotate the inspect token into an install token
POST /routers/{router}/cancel-onboarding	Delete a Pending router before the install script fetch boundary
POST /api/routers/{router}/capture-snapshot	Queue a fresh router snapshot
GET /api/router-snapshots/{snapshot}	Fetch snapshot review payload
POST /api/router-snapshots/{snapshot}/recapture	Re-snapshot during review
POST /api/router-snapshots/{snapshot}/confirm	Import plans and subscribers from the review page

Router callback and polling routes

Route	Purpose
POST /api/routers/preflight	Router callback for inspect results
POST /api/routers/claim	Router callback for final claim
GET /api/setup/{token}	Serve the install script
POST /api/setup/log	Router callback for setup errors
GET /api/routers/{device}/status	Sanctum-authenticated onboarding poll endpoint

Persisted phases vs UI states

Persisted state	UI state	Notes
no router yet	generate	/routers/create with device = null
status = pending, onboarding_phase = preflight_pending	inspect-waiting or inspect-attention	Attention depends on whether the latest preflight failed
status = pending, onboarding_phase = install_ready_bridge	bridge	Inspect completed, install not yet issued
status = pending, onboarding_phase = install_pending, setup_script_fetched_at = null	install-awaiting	Waiting for the install command to run
status = pending, onboarding_phase = install_pending, setup_script_fetched_at != null	install-registering or install-stuck	install-stuck starts after 90 seconds elapsed since fetch
status = online or status = offline before first review page loads	snapshot-capturing	Router is connected; waiting for or redirecting to the first snapshot review page

?phase= on /routers/onboarding/{router} is advisory only. The page rewrites the URL to match the router's real phase if they diverge.

Tokens and timers

Rule	Value
Initial inspect token lifetime	60 minutes
Bridge-phase token lifetime	same inspect token, still 60 minutes from issuance
Install token lifetime	60 minutes from advance-to-install
Registering timeout in the UI	90 seconds since setup_script_fetched_at
Pending onboarding cleanup window	ONBOARDING_TTL_HOURS, default 24 hours

Additional timing rules:

• setup_script_fetched_at is stamped only on the first successful install-script fetch while the router is in install_pending.
• The UI computes the stuck state from elapsed time since setup_script_fetched_at, not from a server-sent absolute deadline.
• Once the router claims successfully, the onboarding token and phase are cleared.

Action matrix

Action	Allowed when	Effect
Create router	No router exists yet	Creates a Pending router in preflight_pending and issues an inspect token
Regenerate token	Router is pending	Preserves the current phase, clears transient setup errors, and issues a fresh token
Restart preflight	Router is pending, online, or offline, and has no imported subscribers	Resets to preflight_pending, clears tunnel/API/setup state, and removes any existing WireGuard peer
Continue to final setup	Router is at the bridge, or already at install with an expired token	Rotates to install_pending, issues a fresh install token, clears setup_script_fetched_at
Cancel onboarding	Router is pending and setup_script_fetched_at is still null	Deletes the pending router and releases the onboarding state
Re-snapshot router	Router has a reviewable snapshot page	Captures a fresh snapshot without disconnecting the router
Import into ISP-OS	Snapshot review is complete enough to proceed	Creates plans, subscribers, and services from the selected snapshot data
Skip for now	Router is already connected	Leaves the router managed but defers the brownfield import

Action-specific notes

• Regenerate token keeps the bridge phase on the bridge. It does not silently skip you into install.
• Regenerate token preserves setup_script_fetched_at during install_pending so the cancel boundary cannot be reopened after the router has already fetched the install script.
• Restart preflight is the explicit "start over" path. It is the action that clears setup_script_fetched_at.
• Continue to final setup is idempotent for a still-valid install token. A double-click does not create two live install tokens.

Auto-navigation rules

• /routers/create is the only generate-state entry point.
• Pending rows resume at /routers/onboarding/{router}.
• Once the router becomes online or offline, the onboarding page waits for the first router snapshot and then redirects to /routers/{router}/snapshots/{snapshot}.
• Snapshot review is now the only canonical brownfield review entry point. The old /routers/create?device={id} compatibility route is gone.

Status payload surface

The onboarding poll endpoints expose the fields the page actually uses:

• router identity and persisted status
• onboarding_phase
• setup_kind
• setup_command, setup_expires_at, setup_expired
• setup_script_fetched_at
• latest_preflight
• latest_snapshot
• last_setup_error

The old registering_timeout_at and last_setup_error_at response fields are no longer part of the public status payload.

See also

• How to Connect a MikroTik Router via WireGuard
• Review a Router Snapshot
• Why Router Onboarding Is Two-Phase

Was this helpful?