Install Tealhand Host on Windows

Tealhand Host is the service on a computer that checks and runs the commands your phone signs. This page installs it on Windows 11 x64 from source. It runs as you, never as an administrator or as SYSTEM.

Coming in M1

There is no Tealhand-Desktop-Setup-x64.exe yet, so there is no installer and no Start menu entry. The Tealhand app for computers, the small settings app that wraps the Host, is not packaged yet (you can build it from source). Today you build tealhand-host.exe and run it from a terminal.

Caution

A release build of tealhand-host refuses to start until a tealhand-power program sits next to it: “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

• Windows 11 x64.
• Git and Rust through rustup. The repository pins Rust 1.99.1 in rust-toolchain.toml.
• The Visual Studio C++ Build Tools (the “Desktop development with C++” workload), which Rust needs to link.

Build

In PowerShell:

git clone https://github.com/tealvpn/tealhand
cd tealhand
rustup toolchain install
cargo build -p tealhand-host

The program is target\debug\tealhand-host.exe. Run the commands below from the tealhand folder, or copy the file where you like. tealhand-host --help lists every command; the full list is in the command line reference.

Where Tealhand Host keeps its files

%LOCALAPPDATA%\Tealhand\host

That is the data folder: the signed device list, the rules, the settings, the shared folders list and the activity journal. The computer’s own key is in the Windows Credential Manager, under the name tealhand-host, not in this folder. Add --data-dir <folder> to any command to use another folder. The full list of files: Headless computers.

Connect your phone, then run

Connect first. connect starts a Host just for connecting, so quit any running tealhand-host first.

.\target\debug\tealhand-host.exe connect

It prints a QR code in the terminal and a line of text under it. Open Tealhand on your phone, choose “Scan the code” and scan it. If the camera can’t read it, choose “Paste the code” on the phone and paste the text line. The phone and the computer must be on the same network. 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]

Type y and press Enter only if both codes are the same. The terminal then says Connected to "Pixel 8". Start Tealhand Host with: tealhand-host run. How and why both sides confirm: Connecting a phone.

Then start the Host and leave it running:

.\target\debug\tealhand-host.exe run

It stops cleanly on Ctrl-C. Closing the terminal window stops it too. It logs one line per event to the terminal. Remote control is on after a fresh install, so the phone can use the computer right after connecting.

To use a relay, give connect the choice once and run reuses it:

.\target\debug\tealhand-host.exe connect --relay https://relay.example.com

With a relay that uses a self-signed certificate, add --relay-pin sha256:<64 hex digits>. See Install Tealhand Relay.

The port and the Windows firewall

Tealhand Host listens on one UDP port, the one iroh uses. The first time it runs, Tealhand Host picks a free port and saves it in the data folder. Every later start uses the same port, so the address in a connection QR code stays valid when you run the Host. To choose the port yourself, add --port <n> (1 to 65535) to connect or run. If the saved port is taken, Tealhand Host uses a free one and saves that one.

The first time a program starts listening, Windows Defender Firewall may ask whether to let it through. Allow it on private networks: the phone reaches the computer on your home or office network through that port. Without it, connecting over the local network cannot work, and the phone can reach the computer only through a relay.

If you chose the port yourself and want an explicit rule, run this once in an administrator PowerShell (replace 41234 with your port):

New-NetFirewallRule -DisplayName "Tealhand Host" -Direction Inbound -Protocol UDP -LocalPort 41234 -Action Allow -Profile Private

Nothing else listens: no TCP port and no local control port.

Share folders

Folders for the phone’s Files screen are shared at the computer, while the Host is stopped: Share folders.

Switch remote control off, or forget the phone

To	Run (with the Host stopped)
Keep remote control off from the next start	tealhand-host remote off
Forget the connected phone, for a lost or replaced phone	tealhand-host unpair

Only this computer can switch remote control on again, and that switch comes with the Tealhand app. See Remote control on and off and Lost or stolen phone.

Update

Pull the repository, build again, and start the new tealhand-host.exe. The data folder keeps your connected phone, rules and shared folders.