nosignal/omatether
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
omatether/README.md
28allday 52c21e2467 Add gum TUI (default mode) + Walker floating launcher 
Context-aware menu: Connect phone (USB wait + Trust walkthrough),
Switch internet → iPhone / back, live status header. install now
writes a TUI.float .desktop entry and restarts elephant.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-03 19:35:43 +01:00

2.8 KiB
Raw Blame History

omatether

iPhone USB tethering for Omarchy / Arch (systemd-networkd + iwd stack), with a gum TUI. Plug an iPhone in over USB and use its internet connection — the phone's Wi-Fi if it's on one, cellular otherwise. Works headless too.

TUI

Run omatether.sh with no arguments (or launch iPhone Tether from Walker — it opens as a floating window). The dashboard shows phone / tether / route state live and offers only the 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)

> Switch internet → iPhone
  Status (full check)
  Refresh
  Quit
  • Connect phone — waits for USB, walks you through unlock + Trust, brings the connection up (shown only when not yet connected)
  • Switch internet → iPhone — routes all traffic via the phone
  • Switch back → ethernet/wifi — back to normal (tether stays as fallback)

How it works

  • usbmuxd handles the iOS pairing/trust handshake (udev-activated, no service to enable)
  • the kernel's ipheth driver exposes the phone as a normal network interface
  • a systemd-networkd profile (10-iphone-tether.network) matches by Driver=ipheth and DHCPs it, at fallback priority (route metric 750) so it never hijacks ethernet (100) or Wi-Fi (600); "Switch → iPhone" rewrites the metric to 50 and reloads networkd

Install

./omatether.sh install   # packages + networkd profile + Walker launcher
./omatether.sh           # TUI: pick "Connect phone", unlock, tap Trust

Then on the phone: Settings → Personal Hotspot → Allow Others to Join: ON. After that it's zero-touch — plug in and the connection comes up by itself.

CLI

Everything is scriptable without the TUI:

Command What it does
install Install packages, networkd profile, Walker launcher
pair / unpair Manage the Trust pairing
status Device, interface, IP, route, live connectivity test
priority high Route all traffic via the phone even when ethernet is up
priority low Back to fallback-only (default)
uninstall Remove the networkd profile + launcher

Notes

  • iOS shares whatever uplink it has: on Wi-Fi it shares the Wi-Fi; otherwise cellular.
  • The tether interface usually appears as eth0; the profile matches by driver, not name.
  • RequiredForOnline=no — an unplugged phone never blocks boot.
  • DNS follows the Omarchy convention (UseDNS=no; global resolvers via systemd-resolved).
  • If the phone was plugged in before usbmuxd existed it can show as unresponsive — the tool restarts usbmuxd automatically to rescan.