TogetherYour Mac and your iPhone
On this page
What happens where
| You want to | On the phone | On the Mac |
|---|---|---|
| Chat with a model | Ask in RoachClaw, by typing or by voice | The model runs and answers |
| Check on things | Home shows the Mac's status, quick actions and the Org at a glance | The runtime reports its state |
| Approve an Org decision | Decide behind Face ID, Touch ID or your passcode | The hire, board decision or budget override waits for you |
| Install from RoachNet Apps | Send the install | The Mac downloads, checks and installs it |
| See what's in the Vault | A summary, cached on the phone | The files stay in ~/RoachNet/storage/Vault |
| Use a theme | The companion follows the Mac's theme | You pick it in Settings › Appearance |
| Get a GPS fix for Maps | Send the phone's position over Bluetooth | Maps uses it |
Companion 0.3.1 works with RoachNet 1.0.6 or later on the Mac. Themes, theme packs and the Org on the phone need RoachNet 1.1.
Set it up once
Install the iOS companion with SideStore or AltStore.
Give the phone a way to reach the Mac: your tailnet, or an HTTPS relay you run yourself.
Turn on RoachTail on the Mac, then pair from the phone with the join code. Pair with your Mac has the steps.
How the phone reaches your Mac
The companion bridge listens on the Mac's loopback address only, 127.0.0.1:38111, so the phone needs a secure path that you control:
- Your tailnet. The companion sends its token to Tailscale addresses and
*.ts.netnames. - A relay you run, over HTTPS. Set it with
ROACHTAIL_RELAY_HOST.
The companion won't send its token over plain http:// to a .local name or a Wi-Fi address. Whichever path you use, the phone's token opens only the companion's routes on the bridge, never the rest of the local API.
When the Mac is out of reach
- The phone keeps showing the Mac's last known state and the Vault summary it cached.
- Installs you send wait in a queue and go through when the Mac is back.
- Chat needs the Mac, because that's where the models run.
GPS sharing works differently: it goes over an encrypted Bluetooth link, only while the app is open and only after you press Start on the Runtime tab.
Remove a phone
On the Mac, open Linked devices and remove the phone. Its token stops working, and your other devices stay paired. A device token that goes unused for 90 days stops working on its own (ROACHTAIL_PEER_IDLE_DAYS; 0 turns that off).
On the phone, forgetting the Mac asks for Face ID, Touch ID or your passcode first.
Related
- Install the iOS companion
- RoachTail explains pairing and device tokens.
- Companion bridge reference lists what the phone can call.