Relays

Your phone and your computers talk over one encrypted connection, made by iroh. Most of the time that connection needs no server. A relay is the fallback for when the two devices can’t find a direct path, for example when you are away from home and the computer is behind a router.

Three ways to connect

You choose one on the phone (Settings, then Network) and, for each computer, with --relay on tealhand-host connect:

Choice	How devices find each other	Who else is involved
This network only (disabled)	On the local network, by mDNS (below) and by the addresses saved from the connection QR code	Nobody. No relay, and the phone can reach a computer only while both are on the same network
My own relay (an https:// address)	Directly when they can, otherwise through your relay	Your relay, which you run
Public relays (public)	Directly when they can, otherwise through the public relays run by n0, the makers of iroh	n0’s relays, and n0’s address lookup, which publishes a device’s key and its home relay address, never its IP address

With your own relay, nothing is published to a public service.

Direct on the local network

When the phone and the computer are on the same network, they connect directly. They find each other in two ways:

• mDNS, a way for devices on a local network to announce themselves with no server. A device announces its key and its local addresses, never its name. Other devices on the same network can see that a Tealhand device is there. mDNS is on with your own relay or with no relay, and off with public relays.
• The QR code’s addresses. The phone saves each computer’s addresses from the connection code. That is also why the computer keeps the same UDP port from one start to the next.

If a direct path can’t be made, the same connection goes through the relay. The phone shows which path is in use (Settings, then Network, under Right now: direct or via relay).

What a relay does

A relay forwards encrypted packets between two devices. It can’t open them: they are encrypted end to end between the two devices’ keys, and the relay holds no key that could decrypt them, or sign anything.

What your own relay sees: which device keys connect, from which IP address, when and how much. It sees sizes and timing. It does not see what is in the traffic. A network between you and the relay sees the same.

What your own relay keeps: for each owner you allow, the newest signed device list. That list holds each device’s name, kind (phone or computer), key, the phones’ public hardware keys, and when each was added and when it expires. There is no access log.

What it can’t do: command a computer, add a device, or change a device list. Only your devices sign (your phone, and your computers for their own commands), and a computer checks each signature itself. A hacked relay can refuse to pass your traffic, and nothing worse.

How your own relay admits only your devices

A public relay lets anyone in. Tealhand Relay doesn’t:

1. You list your phone’s owner key in the relay’s allowed_owners. The phone shows it in Settings, then Network.
2. The phone uploads its signed device list to the relay over HTTPS, on every app start, on a reconnect, and after every change. The relay stores it if the signature is valid, the owner is allowed, and the version is higher than the one it has.
3. A device can connect through the relay only if an unexpired entry in a stored list of an allowed owner names its key, and each device may hold at most 4 connections. Every 15 seconds, and after every upload, the relay disconnects devices that are no longer listed.

The relay serves uploads on a separate address from the relay itself (roster_bind), so the phone has two addresses to fill in. Both must start with https://. Computers don’t depend on the upload: the phone also sends every new device list to each computer directly.

The relay can’t forge a device list, because it holds no key. A relay that claims a much newer list than the phone has (more than 8 versions ahead) is not believed: the phone keeps its own list and says so.

Pinning a self-signed certificate

A relay needs a TLS certificate. With a DNS name, a certificate from Let’s Encrypt is checked against the public roots, and there is nothing to configure. Without a DNS name, you can make a certificate yourself, which the public roots don’t know. Then you pin it:

• The relay prints the certificate’s SHA-256 fingerprint: tealhand-relay fingerprint.
• You give that fingerprint to the phone (the Certificate fingerprint field) and to each computer (--relay-pin sha256:<64 hex digits>, only together with --relay).
• From then on, the phone and the computer, for both the relay connection and the device list upload, accept only that one certificate. They don’t check its name, because a self-signed certificate on an IP address has none to check. They still check its dates. They refuse every other certificate, including one a stranger presents from a network in the middle.

There is no switch that turns certificate checking off. Without a fingerprint, the public roots apply, as always. A new certificate has a new fingerprint, so pin the new one everywhere. Don’t pin a certificate that renews by itself; leave the field empty for those.

The Host’s log says “Tealhand Host is running, relay pinned” when a fingerprint is in use. Setup steps: Install Tealhand Relay.

What the relay can’t hide

A relay, and any network on the path, can see that your devices talk, and how much and when. Tealhand does not hide traffic patterns. If that matters to you, run your own relay on a server you trust, or use no relay. The full list of what leaves your devices, per choice: What leaves your devices.