zackb/tether

Bridge your iPhone to the Linux Wayland desktop

Tether aims to support all of the Apple 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.

Text copied on your Linux desktop appears instantly on your iPhone, and vice versa.

Drag and drop files from Linux directly into the iPhone app, or receive files automatically to your $XDG_DOWNLOAD_DIR (~/Downloads).

Read and reply to SMS and iMessage conversations, and see notifications from any app on the phone, on the Linux desktop.

There are two ways tether communicates with the iPhone:

• WiFi: for clipboard sync, file transfer, and OTP handling
• Bluetooth: for Messages, Notifications, and Calls

You can use either or both, depending on your needs.

Connections run over TLS 1.2 and both sides present a self-signed X.509 certificate.

Place, answer and end calls on the iPhone from the desktop, complete with caller ID and the phone's carrier and signal. Recent calls from the iPhone are listed with a button to call back, and the iPhone's favorites are starred at the top of Contacts. These need Phone Recents and Phone Favorites turned on under the iPhone's Bluetooth settings for this computer. The call audio stays on the iPhone. If you've used Linux long enough you know why (it sounds like "FalsePotty-o"). PulsAlsaWire is too hard to support across all deployment targets.

Stock PipeWire makes the computer a speaker for the phone, which takes call control away and moves the iPhone's music and sounds to the desktop. The recommended audio setting is in Keeping the phone's audio on the phone.

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.
• SMS / iMessage: Detects OTP codes in incoming messages and notifications and offers them to the browser extension for autofill.

A unified WebExtension that works in 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.

• Get the app: Tether - Linux Companion

• Firefox: Tether Browser Extension
• Google Chrome / Chromium: Build and install locally.

• Thunderbird: Tether Mail Extension

yay -S tether

One file, no install, for distros without a package and for immutable systems. Download tether-<version>-<arch>.AppImage from the releases page, then:

chmod +x tether-*.AppImage
./tether-*.AppImage                              # the GTK app
./tether-*.AppImage --bt-setup                   # the CLI, same binary
./tether-*.AppImage --install-extension-host     # if you use the browser or mail extension

The iPhone Bluetooth features need one-time system setup the AppImage cannot do for you. --bt-setup prints the commands for this machine.

Requires glibc 2.38 and libstdc++ from GCC 13 (Fedora 39+, Ubuntu 23.10+, Debian 13+, Arch).

Download tether-<version>-<arch>.flatpak from the releases page if you're into that, then:

flatpak install ./tether-*.flatpak
flatpak run com.tether.desktop                                          # the GTK app
flatpak run --command=tether com.tether.desktop --bt-setup              # the CLI
flatpak run --command=tether com.tether.desktop --install-extension-host

Clipboard sync will most likely not work as it is a privileged protocol (data-control). Use the AppImage instead if you want clipboard sync.

Enter the development shell and run the test suite:

nix develop
make test

Build or run Tether directly from the flake:

nix build
nix run
nix run .#tether -- --help
nix run .#tetherd

Bare nix run launches tether-gtk. The named app outputs are tether (CLI), tether-gtk (GUI), tether-tui (terminal UI), tetherd (daemon), and tether-dialog (dialog helper).

After adding Tether as a flake input, install its package directly:

environment.systemPackages = [
  inputs.tether.packages.${pkgs.system}.default
];

Alternatively, apply the overlay and install pkgs.tether:

nixpkgs.overlays = [ inputs.tether.overlays.default ];
environment.systemPackages = [ pkgs.tether ];

Import the module in your NixOS configuration:

imports = [ inputs.tether.nixosModules.default ];

programs.tether = {
  enable = true;

  wifi = {
    enable = true;
    openFirewall = true;
  };

  bluetooth = {
    enable = true;
    adapters = [ "hci0" ];
  };

  extensions = [
    "firefox"
    "chromium"
    "thunderbird"
  ];
};

Base enablement installs Tether and registers its native messaging hosts; it does not start a daemon. Firewall opening is opt-in. Bluetooth experimental mode and adapter class changes are also opt-in. If your system uses another adapter or multiple adapters, change bluetooth.adapters accordingly.

A headless Linux Docker deployment is available for amd64 and arm64. It runs tetherd and its session services as non-root, using the host's BlueZ/Avahi and persistent state/download mounts. Pair and send messages/files through the CLI; there is no web UI yet. Bluetooth messaging still needs the iPhone near the host.

See docs/CONTAINER.md for prerequisites, Compose setup, security considerations and the real-iPhone acceptance checklist. No registry image is published by this setup.

On Debian/Ubuntu:

sudo apt install build-essential cmake ninja-build pkg-config git \
    libwayland-dev libavahi-client-dev libssl-dev libsecret-1-dev \
    libglib2.0-dev libgtk-3-dev libgtk-layer-shell-dev libnotify-dev \
    libncurses-dev npm zip

On Fedora:

sudo dnf install gcc-c++ cmake ninja-build pkgconf-pkg-config git \
    wayland-devel avahi-devel openssl-devel libsecret-devel \
    glib2-devel gtk3-devel gtk-layer-shell-devel libnotify-devel \
    ncurses-devel npm zip

# Clone the repository
git clone https://github.com/zackb/tether.git
cd tether

# Build and test
make release

# Install the daemon, cli, GTK app, and terminal UI
make install

1. On Linux, launch the GTK app (tether-gtk) or run the CLI to pair your iPhone.

2. WiFi pair via the GUI or CLI:

   Open the iOS app, it will auto-discover the daemon. You will be prompted on both the iPhone and Linux to accept the pairing request. Once accepted on both ends, the devices are paired.

   or

   tether pending               # the requests waiting, with their fingerprints
   tether accept <fingerprint>

3. Bluetooth (for Messages and Notifications):

   First, one-time system setup. This prints only the steps your machine still needs, with the exact commands:

   tether bt setup

   Tether never applies these itself: they change how the machine behaves over Bluetooth outside of Tether, so running them is your call. The same steps appear in the GTK app's Devices page, with a "Copy commands" button.

   If you have more than one Bluetooth controller, pick the one to use. Default is the first powered one.

   tether bt adapter hci1  # or the controller's address, or "auto"

   Then pair. In the GTK app, pick your iPhone under BLUETOOTH on the Devices page and press "Pair over Bluetooth". Confirm the code on both the iPhone and Linux.

   or

   tether bt devices         # find the iPhone's address
   tether bt pair <address>
   tether bt connection      # what is up, and what is not

4. On the iPhone, under Settings > Bluetooth > (i) for this computer, enable "Show Message Notifications" and "Sync Contacts". Both are needed. They can take a few minutes to appear; "Show iPhone Permissions" in the GTK app re-advertises so they show up again.

The daemon does not need a Wayland session. Everything but clipboard sync works over SSH, pairing included:

systemctl --user enable --now tetherd.service  # portable build? tether service first
tether pending                                 # the pairing requests waiting, with fingerprints
tether accept 9a4f21...
tether status                                  # devices, links, and recent transfers

See docs/HEADLESS.md, or the container guide for Docker deployment.

tether-tui is a front end for tetherd in the terminal, with vim keys: j/k to move, h/l between panes, 1-6 or gt/gT for tabs, / to filter, i to write in a conversation, o for a new message, dd to dismiss or forget, :q to quit. Press ? for the full list.

The tether-web project provides a lightweight browser interface for running Tether without a desktop session. It runs tetherd in headless mode and lets you pair and manage a Bluetooth-connected iPhone from a browser.

This setup is useful for homelabs and headless Linux servers where a full GTK desktop is not available. The iPhone must remain within Bluetooth range of the Linux host. The current interface focuses on guided pairing and connection status.

1. tetherd: A background process running on Linux manages Bluetooth, TCP+TLS with pinned device certificates, and Wayland integration.

2. tether: A CLI to communicate with the daemon. This also allows the WebExtension to interface with the daemon via native messaging.

3. tether-gtk: An application for Linux that provides a graphical interface to manage devices, send files, trigger clipboard sync, read and reply to iPhone messages, see mirrored notifications, and monitor connection status. tether-tui does the same in a terminal.

4. iPhone App: Discovers the daemon via Bonjour/mDNS, utilizing Apple's Network.framework for secure TLS negotiation. Not required for SMS/iMessage and notification mirroring, which use Bluetooth.

5. Browser/Mail Extension: WebExtension that interfaces with the daemon via native messaging. Use with Thunderbird/Betterbird and Firefox or Chromium-based browsers.

• Wayland compositor with wlr-data-control protocol (Hyprland, Sway, Fenriz etc.)
• Build tools: cmake, ninja, pkg-config
• x86_64 or aarch64 (Asahi, Raspberry Pi OS Trixie+). 32-bit ARM is not supported.

• wayland-client
• openssl
• pkg-config
• ninja
• gtk3 (for tether-gtk)
• ncurses (for tether-tui; turn off with -DTETHER_BUILD_TUI=OFF)
• nlohmann-json
• glib2
• avahi
• bluez, bluez-utils, and bluez-obex (for messages and notifications)

• BlueZ 5.86+ must be running with experimental bearer API. tether bt setup prints the command that enables it on this machine. Do this before pairing.
• A controller with BR/EDR, LE, and advertising support.
• Notification mirroring does not work on iOS 18 and earlier.

WiFi features need two inbound ports on the Linux machine:

Probably firewall. Most firewalls allow mDNS through, so discovery works, but then the iPhone can't get through on it's port (5134/tcp). Open the ports in your firewall.

sudo ufw allow Tether                                  # ufw
sudo firewall-cmd --permanent --add-service=tether     # firewalld
sudo firewall-cmd --reload

AppImage or the Flatpak, open the ports directly:

sudo ufw allow 5134/tcp && sudo ufw allow 5353/udp
sudo firewall-cmd --permanent --add-port=5134/tcp --add-port=5353/udp
sudo firewall-cmd --reload

On NixOS, set programs.tether.wifi.openFirewall = true; instead (see the NixOS module above.

avahi-daemon is not running, so nothing can discover this machine:

sudo systemctl enable --now avahi-daemon

Messages and notifications need one-time system setup. See docs/BLUETOOTH.md, or run:

tether bt setup

Tether should work for everyone. The desktop app is built to work with the Orca screen reader, keyboard-only use, and the system's text scaling. The iOS app is built to work with VoiceOver and Reduce Motion.

Keyboard shortcuts in the desktop app:

If something can't be reached with the keyboard, is read wrongly by a screen reader, or is hard to see, please open an issue. Those reports are bugs.

The manual checks run before a release are in docs/ACCESSIBILITY.md.

Report security findings privately through GitHub Security Advisories, not a public issue. See SECURITY.md.

• ancs4linux for pioneering the ANCS notifications technique.
• iphonebridge for the research on MAP Messages.
• BlueFerry for the gold mine.
• @orychalk for many many feature ideas, bug reports, beta testing.

Contributions are welcome!

Tether is licensed under the MIT License.