Connect your phone

Connecting puts your phone and a computer on the same signed device list. Both sides confirm, and both sides show the same check code so you can see that nobody sits in between. The pieces and the reasons are in Connecting a phone.

On a computer with a screen, the code comes from “Connect a phone” in the Tealhand app. On a computer without one (a server), run tealhand-host connect in a terminal (Windows, Linux). What happens underneath: Connecting a phone.

Before you start

Put the phone and the computer on the same network. In M1, connecting works only there. Once connected, control also works over a relay.
Only one phone connects at a time on a computer.
A computer belongs to one owner. If it was connected to another phone before, forget that phone first (Lost or stolen phone).

Steps

On the computer, show a code: “Connect a phone” in the Tealhand app, or run tealhand-host connect (quit a running tealhand-host run first). A QR code appears. It is valid for 10 minutes and works once. The computer accepts connections only while the QR is showing. No camera at hand? The terminal also prints a line: copy it to the phone (a note to yourself works), then tap “Paste the code” on the phone’s scan page. One tap reads it and goes on.
On the phone, scan the QR. The phone connects to the computer by the key printed in the QR and refuses to talk to any other key. It asks for your fingerprint or PIN: it signs a short proof with both of its keys.
Both screens show the same check code, eight characters such as ABCD EFGH. The phone also shows the computer’s name and OS. Compare the codes.
On the phone, tap “Yes, connect”. The phone signs the new device list (no prompt) and sends it to the computer.
On the computer, the phone’s name and the check code appear, and the computer waits for you. Click Connect in Tealhand, or answer y in the terminal:
```
"Pixel" wants to connect to this computer.
Check code: ABCD EFGH. Connect only if the phone shows the same code.
Connect? [y/N]
```
Done. The terminal says Connected to "Pixel". Start Tealhand Host with: tealhand-host run. The phone then sends the device list to every computer and uploads it to your relay, if you use one. The computer you just connected is the one Home shows on the phone.

Nothing is stored on the computer before you click Connect (or answer y).

Time limits

Limit	Value
The QR code is valid	10 minutes, one use
The whole connection, from the phone’s first valid message	2 minutes, including the wait for your click
Wrong attempts before the QR is burned	5
Connections open at once	4

When a limit runs out, start again for a new code.

When it fails

Message (terminal)	What to do
`Connecting cancelled. Nothing was changed.`	You answered no (or pressed Ctrl-C). Run the command again
`error: connecting took too long and stopped`	The QR or the 2 minutes ran out. Run `tealhand-host connect` again for a new code
`error: this computer is connected to another owner's phone`	Forget the old phone on this computer with `tealhand-host unpair`, then connect again
`error: connecting didn't finish`	A bad message or a proof that did not match. Run `tealhand-host connect` again for a new code
Log line: `the saved connection does not belong to this computer; run tealhand-host unpair to forget it`	The computer’s key changed. Run `tealhand-host unpair`, then connect again

On the phone, the matching messages include “The codes were different, so nothing was connected: another device may be in between. Make a new code on the computer, then scan it again.” and “That computer already belongs to another Tealhand owner. Forget the old phone on it first.”

Why both sides confirm

The QR carries a one-time secret. Both devices prove they know it, and the check code is computed from both devices’ keys and the secret. The phone signs a device list that names the computer’s key as the phone saw it, and the computer refuses a device list that does not name its own key. So a stranger who swaps the QR, or who photographed it, cannot end up in the middle: at worst the connection fails. The click on the computer stops someone who copied the QR from connecting their own phone. Details: How commands are signed.