What leaves your devices

This page lists what Tealhand sends, to whom, and what it keeps. It describes the code as it is today.

Coming in M1

The Tealhand app for computers and the phone’s Files screens are built from source and not packaged yet. Everything below comes from the phone app, the libraries under it (tealhand-mesh, tealhand-core, tealhand-files, tealhand-host) and from Tealhand Relay and Tealhand Planner.

Between your phone and your computers

All traffic between connected devices is iroh QUIC, encrypted end to end between the two devices’ keys. A relay in between sees only encrypted bytes.

From	To	What
Phone	Computer	Signed commands; the signed device list after every change
Computer	Phone	Status every 5 seconds while the phone watches (CPU, GPU, memory, battery, uptime, remote control on or off), the 20 busiest programs (name, process id, CPU and GPU use), the rules list, and rule and power events
Phone	Computer, over files/1	Which shared folder and path you open, the bytes of files you send, and a signed command for each change
Computer	Phone, over files/1	Folder listings (names, sizes and dates) and the bytes of files you open or play
Phone	Your own relay, only with your own relay	The signed device list, to the upload address you gave the phone: on every app start, on a reconnect (at most every 10 minutes), after every change, and on a retry timer after a failure. Nothing is uploaded with public relays or no relay
Phone	Computer, when connecting	The phone’s name, its iroh key and its two public hardware keys
Computer	Phone, when connecting	The computer’s name and its OS (Windows, Linux or macOS)
Computer	Another of your computers	The same as a phone sends and gets: signed commands, status, events, folder listings and file bytes. Never the device list
Computer	Phone	A report of each change another computer made there: who, which action, and at most a short name (a file or folder name, a shared folder, a download’s host, a saved command’s key). Never a path, a link, text or file content

The connection QR code carries the computer’s key, its address (its relay address, if it uses one, and its IP addresses), a one-time secret and the time it expires. Treat a QR on screen like a password for 10 minutes.

Per relay choice

Each phone and computer is set to one of three choices. What they publish or ask:

	Your own relay	iroh’s public relays	No relay (this network only)
Relay used	The one you configured	The public relays run by n0, the makers of iroh	None
Public address lookup	None: nothing is published to a public service	This device’s key and its home relay address are published to n0’s address lookup (never its IP addresses), and anyone who knows a key can look up that relay address	None
mDNS on the local network	On: announces the device’s key and its local IP addresses, no name	Off	On, as with your own relay
Router port mapping (UPnP, NAT-PMP, PCP)	Off	On: the device asks your router for a port	Off
Who learns your IP address	Your relay	n0’s relays	Devices on your local network

With your own relay, the configured relay always wins over a relay address in a QR code, so a QR cannot point your devices at another relay. Relay addresses must be https://: on the phone both the relay address and the upload address, with no plain http:// exception.

In every mode, iroh’s UDP socket listens on all interfaces and accepts only devices on your device list, and connection attempts from a new phone only while a QR code is showing. Nothing else listens, with one exception you choose: while AI apps are on, the MCP endpoint listens on 127.0.0.1 only (below).

AI apps on a computer

Only while you turn them on. The AI app talks to Tealhand on the same computer, over 127.0.0.1, with a token from your user account’s credential store. Tealhand turns each call into a read of another computer, so only reads go out: status, the busiest programs, folder listings and file bytes. A copied file is saved on this computer. What the AI app then sends to its own model or service is between you and that app. Every call is a line in this computer’s Activity; nothing goes to the phone. See Use Tealhand from your AI app.

What the relay sees and keeps

• Sees: the encrypted bytes it passes, which device keys connect, from which IP address, when, and how much. It cannot read or change the traffic, and it holds no key that could sign a command.
• Keeps: for each allowed owner, the newest signed device list. That list holds each device’s name, kind (phone or computer), key, the phones’ public hardware keys, when it was added and when it expires. The names are in there because the phone’s signature covers them.
• Logs: no access log. At start it logs the first characters of each owner key and the device list version, and later the number of devices it disconnected.

Downloads on a computer

When you ask a computer to download a link, the computer connects to that web address, and to the addresses it redirects to. The website sees the computer’s IP address and the program name Tealhand-Host/<version>. Nothing about you or your phone goes along. The computer refuses links that lead to your own network. If the link is a web page, the computer reads the page (at most 2 MiB, in memory), and the phone offers the file links on it; the file you pick is a new download with its own card. A Dropbox or Google Drive share link is rewritten on the phone, before the card, and the phone sends nothing to those sites. Details: Files.

A relay’s certificate fingerprint

If you pin a self-signed relay certificate, its fingerprint is stored on the phone and, for a computer, in the Host’s settings.bin. It is public information, not a secret, and it is never sent anywhere.

What the planner gets

Only when you use one: your sentence, the names of your computers (as D1, D2 and so on) and the language code. Not the computers’ status, tasks, rules, files, addresses or keys. The planner stores nothing and logs only the status code, the duration and the number of steps. It asks a model on its own machine (127.0.0.1).

What stays on the computer

• The data folder (owner-only on Linux): the signed device list, the rules, the remote control setting (and, for a headless computer, the relay choice made at connect, which is not a secret), the activity journal, and the AI apps settings (ai.bin; while on, mcp.json with the port only, never the token). On Linux without a secret service, also the computer’s iroh key, mode 0600. See Headless computers.
• The journal (journal.log): one line per event, with the time, who (a device name, “this computer”, “rule” or “AI app via MCP”), what (an action id or a short fact) and how it was allowed. Never program names, parameters, file contents or keys. Lines older than 30 days are dropped, and the file is capped at 8 MiB.
• Logs on standard error: event kinds only, no program names, keys or content.

What stays on the phone

• roster.bin: the signed device list (public data).
• peers.bin: each computer’s address from its QR code, its OS, when it was last seen and the newest device list version it confirmed.
• lock: an empty file that keeps a second copy of the app from using the same folder.
• No key, token or sentence is written by the core. The hardware keys stay in the Android Keystore.

Not hidden

Tealhand does not hide traffic patterns. A relay and the networks in between can see the sizes and timing of the encrypted packets. Devices on your local network can see that a Tealhand device is there when mDNS is on.