Agent Wikis

wikis / Orca / wiki / concepts / mobile-companion.md view as markdown report a mistake

Mobile Companion

type: conceptconfidence: mediumupdated: 2026-09-09sources: 7

The Orca mobile companion is an iOS/Android app that pairs with your desktop Orca and gives a read-mostly view of running agents — agent status, recent terminal scrollback, and the controls you actually want from a phone. Pairing is one-time and the desktop is always the source of truth. The docs state the design intent directly: "The mobile app is intentionally not a full editor — it's a remote control for the desktop you already have running."

What you can do from the phone

  • See every worktree, its agent, and its current status (working / done / waiting on input). Mobile lists worktrees from every host you're connected to — local desktops and remote Orca servers — in a single view.
  • Browse the workspace's full file tree, including deeply nested paths.
  • Open supported agent sessions in Chat UI (a chat-style transcript) or the raw terminal.
  • Hydrate recent terminal scrollback. Markdown in chat-style views can render Mermaid diagrams when the message includes them.
  • Select, copy, and paste text from the mobile terminal view — long-press to select, share-sheet to paste back into a reply.
  • Use the terminal accessory row for awkward keys including Tab and Shift+Tab, or switch to Live when each typed character should go straight to the active terminal.
  • Send a short reply (continue, yes, free-text) when an agent is waiting on input, attach a photo or file, or dictate. In Live mode, dictated text is inserted into the active terminal without pressing Return for you.
  • Run Quick Commands from the session tab strip — the same saved list as desktop, synced both ways.
  • Open a browser session in Web or Mobile view.
  • Open Source Control for a worktree to review changed files, stage or unstage, and commit.
  • Switch the active agent account and see usage / rate-limit state; when Codex has earned reset credits, spend one from the accounts screen (see Usage and rate limits).
  • Create a workspace with the same Smart source modes as desktop: Smart, GitHub, Linear, GitLab, Branch, and Name.
  • Get push notifications when an agent finishes, mirroring desktop notifications (see Notifications and inbox).

Installing on Android

Android is distributed as an APK, not through Play:

  1. Open the Orca download page in Chrome or another full browser and select Android.
  2. When the download finishes, open your browser's Downloads or your device's Files → Downloads, then tap app-release.apk.
  3. Follow Android's installation prompt. If asked, allow only the browser or Files app to install unknown apps, then turn that permission off after Orca is installed.

Two documented install snags:

  • Download never starts or finishes. If the link opened inside Discord, GitHub, or another app, choose Open in browser / Open in Chrome, or copy it into a full browser, then start the Android download again.
  • Samsung Galaxy Auto Blocker. If Auto Blocker prevented the install, open Settings → Security and privacy → Auto Blocker, temporarily turn it off, install Orca, then turn it back on. The docs add: do not disable Play Protect.

Pairing

On desktop, open Orca's pairing flow from the account / status menu; Orca shows a one-time pairing code. On mobile, open the companion app, choose Pair, then paste the code — or follow a deep link from the desktop straight into the mobile pairing screen.

The docs recommend Orca Relay for pairing when it is available; sign-in is required for Relay only. The local network address picker is optional on Relay (expand it when you want a LAN fast path), while LAN pairing still needs an address. The pairing exchange establishes a device token for that phone, and you must keep the desktop reachable on the path you chose.

Closing the desktop app drops a direct/LAN session until you reopen it. Relay-backed pairing follows the desktop Relay connection.

From a headless server

For a host running orca serve, request a mobile-scoped QR code and link:

orca serve --pairing-address 100.64.1.20 --mobile-pairing

Keep the phone on the same tailnet, open Orca Mobile, choose Pair, and scan the terminal QR code or paste the printed link. See Remote Orca Servers.

Editing a paired host without re-pairing

On the hosts list, tap the host card's ⋯ button (or long-press the card) and choose Edit host:

  • Name — display name on this phone only.
  • Address — IP, host:port, or ws:// / wss://. A missing port keeps the current port, or defaults to 6768. Address edits only change where this phone connects; they do not re-pair, and the pairing token stays the same. Saving an address change reconnects to the new endpoint.

This is the documented fix for a desktop that moves between home LAN and Tailscale.

Chat UI on mobile

For chat-capable agents (Claude, Codex, and others Orca recognizes), a session can open in Chat UI instead of the raw terminal.

  • Device default — on first launch mobile asks how sessions should open on this phone; change it later under Settings → Chat UI → Open sessions in Chat UI. The default is terminal until you choose Chat UI.
  • Per-session — long-press a session tab and choose Switch to chat view or Switch to terminal view; that override sticks for the tab without changing the device default.
  • Composer — type a reply, @ mention workspace files, use agent-aware / slash commands from the shared catalog (Claude vs Codex sets, with descriptions), attach a photo, or dictate. Attached images appear as removable thumbnails and ride along on send, including image-only and multi-image sends.
  • Model and session options — a pill row shows the current model and session options, including direct Codex model selection, without dropping into the raw terminal.
  • Desktop still owns the agent — Chat UI is a view over the paired desktop session, not a separate cloud agent.

Terminal settings on the phone

A dedicated Terminal settings screen (Settings → Terminal) exposes:

  • Text size — a 50%–200% baseline zoom the WebView applies on top of fit-to-width. Pinch-to-zoom snaps to the same presets and persists. Per-device; it does not change the desktop terminal.
  • Autocomplete & autocorrect — off by default so the OS never rewrites commands, flags, or paths in the command bar. The live keyboard-capture input streams raw keystrokes either way.

Protocol versioning is a hard gate

The phone and desktop speak a versioned mobile protocol. If either side is too old, mobile blocks that host and points you at the App Store (iOS) or GitHub Releases (Android APK or desktop), then back to hosts. After updating, refresh the connection; if the message persists, remove the host and pair again.

The repo README explains why this exists: mobile updates lag desktop by 24–48h via the App Store, so both sides exchange version numbers on status.get "so a genuinely incompatible combo can hard-block instead of silently misbehaving." Constants live in src/shared/protocol-version.ts (DESKTOP_PROTOCOL_VERSION, MIN_COMPATIBLE_MOBILE_VERSION) and mobile/src/transport/protocol-version.ts (MOBILE_PROTOCOL_VERSION, MIN_COMPATIBLE_DESKTOP_VERSION). The README states that at the time it was written, "all four are set so evaluateCompat always returns { kind: 'ok' } — nothing blocks. The wire format is in place to flip a switch when needed." Bumps are for breaking changes only — a removed RPC method or required parameter mobile uses, a changed meaning (units, nullability) of a field mobile reads, or changed encryption, framing, or auth handshake — and explicitly not for new RPC methods, new optional fields, or new event types in terminal.subscribe.

Known limits and reported problems

The docs' own troubleshooting list:

  • Stuck spinner on a worktree — the phone tracks a heartbeat from the desktop agent process; if the desktop says idle but the phone shows working, force-refresh the worktree row.
  • Pairing fails — desktop and phone must be signed into the same Orca account, and pairing codes expire after a few minutes.
  • Authentication failed / pairing invalid — the desktop no longer accepts this device token (for example after desktop cleared paired devices). Try Retry on the banner first, since transient rejections can recover without re-pairing; if it keeps failing, use Re-pair from desktop or Remove the host and pair again.
  • Quick Commands unavailable — update the paired desktop so it advertises the quick-commands capability. The same applies to the Quick Commands launcher, which is disabled when the paired desktop is too old.
  • Can't reach desktop — phone and desktop must share a network path (LAN, Tailscale, or the pairing path you used).

Three community reports add detail the docs do not:

  • Relay off-LAN failures. Issue #10425 reports pairing through Orca Relay failing with "the relay can't be reached and it's falling back to local." A maintainer replied: "Turns out it's our server got overloaded. Too many users. We're rolling out a self-hosting version this week. Also trying to scale out our server." A later comment reports the same class of failure on iOS where same-Wi-Fi pairs and connects but cellular-only does not. Issue #16448 is a further cluster of the same shape, with a maintainer comment suggesting it may be the same Relay failure as #16238 (relay director move was not strictly newer) and one user reporting "direct LAN works but not relay." Both #10425 and #16448 are closed as completed upstream — a maintainer closed #16448 on 2026-09-05 with "This was resolved! Though you may need to re-auth". The separate relay-director issue #16238 referenced from that thread is the one that remained open. Re-authenticating is the documented first step if pairing fails on a current build.
  • Windows firewall blocks LAN pairing. Issue #8371 reports Android QR pairing timing out after ~25s with "Couldn't connect within 25s" and "WebSocket closed." The most detailed maintainer analysis concludes the socket never opened at all — retries closing every ~10 seconds match React Native Android's OkHttp 10-second TCP connect timeout — and names the likely cause as Windows Defender Firewall dropping inbound TCP to Orca on port 6768, noting that having no third-party antivirus does not disable Defender Firewall and that a Public network profile can block an allowance scoped to Private. The decisive test given is to open http://<desktop-lan-ip>:6768 in Chrome on the phone: a timeout confirms a firewall/routing/AP-isolation problem. The stated interim workaround is Tailscale on both machines with the 100.x.x.x address selected in Orca's Network Interface menu, then regenerating the QR code. A maintainer opened a follow-up (#8439) for a Windows-only pairing-page improvement offering a UAC-gated Private-network firewall rule; PR #8439 merged on 2026-07-13, and the parent issue #8371 closed as completed on 2026-07-15 via merged PR #8846. The firewall diagnosis above remains the right first check, but the in-app affordance now exists.
  • Do not share the QR. A maintainer's request in that thread is worth repeating as a rule: don't share the QR code or full pairing code, since those contain credentials.

Development notes

The repo README documents the local dev topology: Orca desktop/Electron hosts the mobile WebSocket RPC server on port 6768, and Expo Metro serves the React Native app on port 8081. Pairing in dev goes through Settings > Mobile, and the mobile host endpoint is confirmed as ws://<desktop-ip>:6768 — with ws://10.0.2.2:6768 for the Android emulator. The QR encodes the connection endpoint, device token, and TLS fingerprint. A mock server is available on port 6768 with token mock-device-token for developing without a desktop instance.

Related pages

Sources

raw/web_community-mobile-companion-orca-docs.md, raw/web_community-install-orca-mobile-on-android-orca-docs.md, raw/github_doc-mobile-readme-md.md, raw/web_community-remote-orca-servers-orca-docs.md, raw/github_issue-bug-mobile-qr-pairing-never-connects.md, raw/github_issue-bug-orca-relay-for-mobile.md, raw/github_issue-bug-mobile-connection-issue.md.