# 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](https://github.com/charmbracelet/gum) for the TUI,
which the installer pulls in.

## Install

```bash
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](LICENSE)