The five safety rules

These five rules are not negotiable. A change to any of them is discussed in an issue before anyone writes code for it. For each rule, this page says what the code does today.

1. The AI only proposes actions from the fixed list; the person confirms each one on a card

There is one action list, in tealhand-actions: 33 actions, each with a fixed risk level (Actions). The phone, the palette, the planner and the computer all use it.
The planner’s model can only answer in a JSON Schema built from that list, and only with the actions marked for chat. Its answer is then parsed, checked (validate) and passed through the chat gate in Rust. Anything else becomes “no matching action”.
The phone checks every proposed step again, drops steps for unknown devices or actions chat may not run, and shows one card per step.
The card’s words are built by code from the checked action, never from the model’s text. A card works once and expires after 5 minutes.
Nothing is signed or sent until the person taps the card’s button. On another computer’s page in the Tealhand app, every change is a card too.
An AI app on a computer gets no action list at all: its six MCP tools map to five reads (device.status, device.tasks, files.list, files.stat, files.get). Rust refuses anything else before it leaves the computer, whatever the model asks (Use Tealhand from your AI app).

2. Risky actions need a fingerprint or PIN; destructive ones are never available from chat

Fingerprint or PIN is needed for: a rule that shuts down or sleeps, power.shutdown, device.remove, device.forget (Windows Hello on the computer), turning remote control on, replacing a file, deleting a file, adding a shared folder (Windows Hello), opening a terminal, adding a saved command from the phone, and running a saved command that the owner marked to ask for it. On a computer, Windows Hello stands in for the fingerprint: turning remote control on, sharing a folder, turning SSH access on, changing saved commands, turning AI apps on, and disconnecting a phone. Opening a terminal, and adding or removing a saved command from a phone, also need SSH access to be on at the computer, which only the computer can switch on.
On the phone this is a second hardware key, the presence key, which the Android Keystore lets sign only after a fingerprint or PIN. The computer refuses those actions without a valid presence signature (PresenceRequired), so the phone app cannot skip the prompt.
A command from another of your computers carries no fingerprint, because a computer has no fingerprint key (see rule 4). A saved command the owner marked to ask for the fingerprint still needs one, so only the phone can run it.
The destructive actions, device.remove, device.forget and files.delete, are never offered to chat or the palette, and the chat gate refuses any destructive or local-only action.
The risk of an action comes from the list, never from a model.

3. Text from web pages or files can never trigger an action

Only the person’s own typed or spoken sentence goes to a model. Task names, events and other text from a computer are shown as data and never create a card.
The planner wraps the sentence as one JSON object and tells the model it is data, not instructions. That alone would not be enough, so the output is limited to the action list, checked in Rust, and still needs the person’s tap on a card.
Strings that come from a computer (program names, device names) are cleaned before they are shown: control and invisible characters are removed and the length is capped.
File and folder names, and the links you ask a computer to download, are data. Names are cleaned before they are shown, a download link is checked by the address rule that keeps it away from your own network and still needs your tap on a card, and the computer never opens or runs a downloaded file.
A file an AI app reads through Tealhand can say anything (“delete everything”). The AI app can only read, so such text can at most make it read or copy more. It never becomes a Tealhand action.

4. The computer only obeys commands signed by a device on the owner-signed list

A device on the list is a phone with its hardware key, or one of your computers. A phone signs every command with its device key (and the presence key when needed); a computer signs with its own iroh key and has no fingerprint key, so a command from it needs no fingerprint. The computer verifies the signature against the signed device list before it reads the command.
It checks, in order: the connection’s peer is on the device list, the signatures, the command’s format, that the command was issued by that device for this computer, the time window, and that the command has not been seen before.
A command from another computer still meets this computer’s own switches (remote control, SSH access), and what it changes is reported to your phone. Anyone at an unlocked controlling computer can do what your phone can without a fingerprint: remove that computer on your phone to cut it off. How commands are signed has the details.
The device list itself is signed by the phone and hash-chained. The relay and the planner hold no key, so a hacked server cannot command a computer or add a device.
Unknown devices cannot even open a connection: the roster gate turns away every connection that is not from a current member, except a phone being connected while a QR code is showing.
A device list pushed by the phone cannot add a phone, change a device’s kind or keys, or give a computer keys. Only connecting, with a click on the computer, adds a phone.
Removing a computer is done on the phone, like every device list change. Each computer then refuses that computer’s commands.

5. The hosted AI sees only the person’s sentence, never the computer’s data

The phone sends the planner the sentence, the names you gave your computers (as D1, D2 and so on) and the language. Never status, tasks, rules, files, addresses or keys.
The planner stores nothing and logs only status codes, durations and step counts.
Using a planner is opt-in. Without one, the ask box searches the action list on the phone.
Its code is open, but you cannot verify what a server runs. If that matters to you, run your own.

What Tealhand accepts

The threat model (docs/threat-model.md in the repository) lists what the code defends against and what it accepts. The highlights for computers and AI apps:

An unlocked computer on your device list (C1). Anyone at it, or malware running as your user there, can do on your other computers what your phone can, without a fingerprint: shut down, delete files in shared folders, and open a terminal where SSH access is on. Each computer’s own switches still apply, your phone is told of every change while it is connected to that computer, and removing the computer on the phone cuts it off.
A computer’s key passed off as something else (C2, C3). A computer’s command signature starts with tealhand-cmd-v1, which none of iroh’s own signed messages do, and the key that is checked is fixed by the device list entry: a phone’s hardware key for a phone, the iroh key for a computer.
An AI app that tries to change something (AI1). Refused in Rust, before anything leaves the computer.
Another program on the same computer using the AI endpoint (AI2). It listens on 127.0.0.1 only and needs a token kept in the OS credential store. A program running as your user can still get the same reads, as it could already read the computer’s key. The endpoint is off by default.
A web page reaching the AI endpoint (AI3). The address, Host and Origin checks and the token refuse it.
Text in a file steering the model (AI4). The tools only read, so it can’t change your computers.
Copies filling the disk (AI5). Copies go only into the folder you chose, never replace a file, and stop at the size limit. Many copies under the limit can still fill the disk.