The phone app talks to a running Tori over Tailscale, it is not a standalone app, and it never uses anything but that connection: no shared process, no iCloud sync, just a WebSocket to the Mac you paired it with.
Tailscale first
The phone reaches the Mac over Tailscale and nothing else. Tori has no relay or cloud service of its own, and its WebSocket is not encrypted, so it only listens where Tailscale does the encrypting. A local network address is not offered, not even on your own Wi-Fi.
Install Tailscale on the Mac and on the phone and sign both in to the same account. It has to be running on the phone whenever you use the app, at home or away.
Turning it on
Settings > Remote > Remote access. The Tailscale row says whether it is installed and connected, with a button to get it or open it when it is not. Then pick a Listen on address: your Tailscale address, or this Mac only, which is really “off” for anything but local testing. Tori never listens on more than one address at once, and a local network address saved by an older build is refused.
Remote access stays on after you quit Tori: the daemon keeps listening, so the phone works with the window closed. While a phone is connected or a session is working, the Mac is kept from idle sleeping so the connection holds; this costs battery on a laptop, which is why remote access defaults off.
Pairing a phone
Pair a device shows a QR code and a typed code as a fallback, both live for five minutes and the code works once. Scan it, or open the phone app and type the address and code by hand, along with a name for the phone. Five wrong tries burns the code early.
Pairing takes a confirm on both ends:
- On the phone, tap Pair with the Mac’s address. Scanning the code fills in the address and code but pairs nothing until you tap, so a code you scanned by mistake goes nowhere.
- On the Mac, click Allow. Settings > Remote asks Allow Pixel 8 from
100.64.0.2? with the phone’s name and Tailscale address. Deny is the
one already selected, so pressing
Enteron a request you did not expect turns it away. The phone waits up to a minute for the answer; Deny, no answer in time, or no Tori window open on the Mac refuses it, and the code stays live for another try. While one phone waits, another with the same code is told a pairing is already waiting.
If Tori on the Mac cannot read its list of paired devices, a phone that tries to connect is told the device store is unreadable and keeps its credential, so it connects again once the file is fixed.
Paired devices are listed in Settings > Remote, each with a Revoke button; revoking closes its connection immediately and it has to pair again to reconnect. Re-pairing the same phone replaces its old entry rather than adding a second one.
What a paired phone can do
A paired device reads sessions, transcripts, the project tree and budgets the same as sitting at the Mac; it can steer or interrupt a live chat and answer any session’s pending question, permission prompt, or approval as a real user, not just a bystander. It can start a chat in a folder or a new worktree, from an issue or a pull request review, in the foreground or the background, and attach files it uploads to the Mac. It can rename, close and resume a session, remove a worktree that has nothing uncommitted and no session running, and attach an existing local branch. It cannot delete a session or a space, or promote an attempt, which deletes the others. It can make, edit and reorder spaces, make and change Topics, fan out, fork a chat, and read and revert what a session changed. It can turn the autopilot on and off, switch a live chat’s model and mode, and mark finished work reviewed from the Inbox. It cannot pair another device; that stays Mac-side, in person.
Titlebar indicator
A phone icon in the title bar lights up when at least one paired device is connected, and its popover shows connected and offline state per device with a quick Revoke, without opening Settings.