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.
While the Mac waits to be answered, this client 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 this site
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 in the browser and out of server logs and
Referer headers, and the page strips it
from the address bar as soon as it reads it.
The link removes the transcription, not the trust: the code is still single-use and short-lived, and the account still has to match.
It is also how a phone gets back in. A device stays paired — the grant lives in this browser, and the Mac keeps its half in the login Keychain — so scanning the QR code again opens the client on a Mac this device is already paired with, spending no code and raising no card. Only a link naming a different Mac drops the grant, because a token means nothing against a server that did not mint it. To pair the same Mac afresh — at a different tier, say — tap unpair in the client 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 terminals 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.