All pages

Docs · Background features

Remote control (pair + tunnel)

Availability: macOS, paired from the iOS app. The cloud workspace is reachable without a Mac — see Platforms.

TRMNLY can expose its MCP server beyond the Mac so a Claude Code session — or any MCP-compatible client — running on another machine can drive the Mac you have TRMNLY open on. The mechanism is a paired device, a transport (a Cloudflare tunnel by default; a direct LAN or Tailscale path if you turn one on), and a small heartbeat to trmnly.dev so clients can resolve the current address and learn who is allowed in.

This is the remote counterpart to the local MCP bridge: same tools, same approval gates, different transport. Ready-made clients include the web remote at trmnly.dev/remote and the TRMNLY iOS app — both below.

When to reach for this

  • You're at a coffee shop with a laptop and want a Claude Code session on it to drive a build that's running on the iMac at home.
  • You want to ask a long-running, multi-turn refactor (a Claude Agent SDK script, a CI job) to use your dev machine's environment without copying it.
  • You're away from the desk and want to answer the agent's approvals, watch a build finish, or type into a pane from your phone.
  • You're handing a teammate temporary, limited remote control of your TRMNLY for a pair-debug session — send them an invite.

For purely local use — Claude Code in another terminal on the same Mac — the MCP server bridge is enough; you don't need to enable Remote control.

Architecture

┌─ Mac you're using ──────────────────────┐    ┌─ trmnly.dev ──────────────┐
│                                         │    │                           │
│  TRMNLY                                 │    │ /api/v1/pair/…            │
│  ├ AgentMCPSSEServer (loopback :PORT)   │    │ /api/v1/devices/me/tunnel │
│  │   /mcp  /sse  /attach                │◀──▶│   (heartbeat → roster)    │
│  ├ LAN listener (TLS, optional)         │    │ /api/v1/devices/[id]/…    │
│  ├ RemoteControlService                 │    │ /api/v1/push/…            │
│  ├ RemotePairingClient (3-leg pair)     │    └────────▲──────────────────┘
│  └ RemoteTunnelManager (cloudflared)    │             │
└─────────────────┬───────────────────────┘             │ token-auth
                  │ quick tunnel / named tunnel /        │ resolve URL
                  │ LAN / Tailscale                      │
                  ▼                                      │
              ┌────────────────────────┐                 │
              │ Remote client          │ ────────────────┘
              │ (web, iPhone, script)  │
              └────────────────────────┘
  • RemotePairingClient — the three-leg pairing dance with trmnly.dev. Desktop hits /api/v1/pair/start, surfaces the short code, polls /api/v1/pair/poll with the nonce. The user opens the link, claims the code, and the token comes back on the polling response.
  • RemoteTunnelManager — owns the cloudflared subprocess (or, in Tailscale mode, none). Brings up the tunnel, watches its output for the URL, heartbeats trmnly.dev every 20 seconds while a device is connected (60 otherwise), restarts on unexpected exit with backoff, and recovers a few seconds after the Mac wakes.
  • The heartbeat reply is the roster. Each heartbeat brings back the list of devices allowed to talk to this Mac (as token hashes, with each one's kind, scopes and expiry), the public key for access tokens, and whether the account has killed remote access. The Mac never sees anyone's token in the clear.
  • RemoteControlService — the on/off coordinator. Holds the issued token, mirrors it into the listener's bearer slot, and brings the transport up.

Turn it on

  1. Settings → AI Agent → Remote Control → enable.
  2. Click Start pairing. TRMNLY shows a short device code and opens the trmnly.dev pairing page in your browser — sign in and confirm the code. The pairing page names the device, its platform and app version before you confirm, so you can tell it's yours. The desktop's poll picks up the token automatically. Codes expire after 10 minutes.
  3. TRMNLY brings up the tunnel and heartbeats the URL. The settings panel shows the live tunnel URL and the device id.

If you don't have cloudflared installed, TRMNLY downloads it on first enable. It lands in ~/Library/Application Support/TRMNLY/bin/ and is only used for the tunnel. The download is pinned to a known release and checked — SHA-256 against two independent sources, plus Cloudflare's code signature — before it ever runs; a copy from an older pin is replaced on the next tunnel start. An existing Homebrew install (/opt/homebrew/bin/cloudflared) is picked up instead if present.

Choosing a transport

Settings → AI Agent → Remote Control → Connection has three transports and one extra:

Transport What it is
Quick tunnel (default) A free *.trycloudflare.com tunnel. No account needed. The address changes on every restart; paired devices follow it through trmnly.dev.
Named Cloudflare tunnel Your own tunnel at a fixed hostname. Create it in Cloudflare Zero Trust, route the hostname to http://127.0.0.1:<port> (Settings shows the port), and paste the hostname and token. The token is kept in the keychain and never appears on a command line.
Tailscale No cloudflared at all. TRMNLY needs Tailscale running with a MagicDNS name, turns the LAN listener on, and advertises https://<magicdns>:<port>. Only the iPhone app can use this path, because it pins the Mac's certificate; a browser can't.
Direct LAN connection (toggle, off by default) A second listener on your local network with TLS and a self-signed certificate. The iPhone app tries it before the tunnel when you're on the same network, and the Mac picker says "on this network".

The LAN listener answers only peers on private, link-local, Tailscale/CGNAT or loopback addresses, and every request needs a bearer — there's no anonymous access on it. The phone sends its token only to a private, .local or .ts.net host whose certificate matches the SHA-256 the Mac advertised. Live terminals (/attach) still go over the tunnel.

Advertise with Bonjour (_trmnly._tcp) is an option under the LAN toggle. The current iPhone build doesn't browse for it yet, so it finds the Mac through the addresses the heartbeat advertises instead; those work without Bonjour.

Wake

While awake, the Mac tells trmnly.dev its Wake-on-LAN address (Settings → Remote Control → Wake shows it), and it sends a "going to sleep" heartbeat before it sleeps so clients can say Studio went to sleep at 14:02 rather than just "offline". To be reachable over the network while asleep, turn on Wake for network access in macOS Battery/Energy settings. A scheduled wake from the phone isn't possible: pmset schedule wake needs administrator rights, so TRMNLY can't set one.

Connect from somewhere else

Once the Mac is paired, remote clients resolve it through trmnly.dev rather than hard-coding the address. Three flows are supported.

The web remote (trmnly.dev/remote)

Pair a browser tab with a Mac code, or open an invite link, and Remote becomes a control surface for that Mac: a Terminal with explicit pane targeting, an Approvals inbox that updates live (with safety badges and Allow for 15 min), and Chat, Prompts, Queue and Files views that call the same Mac tools as the phone, plus a tool console. Each view checks that the Mac offers its tools first.

The tab gets a browser token of its own — never the Mac's own token. It holds the read and terminal scopes, works only against the Mac it was paired with, and expires after 12 hours. It's kept in the tab's session storage, and Sign out revokes it on trmnly.dev. A tab paired before browser tokens existed is simply forgotten. Sends from the web remote go through the Mac's approval path: if the Mac wants a decision, the send says it's waiting and the card appears on your phone and in the inbox.

The iOS app

Signing in. Two roads onto a device token:

  • Sign in with GitHub (the quick one) — the phone shows a short code, copies it to your clipboard, and opens github.com/login/device, where Safari is usually already signed in. Approve, and the phone is paired. The GitHub token never reaches the phone: the site exchanges it, resolves your account and mints a TRMNLY device token instead. A phone paired this way starts unconfirmed — you get an email, and until you confirm it on trmnly.dev/app the Macs don't admit it. The app shows Confirm this iPhone at trmnly.dev/app with a link and a retry; it never signs you out over it.
  • Use a pairing code — the phone shows a code you confirm on a trmnly.dev page you're signed into. Tick This is my iPhone running TRMNLY there to make it your trusted phone.

Two ends, one app. Once signed in, the switcher in the title bar picks your Mac or the Cloud workspace. They are peers: the Mac is your real machine, the cloud box belongs to the account and answers with every Mac asleep.

Several Macs. Choose a Mac… lists every Mac on the account with its state (and the reason when it's offline). The one you pick is the one you drive; every other online Mac keeps a side connection, so their approvals and completion events still arrive. The picker shows approvals live and how many are waiting on each.

The app has five tabs: Now, Terminal, Prompts, Browse and Account. On an iPad at full width it becomes a split view instead: a sidebar with those jobs plus the Mac's tabs and panes (tap one to target it), the job in the middle, and Approvals in an inspector that opens when a new one arrives (⇧⌘A toggles it).

Now

The front page: what needs you, then what's running.

  • Approvals waiting on you, from every connected Mac, grouped by Mac — see Approvals. The tab's badge is their count.
  • The selected end's state, with a Try again when it's offline.
  • Queued sends — anything you sent while offline. See Offline sends.
  • Sessions — the Mac's panes, each with a 🔔 to notify you when it's done.
  • Pane activity — every pane from the Mac's surface list, flagged ones first, then ones that look like they're waiting, then working, then quiet. Tap one to point Terminal at that exact tab and split.
  • Keep awake — 1 hour, 4 hours or Off, with who else is holding the Mac awake. On a current Mac the timer runs on the Mac itself, so the claim ends on time even if you never open the app again.
  • Mac clipboard — send this iPhone's clipboard to the Mac (touch and hold Send in a composer does the same for typed text). Reading the Mac's clipboard is blocked for remote callers, so it isn't offered.
  • Shortcuts to Terminal, Files, tasks and git, and Agent conversations (on the Mac) or Cloud agent (on the box).

A composer at the bottom sends to the pane Terminal is pointed at. Above it, chips hold your last 8 sends to this Mac (kept only on this phone) — tap to refill, touch and hold for more. The field says which pane it types into and that it presses Return; Hide keyboard beside Send, or dragging the list down, puts the keyboard away. Each pane row leads with its tab or session name, with the program, project and branch underneath.

Terminal

Read the Mac's panes and type into them. The title says what the phone is driving; tap it to pick a project, then any tab open in it (in any window), then a split. Follow the Mac is the default: the Mac's focused tab, or the chosen project's front tab. The choice is remembered, Now's composer sends to it, and Files, Tasks, Git and Chat follow the chosen project. Picking a tab on the phone doesn't change what the Mac shows. If the tab closes, the phone says so and goes back to following the Mac.

The tab picker numbers each tab and shows the name you gave it on the Mac, with what it's running and its folder underneath. New tab: ⋯ → New Tab in opens a shell tab on the Mac in the project the title points at (a tab of that project's window, or a new window when it has none) and points the phone at it; the picker offers Open a tab in … too, including for a project with no tabs open. On the Mac this is the open_tab tool, which your trusted iPhone may run without a prompt.

Live. On a current Mac the pane streams over a live connection (/attach) instead of being re-read every few seconds: output appears as it happens, about ten frames a second, and history is kept as it scrolls off. If the stream can't hold (four failed reconnects) or the pane closes, the phone falls back to polling; ⋯ turns live off. An older Mac is polled, more slowly while nothing changes.

Drawing. The pane is drawn in colour — the Mac theme's colours, bold, italic, faint, underline, strikethrough, inverse video and the cursor — and you can drag-select and Copy. Fit width fits the Mac's column count to the screen (pinch to read a wide pane); Original keeps the pinched size and scrolls sideways; Wrap reflows at the phone's width. New output follows the bottom only while you're there: scroll up and a New output pill takes you back (iOS 18 also remembers where you were per pane). ⋯ → Find in output searches the scrollback. Links are tappable — web URLs, OSC 8 hyperlinks, and file paths such as src/a.ts:12:3, which open the file from the Mac at that line (touch and hold to copy the path). A "N approvals waiting on you" pill opens them without leaving the pane.

Composer. Two modes. Send (the default) types the text and presses Return — a shell runs it, Claude Code or any TUI takes it as a turn. Type types it and leaves it there; multi-line text asks whether to type it as one line or with line breaks. Single-line text sends on Return; once the text has a line break the field grows to six lines and the paper plane sends. Your draft survives a reconnect. Pasted and long text is typed first and Return pressed a moment later, so Claude Code doesn't swallow it into the paste, and the stray characters a paste brings (trailing newlines, no-break spaces, curly quotes, an em dash where -- was typed) are cleaned up. If the Mac refuses a send, the phone says why and keeps your text. Saved prompts, the share sheet, Shortcuts and queued sends get the same treatment.

Key bar. Three pages: keys (esc, tab, ⇧Tab, ^C, arrows, ⏎), navigation and symbols (| ~ / - _ * & > < $ and friends), and F1–F12. Ctrl and Alt are sticky — tap once for the next key (including the next character you type in the composer), double-tap to lock. Arrows and navigation repeat while held. ^D, ^Z, ^L, ^R, ^A, ^E, ^U and ^W are under •••, so ^D can't end a shell on a mis-tap. Each key is a real keystroke (terminal_press_key), so ^C interrupts Claude Code and Esc leaves vim; presses queue in order rather than being dropped. A swipe across the bar scrolls it rather than pressing the key under your finger; the cursor-trackpad key takes a short hold before it moves the cursor. Paste shows a preview with line and character counts for anything long or multi-line, and offers Paste as one line. VoiceOver reads keys by name ("control C", "Up arrow").

Hardware keyboard. ⋯ → Direct keyboard input sends every keystroke straight to the pane — arrows, Esc, Tab, F-keys and Ctrl/Alt chords. ⌘K clears the screen, ⌘↩ sends from the composer.

Queue above the key bar is that pane's command queue — the Mac's Queue tab — with how many entries wait in it. Tap it to see them (head first, marked Next), add a command or a saved prompt, swipe one away, run the next one now (it asks first), or clear the lot. Each entry runs when the pane's current command finishes.

Prompts

The Mac's Prompts sidebar as a tab: filter, tag chips, and the Pinned, Most used, Recent today and Prompts sections, plus a folder per pack you've added on the Mac. ▶ sends a prompt to the pane Terminal is pointed at and presses Return; the queue button adds it to that pane's command queue; tap a row to insert it into the terminal's composer and edit it first. The ★ in the terminal composer opens the same library. A send counts as a use on the Mac, and the list is what the Mac's sidebar shows for the project you're driving.

Prompts with placeholders ask for each value before they're sent or queued:

Placeholder Becomes
{{name}} A text field, with chips for the last five values you used
{{name:default}} A text field that starts on default
{{name:a|b|c}}, {{a|b|c}} A picker, starting on your last choice
{{date}} Today, as yyyy-MM-dd
{{clipboard}} This iPhone's clipboard (read only when used, never stored)
\{{name}} The literal {{name}} — the backslash is removed on send

Send as written skips the form. Template syntax such as {{ .Values.x | quote }} is left alone; a tight Jinja filter like {{name|upper}} reads as a choice, so escape it with \{{. Browsing and adding packs stays on the Mac.

Browse

A row of chips switches sections. Against the cloud box only the first four exist.

  • Files — browse, read, and edit with approval. Download pulls a file from the Mac in chunks with progress and cancel, then opens it in QuickLook or the share sheet; Upload sends a photo or file to the Mac (it asks before overwriting). Uploads and edits need the files:write scope and an approval.
  • Tasks — the board the project has selected, so it shows what the desktop shows. When the project has more than one board, the screen names the one you're on and lets you switch — switching moves the Mac's Tasks tab with it (several boards). Against the cloud box it's the box's own boards, with Main in place of a project name.
  • Git — status, history and a Changes pane for reviewing a diff: staged and unstaged files, then hunks, with stage, unstage and discard per file and per hunk (discard always confirms). Where the Mac has no per-hunk git tool, the phone sends the patch as a single git apply line typed into the visible pane, and says so.
  • Chat — the project's chat threads.
  • Screen — the Mac's display, live at 1, 2 or 5 seconds a frame, or one shot, with pinch-zoom. On a current Mac each frame comes back inline and nothing is left on disk. Needs the gui scope.
  • Docker — runtimes, every container (stopped ones too, on a current Mac), start/stop/restart, logs, and Compose projects with Up and Down (volumes are never removed).
  • Ports — the Mac's whole ports table with a conflicts filter, a port checker that takes an alias like aw3.3000, Kill listener, and Preview, which opens localhost:<port> in the Mac's browser and shows you a screenshot.
  • Schedules — scheduled jobs with cadence, next run and last result. Pause/Resume and Run now are offered when the Mac allows them, and say when they'll ask.
  • Runbooks — the Mac's runbooks; Run asks for Face ID and a confirm.
  • Tools — a console for every tool the Mac offers: search, star favourites, fill a form generated from the tool's schema (or raw JSON), run it, and read the result. Each tool carries a badge saying whether it's blocked remotely, runs without asking, or may ask.

Writes on these screens say "may need approval", and after three seconds "waiting — answer it in Approvals". The phone asks the Mac what this device may do (remote_capabilities), so a blocked action is shown disabled with the reason rather than failing.

Agent conversations

Now → Agent conversations chats with the TRMNLY agent on the Mac. The list is every conversation in the Mac's agent sidebar, in every project, grouped by project. Open one to read it and send a message; the reply appears as the turn runs, tool calls show as status lines, and an approval the turn needs appears inline. While a turn runs, Stop ends it the way the sidebar's Stop does — a turn parked on an approval card leaves that card for you to answer. A conversation that isn't open on the Mac runs in the background; one that is mid-turn queues your message. New conversation (✎) picks a project and sends the first message. Transcripts imported from Claude Code are shown with a lock and stay read-only.

Account

  • This iPhone — whether it's your trusted phone, and what that means; a link to trust it on trmnly.dev when it isn't.
  • All devices — every device on the account with its kind, scopes, expiry, last seen and state (unconfirmed, Remote off). Tap one to rename it or revoke it. Scopes and expiry are shown here but changed only from a signed-in browser, so a phone can't widen its own access.
  • Security — Face ID settings (below), Activity, and Kill all remote access.
  • Activity — what remote devices did on the Mac: tool, device, result and time, newest first, filterable by device and tool. Refusals are listed too.
  • Approvals — whether notifications are allowed (needed for approvals while the app is closed).
  • Cloud workspace, Sign out (which revokes this phone's token on trmnly.dev, not just locally) and Delete account.

On the cloud box

The same app, pointed at the box behind trmnly.dev/trmnly:

  • Terminal — three engines: the web client in a WKWebView, a native renderer, and a text poll that works on any network.
  • Cloud agent — one headless Claude Code turn per message, streamed, resuming the same session between messages. Plan, Ask and Auto modes — Ask parks each unsettled tool call as a card with Allow, Always and Deny — a model picker, a working-folder field, and photo attachments (up to six, 8 MB). Stop cancels the turn on the box. See Cloud workspace → Agent.
  • Files, Tasks, Git and Chat in Browse, Save workspace, the running quota, and a link out to the full web app.

Background reads from the phone — the terminal poll, the pane list, the tool list — never start a stopped box, so they never bill one. See Cloud workspace → Starting, stopping.

Shared screens. Files, Tasks and Git are one screen each, pointed at whichever end is selected — the box's agent deliberately uses the same tool names as the desktop (list_dir, read_file, git_status, kanban_list). Each entry is offered only where the target actually advertises the tool.

Approvals

When an agent or MCP client on your Mac hits a tool that needs your OK, the phone gets it two ways. With the app open, the card appears on Now (and in Terminal's pill) live. With the app closed, it arrives as a notification.

Each card shows a safety badge — Read-only, Writes or Dangerous — "Asked by on ", the reason, and the arguments. A write_file, edit_file or patch card shows the diff.

  • Approve / Deny answer once. The Mac waits two minutes, then denies.
  • Allow for 15 min approves this one and similar calls from this device in this project for 15 minutes. It always asks for Face ID first, and it's never offered on a dangerous tool. The Mac caps any remembered grant at an hour.
  • From a notification, Approve and Allow for 15 min ask for your unlock; Deny doesn't. Allow for 15 min on a dangerous request answers nothing and explains — approve it once in the app.
  • If an answer doesn't reach the Mac, the card comes back with Couldn't send your answer rather than vanishing.

Cards are bound to the Mac that asked, so with several Macs an answer always goes to the right one. Approvals from the Mac's own sidebar agent push to the phone according to a Mac setting — see Sidebar approvals.

Notify when done

The 🔔 on Terminal's toolbar, on Now's pane rows and in the iPad sidebar asks the Mac to tell you when that pane is done: when it goes idle (ten seconds of quiet after output) or when its command finishes. A watch is one-shot and lapses after 24 hours. With the app open you get a banner and a haptic; otherwise a notification — tap it to open the pane. If a Live Activity is running, the pane shows there too, and stays for 15 minutes after it finishes.

Without any watch, the Mac also pushes a raised flag and an agent turn over a minute long — but only while you're away from the Mac and no phone has the app open.

Offline sends

A send from Now or Terminal made while offline, or one that fails in transit, is kept on the phone (up to 20, for 24 hours) instead of lost. A banner offers Send now, Review (send or discard each) and Discard. Nothing is sent without a tap, and each entry is sent at most once.

Face ID

Account → Security has:

  • Ask for Face ID when opening — after a minute in the background.
  • Ask before approving dangerous tools — on by default.
  • Ask before sending after being idle — pick the idle time.

Allow for 15 min and Kill all always ask, whatever these say, as does running a runbook.

Beyond the app

  • Widgets — Mac status and waiting approvals on the Home and Lock Screen.
  • Live Activity — a watched pane on the Lock Screen and in the Dynamic Island until it finishes.
  • Shortcuts and Siri — Send to Mac Terminal, Run Saved Prompt, Ask Mac Agent, Copy to Mac Clipboard, Keep Mac Awake, Open TRMNLY Approvals, Approve Latest Request (shows what it is, asks you to confirm, and refuses dangerous tools) and Run Mac Tool (Advanced).
  • Apple Watch — waiting approvals and watched panes, plus a complication. Approve and Deny are relayed through the phone, so the Watch never holds a token; dangerous tools can only be denied from the Watch.
  • Share sheet — TRMNLY sends text or a link to the Mac's clipboard, a new agent conversation or the focused pane, and files to the Mac's ~/Downloads.
  • Handoff — the phone opens a com.trmnly.pane activity (and widget and Live Activity links) on the right Mac and pane. The Mac doesn't advertise that activity yet, so Handoff from the Mac arrives separately.

Scripts / direct API

If you'd rather call the bridge directly, the v1 device API gives you:

  • GET /api/v1/devices — your paired devices, with each one's kind, scopes, expiry, confirmation and tunnel state.
  • GET /api/v1/devices/[id]/endpoint — the current tunnel URL for one device, and a short-lived access token for it.
  • POST /api/v1/devices/me/tunnel — desktop-side heartbeat (used by TRMNLY, not normally by clients).
  • DELETE /api/v1/devices/me — a device revokes its own token.
  • POST /api/v1/pair/github/start + /poll — the device flow behind "Sign in with GitHub", for any client with no browser of its own. Start returns a nonce and a user code; poll until status: "claimed" returns the device token. Honour the interval the poll echoes back — GitHub rate-limits the whole session otherwise.

Authenticate with the bearer token from the pairing flow or a device API token. The bridge itself speaks MCP: POST <tunnel>/mcp with a JSON-RPC body (the reply comes back as a single SSE event), GET <tunnel>/sse for live notifications (every event carries an id; send Last-Event-ID on reconnect to get what you missed), and <tunnel>/attach for a live pane over WebSocket. Call remote_capabilities to learn what your token may do on this Mac. Full contracts are in API reference.

Who may do what

The roster

Every request is checked against the Mac's roster: the hashes of the device tokens allowed in, refreshed with every heartbeat. Each entry says what kind of device it is — phone, browser, mac or api — and may carry scopes and an expiry. The roster leaves out revoked, expired and unconfirmed devices, and a token bound to one Mac appears only on that Mac. Anything not on the roster gets a 401; nothing on the tunnel or the LAN listener is anonymous.

Revoking a device takes effect at the next heartbeat — about 20 seconds while something is connected — and the Mac then closes that device's open live connections too.

Scopes

Scope Covers
read Reading: panes, files, git status, the board, lists
terminal Typing into panes, keys, the command queue, keep-awake, ports, and typing over /attach
files:write write_file, edit_file, uploads, git and board writes
agent Chatting with the Mac's agent, stopping a turn
gui Screen capture, mouse and keyboard control of apps
docker Starting, stopping and changing containers
admin Schedules, runbooks, worktree changes

A device with explicit scopes may use exactly those; anything else is refused with needs the scope for this device. A device scoped to just read is read-only. Set scopes and an expiry for any non-Mac device from the dashboard's Access editor; an expired device is refused everywhere. A device with no scopes set follows the defaults:

Device Default
Your trusted phone Everything; admin actions ask first
A browser token read and terminal
Any other paired device read; other actions ask first, dangerous ones are refused

The trusted phone

Approval requests go to your phone, so for a send the phone itself made, a prompt would just be the phone approving itself. So one iPhone — the one you confirmed on trmnly.dev (This is my iPhone running TRMNLY when you approve its pairing code, or Trust this iPhone on the dashboard) — drives the Mac from its own UI without approval cards or the Mac's consent dialog: reading and typing into panes, keys, opening tabs, the pane queue, messages to the agent — including reordering the queue (queue_move) and deleting a conversation, which the phone confirms itself — and its own Git and Tasks writes. A message from the phone starts a turn; what the agent then does still asks under the project's approval settings. The device's own claim to be an iPhone is not enough, and a GitHub-paired phone starts unconfirmed.

The trade-off: a stolen trusted-phone token can type into the Mac with no prompt on the Mac. Revoke it — or kill all remote access — and it stops at the next heartbeat.

Live terminals (/attach)

Opening a live pane needs the read scope; every keystroke sent over it needs terminal, checked frame by frame, and refused input is answered with an error and written to the audit log. Explicit scopes win in both directions: a trusted phone narrowed to read can't type, and a browser token with terminal can. Raw keystrokes don't pass through the command rules or the destructive-command check — keys are encoded on the client — which is why typing over /attach is held to the same devices that may already type without a prompt.

Approvable versus blocked

For tools a device's scopes cover:

  • Ordinary writes follow the Mac's approval tier, as for a local client.
  • Dangerous tools — shell commands and typing into panes, write_file, edit_file, uploads and patches, ssh_exec, container_exec, AppleScript, sub-agents — ask for approval every time (except the trusted phone's own terminal sends, above). File writes used to be refused outright for every remote caller; now a card on your phone decides. Allow for 15 min is never offered for them.
  • admin tools — pausing or running a schedule, running a runbook, worktree changes — ask first even from the trusted phone.
  • Never from outside the Mac, whatever the scopes: reading or setting vault keys, browser cookies and storage, credential lookup and autofill, and browser-allowlist edits. No approval card can show what those are about to send.

With Require approval on and nobody listening, a call that needs an approval is refused with a message pointing at Approvals on the phone or in the web remote.

Per-Mac access tokens

trmnly.dev can mint a 15-minute token bound to one Mac (signed with Ed25519; the Mac gets the public key on every heartbeat). The Mac accepts it in place of a device token and applies that device's roster entry — scopes, trust, expiry — exactly as if the device token had been sent, so revocation still works within one heartbeat. The Mac advertises support; the iPhone app and the web remote still send their device token for now, restricted to tunnel and pinned LAN hosts.

Safety guarantees

Remote control inherits all the local MCP server guarantees and adds a few of its own:

  • Bearer token required. See Who may do what. Tokens are compared in constant time, the Mac's own token lives in the keychain, and ?token= in a URL is honoured only from the Mac itself.
  • Approval policy still applies. A paired phone or the web remote listening on the approvals channel gets an interactive approve/deny (as does the Mac's own banner), and the Mac waits for the decision.
  • The rest still applies. Command rules, the destructive-command check, the terminal rate limit, and a policy deny hold for every remote caller.
  • Tunnel URL rotates. Quick tunnels get a new trycloudflare.com hostname on every restart, so anyone scraping logs sees stale URLs.
  • Audit log records the remote session. Every remote tool call — refusals included — is stamped with the device that made it. Read it on the phone under Account → Activity, or from Agent safety → Audit log.
  • Kill switches. Toggling Remote control off stops the transport. Unpair… goes further: it stops the tunnel, clears the device token locally, and revokes the device server-side. Kill all remote access is the account-wide one.

On the Mac

Settings → AI Agent → Remote Control:

  • Connected now — every live remote connection: the device, how it's connected (tunnel, LAN), the panes it has attached and for how long, with a Disconnect button each.
  • Kill all remote access… — see below.
  • Connection — the transport and LAN listener.
  • Notifications — the sidebar-approval push setting.
  • Wake — the Wake-on-LAN address the Mac advertises.

While a remote device has a pane attached, a green dot appears in the menu bar; its menu lists each connection with Disconnect.

Push sidebar approvals to the phone decides when cards from the Mac's own sidebar agent go to your phone:

  • When away (default) — only after two minutes without input, or with the screen locked. At the desk, you answer on the Mac.
  • Always / Never.

Cards from MCP clients always go to the phone, and an app that's open sees every card live either way.

Manage paired devices

The trmnly.dev dashboard (trmnly.dev/app) lists your paired devices, each with its kind, scopes and expiry. From there you can:

  • Revoke a device. Revoking a Mac also revokes every token bound to it.
  • Rename it, and edit its Access — scopes and an expiry.
  • Confirm an unconfirmed device (a banner lists them), or revoke it.
  • Trust this iPhone to make it your trusted phone.
  • Turn a Mac's remote access back on after a kill-all.
  • Create a device API token for scripts.

The phone's Account → All devices covers rename and revoke too.

Invites

The dashboard's Remote access section makes invite links: pick the scopes, how long (5 minutes to a week), and optionally one Mac. You get a code, a link and a QR code. Whoever opens the link signs in to their own trmnly.dev account (everyone who uses TRMNLY needs one, guests included; someone without one can create one from the invite, even while sign-up is invite-only), presses a button and lands in the web remote with a token that carries exactly those scopes and ends when the invite does. An invite works once; you're emailed when it's used, with the account that used it, and pending ones can be cancelled.

Kill all remote access

From the dashboard, the phone (Account → Security, behind Face ID) or the Mac (Settings → AI Agent → Remote Control):

  • every phone, browser and API token on the account except the one you used is revoked, and pending invites are deleted;
  • every Mac stops its tunnel and LAN listener, disconnects everyone, and rotates its listener token. Macs are marked Remote off, not unpaired.

Switching Remote Control back on at the Mac (or Turn remote back on on the dashboard) restores the Mac; revoked devices pair again.

Troubleshooting

Symptom Likely cause / fix
Pairing code never claims Make sure you're signed in to trmnly.dev in the browser. Stale codes expire after 10 minutes; restart pairing.
Phone says Confirm this iPhone It was paired through GitHub sign-in. Confirm it on trmnly.dev/app, then retry.
Tunnel URL flapping cloudflared restarted unexpectedly. The settings panel shows restart attempts; details are in the unified log (Console.app, subsystem TRMNLY, category remote.tunnel). The desktop heartbeats the new URL automatically — clients follow it.
Remote client gets 401 The device was revoked, its access expired, or remote access was killed. Re-pair, or extend its access on the dashboard.
needs the … scope for this device The device's scopes don't cover that action. Change its Access on the dashboard.
Remote tool call refused for approval Nobody was listening for approvals. Open the app or the web remote's Approvals, grant a time-boxed per-client bypass from the Mac's approval panel, or turn off Require approval in the MCP server settings.
Blocked for remote callers The tool is one that never runs from outside the Mac (vault, cookies, credentials). Run it at the Mac.
Mac shows Remote off Someone used Kill all. Turn Remote Control back on at the Mac.
Tailscale mode won't start Tailscale isn't running on the Mac or has no MagicDNS name. Sign in to Tailscale, then switch back.
cloudflared won't install The error shows in the settings panel. Drop a binary into ~/Library/Application Support/TRMNLY/bin/cloudflared yourself, or brew install cloudflared — Homebrew installs are picked up automatically.

Source pointers

  • RemoteControlService.swift
  • RemotePairingClient.swift
  • RemoteTunnelManager.swift
  • RemoteTransport.swift
  • RemoteAuthorizedTokens.swift
  • RemoteAccessToken.swift
  • RemoteEventHub.swift
  • RemotePresence.swift
  • AttachServer.swift
  • AgentMCPPhoneTrust.swift — scopes and the remote verdict
  • CloudflaredInstaller.swift
  • RemoteControlSettingsView.swift
  • iOS app — macos/Sources/App/iOS/Remote/, extensions in macos/iOSExtensions/
  • Web side — site/app/api/v1/, site/app/remote/