Pairing your phone

Pairing connects your phone to your Gateway once; after that your fleet 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 - your fleet 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.

Be clear about what that key does reach, because it is the credential behind every screen in this app. Anyone holding it can do what the app can do: read and answer your live sessions, open a session's terminal, search and read files on the machines the fleet is paired to, and send an agent new instructions - which is to say it can reach your code. What it does not give is your account: it is not your sign-in, it does not open the account dashboard, and it does not carry any other device's key.

So treat a lost phone as a key to revoke, not a device to write off, and revoke it the same day. A self-hosted pairing is revoked from Devices in your dashboard; a phone paired to the hosted gateway is revoked by the hosted gateway that minted its key.

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.

Signing out, and running two accounts

Pairing has an inverse, and it lives on the phone. The menu's Sign out row does not sign you out where it stands - it opens the phone's Account screen, one tap further, because a mis-tap that ended the session would cost you another trip through devthrottle.com. The Account screen lists the accounts signed in on this phone and holds three buttons:

• Add account - run a second pairing on the same phone. Once a second account is signed in, an account switcher appears in the top bar of the roster, so you always know whose sessions you are looking at. Switching reloads the app as that account; both stay signed in, so it needs no password and works with no connection.
• Sign out (or Sign out of this account when there are two) - signs out the account you are using now. The confirmation names it, and says whether the app will switch to your other account or ask you to sign in through devthrottle.com again.
• Sign out of all - offered only when more than one account is signed in. Every account leaves this browser, and each one signs back in through devthrottle.com.

Signing out makes this browser forget its key. It is not the same as removing the device: a phone paired to a self-hosted Gateway stays on your account at devthrottle.com until you remove it in Devices. That is the difference that matters when the phone is in your hand versus when it is gone.