Pair the Zara phone app to this zara-server
Goal
The Zarathushtra Android app (ai.zara.app) authenticated to this host's
zara-server over CURVE, with the turn path verified end to end.
Input
An adb-reachable phone, the desktop LAN IP of the server (default port 6060),
and the security state dir (default ~/.local/state/zarathushtra/security).
Output
A connected/authenticated phone session, or the precise blocked step
(locked screen, foreign focused app, stale endpoint, enrollment rejection).
Fast path (preferred)
Run the maintained tool; it is guarded and idempotent:
zara-adb-pair # guarded: aborts if another app has focus
zara-adb-pair --takeover # bring Zara to the foreground and pair
zara-adb-pair --check # report state only, inject nothing
It reads the client key from the app UI, enrolls it server-side, pins the
server key, fills the endpoint, taps Connect, and verifies AUTHENTICATED.
Manual fallback (no script)
- Server side (while
zara-server runs with
--remote-endpoint tcp://0.0.0.0:6060 --security-dir <DIR>):
- public key:
zara-server --security-dir <DIR> --security-show-public-key
- enroll phone:
zara-server --security-dir <DIR> --security-enroll-key <Z85> --security-device-id <ID>
- Phone side (Settings → Connection):
- read CLIENT PUBLIC KEY (40-char Z85); enroll it server-side
- paste server key into Server CURVE public key → Pin server key
- SERVER section:
tcp://<LAN-IP>:6060 → Connect
- Verify: app footer shows
REMOTE • AUTHENTICATED • SYMBOLIC; server shows
ESTAB <ip>:6060 in ss -tn; submit a turn and watch
journalctl --user -u zara-server for [TurnCoordinator] started turn.
Hard rules
- Never inject input while another app owns
mCurrentFocus. Check
adb shell dumpsys window | grep mCurrentFocus before every tap/type;
a stray keystroke lands in whatever the user is doing (this has really
happened: an Amazon search got typed into).
- A locked phone shows
Bouncer focus. Stop and ask the user to unlock;
never attempt PIN entry.
adb shell input text runs through the device shell: wrap the payload in
embedded single quotes, e.g. send the single argv token
input text 'KEY' — Z85 keys contain $ & ( ) { } # ? %.
- The pairing port and the connect port of wireless debugging are distinct;
prefer an already-established TLS adb transport (
adb devices -l, state
exactly device).
- uiautomator dumps can return empty or the wrong window in split-screen;
retry, and tap the Zara half first to steal focus back.
- "enrollment ready" on the phone only means local identity + server pin;
server-side enrollment and a live connection are separate facts.
- Fail closed on server key changes: re-pinning requires the explicit
Change trusted server key flow.
Troubleshooting
protocol_error bubbles after a turn reaches the server: the desktop
build is older than the app. Rebuild/switch home-manager from the current
zara pin, then reconnect.
- Auto-reconnect: with Chat Backend
Auto, the app reconnects by itself
after a server restart once the endpoint is saved.
- Server binds
0.0.0.0:6060; use the host's LAN address
(ip route get 1.1.1.1 → src), not localhost, on the phone.
1---2name: zara-phone-pair3description: zara, phone, pairing, adb, wireless-debugging, curve, enrollment, android4compatibility: Requires android-tools (adb), the zara-adb-pair script (zara.workflows), and a running zara-server with a remote listener.5metadata:6 source: https://skillmd.com/skills/lost-rob0t/zara-phone-pair7---89# Pair the Zara phone app to this zara-server1011## Goal1213The Zarathushtra Android app (`ai.zara.app`) authenticated to this host's14zara-server over CURVE, with the turn path verified end to end.1516## Input1718An adb-reachable phone, the desktop LAN IP of the server (default port 6060),19and the security state dir (default `~/.local/state/zarathushtra/security`).2021## Output2223A connected/authenticated phone session, or the precise blocked step24(locked screen, foreign focused app, stale endpoint, enrollment rejection).2526## Fast path (preferred)2728Run the maintained tool; it is guarded and idempotent:2930```sh31zara-adb-pair # guarded: aborts if another app has focus32zara-adb-pair --takeover # bring Zara to the foreground and pair33zara-adb-pair --check # report state only, inject nothing34```3536It reads the client key from the app UI, enrolls it server-side, pins the37server key, fills the endpoint, taps Connect, and verifies AUTHENTICATED.3839## Manual fallback (no script)40411. Server side (while `zara-server` runs with42 `--remote-endpoint tcp://0.0.0.0:6060 --security-dir <DIR>`):43 - public key: `zara-server --security-dir <DIR> --security-show-public-key`44 - enroll phone: `zara-server --security-dir <DIR> --security-enroll-key <Z85> --security-device-id <ID>`452. Phone side (Settings → Connection):46 - read CLIENT PUBLIC KEY (40-char Z85); enroll it server-side47 - paste server key into *Server CURVE public key* → *Pin server key*48 - *SERVER* section: `tcp://<LAN-IP>:6060` → *Connect*493. Verify: app footer shows `REMOTE • AUTHENTICATED • SYMBOLIC`; server shows50 `ESTAB <ip>:6060` in `ss -tn`; submit a turn and watch51 `journalctl --user -u zara-server` for `[TurnCoordinator] started turn`.5253## Hard rules5455- Never inject input while another app owns `mCurrentFocus`. Check56 `adb shell dumpsys window | grep mCurrentFocus` before every tap/type;57 a stray keystroke lands in whatever the user is doing (this has really58 happened: an Amazon search got typed into).59- A locked phone shows `Bouncer` focus. Stop and ask the user to unlock;60 never attempt PIN entry.61- `adb shell input text` runs through the device shell: wrap the payload in62 embedded single quotes, e.g. send the single argv token63 `input text 'KEY'` — Z85 keys contain `$ & ( ) { } # ? %`.64- The pairing port and the connect port of wireless debugging are distinct;65 prefer an already-established TLS adb transport (`adb devices -l`, state66 exactly `device`).67- uiautomator dumps can return empty or the wrong window in split-screen;68 retry, and tap the Zara half first to steal focus back.69- "enrollment ready" on the phone only means local identity + server pin;70 server-side enrollment and a live connection are separate facts.71- Fail closed on server key changes: re-pinning requires the explicit72 *Change trusted server key* flow.7374## Troubleshooting7576- `protocol_error` bubbles after a turn reaches the server: the desktop77 build is older than the app. Rebuild/switch home-manager from the current78 zara pin, then reconnect.79- Auto-reconnect: with Chat Backend `Auto`, the app reconnects by itself80 after a server restart once the endpoint is saved.81- Server binds `0.0.0.0:6060`; use the host's LAN address82 (`ip route get 1.1.1.1` → `src`), not localhost, on the phone.