Install Tealhand Host on Linux

Tealhand Host is the service on a computer that checks and runs the commands your phone signs. This page installs it on a Linux computer with no screen, from source, and keeps it running as a systemd user service. It runs as you, never as root.

Coming in M1

There is no tealhand-host download and no .deb yet. The Tealhand app for computers (tealhand-desktop_amd64.deb) is not packaged yet either. Today you build tealhand-host and run it yourself.

Caution

A release build of tealhand-host refuses to start until a tealhand-power program sits next to it or at the path you give with --power-helper (“the power helper was not found”). That helper (sleep and shut down) is not built yet; it comes in the next milestone. Until then, use the debug build below. Status, the task list, connecting a phone, shared folders and downloads all work with it. Sleep and shut down are refused until the helper exists.

Before you start

• A Linux computer you can log in to, over SSH or at the keyboard.
• Git, Rust through rustup (the repository pins Rust 1.99.1 in rust-toolchain.toml) and a C compiler. On Debian or Ubuntu: sudo apt install build-essential git curl.
• systemd, for the service below.

Build and install

git clone https://github.com/tealvpn/tealhand
cd tealhand
rustup toolchain install
cargo build -p tealhand-host
mkdir -p ~/.local/bin
install -m 755 target/debug/tealhand-host ~/.local/bin/tealhand-host

Check that it runs, and make sure ~/.local/bin is on your PATH:

tealhand-host --version

Every command and option: command line reference.

Connect your phone over SSH

Connect first, with Host not running. If it already runs as a service, stop it: systemctl --user stop tealhand-host.

tealhand-host connect --relay https://relay.example.com

Leave out --relay to use this network only. A relay you give here is saved and used by run and by the service. See Install Tealhand Relay for your own relay, and add --relay-pin sha256:<64 hex digits> if it uses a self-signed certificate.

Over SSH the QR code is drawn in your terminal. If it is hard to scan, the command also prints the code as a line of text: “No camera at hand? Copy the line below to the phone and choose “Paste the code” there:“. On the phone choose “Paste the code” and paste that line. The phone and the computer must be on the same network to connect, and the code works for 10 minutes. The phone shows a check code and the terminal asks:

"Pixel 8" wants to connect to this computer.
Check code: ABCD EFGH. Connect only if the phone shows the same code.
Connect? [y/N]

Answer y only if both codes are the same. The command ends with Connected to "Pixel 8". Start Tealhand Host with: tealhand-host run. More on what happens: Connecting a phone.

Run it as a systemd user service

The repository ships a sample unit, crates/tealhand-host/packaging/tealhand-host.service. It runs tealhand-host run --power-helper %h/.local/bin/tealhand-power, restarts on failure after 5 seconds, and holds no address and no key. %h is your home folder. With a debug build the helper file does not have to exist yet, but the path must be absolute, as it is.

mkdir -p ~/.config/systemd/user
cp crates/tealhand-host/packaging/tealhand-host.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now tealhand-host
loginctl enable-linger "$USER"

loginctl enable-linger keeps your user services running when nobody is logged in, and starts them at boot. Without it, the service stops when your last session ends.

Check on it:

systemctl --user status tealhand-host
journalctl --user -u tealhand-host

The journal shows one line per event and, when it stops, an error line with the fix under it. Set RUST_LOG in the unit to change the log level.

The port and the firewall

Tealhand Host listens on one UDP port, the one iroh uses. The first run picks a free port and saves it; every later start reuses it, so the address in a connection QR code stays valid. Choose it with --port <n> on connect or run. Nothing else listens.

If the computer has a firewall that blocks inbound UDP, open that port for your local network. For ufw, with your port in place of 41234:

sudo ufw allow 41234/udp

Without an open port the phone can still reach the computer through a relay once connected; only connecting and direct local connections need it.

Data and key

What	Where
Data folder	$XDG_DATA_HOME/tealhand/host, or ~/.local/share/tealhand/host when that is not set. Made 0700
The computer’s key	The Secret Service when one runs; on a headless server without one, key.bin in the data folder, mode 0600

The files in the data folder: Headless computers.

Share folders

Folders for the phone’s Files screen are shared at the computer, with the service stopped: Share folders.

Switch remote control off

systemctl --user stop tealhand-host
tealhand-host remote off
systemctl --user start tealhand-host

remote off keeps remote control off from the next start. It prints “Remote control is off from the next start. Only this computer can switch it on again.” While it is off, a phone can still see the computer’s status and cancel a running countdown, but it cannot change anything or open a file. See Remote control on and off.

To forget the connected phone (a lost phone), stop the service and run tealhand-host unpair.

Update

Pull the repository, build again, install over ~/.local/bin/tealhand-host, and restart the service: systemctl --user restart tealhand-host. The data folder keeps your connected phone, rules and shared folders.