How the pieces fit

Tealhand has one owner device (your phone) and any number of controlled computers. A computer on your device list can also control your other computers, and let AI apps on it read them. Two optional servers help the devices reach each other and understand plain sentences. Neither server can command anything.

The names

Name	Runs on	Job
Tealhand (the phone app)	Android (iPhone later)	The remote: asks, shows the confirmation card, signs the command with the phone’s key
Tealhand on a computer	Windows, Linux (macOS later)	Settings, the Ctrl+K command palette, the connection QR code, the 60-second notice, your other computers’ pages, and AI apps. It contains Tealhand Host
Tealhand Host (tealhand-host)	Every controlled computer. Without the Tealhand app: tealhand-host run	Status, rules, checking and running signed commands
tealhand-power	The same computer, shipped with Tealhand Host	Only sleep and shut down
Tealhand Relay (tealhand-relay)	A server you run	Passes encrypted traffic when two devices cannot connect directly. Holds no keys
Tealhand Planner (tealhand-planner)	Teal’s servers later, or your own	Turns a sentence into a proposed action. Sees only the sentence and your computers’ names

In the apps, phone means the controlling device, computer means a controlled device (which may control your other computers too), and connected devices means both. The word agent always means an AI agent (for example Claude Code or Hermes), never Tealhand Host.

Coming in M1

The installers and tealhand-power are not built yet. The phone app, the Tealhand app on a computer, Tealhand Host, Tealhand Relay and Tealhand Planner exist as source code you can build. See Status of M1. For a map with every link and what it carries, see The big picture.

Who holds which key

There is no central server that controls computers. The phone holds the key that signs the device list, and each computer checks every command against that list.

Device	Key	Where it lives	What it does
Phone	iroh key (Ed25519)	Keystore-encrypted storage on the phone	Proves the phone’s network identity. Cannot sign commands
Phone	device key (P-256)	Android Keystore (StrongBox when the phone has it), cannot be exported	Signs every command and every device list (roster), without a prompt
Phone	presence key (P-256)	Android Keystore, signs only after a fingerprint or PIN on each use	Signs the commands that need you to be there
Computer	iroh key (Ed25519)	The OS credential store (Windows Credential Manager, Linux Secret Service). Linux without one: a private file	Proves the computer’s network identity, and signs its commands to your other computers. Never signs the device list
Computer	AI apps token (256 random bits), only while AI apps are on	The OS credential store, next to the iroh key	Lets an AI app on the same computer use the MCP endpoint on 127.0.0.1. Never leaves the computer
Tealhand Relay	Its TLS certificate key only	The relay server	Serves HTTPS. Holds no Tealhand key
Tealhand Planner	None		Holds no Tealhand key

Apart from the local AI apps token, none of these is a bearer token: no secret is ever sent to a server to prove who you are. Details: How commands are signed.

A picture in text

 Phone (Tealhand)                                   Computer (Tealhand Host)
 device key, presence key                           iroh key only
      |                                                    |
      |====== iroh QUIC, end to end ======================>|---> tealhand-power
      |       signed commands, status, rule events         |     (sleep, shut down)
      |                                                    |
      +- - - - only when a direct path fails - - - - - - - +
                    Tealhand Relay
                    (sees encrypted bytes, holds no keys)
      |
      +------ your sentence + your computers' names ------> Tealhand Planner
              (optional, holds no keys)                     (asks a model on 127.0.0.1)

How one action travels

1. You type or say what you want, or tap a button in the app.
2. The phone turns it into one action from the action list and shows a confirmation card. The card text is built by code from the action, never written by a model.
3. You confirm. For risky actions the phone asks for your fingerprint or PIN on the same card.
4. The phone signs the command with its device key, and with its presence key when needed.
5. The command goes to the computer directly over iroh, or through the relay when a direct path fails. The relay only sees encrypted bytes.
6. Tealhand Host checks the signature, the device list, the expiry and that the command is new. Only then does it read the action, check it again and run it.