https://github.com/zackb/tether
Linux + iPhone Continuity
https://github.com/zackb/tether
iphone linux wayland
Last synced: 11 days ago
JSON representation
Linux + iPhone Continuity
- Host: GitHub
- URL: https://github.com/zackb/tether
- Owner: zackb
- License: mit
- Created: 2026-04-12T04:31:45.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-06-27T05:11:35.000Z (12 days ago)
- Last Synced: 2026-06-27T05:14:26.428Z (12 days ago)
- Topics: iphone, linux, wayland
- Language: C++
- Homepage:
- Size: 3.92 MB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Tether
> Bridge your iPhone to the Linux Wayland desktop
**Tether** aims to support all of the [Apple Continuity](https://www.apple.com/macos/continuity/) features on Linux that are technically possible. If you've migrated away from macOS but still carry an iPhone, Tether provides the missing ecosystem integration.
[](LICENSE)
[](https://wayland.freedesktop.org/)
[](https://addons.mozilla.org/en-US/firefox/addon/tether-browser-extension/)
[](https://addons.thunderbird.net/en-US/thunderbird/addon/tether-mail-extension/)
[](https://apps.apple.com/us/app/tether-linux-companion/id6762097135)
[](https://apps.apple.com/us/app/tether-linux-companion/id6762097135)
## Features
| Feature | Status |
|---------|--------|
| **Clipboard Sync** | ✅ Stable |
| **File Transfer** | ✅ Stable |
| **iOS App** | ✅ Stable |
| **Browser Extension** | ✅ Stable |
| **Mail Extension** | ✅ Stable |
| **TOTP/OTP Vault** | 🗓️ Planning |
### Clipboard Sync
Seamlessly share your Wayland compositor (`wlr-data-control`) clipboard over the Tether network. Text copied on your Linux desktop appears instantly on your iPhone, and vice versa.
### File Transfer
Drag and drop files from Linux directly into the iPhone app, or receive files automatically deposited to your `$XDG_DOWNLOAD_DIR`.
### Device Pairing
Securely pair devices using **Mutually Authenticated TLS (mTLS)**, restricting TCP traffic securely using X.509 RSA certificates.
### OTP Handling
Streamline two-factor authentication across your devices:
- iOS Share Extension: Send OTP codes from your iPhone to your Linux clipboard.
- Thunderbird Addon: Automatically parse OTP codes from incoming email messages.
- Browser Extension: Autofill OTP codes into login forms from the iOS app or the mail extension.
### Browser & Mail Extensions
A unified WebExtension that works across Thunderbird/Betterbird and Firefox/Chromium browsers:
- **Thunderbird/Betterbird:** Detects OTP codes in incoming emails (verification codes, 2FA messages) and copies them to the clipboard or sends them to the Tether daemon for vault storage
- **Firefox/Chromium:** Autofills OTP codes into login forms by retrieving secrets from the Tether vault, with one-click verification for sites using TOTP-based 2FA
The extension communicates with `tetherd` via native messaging. This allows users to autofill OTP codes into websites when the email arrives.
## Architecture
Tether uses a multi-component architecture:
1. **`tetherd` (Linux Daemon)** — A background C++ process built on `epoll` and Wayland protocols via `hyprwayland-scanner`. Anchors the Linux clipboard and broadcasts events over UNIX Domain Sockets (`$XDG_RUNTIME_DIR/tether/tetherd.sock`). Network traffic securely traverses local TCP via OpenSSL.
2. **`tether` (CLI)** — A lightweight C++ CLI program to communicate with the daemon. This also allows the WebExtension to interface with the daemon via native messaging.
3. **`tether-gtk` (GTK App)** — A native GTK4 application for Linux that provides a graphical interface to manage devices, send files, trigger clipboard sync, and monitor connection status.
4. **iPhone App** — Native SwiftUI iOS 16+ app that discovers the daemon via Bonjour/mDNS, utilizing Apple's `Network.framework` for secure TLS negotiation.
5. **Browser/Mail Extension** — WebExtension that interfaces with the daemon via native messaging. Use with Thunderbird/Betterbird and Firefox or Chromium-based browsers.
## Requirements
### Linux
- **Wayland compositor** with `wlr-data-control` protocol (Hyprland, Sway, etc.)
- **Linux 5.15+** with glibc
- **Build tools:** CMake, Ninja, pkg-config
### Dependencies
- `wayland-client`
- `openssl`
- `pkg-config`
- `ninja`
- `gtk4` (for `tether-gtk`)
- `nlohmann-json`
- `glib2`
### iOS
- iOS 16+
- Get the app: [Tether - Linux Companion](https://apps.apple.com/us/app/tether-linux-companion/id6762097135)
### Browser Extension
- Firefox: [Tether Browser Extension](https://addons.mozilla.org/en-US/firefox/addon/tether-browser-extension/)
## Installation
### Arch Linux
```bash
yay -S tether
```
### Build from Source
```bash
# Clone the repository
git clone https://github.com/yourusername/tether.git
cd tether
# Build with CMake presets
make debug
# Run the daemon
make run-daemon
```
The daemon uses an advisory lock (`$XDG_RUNTIME_DIR/tether/tetherd.lock`) ensuring only one instance controls the Wayland connection at a time.
## Quick Start
1. **Build the project:**
```bash
make debug
```
2. **Start the daemon:** (optional, the GTK app will auto-launch it if not running)
```bash
make run-daemon
```
3. **Launch the GTK app** (optional, for GUI-based device management):
```bash
make run-gtk
```
4. **Pair your devices** (select the auto-discovered iPhone from the GTK app or CLI):
```bash
./build/debug/tether pair
```
5. **Start syncing** clipboard and transferring files
## Roadmap
- [x] Complete iOS app development
- [x] Add end-to-end encryption for file transfers
- [x] Release browser extension for Firefox
- [x] Release mail extension for Thunderbird
- [ ] Implement TOTP/OTP vault with Safari autofill
- [ ] Explore macOS support
## Contributing
Contributions are welcome! Please read our contributing guidelines before submitting PRs.
## License
Tether is licensed under the [MIT License](LICENSE).