tether

Reach a machine over its maintenance tunnel.

Current build: v1.0.0 (964afe9b, 2026-09-22)

Each archive contains tether and tether-tui.

tar -xzf tether-*.tar.gz
sudo mv tether tether-tui /usr/local/bin/
tether login
tether devices

Already installed? tether --version tells you what you have, and tether update (with no board) replaces it and tether-tui in place.

Opening a tunnel (tether tunnel, shell, adb or logs) also needs frpc on your PATH — the client half of the reverse proxy tether uses to reach a board behind NAT. It is not in this archive; install it separately before you tunnel.

agent

Goes on the vending machine itself.

The two differ only in signature. Android refuses an update signed by a different key, so an existing machine needs the build matching what it already runs — otherwise pm install -r fails with INSTALL_FAILED_UPDATE_INCOMPATIBLE. These boards are API 25, which predates signing-key rotation, so there is no lineage to fall back on. Check with tether apps <machine>, or just try the new key first: a refusal costs nothing and tells you which one you need.

Installing by hand, without adb? On the board, first turn on Settings → Security → Unknown sources, or Android refuses the file as coming from an unknown source. On these boards it is a single global toggle rather than a per-app permission. Installing over adb with the command below does not need it.

adb install -r tether-agent-1.2.85.apk

Then, on the machine: tap Tether setup in the app drawer once, enter the api key, and read the serial off the screen. The icon removes itself after that first tap — from then on the agent starts itself on boot and its notification is the way back into the screen.

tether devices                 # it appears as unbound
tether bind <serial> --machine <id> --label "..."
# it claims its identity on the next check-in, within a minute

The one-shot icon exists because Android keeps a freshly installed app dormant until something launches it — no broadcasts, not even boot. Before 1.1.9 a new machine needed am startservice over adb. It no longer does, and the kiosk stays clean because the icon is gone after its single use.

What changed in each build, newest first: release notes.

Checksums for everything: SHA256SUMS

macOS may quarantine a downloaded binary. If it refuses to run:
xattr -d com.apple.quarantine /usr/local/bin/tether

You need an account — ask an admin. There is no token to paste: tether login is the only way in, so the audit trail names a person rather than a shared secret.

New to this? The documentation covers installing the CLI, getting a board into the fleet, and opening a tunnel.