Install the phone app

Tealhand, the phone app, runs on Android 10 or newer. iPhone comes later.

Before you start

On the computer you build on:

Rust, through rustup. The repository pins Rust 1.99.1 and the three Android targets in rust-toolchain.toml, so rustup toolchain install in the repository gets all of them.
cargo-ndk 4.1.2, the version CI uses.
The Android SDK and NDK 30.0.16248370 (the NDK the app is built with), and adb.
Flutter 3.47.7 (the version CI uses).
Git Bash on Windows: the library script is a bash script. Linux and macOS use their normal shell.

On the phone: Android 10 (API 29) or newer, a screen lock (PIN, pattern or password), and USB debugging turned on for adb. Tealhand keeps its keys in the phone’s secure hardware, which needs a screen lock. On Android 10, add a fingerprint as well.

Build and install a debug APK

Run these from a terminal. The two export lines name your SDK and NDK folders; change them to where yours are.

git clone https://github.com/tealvpn/tealhand
cd tealhand
rustup toolchain install
cargo install --locked cargo-ndk@4.1.2
export ANDROID_HOME="$HOME/Android/Sdk"
export ANDROID_NDK_HOME="$ANDROID_HOME/ndk/30.0.16248370"
apps/mobile/tool/android_libs.sh
cd apps/mobile
flutter pub get --enforce-lockfile
flutter build apk --debug
adb install -r build/app/outputs/flutter-apk/app-debug.apk

What each step does:

Step	What it does
`rustup toolchain install`	Installs the pinned Rust and, from the same file, the three Android targets: `aarch64-linux-android`, `armv7-linux-androideabi` and `x86_64-linux-android`. If a target is missing, run `rustup target add aarch64-linux-android armv7-linux-androideabi x86_64-linux-android`
`tool/android_libs.sh`	Builds the Rust core (`tealhand-ffi`) with `cargo ndk` for `arm64-v8a`, `armeabi-v7a` and `x86_64`, and puts the libraries in `apps/mobile/android/app/src/main/jniLibs/`. They are never committed. Without them the app starts and says part of it is missing
`flutter build apk --debug`	Builds the app around those libraries
`adb install -r`	Installs it on the phone that `adb devices` lists. `-r` replaces an earlier install and keeps its data

The debug build is signed with Android’s debug key and logs more.

Build a release APK

apps/mobile/tool/android_libs.sh --release
cd apps/mobile
flutter build apk --release

A release APK is signed only from your environment. No key or password is ever stored in the repository:

Variable	Meaning
`TEALHAND_KEYSTORE`	Path to your keystore file, kept outside the repository
`TEALHAND_KEYSTORE_PASSWORD`	Its password
`TEALHAND_KEY_ALIAS`	The key’s alias
`TEALHAND_KEY_PASSWORD`	The key’s password

Without TEALHAND_KEYSTORE the release APK is left unsigned, and Android refuses to install an unsigned APK. Use the debug build for your own phone.

What the app asks on its first start

A screen lock check. Without one the app tells you to set one in Android settings first.
How your devices find each other: your own relay, iroh’s public relays, or this network only. If you have no relay yet, pick this network only; you can change it in Settings, then Network, at any time. How relays work is explained in Relays, and setting up your own is in Install Tealhand Relay.
How you want to use Tealhand: Chat (the ask box) or Classic (buttons and lists). You can switch any time.
Connect your device: scan the code a computer shows. See Connect your phone.

The app’s text for step 4 says “Install Tealhand on your computer, open it and choose “Connect a phone”“. The Tealhand app for computers has no installer yet (you can build it from source); on a computer without it, the connection code comes from tealhand-host connect.

Logs

adb logcat -s tealhand

shows what the Rust core and iroh log. Debug builds show more than release builds.

Check the build

To run the app’s own checks (the analyzer and the tests) instead of installing it, see Build from source.

Next: Install Tealhand Host on Windows or on Linux.