Pairing a device
Pairing is one scan, and it happens once. What decides it is your account: a device pairs with a Mac because both are signed into the same Marginal Utility account. A code glimpsed over your shoulder — or read off a screen in a photo — pairs nothing on its own.
The ceremony
- Scan the QR. It names the Mac and carries the live code, so nothing is transcribed. The device offers both, plus a token for the account it is signed into.
- The Mac checks the account. It asks the account backend to name the token, and continues only if that names the account the Mac itself is signed into. Anything else is refused, and the refusal says which end to fix.
- Someone at the Mac says yes. A card appears there naming the device and the account, and nothing is paired until it is answered. The account check always runs first, so a device on someone else's account never reaches that card at all.
Both steps run, every time. They answer different questions: the backend knows whose device is asking, and the person at the Mac knows whether they meant to do this just now. Neither can stand in for the other.
Answering from the notification
The Mac also posts a notification carrying the same two answers, so a request can be answered without going to find the window. Yes, this is me there mints exactly the grant the card would have, and it requires an unlocked Mac — a locked one can decline from the notice, but not approve. Clicking the notice itself decides nothing; it opens the card.
While the Mac waits
While the Mac waits to be answered, the app keeps polling — so a pairing that seems to hang is usually a card nobody has looked at yet. Requests lapse after a couple of minutes; scan again for a fresh one.
Codes are single-use and renew every few minutes. Repeated wrong guesses are throttled, and the Mac holds a small number of undecided requests at a time.
Once, and then not again
A grant does not expire on its own. A phone that has been in a pocket for six weeks is still paired when it comes out, which is the point — the moment you need this is the moment you last thought about it.
What revokes instead is the account. Every authorized request re-checks that the grant's account is still the Mac's, so signing out on the Mac — or signing it into a different account — drops every paired device on the next request, with no waiting and nothing to remember to do. Signing back in as the same account brings them all back.
Nothing to type, and no address to know
The QR in Settings → Remote control opens the Saggar phone app with the Mac named and the live code already filled in. What it names is an opaque id, not an address — the phone reaches the relay, and the relay knows which connection that id belongs to, so nothing about where your Mac is travels in a QR code.
The payload rides the URL fragment, which stays on the phone and out of
server logs and Referer headers.
The link removes the transcription, not the trust: the code is still single-use and short-lived, and the account still has to match.
On a phone without the app
The same link opens this site, which can't pair a device. It points you to the app instead; install it and scan again. Remote control has no browser client.
Scanning again
The link is also how a phone gets back in. A device stays paired — the grant lives in the app, and the Mac keeps its half in the login Keychain — so scanning the QR code again opens the app on a Mac this device is already paired with, spending no code and raising no card.
A link naming a different Mac switches the app to that Mac and keeps the first Mac's grant for later, because each grant is stored against the Mac that minted it and means nothing to any other.
To pair the same Mac afresh, choose Unpair this device in the app's settings first.
Capability tiers
An armed Mac pairs a device for Drive: controlling a terminal from your phone means being able to type into it, and a device that could watch a question but not answer it would be the half-useful version.
The tiers below still exist and are still clamped on the Mac — a device asks, the Mac decides — and older grants keep whatever tier they were given.
| Tier | Can | Cannot |
|---|---|---|
| View | See sessions, statuses, and git state. | Act at all. Also sees no transcript tails and no filesystem paths — those are redacted before they leave the Mac. |
| Approve | Approve waiting prompts, nudge idle agents, focus a session. Every one of these is a bounded action with a fixed answer. | Type arbitrary text into a shell. |
| Drive | Everything above, plus send arbitrary text into a session. | Nothing. It is what a phone paired to answer your sessions needs, and why every paired device is listed and revocable. |
No fingerprint to compare
Pairing used to end with you checking a certificate fingerprint against the one in Settings. There is nothing to check now: your Mac serves no certificate to anyone, because it makes an outbound connection to a real one instead. No warning page, no clusters of hex, nothing to configure.
Revoking
Paired devices are listed in Settings → Remote control, and revoking one takes effect on the next request — as does signing the Mac out, which revokes all of them at once.
Grants live in the Mac's login Keychain, not a file in a project. Any push subscription a device made belongs to its grant, so revoking the device silences its alerts on the same beat.