Control Godmode from your phone: iOS and Android app, paired over Tailscale (GODM-33)

[danielehrhardt]

Closes GODM-33.

What does this change?

Godmode now has a phone app for iOS and Android (apps/mobile, Expo SDK 57). It controls the Godmode running on your computer, and nothing else.

• Home: what agents are doing right now (with a stop button), live screens, things that need you (a locked vault, missing logins) and recent chats. A floating bar above the tab bar shows the current activity from any tab.
• Chats: answers stream in as they're written. Steps show up as short lines like "Opened linear.app". Markdown, tables and code render natively. A live thumbnail of the agent's browser or VM sits above the message field, and Stop is one tap.
• Screens: every browser tab, shared screen and VM an agent works in, live. Open one full screen, pinch to zoom, and Take control: tap to click, type, scroll. VMs can be started and stopped.
• Agents: status, give an agent a task, run automations or switch them on and off.
• iOS 26 Liquid Glass throughout: native tab bar with a bottom accessory, native headers and toolbar buttons, glass controls. The app icon is an Icon Composer file. Android uses Material symbols and solid surfaces. Light and dark mode.

Connecting (Settings → Phone on the computer)

1. Tailscale on the computer and the phone, same account.
2. Settings → Phone → Connect a phone shows a QR code.
3. Scan it in the app, or with the camera app (godmode://pair?d=… opens the app).

The settings page shows the Tailscale status, the phone-access switch and port, and paired phones (online state, last seen, remove).

Security

• One-time code: 32 random bytes, valid for 5 minutes, single use. Only its hash is kept, in memory.
• Device key: each phone gets its own key. The computer stores only its hash. On the phone it lives in the Keychain / Keystore.
• Removing a phone disconnects it right away. Pairing and removal are audited. Pairing also notifies you.
• Separate listener on this computer's Tailscale address only, never the LAN. It serves no dashboard, sign-in, MCP or webhooks. The access token and dashboard sessions are refused there. It checks the Host header and the decoded path (/api/%61uth is refused too).
• Device keys only work on that listener, and only while phone access is on.
• Route allowlist: phones reach a fixed set of routes with restricted bodies.
  • They can't reach logins, 2FA, backups, integrations, settings or folders.
  • They can't change a chat's folder, VM, instructions or shared screen, or an automation beyond on/off.
  • They can only control screens shared in a chat.
• The app protects its key:
  • It sends the key over plain HTTP only to Tailscale addresses (100.64.0.0/10, *.ts.net), or over https anywhere, for the planned gateway.
  • Before sending it, it checks that the address answers with the paired instance id.
  • Writes are never retried on another address, so a slow network can't duplicate a message or a run.
• Optional Face ID lock.
• Backups never carry paired phones or phone settings.

Core changes

• packages/core/src/mobile/: Tailscale detection (CLI or interface), pairing and devices, the listener, and the phone scope.
• Routes under /api/mobile.
• Migration 15 (mobile_devices).
• WebSocket: phones only get streaming deltas for chats they have open (conversation.subscribe). New sockets get the current activity of every run, for the desktop too.
• @godmode/shared gets mobile.ts: types, pairing-link encode/parse, URL policy.

Tooling

• apps/mobile has its own toolchain (bun) and is excluded from the pnpm workspace. CI, Docker and the desktop build don't install React Native.
• It imports @godmode/shared from source through Metro.
• New CI job: Phone app (typecheck).
• scripts/icons.ts --mobile generates the app icons from the logo.

How was it tested?

• Core tests: bun test passes, 757 pass, 0 fail. The new test/mobile.test.ts has 15 tests. They cover:
  • pairing codes: single use, expiry, voided when access is turned off
  • device scope and body rules, and that device keys are refused off the phone listener
  • the phone listener: Host, decoded-path check, access token refused
  • WebSocket delta filtering, and removal closing the socket
  • the Tailscale parser and the URL policy
• Other checks:
  • Typecheck passes for shared, core and desktop.
  • The mobile typecheck passes, also without the generated Expo types (a clean clone).
  • expo-doctor passes 21/21.
  • The desktop build passes, and the core binary smoke test passes.
• End to end: I ran a development build in the iOS 26.5 Simulator against a real core over this Mac's Tailscale address.
  • Paired through the deep link.
  • Chats, streaming, stop, sending a message, agents, the new-chat sheet and settings all worked.
  • The live browser worked, and a tap clicked through on the remote page.
  • Disconnect removed the device on the computer, then re-paired.
  • Both light and dark mode were checked.
• The desktop QR code was decoded from a screenshot with the macOS QR detector.
• An independent review found an encoded-path bypass, device keys working on the main listener, and a vanished reply after backgrounding. All were fixed and covered by tests.

Notes

• Android is configured (cleartext only needed for Tailscale addresses, adaptive icon, Material symbols) but not built here: this machine has no Android SDK.
• Face ID lock is implemented, but the Simulator has no enrolled Face ID, so I didn't try it.
• Migration id clash: open PRs Give agents any API with your key: Tools with Nano Banana, OpenAI and more (GODM-37) #35 and Let agents work on SSH servers with a password or key (GODM-36) #36 also add migration 15. Whichever merges second needs to renumber.
• Store builds: eas.json is included, but no App Store or Play credentials are set up yet.
• Gateway: the pairing link already carries a list of addresses, so the planned gateway (https) can be added later as another address.