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 and Notifications

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.

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

• Thunderbird: Tether Mail Extension

yay -S tether

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

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

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

Download tether-<version>.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), 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" ];
  };
};

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.

On Debian/Ubuntu:

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

On Fedora:

sudo dnf install gcc-c++ cmake ninja-build pkgconf-pkg-config git \
    wayland-devel avahi-devel openssl-devel \
    glib2-devel gtk3-devel gtk-layer-shell-devel libnotify-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, and GTK app
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 --accept <fingerprint>   # fingerprint is printed by the daemon log

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.

   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.

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.

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

• wayland-client
• openssl
• pkg-config
• ninja
• gtk3 (for tether-gtk)
• 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 systemd drop-in command that enables it. Do this before pairing.
• A controller with BR/EDR, LE, and advertising support.
• Notification mirroring does not work on iOS 18 and earlier.

• Complete iOS app development
• Add end-to-end encryption for file transfers
• Release browser extension for Firefox
• Release mail extension for Thunderbird
• Read and reply to iPhone messages over Bluetooth
• Bluetooth for messages and notifications
• Implement TOTP/OTP vault with Safari autofill
• Explore macOS support

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.