Pairing your phone

Pairing connects your phone to your Gateway once; after that the Director follows you. The flow is built so the phone ends up holding as little as possible: a key for itself, not your account.

Before you start

• You have a Gateway - the hosted one your machine enrolled with in the setup wizard, or one you run yourself.
• Your phone can reach it at its secure (https) address. The hosted Gateway is reachable from anywhere by nature. A self-hosted Gateway's address is its Tailscale front door, reachable once the phone has joined your tailnet - the approval step will not hand a key back to a plain http address, so a bare same-Wi-Fi IP address does not work.
• A self-hosted Gateway must itself be signed in to your DevThrottle account - it verifies the phone's key against that account before accepting it. If it is not, the connecting screen says so and offers the sign-in that fixes it.

The pairing flow

1. Open your Gateway's address on the phone

   On the phone, browse to your Gateway's address - the one the setup wizard showed on its "This machine is enrolled with" line, kept in the Director's Settings under Gateway. The Gateway recognises a phone and serves it the phone app (it lives under the Gateway's /mobile path), which opens on its Sign in screen.

2. Approve the phone on devthrottle.com

   The phone is sent to the approval page, where you sign in with your DevThrottle account and see exactly what is asking, by its device name, and which account it would join. Two buttons: connect this phone, or deny it.

3. The phone gets its own key

   What approval hands over depends on your gateway. Pairing with a self-hosted Gateway, the phone is handed a per-device key, which your Gateway checks against its own signed-in account before accepting. Pairing with the hosted gateway, the phone is handed a short-lived sign-in token instead; the gateway validates it once, mints the per-device key itself, and discards the token. Either way, what the phone stores is one per-device key, scoped to your account, identifying this one phone.

4. Done - the Director is in your pocket

   The phone shows your sessions. Add the app to your phone's home screen and open it from there - on some phones, iPhones in particular, notifications only exist for an app installed on the home screen - then tap Enable notifications and allow the permission: from then on the app icon carries a dot while a session needs you, and the dot clears when nothing does. If the Enable notifications banner is missing, that browser cannot show notifications - open the app from its home-screen icon instead of a tab. If notifications are blocked, the banner says so; the block is lifted in the browser's site settings.

Why the phone does not keep your account

What the phone stores is a device key, never your account session. On the self-hosted path nothing else is ever handed over; on the hosted path a short-lived sign-in token makes the one trip needed to mint that key and is then discarded, not stored. The difference matters exactly once - the day the phone is lost. A leaked device key costs you one device's access, not your account, your other devices, or your code.

A phone paired to a self-hosted Gateway is registered on your account: it shows up as its own row in Devices in your dashboard, so a family tablet and your phone are separately revocable there. A phone paired to the hosted gateway does not appear on that page - its key is minted and held by the hosted gateway itself.