Pairing a Phone

Pairing links one phone to one desktop. It happens once per device, takes about fifteen seconds, and ends with a six-digit code you compare on both screens.

Before you start

You need the app on your phone first. See Install Kangentic Mobile.

Pairing needs your operating system’s secure storage to be available, because the desktop’s device identity is encrypted at rest. If it is unavailable, the Pair a device button is disabled rather than falling back to storing keys unprotected.

The flow

1. Open the pairing screen.

   On the desktop, go to Settings > Mobile Devices, turn on the Mobile Bridge toggle, then click Pair a device.

2. Pick a relay, if you have not already.

   The Relay row selects between Kangentic Relay, the hosted instance marked Official, and Custom Relay. The default is the hosted one. If you run your own, choose Custom Relay and enter its address. See Self-Hosting the Relay.

3. Scan the QR code.

   The desktop shows a QR code carrying its public key, a single-use pairing token that expires in about ten minutes, and the relay address. Scan it with the Kangentic Mobile app.

   If the phone cannot use its camera, use Copy pairing link on the desktop and paste the link into the app instead.

4. Compare the six digits.

   Both devices independently derive a six-digit confirmation code from the handshake. The desktop shows it under “Waiting for your phone”, and the phone shows the same digits with a single Confirm button.

   Compare them. If they match, tap Confirm on the phone. The desktop does not ask a second question, and backing out on the phone is how you decline.

5. Done.

   The phone is signed into the desktop’s device roster and can connect from then on. There is nothing else to configure.

Why the six digits matter

The code is derived from the handshake itself, so it only matches if both devices completed the exchange with each other. Comparing it is what rules out a machine-in-the-middle sitting on the relay. It is the one step worth actually reading rather than tapping through.

Timeouts

Stage	Limit
Waiting for the phone to scan	The pairing token’s remaining life, about ten minutes
Waiting for the six-digit confirmation	Five minutes

If either lapses, start again from Pair a device. Pairing tokens are single-use, so a scanned or expired QR code is spent.

Version compatibility

The QR code carries the bridge protocol version, and that version is mixed into every handshake. Two sides running different versions therefore fail immediately and visibly: the phone reports an incompatible version the moment it scans, before anything dials the relay, rather than connecting and hanging until the relay gives up on it. If you see that, update whichever side is behind and scan again.

The version is also bound into the session handshake of an existing pairing, not just the pairing ceremony. So when a release changes the protocol, already-paired phones do not silently keep working in a degraded mode. They stop connecting, and you re-pair them once both sides are updated. This is rare and only happens on a wire-incompatible change, which the changelog calls out as a breaking change.

What a paired phone can do

Pairing grants the full set of ten capabilities at once. There is no per-verb toggle: an earlier version had one and it was deliberately removed, because a phone that cannot answer a permission prompt or send a message is not useful as a companion.

What pairing does not grant, and cannot be made to grant, is shell access, file reads, or arbitrary commands. Those verbs do not exist in the protocol. See Kangentic Mobile.

Managing paired devices

The Paired Devices list on the desktop shows each phone by:

• Key fingerprint, the leading 16 hex characters of its public key, shown in four groups. The phone formats its own fingerprint identically, so you can hold the two screens side by side and compare.
• Connection status, one of Connected, Connecting, Reconnecting, Offline, or Disconnected.
• Paired date.

You can rename a device inline, up to 64 characters.

Unpairing

Click the trash icon next to a device and confirm. Revoking takes effect immediately: the phone is told first, then the roster entry is dropped, any live session is torn down, and the device’s push registration is cleared. The phone has to be paired again from scratch to reconnect.

Unpairing works the same way in either direction. Telling the phone before teardown is what stops it sitting on Connecting forever against a slot the desktop will never dial again, and unpairing from the phone instead is treated as the same signal: the desktop drops the device from the roster, clears its push registration, and tears down the session, rather than leaving a half-live entry behind. Only a deliberate unpair sends that signal. Quitting either app, disabling the bridge, backgrounding the phone, or reconnecting after a drop are all presence changes, not revocations, and none of them unpair anything.

Next steps

See also:

• Install Kangentic Mobile - get the app on iOS or Android
• Security & Encryption - what the handshake protects, and what it does not
• Push Notifications - what a paired phone will alert you about
• Kangentic Mobile - what the app does once paired