Chapter 2

Pairing Your Device

Scan one QR code from the Mac and your iPhone or iPad enrols its own key — then the Mac decides exactly what it may do.

Pairing connects this app to FrontierStack running on your Mac. It takes one QR code and a few seconds. Behind that simplicity, the app enrols a private key that only ever lives on this device, so from then on the Mac can recognise — and trust — this exact phone or iPad. This chapter walks through pairing, approving a new device, and the permission levels that decide what it can do.

2.1How pairing works

Your Mac is the brain: it talks to your servers, agents and devices. This app is a secure remote control for it. Pairing is how the two recognise each other for good. When you scan the QR code, three things travel to the phone — the ways to reach your Mac (your home or office network, Tailscale, and a Cloudflare tunnel), a one-time token, and the Mac's certificate fingerprint so the connection can be pinned. The phone then generates its own key and enrols it with the Mac. After that first handshake the one-time token is spent; every later request is proven by the device's own key (see Security).

2.2Pairing step by step

On your Mac, open FrontierStack → Paired Devices (in the Overview group).
Click Pair a device. A QR code appears.
In this app, tap Scan QR code and point the camera at the Mac's screen.
The app reads the code, enrols its key, and connects. The new device appears in the list on the Mac.

screenshot to be added

Figure 2.1. The Mac shows a pairing QR code in the Paired Devices pane while the iPhone's scanner frames it.Capture: photograph the Mac's "Pair a device" QR sheet next to the iPhone showing the Scan QR code camera view

TipKeep the phone close to the screen and steady. If the camera will not focus, raise the Mac's display brightness and fill the frame with the code.

Can't reach the Mac? Pair over Bluetooth. On a locked-down Wi-Fi network — guest networks, client isolation, a captive portal — the app may read the QR fine but fail to connect. If the Mac has Allow Bluetooth pairing turned on (in its Paired Devices pane) and you are within a few metres of it, tap Pair over Bluetooth and enrolment finishes over a short-range Bluetooth link instead. It uses the same one-time QR code and the same signed handshake — only the transport changes — so the result is identical to pairing over the network. The Mac only advertises over Bluetooth while its Pair dialog is open.

2.3What the QR code carries

The QR is not just a token — it is everything the app needs to reach your Mac safely:

Reach paths — the addresses for your home/office network, Tailscale, and any Cloudflare tunnel, so the app can find the Mac whether you are home or away (Staying Connected).
A one-time token — used only for the initial enrolment, then discarded.
The certificate fingerprint — lets the app pin the Mac's HTTPS certificate, so the connection cannot be intercepted even though the certificate is self-signed.

2.4Approving the new device

A freshly paired device starts read-only — it can see status and alerts but cannot change anything until you say so. On the Mac, in the Paired Devices pane, each device is listed by name with a key fingerprint and a last-seen time. There you raise its permission level, rename it, or revoke it.

SecurityEvery device has its own key. Revoking one on the Mac cuts it off instantly and does not affect any other paired device. If a phone is lost, revoke it here.

2.5Permission levels

The Mac decides how much each device may do. Set the level on the Mac in the Paired Devices pane (Overview group).

Level	What this device can do
Read-only	See status, alerts, logs and device pages. No changes.
Restart	Read-only, plus start / stop / restart services.
Operate	Restart, plus fleet operations.
Full control	Everything, including tools, scripts and opening shares.

If a button is disabled or an action is refused, this device's level does not allow it — raise it on the Mac, or use a device that already has the rights.

TipKeep a phone you carry everywhere at a low level (Read-only or Restart), and reserve Full control for one trusted device. You lose nothing day to day and limit what a lost phone could do.

Pair more than one device

Pair as many iPhones and iPads as you like — each enrols its own key and gets its own level. A wall-mounted iPad might sit at Read-only as a status display, while your main phone has Restart for quick fixes on the go.

With the device paired and its level set, you are ready to use the app. Connectivity from home and away is covered next in Staying Connected, and the day-to-day tabs in Using the App.

FrontierStack User Manual · Version 1.0.0 · Chapter 2