Pairing connects one phone to one Kubyl Server. You need a running server first; see Kubyl Server: install and pairing.
Pair a phone
- Open the server's console (Overview tab) or the web UI's Pair page. It shows a QR code and a pairing link.
- In the app, add a server and scan the QR code. If the phone cannot scan it (or you are on a simulator without a camera), paste the pairing link instead.
- The app checks the server's key against the one in the link before it sends anything, then you confirm and pair.
A pairing code works for one device and 10 minutes. If it expired, make a new one on the server (R in the console, or the web UI). The link looks like kubyl://pair?url=…&fp=…&code=…&name=…: it carries the server's address and the hash of its certificate key, so the app pins the server's certificate: there is no certificate authority to trust and nothing to type. The phone keeps its sign-in in the iOS Keychain or the Android Keystore, and nowhere else.
The camera starts only when you tap the scanner frame, so the permission prompt never appears unasked. The link works from the clipboard too: tap Paste a pairing link.
After pairing the phone holds a long-lived refresh token (in the Keychain or Keystore) and trades it for a 15-minute access token that stays in memory; renewal is automatic and invisible. If the server says the device was revoked, the app shows Pair again or Remove.
Paired devices and revoking
In More, Paired devices lists every device paired with the server. Revoking one asks for confirmation; the device's sessions end at once and its streams close. You can also revoke a device on the server (Devices tab of the console, or the web UI). Revoking the device you are holding forgets the server on it.
There is one user per server, so any paired phone can list and revoke the others. Pair only devices you trust.
More than one server
The app can keep several servers. More, Switch server lists them with their clusters and Add a server pairs another one. Tap the server card on the home screen to see its details, appearance and security settings, or to forget it. Forgetting a server revokes this device on it first.
If pairing fails
- The certificate doesn't match. The app compares the key in the link with the one the server presents before it sends anything. The server's key changed (config directory lost, or a new TLS key), or a proxy sits in front of it (see Server operations): pair again with a fresh link.
- `device_limit`. Your plan's device limit is reached: revoke a device on the server.
- `license_required`. The server is unlicensed or locked: activate it.
- “Try again in N minutes”. Five failed attempts from one address in 10 minutes lock out that address only; successful pairings cost nothing. Wrong, used and expired codes all get the same refusal.
- You were signed out after a bad network moment. Token refresh rotates the refresh token, and a refresh whose answer was lost revokes the device on retry (it looks like a leaked copy). Pair again.
More in Server troubleshooting.