tether

Universal clipboard. Shared Rust engine + native clients on every platform.

An HTTP+SSE broadcast bus that also bootstraps WebRTC DataChannels between participants. Once paired, clipboard text flows direct peer-to-peer with DTLS encryption — the server never sees the payload.

The wire protocol (codec + SSE + RTC + reconnect) lives once, in a Rust crate core/ (tethercore), exposed via UniFFI. Every native client — iOS, macOS, the desktop agent, Android — drives that same engine; only the UI and binding language differ. The browser client and Go server interoperate over the same wire format.

                       ┌──────────────── tethercore (Rust) ────────────────┐
                       │  Message codec · Transport trait · dedup           │
                       │  ├─ SSE   (reqwest)      reliable relay floor      │
                       │  ├─ RTC   (webrtc-rs)    direct P2P data channel   │
                       │  └─ LAN   (mDNS + TCP)   serverless same-network   │
                       └───────────────────────────────────────────────────┘
   iOS (Swift) ─ macOS (Swift) ─ agent (Rust, Linux/Win/Mac) ─ Android (Kotlin)
                       └──── all via UniFFI bindings ────┘
   browser (JS, native WebRTC) ── interoperates over the wire ──┘

The roadmap is what makes it interesting: symmetric presence chirps for self-healing mesh discovery, Sign in with Apple for cross-device identity, mDNS for zero-config same-LAN discovery, file drop, system tray UX.

phone (web UI)              tether-server                tether-client
─────────────               ─────────────                ──────────────
type/paste                  HTTP+SSE relay               Linux/Mac/Win
  │                              │                              │
  └─── POST /api/send ──────────▶│                              │
                                 ├──── event: clipboard ───────▶│
                                 │                              ▼
                                 │                          stdout / OS
                                 │                          clipboard
                                 │◀──── POST /api/send ─────────┘
                                 ▼
                          web UI shows it

Quick start

go run ./server
# in another terminal
go run ./client -server http://localhost:8765

# send a one-shot message from CLI:
go run ./client -server http://localhost:8765 -send "hello"

Then open http://localhost:8765/ on your phone (same network) and try the buttons.

Pieces

Server & web (Go / JS)

• server/ — single Go binary. Embedded HTML page. Exposes GET / (phone UI), POST /api/send, GET /api/stream (SSE), GET /healthz, /metrics.
• server/web/index.html — browser client (paste, send, live feed; native WebRTC).
• client/ — Go CLI client (atotto/clipboard), -send for one-shot.

Shared engine & native clients (Rust / Swift / Kotlin)

• core/ — tethercore, the Rust sync engine (SSE + RTC behind a Transport trait, dedup, reconnect). Exposed via UniFFI; build-apple.sh / build-android.sh emit the xcframework / .aar artifacts. examples/ prove it end-to-end.
• ios/TetherApp — SwiftUI iOS client on tethercore.
• ios/MacTetherApp — SwiftUI macOS client on tethercore (window + menu bar).
• ios/TetherKit — thin SPM package, now just RoomIdentity (platform room-id).
• agent/ — headless Rust daemon (tethercore + arboard) for macOS/Linux/Windows.
• android/ — Jetpack Compose client on tethercore (Kotlin/UniFFI).

Roadmap

Phase	What	Why
✅ v0.1	HTTP+SSE relay, single broadcast bus	Prove the shape end-to-end
✅ v0.2	/metrics endpoint, server-side observability	Latency/throughput visibility
✅ v0.3	WebRTC DataChannel (Pion ↔ browser RTCPeerConnection), peer chirps offer until paired	True P2P with mandatory DTLS encryption
v0.4 (next)	Symmetric presence chirps — every participant (peer, browser, future Mac) broadcasts {type:"presence", from, role, capabilities} every 10-15s. Lets peers/browsers self-discover, auto-upgrade SSE→RTC, detect dead participants via heartbeat timeout. Pairs N-way (mesh, not star).	Self-healing discovery without the "happen to be open at the right moment" timing trap of v0.3's single-direction chirp
v0.5	mDNS service advertisement + QR pairing	Zero-config same-LAN discovery
v0.6	Sign in with Apple OAuth → stable sub ties multiple devices to one trust circle	Identity without account/password
v0.7	OS clipboard hook on client (read + write) — phone copy → laptop paste appears automatically	The actual Universal-Clipboard UX (current v0.3 has write on receive; missing the read on local change)
v0.8	File drop (large blob over WebRTC), encrypted at-rest history	Snapdrop-like UX bundled in
v0.9	Mouse/keyboard handoff (Synergy-style) using the same authenticated peer set + DataChannel	Universal Control for the rest of us
v1.0	macOS / Windows tray UX, push notifications when off-network, packaged installers	Product

Note on v0.4 presence chirps

The current peer's "chirp every 5s while unpaired" only solves one-direction late-joining. The full pattern is symmetric:

Every participant emits:
    {type: "presence", from: <peerID>, role: "peer" | "browser",
     capabilities: ["clipboard", "filedrop", "cursor"], ts: …}
every 10-15s on the bus.

Maintains  Map<peerID, lastSeen> table on each side.
- New peer presence seen by browser → wait for offer.
- New browser presence seen by peer → post targeted offer.
- After RTC opens → drop chirp rate to 60s "alive" heartbeats.
- lastSeen > 30s → mark dead, restart discovery.

Once that's in, the system becomes properly mesh-shaped — N devices can all auto-pair, see each other in the UI, drop a file to any one, etc.

Why E2E by default

WebRTC data channels mandate DTLS. Once we move from SSE relay (v0.1) to P2P data channels (v0.3+), the server only ever sees encrypted bytes (and only during signaling — not for the data itself). That's free end-to-end encryption, modeled on Apple's Continuity but using standardized protocols.

Why Sign in with Apple

~80% of Windows users also own an iPhone. SiwA gives us a free, privacy-respecting identity provider that returns a stable per-app subject ID. Devices that authenticate to the same sub are in the same trust circle automatically. No passwords, no per-app account.

What this isn't (yet)

• Not a Snapdrop clone — no file drop (v0.8 roadmap)
• Not KDE Connect — no system-wide integration on the laptop side beyond clipboard (v0.7+)
• Not Pushbullet — server never sees data, no persistence
• Not Universal Control — but the mouse/keyboard handoff is on the roadmap (v0.9)

The foundation is right: bus → signaling → WebRTC → mesh → identity.

License

MIT