Mobile-Desktop Sync

  • Desktop, mobile and web
  • All plans
View as MarkdownFeature page

What it does

The mobile app is a live mirror of your running desktop: projects, agents, terminal output, dev servers, backlog and prompts sync to the phone in real time, and every action the phone takes (start an agent, type in a terminal, answer a permission prompt, close a session) is executed by the desktop on its own processes. The desktop is the source of truth; the phone shows what the desktop knows and nothing else. The link is a one-to-one encrypted channel through the AgentsRoom relay: keys are exchanged on the device (X25519), traffic is encrypted end to end (XSalsa20-Poly1305), and the relay forwards ciphertext it cannot read.

The relay exists in more than one region. Every keystroke from the phone makes a round trip through it, so the desktop picks the relay closest to itself that answers and announces it to the phone; the phone follows that choice and never picks on its own. The list of your desktops (the directory the phone reads when you sign in) always stays on the main relay, whichever region carries the one-to-one link.

Where to find it

  • Desktop: the Mobile pill in the footer opens Pair Mobile App, which confirms the relay is up, carries the remote-access switch and the App Store / Google Play links. Also in Settings > Mobile.
  • Mobile: first launch, sign in and tap your computer under Your desktops. Later, Settings > Your desktops lists paired computers with Switch desktop, Pair a new desktop and Log out from desktop.
  • Relay region: desktop Settings > Mobile > Relay region, visible to every user (it used to sit in the Advanced tab, which only administrators see; moved on 2026-09-16). On the phone, Settings > Connection > Relay region shows the relay the link is on right now.

How to use it

  1. Sign in to your AgentsRoom account on the desktop (the footer says Sign in to pair your phone otherwise).
  2. Sign in to the same account in the mobile app. Every computer of the account that is online shows up under Your desktops: tap yours.
  3. Approve the new device on the desktop (New device pairing, required on first connect). The footer pill turns into Mobile connected: click to manage, listing connected clients and what they are browsing.
  4. From then on the phone reconnects on its own whenever both sides are online, on Wi-Fi or cellular.

Switching desktops: an account can have several computers; the phone talks to one at a time. Settings > Your desktops shows each one as Connected, Offline or Not answering; tap Switch to to move. Projects that live on another computer are marked Not on this desktop and cannot be launched from here.

Settings

  • relayEnabled (global, Settings > Mobile): keep the encrypted relay connection open. Off = the pill shows Remote access disabled and the phone cannot connect.
  • sendNotificationsToPhone (global, Settings > Mobile): mirror agent and terminal notifications to the paired phone.
  • mobilePushOverride (owned by the phone, mobile Settings > Agents and terminals): Follow desktop, Always or Never; Always and Never win over the desktop checkbox.
  • relayRegion (global, Settings > Mobile > Relay region): auto by default, which takes the relay the service suggests for the desktop's location once its health check answers; otherwise the id of a relay the service lists to force one. The relays listed today are Europe (the main one), Asia-Pacific and North America, opened on 2026-09-21; the list and its names come from the service, not from the app, so a new one needs no update, and the main relay is the fallback whenever the chosen one does not answer. The help text: "Relay the mobile app goes through to reach this desktop. Automatic picks the closest one that answers; the list of desktops always stays on the main relay." and the line In use: {relay} names the current one. relayWsUrl (the Relay Server override, maintainer tooling) wins over both.

Agent tools (MCP)

  • settings_get / settings_set: read or change relayRegion (auto or a relay id) like any global setting. A change takes effect without restarting the desktop.

Nothing else: the sync channel carries the app's own state, and agents keep working locally whether a phone is connected or not.

Providers

All providers, no difference. Full-screen terminal interfaces (Grok Build, OpenCode, Antigravity, Copilot, or any TUI such as vim) are mirrored as whole-screen frames rather than a raw byte stream, so the phone shows a readable screen; line-based CLIs (Claude Code classic, Codex) stream as text.

Mobile

This is the mobile app's backbone. iPhone, iPad and Android, paired with macOS, Windows or Linux.

The phone shows the relay it is on under Settings > Connection > Relay region, with the same name the desktop uses (the host name until the list of relays has been fetched). It remembers the relay of each paired desktop and reopens the link there when you switch desktops. When the desktop changes relay, the phone notices the desktop's next announcement and reconnects on its own; nothing to do on the phone.

Limits

  • The desktop app must be running and online; when it is closed the phone shows a disconnected state and its lists empty.
  • One phone seat per desktop at a time: a second device (an iPad on the same account, say) takes the connection and the first one shows Another device took over with a Reconnect here button. Two devices connected simultaneously is not supported.
  • Agents cannot be launched from the phone on a project whose folder does not exist on the connected desktop; the desktop refuses with a message instead of starting in the wrong folder.
  • Behind a corporate proxy or a firewall, the relay address must be allowed; the phone explains which address is blocked. When the connection fails, the pairing popover prints the raw reason next to the relay address, untranslated on purpose so you can hand it to your IT team (DNS lookup failed, Connection refused, Connection timed out, Host unreachable, TLS certificate rejected, Proxy authentication required). A desktop pointed at a self-hosted relay does not show up in the phone's list and cannot be paired: that setting is maintainer tooling.
  • A company gateway that inspects TLS re-signs the relay traffic with its own root authority. The desktop reads the root authorities trusted by the machine (macOS keychain, Windows root stores, Linux bundles) and accepts those, so the link works on such a network without any manual step. It only trusts what the system itself marks as trusted, and changes nothing on a machine that adds no extra root. On a managed Mac, a root pushed by MDM or a configuration profile carries no explicit trust setting, which macOS reads as fully trusted: the desktop accepts it since 1.188.0 (1.186.0 and 1.187.0 skipped those roots, so the link still failed on such Macs).
  • Pairing a phone requires an AgentsRoom account on the desktop.
  • A regional relay is only used when the service lists one; with a single relay listed, everything stays on the main relay exactly as before. A desktop that is not up to date stays on the main relay and its phone follows it there.
  • Forcing a relay by hand is for a desktop the service geolocates wrongly (VPN, carrier-grade NAT, a company IP abroad) and therefore pairs with the wrong relay; otherwise leave Automatic.
  • A phone that has never been paired with any computer does not show a "Desktop disconnected" screen when it opens an agent, a dev command or an SSH terminal: it says No computer connected ("This phone is not linked to any computer yet. Pick the one running AgentsRoom to drive this agent from here.") with a Choose a computer button that opens the Your desktops sheet in place. The console appears there once the link is up.

Common questions

  • Is my code sent through a server? No. Only ciphertext crosses the relay; keys never leave your devices. The server cannot read prompts, output or files.
  • Do I need to be on the same network? No, cellular works. No VPN or port forwarding either.
  • A notification opened the wrong computer. A push from another of your desktops offers to switch to that desktop when you tap it; if the connected desktop does not know the agent, the terminal screen says the agent lives elsewhere and offers the switch.
  • Why did my phone disconnect when I opened the app on my tablet? Same account, same desktop: the tablet took the single seat. Tap Reconnect here on the phone to get it back.
  • The phone says Relay region: Europe while I am in Asia. Is it wrong? No: the phone follows the desktop, not its own position. The desktop is the fixed end of the link, so the closest relay is chosen from where the desktop is, and a phone travelling far from it gets the same total latency either way.
  • On Android, Your desktops stayed empty and the agent screen kept saying Desktop disconnected, while the desktop said it was online. Fixed on 2026-09-16 (reported by Christophe): Android cuts the phone's discovery connection when the app goes to the background, and the app used to treat that cut as final, so it never received the desktop's offer again. The discovery now reopens on its own after a cut and again every time the app returns to the foreground. Update the mobile app.
  • I am behind my company's proxy and the sync will not connect. Read the line under the Mobile pill in the pairing popover: it names the reason and the address. TLS certificate rejected used to mean a gateway inspecting TLS; the desktop now accepts the root authorities installed on the machine, so update first. If it persists, the authority is not trusted at system level: install it in the system keychain (macOS) or the trusted root store (Windows). Connection refused, Connection timed out or Host unreachable mean the relay address is blocked and has to be allowed by IT.
  • My company Mac is managed by MDM and still shows TLS certificate rejected after the 1.186.0 fix. That fix missed the roots MDM installs, which carry no trust setting of their own. Fixed in 1.188.0 (reported by Tomoya): update the desktop, nothing to configure.
  • Where do I pick the relay region now? Desktop Settings > Mobile > Relay region, for every user. Leave Automatic unless the desktop is geolocated wrongly (VPN, company network) and lands on a far relay.
  • The phone shows the same project twice, both marked Not on this desktop. A bug with several computers on one account: a project known from the account registry but not yet set up on the connected desktop was listed once per source. Fixed on 2026-09-15 on both sides: updating the mobile app is enough, even against an older desktop.

Related