--- title: "Mobile Companion" type: concept tags: [mobile, pairing, android, relay, remote] created: 2026-09-09 updated: 2026-09-09 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"] confidence: medium --- # Mobile Companion 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](usage-and-rate-limits.md)). - 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](notifications-and-inbox.md)). ## 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](remote-servers.md). ### 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://: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://: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 - [Remote Orca Servers](remote-servers.md) - [Ways to run Orca](ways-to-run.md) - [Notifications and inbox](notifications-and-inbox.md) - [Usage and rate limits](usage-and-rate-limits.md) - [Supported agents](../entities/supported-agents.md) ## 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`.