Introducing a new way to review your PRs.

Read the announcement

stablyai / orca

Orca lets you run a fleet of bots with your own subscription (e.g. Claude Code, Grok, Agy, Codex). Available on desktop, mobile and remote runtime.

View on GitHub

34 documents · Updated Nov 20, 2026

docs / pairing-and-device-trust

Pairing and device trust

Pairing attaches an Orca client to a desktop runtime through a short-lived access offer. The offer binds a reachable endpoint to a per-device credential and the desktop's encryption identity. Pairing therefore establishes both a connection path and a trust record that the desktop can later limit or revoke.

Pairing model

Pairing offers

The pairing offer is the portable invitation that moves from the desktop to the client. It has a scope that defines the access family: runtime is for another Orca client or browser runtime connection, while mobile is for the mobile client. It also carries the WebSocket endpoint, a device token, the desktop public key, and an optional device identity. Mobile offers can include Relay routing data.

Relay data is a separate, short-lived invitation for the mobile path. It names a Relay director and cell, carries an assignment version and Relay host identity, and expires within a bounded time. The offer rules reject Relay data on runtime-scoped offers and require a canonical desktop public key for Relay offers. src/…/mobile-relay-pairing-offer.ts src/…/mobile-relay-pairing-offer.ts

The desktop encodes the validated offer as an orca://pair?code=... link. The mobile client and the desktop client also accept the bare encoded value, which supports QR scans, deep links, and paste flows without changing the trust rules. The decoder rejects unknown routes, malformed data, and offers that exceed the safe input size. src/…/pairing.ts

The offer is an access grant, not a name for a host. A copied or exposed offer can be used until its pending device grant is replaced or revoked. The desktop keeps the token in its device registry and can rotate a never-used pending grant when the user regenerates a link. src/…/device-registry.ts

References: src/…/mobile-relay-pairing-offer.ts• L9-17 src/…/mobile-relay-pairing-offer.ts• L46-105 src/…/pairing.ts• L14-37 src/…/device-registry.ts• L78-140

Pairing sequence

The pairing sequence turns a user's reach choice into a scoped credential, then checks the remote identity before saving the connection. Direct and Relay paths use the same offer identity and encrypted session rules.

This diagram shows the common path for desktop-to-desktop and desktop-to-mobile attachment.

flowchart LR
    A[Desktop selects scope and reach] --> B[Desktop creates pending device grant]
    B --> C[Desktop builds and displays access offer]
    C --> D[Client scans or pastes offer]
    D --> E[Client validates scope, endpoint, and offer shape]
    E --> F[Client tries an allowed connection path]
    F --> G[Encrypted handshake binds desktop identity]
    G --> H[Desktop checks token, scope, and protocol]
    H --> I[Client saves trusted host and credentials]

For a runtime client, verification requests remote status before the environment is saved. For a mobile client, the client first resolves a stable host identity from the desktop key. It records a pairing journal before Relay work begins, then installs and confirms a durable resume credential before it saves the Relay host profile. Re-pairing updates the existing host identity instead of creating a second host card. src/…/runtime-environment-pairing-verification.ts, mobile/…/pre-profile-pairing-coordinator.ts, mobile/…/pre-profile-pairing-coordinator.ts

References: src/…/runtime-environment-pairing-verification.ts• L21-82 mobile/…/pre-profile-pairing-coordinator.ts• L128-153 mobile/…/pre-profile-pairing-coordinator.ts• L200-245 src/…/remote-runtime-client.ts• L121-177

Serve readiness

The serve readiness output gives a user or a script the endpoint and pairing state after a desktop runtime starts. It reports a pairing URL when an offer is available and gives a reason and guidance when the endpoint cannot support pairing. Human, JSON, and recipe output use the same pairing availability decision. src/…/serve-readiness.ts src/…/serve-readiness.ts

The readiness contract keeps the bound endpoint separate from the advertised endpoint. This distinction lets an operator see what the server listens on and what a remote client should use. A readiness publication is written once, so a partial or failed publication is not silently retried as if it were a new pairing grant. src/…/serve-readiness.ts, src/…/serve-readiness.test.ts

References: src/…/serve-readiness.ts• L4-20 src/…/serve-readiness.ts• L44-125 src/…/serve-readiness.test.ts• L44-111

Address selection

Advertised endpoints

An endpoint is the address and WebSocket scheme that a client uses to reach the desktop. The desktop converts a bound listener plus the user's address choice into a connectable ws: or wss: endpoint. It does not advertise wildcard listeners such as 0.0.0.0; without an explicit address, a wildcard listener resolves to loopback and stays local.

The address picker presents the user's intended reach rather than only the text of the address. Runtime sharing has three intents:

  • Another device selects a discovered address for a LAN, Tailscale, or other reachable client.
  • This computer only selects loopback and records a local-only reach policy.
  • Custom address accepts a host, a host and port, or a full ws(s):// URL for an SSH tunnel, reverse proxy, or other front end.

HTTP and HTTPS custom URLs are normalized to WebSocket schemes. Wildcard hosts, port zero, credentials embedded in the URL, fragments, and malformed destinations are rejected. src/…/pairing-endpoint.ts, src/…/pairing-url.ts

References: src/…/pairing-endpoint.ts• L16-40 src/…/pairing-endpoint.ts• L60-129 src/…/pairing-url.ts• L3-29 src/…/RuntimePairingGeneratorForm.tsx• L62-105

Address discovery

Automatic discovery chooses a usable host address for the selected reach. It prefers a Tailscale IPv4 address, then another usable interface address. It excludes loopback, link-local IPv6, proxy-only addresses, and known virtual bridge interfaces from the automatic choice. A user can still select a bridge or enter a custom address when that is the intended route.

The same selection rule is shared by the main process and the UI. This keeps the address shown in the picker aligned with the address placed in the generated offer. If a refresh removes an automatically selected address, the UI selects a new safe default and invalidates the old QR. An explicit custom address is preserved across a refresh. src/…/pairing-address-auto-selection.ts, src/…/mobile-network-interface-selection.ts

References: src/…/pairing-network-interfaces.ts• L17-79 src/…/pairing-address-auto-selection.ts• L17-40 src/…/mobile-network-interface-selection.ts• L12-41 src/…/use-mobile-pairing-address-preference.ts• L53-75

Reach policy

Reach policy describes where a pending grant is allowed to expose the runtime. this-computer means loopback only. network permits the listener to serve an off-host client. The policy travels with the grant because a custom address can look like loopback while still fronting an SSH tunnel or reverse proxy.

The desktop widens the listener only for an explicit network-reach choice. A local-only grant does not cause a later reconnect to publish the runtime on every interface. This protects the boundary between “the address happens to be local” and “the user allowed off-host access.” src/…/runtime-pairing-reach.ts, src/…/runtime-pairing-link-state.ts, src/…/device-registry.ts

References: src/…/runtime-pairing-reach.ts• L1-5 src/…/runtime-pairing-link-state.ts• L5-11 src/…/runtime-rpc.ts• L664-731 src/…/device-registry.ts• L17-29

Network proxy boundary

The desktop can reach pairing services through an explicit proxy setting, an environment proxy, or the system proxy. Explicit settings take priority. Proxy credentials stay in memory per network session and are supplied only to a matching proxy challenge, so they do not become part of the advertised endpoint or pairing metadata. src/…/proxy-policy-resolution.ts, src/…/electron-proxy-credentials.ts, src/…/electron-proxy-credentials.ts

Proxy changes are ordered per session. Requests wait until the newest change settles and are cancelled when the change fails or the session is retired. This keeps a pairing or Relay request from crossing a half-applied network policy. src/…/proxy-settings.ts, src/…/proxy-settings.ts, src/…/electron-proxy-request-guard.ts

References: src/…/proxy-policy-resolution.ts• L15-43 src/…/electron-proxy-credentials.ts• L37-51 src/…/electron-proxy-credentials.ts• L89-114 src/…/proxy-settings.ts• L168-237 src/…/proxy-settings.ts• L241-283 src/…/bounded-proxy-application.ts• L1-19 src/…/electron-proxy-request-guard.ts• L4-14

Connection modes

Mobile connection modes

Mobile pairing offers have two connection modes. Automatic means Anywhere: the desktop must be signed in so it can create a Relay invite. Local-only means direct access through the selected LAN, Tailscale, or custom endpoint. The default is Automatic unless the user has saved a local-only preference.

The desktop fails closed when Automatic cannot obtain Relay data. It does not label a direct-only QR as Anywhere. The UI can then offer a LAN path or a retry. A mode change invalidates the displayed offer because the old QR carries a different access policy. src/…/mobile-pairing-connection-mode.ts, src/…/runtime-rpc.ts

References: src/…/mobile-pairing-connection-mode.ts• L1-40 src/…/runtime-rpc.ts• L800-862

Direct and Relay paths

Automatic mobile pairing starts direct and Relay candidates when both are available. The first healthy candidate wins; a direct result wins an exact tie. Local-only starts only the direct path. Both paths then use the desktop public key and the device token from the offer.

The mobile client authenticates to a Relay cell with either the short-lived invite or a later resume credential. The Relay must accept that credential before the encrypted channel starts, and the client rejects a response that names the wrong credential kind. The encrypted channel then carries the pairing status request and later RPC traffic. mobile/…/mobile-relay-physical-client.ts, mobile/…/mobile-relay-physical-client.ts, mobile/…/mobile-relay-e2ee-link.ts, src/…/mobile-relay-phone-protocol.ts

If a Relay cell moves, the client asks the configured director for an authenticated assignment with a strictly newer epoch. It persists that move before dialing the new cell. A non-newer response leaves the stored cell authoritative and causes a bounded retry instead of adopting an untrusted location. Only failures that can be relieved by a new assignment enter this recovery path. mobile/…/mobile-relay-invite-director.ts, mobile/…/pairing-relay-candidate.ts, mobile/…/pairing-relay-candidate.ts

The pairing log labels every entry as Direct or Relay at the candidate boundary. This lets the scan screen show which path failed without exposing invite material. mobile/…/pairing-log-path.ts, mobile/…/mobile-relay-physical-client.ts

Relay adds an invite that is short-lived and bound to a Relay host identity. After the initial authenticated connection, the client requests a durable resume credential and the desktop returns the Relay endpoint. The mobile client keeps that credential in the native secure store and uses only unexpired, non-rejected credentials for later connections. mobile/…/pre-profile-pairing-coordinator.ts, mobile/…/mobile-relay-credential-bundle.ts

References: src/…/mobile-pairing-connection-mode.ts• L10-40 src/…/runtime-rpc.ts• L800-938 mobile/…/pairing-candidate-race.ts• L10-59 mobile/…/mobile-relay-physical-client.ts• L91-180 mobile/…/mobile-relay-invite-director.ts• L25-109 mobile/…/pairing-relay-candidate.ts• L47-169 mobile/…/pairing-log-path.ts• L9-27 mobile/…/pre-profile-pairing-coordinator.ts• L218-245 mobile/…/mobile-relay-credential-bundle.ts• L22-109

Trust boundaries

Encrypted identity checks

The offer pins the desktop public key. During connection, the client derives a shared encryption key from its temporary key pair and that pinned key. The encrypted handshake then proves that the endpoint is speaking for the desktop identity named by the offer rather than only proving that a socket is open. src/…/remote-runtime-client.ts, src/…/e2ee-crypto.ts

The mobile protocol makes the transport part of the handshake context. A direct session and a Relay session must agree on the protocol, participants, framing, and Relay host identity when present. The Relay outer handshake runs before E2EE and reports typed close codes, so an endpoint rejection is not confused with a cryptographic failure. src/…/mobile-e2ee-v2-contract.ts, src/…/mobile-e2ee-v2-contract.ts, mobile/…/mobile-relay-e2ee-link.ts

References: src/…/remote-runtime-client.ts• L146-177 src/…/e2ee-crypto.ts• L11-27 src/…/mobile-e2ee-v2-contract.ts• L7-31 src/…/mobile-e2ee-v2-contract.ts• L45-107 mobile/…/mobile-relay-e2ee-link.ts• L86-169

Scope and authorization

After the encrypted channel is established, the desktop resolves the device token to a registry entry. The entry supplies the stable device identity and the access scope. A mobile-scoped token can call only the mobile method set; a runtime-scoped token can use the runtime client surface. The desktop ignores a conflicting token repeated inside an authenticated request.

The runtime client verifies the returned status before it saves a host. It rejects a mobile-only offer, a bad status shape, and incompatible protocol versions. It also reports a host identity mismatch when the reached endpoint does not match the public key in the offer. src/…/runtime-rpc.ts, src/…/remote-pairing-verification.ts

Removing a device deletes its desktop grant and terminates its active connections. Removing a mobile host also schedules deletion of its stored device and Relay credentials. A persistent mobile rejection eventually becomes a re-pair state, while a plain Relay outage remains an unreachable state. This keeps an invalid grant distinct from a temporary network failure. src/…/runtime-rpc.ts, mobile/…/host-store.ts, mobile/…/mobile-relay-pairing-rejection-escalation.test.ts, mobile/…/mobile-relay-pairing-rejection-escalation.test.ts

References: src/…/runtime-rpc.ts• L1637-1723 src/…/remote-pairing-verification.ts• L54-113 src/…/runtime-rpc.ts• L640-656 mobile/…/host-store.ts• L257-287 mobile/…/mobile-relay-pairing-rejection-escalation.test.ts• L72-112 mobile/…/mobile-relay-pairing-rejection-escalation.test.ts• L223-237

Local UI state

Runtime attachment fields

The desktop runtime sharing UI lets the owner choose how a link will be opened and where it will point. The generated link and its display state remain available while the user moves through Settings, but the credential material remains owned by the main process.

The runtime sharing surface exposes these important fields:

FieldPurpose
Link intentChooses another device, this computer only, or a custom address.
Connection addressShows the selected discovered address or the custom endpoint.
Name in OrcaSets the local label for the attached computer.
Access linkAccepts the link or bare pairing value from the other host.
Link destinationShows the parsed endpoint and its loopback, Tailscale, LAN, public, or custom class before connection.
SSH tunnel overrideAllows a loopback endpoint when the user keeps an SSH tunnel active.

The add-host form blocks a loopback link by default. The override is explicit because loopback normally means “this device,” while an SSH tunnel makes it a deliberate local front end for another host. src/…/RuntimeHostAccessForm.tsx, src/…/RuntimeHostAccessForm.tsx

References: src/…/RuntimePairingGeneratorForm.tsx• L62-105 src/…/RuntimePairingGeneratorForm.tsx• L139-191 src/…/RuntimeHostAccessForm.tsx• L43-67 src/…/RuntimeHostAccessForm.tsx• L98-171

Mobile attachment fields

The mobile settings surface controls the path and address used to mint a QR. It remembers the selected mode and custom addresses, refreshes discovered interfaces, and removes a shown QR when its endpoint or policy changes. A paired-device list gives the owner a place to revoke mobile grants.

The mobile surface exposes these important fields:

  • Connection path: Automatic or Local-only.
  • Connection address: A discovered interface or saved custom address.
  • Generate QR: Creates the offer for the current path and address.
  • Pairing code and endpoint: Shows the QR payload and the endpoint that it represents.
  • Paired devices: Shows attached mobile identities and supports revocation.

Automatic generation is disabled while the desktop is signed out. Sign-out also clears a displayed Automatic QR so a stale Relay invite is not left on screen. src/…/MobilePane.tsx, src/…/MobilePane.tsx, src/…/MobilePane.tsx

References: src/…/MobilePane.tsx• L77-114 src/…/MobilePane.tsx• L116-126 src/…/MobilePane.tsx• L170-232 src/…/MobilePane.tsx• L390-460

Mobile scan surface

The mobile scan surface is the receiving entry point for a desktop offer. It accepts a QR code or a pasted orca://pair?code=... value, validates the offer before connecting, and shows a bounded connection state with a path-aware pairing log when the attempt fails.

Camera permission is not required for paste pairing. A scan attempt has a 25-second overall limit, and leaving the screen disposes the active attempt so a late result cannot navigate a new screen. A successful pairing refreshes the cached host client and continues to mobile onboarding. mobile/…/pair-scan.tsx, mobile/…/pair-scan.tsx, mobile/…/pair-scan.tsx

The screen keeps the camera area stable while the paste sheet is open and uses a square scan guide across rectangular camera views. These choices keep the QR action clear without changing the offer or trust rules. mobile/…/pair-scan.tsx, mobile/…/pair-scan-styles.ts

References: mobile/…/pair-scan.tsx• L48-111 mobile/…/pair-scan.tsx• L126-184 mobile/…/pair-scan.tsx• L217-257 mobile/…/pair-scan.tsx• L274-355 mobile/…/pair-scan-styles.ts• L4-57 mobile/…/pair-scan-styles.ts• L103-184

Pairing-local UI fields

Some UI state belongs to the client that displays it and must not cross the pairing boundary. These fields describe local workspace visibility, local ordering, and local automation filtering. The paired UI exchange strips them on the way to a host and keeps the receiving client's own values on the way back.

The protected fields are:

  • automationHostFilter
  • hideWorkspacesFromOtherDevices
  • manualRepoOrder
  • workspaceHostOrder

This separation lets a paired client share host-backed UI data without allowing one device to overwrite another device's local layout or automation choices. src/…/pairing-local-ui-fields.ts

References: src/…/pairing-local-ui-fields.ts• L3-30 src/…/pairing-local-ui-fields.test.ts• L5-41 src/…/web-preload-api.ts• L4160-4185 src/…/client-ui-pairing-local-fields.test.ts• L13-89

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the offer schema and both Node and mobile decoders aligned. QR, deep-link, and paste flows must accept the same shapes.
  • Keep endpoint normalization, address discovery, and UI address defaults aligned. A changed default can make the displayed address differ from the address in a new offer.
  • Treat scope, connection mode, and reach as one grant contract. Changing one without rotating or invalidating the pending offer can widen access under an old policy.
  • Keep the desktop public-key check and the runtime status check in the same verification path. Saving a host before both checks pass weakens the identity boundary.
  • Keep Relay invite installation, endpoint publication, and secure credential promotion ordered. A host record must not point to Relay access that was not durably installed.
  • Persist a newer Relay assignment before dialing it. Do not adopt a non-newer director response or route endpoint errors into director recovery when a new assignment cannot help.
  • Keep direct and Relay log attribution at the candidate boundary. A new log-producing path must not appear to belong to the wrong network path or expose credential material.
  • Keep proxy credentials session-scoped and request readiness closed during failed or retired proxy transitions. Pairing must not use a half-applied network policy.
  • Add new client-local UI fields to the pairing-local field census before exposing them through paired UI RPCs.

Important failure modes

TriggerConsequenceGuard
Automatic mobile pairing while the desktop is signed outNo Anywhere QR is created.Require sign-in for Relay minting and offer Local-only instead.
Relay invite is expired or a cell rejects it after reservationPairing cannot complete, and repeated attempts may consume the invite budget.Validate expiry and do not send cell-load refusals through director recovery.
Relay director returns a same or older assignmentThe client must not move to an untrusted or stale cell.Accept only a strictly newer authenticated assignment and keep the stored cell authoritative otherwise.
A runtime link points to loopback on the receiving deviceThe add-host action is blocked because it may point back to the wrong computer.Require a Tailscale/LAN link or an explicit SSH tunnel override.
The endpoint is wildcard, port zero, malformed, or not WebSocket-basedThe offer cannot produce a usable connection.Normalize and validate the advertised endpoint before encoding it.
The reached host has a different public key or incompatible protocolPairing stops before the host is saved.Verify host identity and runtime compatibility from authenticated status.
A Relay socket error has no close eventThe pairing attempt could remain pending.Convert the missing close into a bounded typed transport failure.
A device token is revoked, expired, or rejectedNew requests fail and the old connection is terminated.Validate the registry entry or Relay credential on every connection path.
Proxy application fails or a proxy session is retiredRequests are cancelled instead of crossing an unknown network state.Hold requests through the newest transition and fail closed after bounded retries.
A paired UI field is exchanged as host stateOne client can overwrite another client's local layout or automation filter.Strip every field in the shared pairing-local census in both directions.

Key files

FileWhy to read it
src/…/pairing.tsDefines the portable access-link format and parse rules.
src/…/mobile-relay-pairing-offer.tsDefines offer scope, Relay invite shape, and expiry rules.
src/…/runtime-rpc.tsShows how the desktop creates grants and chooses mobile pairing modes.
src/…/device-registry.tsShows per-device credentials, scope, reach, rotation, and revocation.
src/…/remote-pairing-address.tsClassifies destinations and rejects unsafe access-link endpoints.
src/…/remote-pairing-verification.tsDefines the checks made before a runtime host is accepted.
src/…/runtime-environment-pairing-verification.tsConnects link parsing, remote verification, and local host saving.
src/…/serve-readiness.tsDefines the pairing information exposed to users and scripts when a server starts.
mobile/…/pre-profile-pairing-coordinator.tsShows the mobile pairing sequence across direct and Relay paths.
mobile/…/mobile-relay-physical-client.tsShows Relay credential acceptance and encrypted pairing RPCs.
mobile/…/mobile-relay-invite-director.tsShows authenticated Relay assignment changes.
mobile/…/pairing-relay-candidate.tsShows bounded Relay recovery and durable move ordering.
mobile/…/mobile-relay-credential-bundle.tsShows where durable mobile Relay credentials are kept and promoted.
mobile/…/pair-scan.tsxIllustrates QR and paste intake, timeout, logs, and post-pair navigation.
src/…/proxy-settings.tsShows how the desktop applies and orders proxy policy for network sessions.
src/…/electron-proxy-credentials.tsShows the session boundary for proxy credentials.
src/…/RuntimePairingGeneratorForm.tsxIllustrates the runtime sharing choices and address fields.
src/…/RuntimeHostAccessForm.tsxIllustrates the receiving form and loopback safeguard.
src/…/MobilePane.tsxIllustrates mobile mode, address, QR, and revocation controls.
src/…/pairing-local-ui-fields.tsDefines UI state that must remain local to each paired client.