What the phone app does

The phone is the remote. It shows your computers, builds a confirmation card for every action, and signs each command with a key that never leaves the phone’s secure hardware.

The screens that exist

First start: a welcome with the Tealhand logo (the Teal bird in a hex-nut cube with a thin gold outline), how your devices find each other (your own relay, public relays or this network only), Chat or Classic, and connecting a first computer. The app needs a screen lock first, because its keys live in the phone’s secure hardware.
Home: Chat or Classic at the top, with the computer picker beside it in both modes: a live dot, the computer’s name and a chevron. Tap it for a menu of your computers with their state; picking one only switches Home to it. With one computer there is nothing to pick. A computer you just connected becomes the one Home shows.
- Chat reads like a messenger (Chat), over a slowly turning ASCII donut. The ask box turns a sentence into one action and shows its card. Chat hides the tab bar, and chat commands stand in for it (see Chat commands).
- Classic keeps the tab bar and a list of tools. The status strip under the top row opens the computer’s page. A running shutdown or sleep countdown stays on Home as one compact strip with Cancel shutdown.
Devices: your connected computers and phones, their status (CPU, GPU, memory, battery, uptime, busiest programs), whether the phone reaches each one directly or via a relay, and connecting a new device. This phone is marked “This phone” with the live dot; another phone says “Another phone on your list”. A computer that forgot the phone, or runs an incompatible version, says so in plain words.
Power and rules: sleep, shut down (now, or when a program closes), the rules saved on the computer, and adding a rule. Every button leads to a card. Sleep and shut down are refused until the power helper exists.
Cards: the confirmation card for each action: a title and one plain sentence. A later time shows only when the action doesn’t happen now, and an undo line only when it matters (removing a device, forgetting a phone, shutting down, deleting or replacing a file). Risky actions also ask for your fingerprint or PIN on the card.
Files: the folders a computer shares, its downloads, and the files in them. See Files and downloads.
SSH access: a computer’s terminal and its saved commands. See SSH access and saved commands.
Connecting: scan the QR code or choose “Paste the code”, compare the check code, tap “Yes, connect”. See Connecting a phone.
Inbox: the notices from your computers (Notices and the Inbox). The tab shows how many you haven’t seen.
Settings: Network, Interface, What leaves your devices, Security and About.

Chat

Chat is one conversation, newest at the bottom, like a messenger:

Your messages are on the right. Tealhand’s are on the left, named “Tealhand” above each group: answers to chat commands, status, rules, and the notices from your computers.
Messages in a row from one sender group together. A time shows at the start and after every pause of more than 10 minutes.
A notice arrives as a message when it comes: its title in bold and its text. A running shutdown or sleep keeps a live countdown and Cancel shutdown in the message.
Hold a message (anywhere on its row) for its options: Copy and Delete, plus its own actions, such as Remove ⟨computer⟩ on a change another computer made. A message whose actions wait behind a hold says “Hold” under it.
Once the chat has started, the example questions wait as a row of short buttons above the empty box.

The donut behind Chat stops when Chat is hidden or the app is in the background, and stands still when the phone asks for less motion.

Chat commands

In Chat, Home hides the tab bar. Chat commands stand in for it and work like completion in a shell: type / to see them, keep typing to narrow the list, and tap one to fill it in. They never go to the planner. The commands that act on a device act on the device chat talks to. Pick it in /devices.

Command	What it does
`/devices`	Lists your devices. Tap a computer to make chat talk to it (the picker in the top row does the same)
`/files`	Opens that device’s files and downloads
`/terminal`	Opens its SSH access, saved commands and terminal
`/power`	Opens its sleep, shut down and rules
`/screen`	Shows a picture of its screen (after your fingerprint)
`/wake`	Wakes it from sleep
`/settings`	Lists this phone’s settings with their values. Tap one to fill in its command
`/inbox`	Opens the inbox
`/classic`	Switches to Classic, with the tab bar
`/help`	Lists every command

/settings takes a setting and a choice:

Command	What it sets
`/settings theme auto`, `light` or `dark`	The theme
`/settings lock now`, `1min` or `5min`	How soon Tealhand locks after you leave it
`/settings home chat` or `classic`	What Home shows
`/settings chat words` or `planner`	Who understands chat: word matching on this phone, or your own planner
`/settings network`, `privacy` or `security`	Opens that page

A word chat doesn’t know gets “There is no such command. Type / to see them.”

Notices and the Inbox

Your computers send notices: a shutdown or sleep counting down, a rule that fired or was refused, a countdown that was cancelled, a shutdown that didn’t happen, and every change another of your computers made on one of them (“Studio PC deleted a.txt on Cloud PC”: see Control your other computers from a computer). Each one is a notification while the app runs (a locked phone shows only “News from one of your computers”), a message in Chat, and a row in the Inbox.

The Inbox lists them newest first, like the notification shade: an icon, the title, one line of text and the time.

Swipe a notice away, or Clear all.
Hold a notice for Remove ⟨computer⟩ (on a change another computer made), Copy and Dismiss.
A running countdown keeps its live time and Cancel shutdown in sight. It can’t be swiped, dismissed or cleared until it ends or is cancelled.
Opening the Inbox marks the notices as seen.

An AI app reading your computers sends no notice: it changes nothing (Use Tealhand from your AI app).

Files and downloads

Files for a computer lists, from top to bottom:

Folders ⟨computer⟩ shares: the folders you shared at the computer. A folder that is read only has a Read only badge, and nothing else is badged.
Downloads, “Links ⟨computer⟩ downloads for you”. Downloads lives inside Files: a computer’s page has only Files.
“Share more folders on ⟨computer⟩: Tealhand → Shared folders, or tealhand-host share add <folder>.”

Tap a folder to open it. Tap a file:

an image, a video or an audio file opens in a viewer;
a text file shows a preview of its first 256 KiB;
anything else is copied to the phone and opened there. A type the phone doesn’t know asks Open with. The progress sheet for the copy has Open and Show folder.

Long-press a file or folder for Send to phone, Rename, Delete (with your fingerprint) and New folder. Changes go through cards. How it works: Files.

Downloads shows what a computer is fetching and has fetched, and has a Paste a link button. Share a web link to Tealhand from your browser, or copy it and tap Paste a link.

The card says Save to ⟨folder⟩, with Change. The phone can pick any shared folder that is not read only. It offers the folder you used last for that computer, then the computer’s default for downloads, then a folder named Downloads, then the first folder that is not read only.
A computer with no folder that is not read only shows “No writable folder on ⟨computer⟩”, with How to set it up (Tealhand → Settings → Shared folders, or tealhand-host share add ~/Downloads --downloads) and Check again.
A link that is a web page shows Pick the file, with the files the computer found on it. A Dropbox or Google Drive share link is rewritten to a direct download first.
A finished download opens its folder with the file marked. Play, Open and Send to phone are done from there.

How downloads are kept safe: Share folders.

Share a photo, a file or a web link from any app to Tealhand, and choose the computer and folder. Shared text that is not exactly one link is shown and goes nowhere.

SSH access and saved commands

A computer’s Terminal page has the SSH access switch. It is read only on the phone: you turn it on at the computer, in Tealhand or with tealhand-host ssh on. With SSH access on, opening a terminal asks for your fingerprint or PIN, and so does adding a command.

Saved commands run by name with one Run button. Some ask for your fingerprint first. Every run notifies the phone when it ends, and tapping a finished run under Recent runs shows what it printed. Clear hides the finished runs on this phone.
Add a command (a dashed button when there are none): a name, the command line, an optional folder (it runs in the home folder without one) and Ask for my fingerprint to run it. Adding asks for your fingerprint.
Remove: long-press a saved command, then Remove. A card asks first.
Open terminal: a terminal with a keyboard row made for a thumb.

Adding commands from the phone needs SSH access on. Saved commands the computer already holds still run when it is off.

Settings

Setting	What it does
Network, relay	Public relays, My own relay, or This network only. Changing it reconnects your devices and loses nothing
Network, My own relay: Relay address	The relay itself, an `https://` address such as `https://relay.example.com`
Network, My own relay: Device list upload address	Where the relay takes device list uploads, such as `https://relay.example.com:8443/tealhand/v1/roster` (the relay’s `roster_bind` address plus the path). Both addresses are required with your own relay: there is no default
Network, My own relay: Certificate fingerprint	Only for a self-signed certificate: `sha256:` and 64 hex digits, from `tealhand-relay fingerprint`. Leave it empty otherwise. With it, the app accepts only that certificate for the relay and the upload. See Relays
Network, Owner key	Your phone’s `device` public key (`thhw:` and 66 hex digits), with a Copy button. Add it to your relay’s `allowed_owners`
Network, Right now	Whether each computer is reached directly or via the relay
Interface	Theme (auto, light, dark), and what Home shows (Chat or Classic). In Chat, `/settings` changes these too
Interface, who understands chat	Word matching on this phone (nothing leaves the phone), or your own planner server: a planner address, where only your sentence and your computers’ names go
What leaves your devices	A plain summary of what goes where, for the choices you made
Security	Fingerprint for risky actions (always on: the computer checks it itself), how soon Tealhand locks after you leave it (immediately, 1 minute or 5 minutes), and whether remote control is on or off on each computer (read only: change it at the computer)

Server addresses must start with https://. Both relay addresses accept nothing else, even for a private IP address. Plain http:// is accepted only for the planner, and only for a loopback or private IP address (a planner on your own network). Addresses with a user name or password are refused. The field keeps what you typed and marks the problem under it.

What the core does underneath

Live status: keeps every connected computer reachable, reconnects with backoff, and receives a status update every 5 seconds plus rule and power events, and a report of each change another of your computers made there. Each computer has a link state: offline, connecting, online, incompatible (the two versions of Tealhand can’t talk: update the older one) or forgotten (the computer closed the connection because it no longer knows this phone: connect again).
Device list duties: after every change (connecting, rename, removal) it sends the new signed device list to each computer and uploads it to your relay. A computer that is offline gets it at its next connect. If your relay claims a much newer device list than the phone has (more than 8 versions ahead), the phone keeps its own list and says so.
Files: one files connection per computer, opened on first use, with reads, batched uploads (one card per batch) and a playback server on 127.0.0.1 for the media player (Files).
Saved commands and notifications: lists a computer’s saved commands and recent runs, runs a command by its key (never a command line), and posts a notification when a run ends, while the app is open.
Cleaning: every name, program, file and message that comes from a computer is cleaned of control and invisible characters and capped before a screen shows it.

Signing never happens in the core. The two P-256 keys live in the Android Keystore; the app signs in Kotlin when the core asks for a signature, and the core checks every signature against the public key before using it.

Requirements

Android 10 (API 29) or newer, with a screen lock. On Android 10 the app also needs a fingerprint for risky actions; Android 11 and newer accept the device PIN as the fallback. iPhone support comes later.