TetherTTY

TetherTTY

A lightweight iPhone SSH companion for reconnecting to your tmux and herdr sessions.

No backend. No account. Direct SSH from your phone to your own machine.

View on GitHub ↗ App Store

TestFlight beta planned · build from source today

WHAT IT DOES

Features

Real SSH, no middleman

Authenticated SSH over SwiftNIO SSH. No relay server, no mock layer — a direct connection from your phone to your machine.

Session discovery

TetherTTY runs real CLI commands on the host and lists your live tmux and herdr sessions. Attach with one tap.

Full terminal emulation

VT100/xterm via SwiftTerm, rendered natively in SwiftUI, with a fixed key row for Esc, Ctrl, Tab, and arrows.

Seamless reattach

Lock your phone mid-build. Come back and you are still in the same session — no re-selection, no re-entering credentials.

Face ID vault

A biometric gate protects your host list. Passwords live in the iOS Keychain, never in plain text.

Host-key trust

OpenSSH-style trust-on-first-use. SHA256 fingerprints pinned locally and verified on every connection — fail-closed.

HOW IT WORKS

How it works

  1. Unlock

    Face ID or your device passcode opens the vault. Your hosts and credentials never leave the phone.

  2. Choose a tether

    Saved machines, one tap to connect. Alias, address, and credential status at a glance.

  3. Trust the host key

    On first contact you review the SHA256 fingerprint yourself. If it ever changes, the connection is refused.

  4. Discover sessions

    TetherTTY asks the host what is running and lists your tmux and herdr sessions — plus a plain shell fallback.

  5. Get back to work

    A real terminal, with the keys that matter. Your shell, your colors, unchanged.

TetherTTY

A quiet tether back to your running terminal sessions.

Unlock Vault

THE LOOM

Saved hosts

Password stored

workstation

dev@10.0.0.12:22

Password stored

build-box

ci@10.0.0.31:2222

No password

homelab

ops@homelab.lan:22

Trust this host?

ops@build-box

SHA256:8kQ2vN4rT7xLmB9pWfC3sZeH6yD1jAoU5nRgK0iXtVc

Cancel Trust

SESSION PICKER

tmux
build notes api-server
herdr
docs — tab code · 2/2 agent-review

Terminal Open

Close

ops@build-box

running tests...

3 passed · 0 failed

done in 1.2s

PERSISTENT SESSIONS

Lock your phone. Come back. Still there.

iOS suspends apps in the background, which closes the SSH socket — a permanently open connection is not possible on iPhone, and TetherTTY does not pretend otherwise.

It does not need one. Your session lives on the server: tmux and herdr keep running whether or not a client is attached. When you return, TetherTTY opens a fresh connection and re-runs the same attach command, dropping you exactly where you left off. That turns out to be more robust than a nominally "kept-open" connection — it also survives network changes and idle timeouts.

  1. Attached

    Your SSH connection to the session is live on the phone.

  2. Phone locked, session runs on

    iOS suspends the app and the socket closes; on the server the session keeps running.

  3. Reattached

    TetherTTY opens a fresh connection and re-runs the same attach command, dropping you exactly where you left off.

  • ~2s grace period
  • silent reconnect
  • exponential backoff retry
  • TCP keepalive

TRUST

Security & privacy

What TetherTTY does

  • No backend, no account, no telemetry. Direct SSH to your own machine.
  • Connections, host-key trust, and app state stored on-device only.
  • SSH passwords encrypted by the iOS Keychain.
  • Host keys pinned with SHA256 and verified fail-closed — unknown host, changed key, or an unreadable trust store all refuse the connection.
  • Remote output treated as untrusted: no OSC 52 clipboard writes, links only over https:// after an explicit tap, startup commands quoted and control-character-rejected, remote output bounded.

What it does not do

  • TOFU first contact. The very first fingerprint for a host is trusted on sight. Verify it out-of-band if it matters.
  • A compromised server controls its own output. TetherTTY limits the local damage; the output itself stays untrusted.
  • The Face ID gate is an entry gate. It is not re-challenged when returning from the background — a deliberate trade-off for seamless reattach (SEC-04).

Full audit and policy: security-audit.md ↗ · SECURITY.md ↗

OPEN SOURCE

Help build it

  • 0 stars
  • 2 open issues & PRs
  • 0 good first issues
  • 2 contributors

as of last deploy

Swift & SwiftUI

The app is MVVM SwiftUI with SwiftNIO SSH and SwiftTerm. iOS 18+, Xcode, no manual dependency setup — Swift Package Manager resolves everything on first build.

Testing & review

Every PR needs green CI. Session parsers, host-key trust, and app-flow tests are the highest-value seams.

Try it and report

Build it, point it at your own machine, and tell us what broke. Bug reports are contributions.

  • Apache-2.0
  • Conventional Commits
  • fork → topic branch → PR
  • CI must be green
  • security issues → private disclosure
Good first issues ↗ Read CONTRIBUTING.md ↗ Report a bug ↗