Headless computers

On a computer without the Tealhand app (a Linux server, a box without a screen, or a terminal you prefer), Tealhand Host runs on its own as tealhand-host.

For step-by-step installs, see Windows and Linux. This page is the reference for what Tealhand Host does and where it keeps things.

Coming in M1

There is no prebuilt tealhand-host download yet: build it from source (Build from source). The tealhand-power helper is not built yet, so sleep and shut down do not work. Status, the task list, connecting a phone, adding and cancelling rules, rules that only notify, shared folders and downloads work today. A power.sleep or power.shutdown request, and a rule that shuts down or sleeps, are refused because the computer first asks the helper who is signed in and cannot reach it.

Caution

A release build of tealhand-host refuses to start when tealhand-power is missing. The error is “the power helper was not found: shutdown and sleep need it next to this program”. On Unix it also refuses when other users could replace the helper or its folder: “the power helper can be replaced by other users: make it and its folder writable by you only”. Both run and connect start Tealhand Host, so both are affected. Until the helper exists, use a debug build (cargo build -p tealhand-host) to try Tealhand Host.

The commands

tealhand-host run          run Tealhand Host until Ctrl-C or SIGTERM
tealhand-host connect      show a QR code in this terminal and connect a phone (quit a running Host first)
tealhand-host unpair       forget the connected phone, for a lost phone (refused while a Host is running)
tealhand-host remote off   keep remote control off from the next start (stop the Host first)
tealhand-host share ...    list, add and remove the folders a phone may browse, and set the default for downloads (stop the Host first)
tealhand-host downloads    list what phones downloaded here; `downloads cancel <id>` stops one (works while the Host runs)
tealhand-host ssh on|off   SSH access: phones may open a terminal here and add saved commands (stop the Host first)
tealhand-host commands ... list, add and remove the saved commands phones run by name (stop the Host first)

A typical first run:

tealhand-host connect --relay https://relay.example.com   # scan the QR with the phone, compare the code, answer y
tealhand-host share add ~/Projects --name Projects         # optional: a folder for the phone's Files screen
tealhand-host share add ~/Downloads --downloads            # optional: the default for downloads from the phone
tealhand-host run                                          # keep it running

The phone picks the folder for each download from your shared folders that are not read only, and offers the default first. A computer with no such folder shows “No writable folder on ⟨name⟩” on the phone, with these commands as the fix. See Share folders.

The old name tealhand-host pair still works as an alias for connect, so notes that use it keep working.

connect, unpair, remote off, share, ssh and commands work on the same data folder as run, so they refuse to start while Tealhand Host is running on it: “Tealhand Host is already running for this data folder: quit it first”. Stop run first. downloads is the exception: it works while the Host runs. The old names terminal on and terminal off still work as ssh on and ssh off.

Every option is in the CLI reference. The ones you are most likely to need:

Option	Default	Meaning
--relay <choice>	disabled	disabled: this network only. public: iroh’s public relays. Or the https:// address of your own Tealhand Relay
--relay-pin sha256:<64 hex>	none	Your relay’s certificate fingerprint, for a self-signed certificate. Needs --relay with your relay’s address. See Install Tealhand Relay
--port <n>	the port used last time	The UDP port Tealhand Host listens on. It is saved, so the address in a connection QR stays valid
--name <name>	the computer’s host name	This computer’s name on the phone, 1 to 64 characters
--data-dir <dir>	this user’s Tealhand folder (below)	Where Tealhand Host keeps its files
--power-helper <path>	tealhand-power next to tealhand-host	The power helper. The path must be absolute

A --relay given to connect is saved in settings.bin, together with its --relay-pin if you gave one, and connect prints “Saved the relay choice. tealhand-host run uses it from now on.” run uses the saved choice when it gets no --relay of its own. A --relay on run wins but is not saved. With no choice at all the relay is disabled. For your own relay, see Run your own relay.

Run it as yourself

Tealhand Host runs as the signed-in user, never as root or SYSTEM. Start it in your own session: a terminal, a terminal multiplexer, your login session’s autostart, or a systemd user unit (below). It stops cleanly on Ctrl-C and on SIGTERM.

A systemd user unit

A sample unit ships in crates/tealhand-host/packaging/tealhand-host.service: it runs tealhand-host run with Restart=on-failure. The commands to install it, and loginctl enable-linger, are in Install Tealhand Host on Linux.

Logs go to standard error: one line per event, never program names, keys or content. Set RUST_LOG to change the level (the default is error,tealhand_host=info,tealhand_mesh=warn).

The data folder

System	Default folder
Windows	%LOCALAPPDATA%\Tealhand\host
Linux	$XDG_DATA_HOME/tealhand/host, or ~/.local/share/tealhand/host when XDG_DATA_HOME is not set

On Linux the folder is made 0700 (a wider folder is tightened, with a warning) and files are written 0600. On Windows the folder inherits the per-user rights of %LOCALAPPDATA%.

File	What it holds
host.lock	The single-instance lock: one Tealhand Host per data folder
roster.bin	The signed device list from your phone (public data)
roster.mismatch.bin	A device list that does not list this computer, kept until you forget it
key.bin	Linux without a secret service only: this computer’s iroh key
rules.bin	The rules saved on this computer (rules.bin.bad if a damaged file was set aside)
settings.bin	Whether remote control is on, the relay choice saved by connect with its certificate fingerprint if any, and the UDP port. Never keys or tokens. Older versions of the file still load
shares.bin	The shared folders (tealhand-host share)
parts.bin	The temporary files of uploads that are running; removed at the next start after a crash
downloads.bin	The downloads: the one running or paused, and the last finished ones
journal.log	The activity journal: one plain line per event, kept 30 days

The device list, the rules, the settings and the key file are written to a temporary file first and then renamed, so a crash leaves the old or the new file, never half of one. The journal is appended to.

Where the computer’s key lives

The computer’s iroh key is its address on the network. It never signs the device list (only your phone’s key can); it signs this computer’s commands to your other computers when you use them from the Tealhand app here.

• Windows: in the Windows Credential Manager, under the service name tealhand-host. There is no file fallback on Windows.
• Linux with a secret service (for example a session with a keyring): in the Secret Service, under the same service name.
• Linux without a secret service (a headless server, WSL): in key.bin in the data folder, mode 0600. Tealhand Host warns when the file is readable by others. Once key.bin exists it stays in use.

A credential store that exists but fails (locked, access denied) is an error: Tealhand Host never replaces it with a file. If the key ever changes, this computer gets a new identity. The saved device list no longer lists it, Tealhand Host starts “blocked” and logs “the saved connection does not belong to this computer; run tealhand-host unpair to forget it”. Forget it and connect again.

Remote control on a headless computer

Remote control is on after a fresh install, so a phone can use the computer right after connecting. tealhand-host remote off (with the Host stopped) keeps it off from the next start and adds a journal line, “remote control off”, from a terminal. There is no terminal command to turn it on again: that switch comes with the Tealhand app. See Remote control on and off.

On a computer without the Tealhand app, cancel a running 60-second notice from the phone.