omatether

Use your iPhone's internet on Omarchy / Arch over a USB cable.

Plug the phone in, tap Trust once, and its connection — the phone's Wi-Fi if it's on one, cellular otherwise — becomes a network interface on your machine. After setup it's zero-touch: plug in and the connection comes up by itself, sitting quietly as a fallback until you need it (or flip a switch to route everything through the phone). Works headless over SSH too.

Built for the Omarchy network stack (systemd-networkd + iwd). No GUI dependencies beyond gum for the TUI, which the installer pulls in.

Install

git clone https://github.com/28allday/omatether.git
cd omatether
./omatether.sh install

The installer:

• installs usbmuxd + libimobiledevice (pacman; usbmuxd is udev-activated, nothing to enable)
• writes a systemd-networkd profile for the phone's interface
• adds an iPhone Tether entry to Walker that opens the TUI in a small centered floating window (Hyprland windowrule, marker-delimited in ~/.config/hypr/windows.conf, cleanly removed on uninstall)

Then plug the phone in and run ./omatether.sh — pick Connect phone, unlock the phone, tap Trust. On the phone make sure Settings → Personal Hotspot → Allow Others to Join is on.

The TUI

Run with no arguments (or launch iPhone Tether from Walker). The dashboard shows phone / tether / route state live and only offers actions that make sense right now:

        ╭───────────────────────╮
        │       OMATETHER       │
        │  iPhone USB internet  │
        ╰───────────────────────╯
           Cowboy Bebop — paired
    󰛳  Tether up: eth0  172.20.10.11/28
 󰈀  Internet via enp6s0 (phone is fallback)

          What do you want to do?
        > Switch internet → iPhone
          Status (full check)
          Refresh
          Quit

• Connect phone — waits for USB, walks you through unlock + Trust, brings the connection up and live-tests it
• Switch internet → iPhone — routes all traffic via the phone, even with ethernet plugged in
• Switch back → ethernet/wifi — normal routing; the tether stays connected as a fallback

CLI

Everything is scriptable without the TUI:

Command	What it does
install	Packages, networkd profile, Walker launcher + windowrule
pair / unpair	Manage the Trust pairing
status	Device, pairing, interface, IP, route, live connectivity test
priority high	Route all traffic via the phone (survives reinstall)
priority low	Back to fallback-only (default)
uninstall	Remove the profile, launcher and windowrule

How it works

• the kernel's ipheth driver exposes the phone as a normal network interface as soon as iOS trusts the machine (usbmuxd handles that handshake)
• a networkd profile matches the interface by driver (Driver=ipheth, not by name — it usually appears as eth0) and DHCPs it at route metric 750, so it never hijacks ethernet (100) or Wi-Fi (600); priority high rewrites the metric to 50
• RequiredForOnline=no — an unplugged phone never blocks boot
• DNS needs no wiring: Omarchy resolves via global resolvers in systemd-resolved

Troubleshooting

• Phone shows "not responding" — usbmuxd lost it (typically when the phone was plugged in before usbmuxd was installed). The tool restarts usbmuxd automatically during Connect; manually: sudo systemctl restart usbmuxd.
• Interface up but no IP — Personal Hotspot's Allow Others to Join is off on the phone.
• Pairing fails with a passcode error — the phone is locked; unlock it and retry.

License

MIT