← All docs

Pairing, re-pairing & sharing a machine

Every machine running Terminull has a permanent identity — a beacon id plus a public key — and shows a terminull://pair QR that carries it. Two different QRs exist, and what a scan does depends on which QR it is and who scans it. That distinction is the whole of this section: one QR hands over the machine, the other lends it out.

Pairing — linking a machine the first time

On macOS the setup wizard shows the QR on its last page, and the menu bar offers it any time under Add device by QR. On a headless Linux box the terminull service prints the pairing URL as text (a terminal QR is unreadable over SSH), which you can paste into the app or drag onto the Mac window.

Scanning it from the app claims the machine to your account — you become its owner. The app registers the beacon id and public key; the machine then polls once for its permanent auth token and comes online. The QR carries only the beacon id, the machine's public key, an ephemeral key-exchange key, its home relay address, and a one-time claim code — never your code, sessions, or credentials.

Getting the QR on a headless machine

A freshly installed service prints a pairing QR to its own output the first time it starts unpaired, and stops printing it once a device has claimed it. To get one at any later moment, ask the running service:

terminull-admin qr        # print a QR (needs the service running)
terminull-admin qr --url  # just the pairing link, on stdout

The QR is drawn on the service's output, not in the terminal you typed the command into — your terminal gets the link back instead. Under systemd that output is the journal, so render it there:

journalctl --user -u terminull --no-pager -o cat -n 40

-o cat is not optional. Without it, journald prefixes every line with a timestamp and unit name — which shifts each row of the code sideways, so it will not scan no matter how it looks at a glance.

Over SSH the link is usually easier than the picture. terminull-admin qr --url prints a bare URL you can paste into the app — or pipe it into your own renderer, which avoids the journal entirely: terminull-admin qr --url | qrencode -t ANSI.

Two things that commonly trip people up: the installer puts the command inside the service's own environment, so if your shell can't find it use the full path ~/.local/share/terminull/venv/bin/terminull-admin; and the command talks to the running service over a local socket, so “terminull is not running” means exactly that — start it with systemctl --user start terminull and try again. Treat whatever it prints as an owner QR, with all the caution described above.

Re-pairing — scanning again from the same account

Scanning the owner QR again from an account that already owns the machine is a re-claim, and it is safe to repeat. It refreshes the stored public key and name, and re-opens the token window. Nothing is lost — your sessions live on the machine itself, not on the phone, so they are all still there afterwards.

Re-pair when you add a second device of your own (an iPad alongside your iPhone), reinstall the app, or reset the machine's identity with a purge-uninstall — the last case regenerates the key, which is exactly what the re-claim writes back.

The owner QR is a secret. If a different account scans it, that is not a join — it is an ownership transfer. The server records it as pending and it takes effect the next time the machine polls, moving the machine out of your account. Holding a claim code proves physical access to the machine, which is why it is treated as authority over it. To let someone else in without giving up ownership, use the share QR below.

In the app, open Account, find the machine, and tap the QR icon beside it. The machine mints a fresh code valid for two minutes, registers it with the server, and displays a share QR with a live countdown. (Share is unavailable for LAN-only machines, which have no account behind them.)

When a different account scans it, they join as a member: the machine appears in their list, they receive push notifications, and they can run sessions on it. Ownership does not change, and the machine's auth token is untouched. Members who have already joined can re-scan any time without you opening a new window.

The expiry is enforced by the server, not just displayed. A scan with no matching code is refused with "this machine isn't being shared right now", and one past the deadline with "this share code has expired — ask the owner for a new QR". So a screenshot of an old share QR is worthless, which is the point: sharing is a deliberate, momentary act rather than a permanent grant.

Which QR am I looking at?

	Owner QR	Share QR
Where to find it	Setup wizard, or menu bar → Add device by QR	App → Account → the QR icon next to a machine
How long it lasts	Until the machine's identity is reset	Two minutes, with a countdown
Your own account scans it	Re-pairs — safe to repeat	Nothing new; you already have it
Someone else's account scans it	Takes ownership of the machine	Joins as a member; you stay the owner
Safe to screenshot?	No — treat it like a password	Harmless once the two minutes are up

LAN-only pairing

A machine configured with pairing_mode = "lan" pairs entirely on your local network: its QR is flagged LAN-only, the app skips the account claim, and no server is involved at any point. The machine is then reachable only from the same network, and push notifications and cloud AI assists are unavailable. It also cannot be shared — sharing is a server-mediated concept, and there is no server in this mode.