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.

On Linux, since desktop v0.44.0, any running keyring that speaks the Secret Service (GNOME Keyring or KeePassXC, say) or the desktop’s secret portal counts, on any desktop. Before that, sway, i3, and WSLg refused pairing even with a keyring running, because the app only looked for one on a fixed list of desktops.

The flow

Open the pairing screen.

On the desktop, go to Settings > Mobile Devices, turn on the Mobile bridge switch, then click Pair a device in the Phones card.

Settings on the Mobile Devices tab: the Mobile bridge switch, off here, with links to how the relay works and how to install and pair. v0.46.0 The real app on a sample install. The projects and terminals are recordings, connected to nothing, so click anything.
Pick a relay, if you have not already.

The Relay card selects between Kangentic, the hosted instance (a shield icon beside it marks it as Kangentic-operated), and Custom. The default is the hosted one. If you run your own, choose Custom and enter its address. See Self-hosting the relay.

Since desktop v0.44.0 the desktop dials the relay through Chromium’s network stack, so it honors your system proxy, PAC or WPAD configuration, and the operating system’s certificate store. Behind a corporate proxy or a TLS-inspecting firewall it used to fail to reach the relay at all.
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.
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.
Done.

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

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 every capability the protocol defines at once (thirteen as of v0.46.0), and a verb added later is granted on the next bridge start with no re-pair. 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 Phones card on the desktop lists each paired 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, with a “since” time beside the badge, so a row stuck on Offline says for how long.
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 its push registration is cleared, the roster entry is dropped, and any live session is torn down. 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 clears the device’s push registration, drops it from the roster, 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.