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 / mobile-web-delivery

Mobile web delivery

Mobile web delivery lets the mobile client open a host workspace web surface inside a native WebView. The mobile client gets a versioned web bundle from the paired desktop, stores a verified copy on the phone, and serves it from a private local origin. A narrow bridge gives the page the selected host's data and approved phone actions without turning the page into a general browser or a second host client. See mobile client and mobile sessions and terminal for the surrounding mobile flows.

Delivery model

The delivery model joins three boundaries: a packaged host route tree, a host-owned bundle cache, and a native WebView shell. The page supplies the workspace screen. The shell supplies the selected host session, native device services, navigation, and the limits that keep the page inside its assigned surface.

Packaged mobile-web application

The packaged application starts at the host route tree rather than at the native app root. Its browser route replacements render host screens directly and replace native-only services with page services backed by the shell bridge. This lets one web build provide workspace screens while pairing, host management, and other root-native work remain in the mobile app.

The entry waits for the shell handshake before it mounts the route tree. It then supplies the host profile, device actions, storage, locale, color scheme, keyboard state, and query state that the page needs to behave like a mobile screen. The page reports readiness and its first painted frame separately, so the native shell does not treat a committed but blank route as usable.

References: mobile/…/index.tsx• L1-65 mobile/…/index.tsx• L153-239 mobile/…/web-overrides.json• L1-39

Host-scoped web routes

Host-scoped routes carry the host identity in the URL and select that paired desktop before the page can read host data. The native shell route is /h/[hostId]/web; browser builds use the matching web route without nesting a native shell inside the page. A route that the bundle does not publish stays on a readable native fallback.

The shell keeps the mounted page for changes that affect the same screen. It sends a new route state for parameters that the page can apply in place. A different screen, an unsupported route, or a route whose grants exceed the current session returns to native navigation. Wide layouts use the page only when the served route can own the host area; otherwise the native layout remains in control.

This diagram shows how a host URL becomes either a native screen or a private web document.

flowchart LR
    A[Host URL with hostId] --> B{Route, build, and layout gates}
    B -->|Native or unavailable page| C[Native screen or route notice]
    B -->|Approved packaged route| D[Read or fetch host generation]
    D --> E[Open private-origin WebView]
    E --> F[Handshake and mount page route]

References: mobile/…/web.tsx• L8-46 mobile/…/web.web.tsx• L1-12 mobile/…/MobileWebShellScreen.tsx• L60-75 mobile/…/MobileWebShellScreen.tsx• L304-378 mobile/…/mobile-web-shell-session-contract.ts• L15-87

Bundle lifecycle

The bundle lifecycle moves one desktop-produced web build to a verified host generation on the phone. The manifest names the build, routes, grants, entry document, asset facts, and compatibility window. The mobile client does not show a generation until its bytes and manifest form one complete build.

Bundle publication

The paired desktop publishes the manifest before it serves asset windows. The mobile client can reject an unsupported capability or protocol range before it downloads the build. The bundle comes from the desktop installation through the paired connection; it is not supplied by a remote execution host.

The manifest may describe ordinary chunks or a compressed range stream. The mobile client chooses only a mode the manifest advertises. Route and capability data travel with the build so the shell can decide whether a page may open and which actions it may request.

References: src/…/manifest-contract.ts• L1-185 mobile/…/mobile-web-bundle-operations.ts• L21-54 mobile/…/mobile-web-bundle-reply-schemas.ts• L23-104

Bundle download and cache

The mobile client reads the manifest, fetches the required assets, and checks each asset against the manifest before staging it. It can reuse matching bytes from a verified generation. It also supports compressed ranges when both the host and the phone can decode them, while keeping the final asset length and hash as the source of truth.

The generation store keeps one active build per host and stages a replacement away from the running page. It commits the replacement only when its complete tree is present, keeps the old build when an update fails, and limits retained host generations. Durable app storage protects verified builds from routine cache cleanup; older cache data can be adopted when that storage is first available.

The session cancels abandoned transfers and ignores results from an older host, route, or retry flow. A connected host can update the active build. An unreachable host can use its last verified build, but a host without one remains offline until a build can be fetched.

References: mobile/…/mobile-web-bundle-fetch.ts• L25-87 mobile/…/mobile-web-bundle-fetch.ts• L152-189 mobile/…/mobile-web-bundle-window-checks.ts• L16-80 mobile/…/generation-store.ts• L30-70 mobile/…/generation-store.ts• L152-247 mobile/…/process-generation-store.ts• L7-25 mobile/…/generation-store-directory.ts• L1-13

Bundle activation

Activation gives the shell a verified generation directory and a fresh session identity. The shell serves the entry document and its named assets from that generation. A cached generation can open without a new download; a newer generation replaces it only after the old page no longer reads it.

The user-facing states distinguish host checks, download, opening, route refusal, offline use, protocol blocks, and failure. The shell keeps the opening cover until the document loads, the page sends ready, and the page reports its first painted frame. A failed update can leave the last working generation visible with a notice. A failed document or renderer receives bounded recovery rather than an endless reload loop.

On iOS, the app may prepare one hidden spare document for the next screen when memory and app state allow it. The screen can claim that document and keep its ready state. Memory pressure, backgrounding, or an unclaimed handoff discards the spare, so this optimization does not change the verified generation or security rules.

References: mobile/…/use-mobile-web-shell-session.ts• L66-73 mobile/…/use-mobile-web-shell-session.ts• L118-153 mobile/…/mobile-web-shell-runtime.ts• L8-31 mobile/…/mobile-web-shell-session-effects.ts• L110-185 mobile/…/MobileWebShellScreen.tsx• L304-378 mobile/…/ShellStateScreen.tsx• L108-160 mobile/…/MobileWebShellSparePool.swift• L13-160 mobile/…/spare-document.ts• L9-28

Native web-shell bridge

The native web-shell bridge connects one loaded page to the already authenticated client for one selected host. The page sends framed messages through the shell. The shell validates them, forwards approved desktop requests and streams, and serves approved phone actions locally.

Page bridge channel

The page begins with repeated ready messages. The shell answers with init, which establishes the session and gives the page the current route, host profile, connection state, storage, grants, display settings, and device geometry. Repeated init frames update the same document when the route, keyboard, safe area, locale, or host status changes. A new session identity means a new document and a new handshake.

After the handshake, the channel carries requests, subscriptions, replies, events, cancellation, acknowledgements, route updates, Back presses, and close messages. Both sides enforce the same UTF-8 message limit and limits on pending requests, subscriptions, reply parts, and stream windows. The bridge is bound to the host client chosen by the native screen, so page data cannot select another host.

The page can use typed native verbs for phone-local work such as clipboard, media, audio, storage, PDF, image, speech, accessibility, and device-store actions. Desktop-bound work still waits for the host connection verdict. The shell substitutes the authenticated device identity when a request needs it instead of exposing that identity to page code.

References: mobile/…/bridge-client-init-handshake.ts• L4-51 mobile/…/bridge-host.ts• L29-143 mobile/…/bridge-init-frame.ts• L27-121 mobile/…/bridge-envelope.ts• L144-194 mobile/…/bridge-envelope.ts• L197-317 mobile/…/bridge-native-verbs.ts• L26-63 mobile/…/bridge-native-verbs.ts• L102-217 mobile/…/bridge-rpc-client.ts• L107-171 mobile/…/bridge-rpc-client.ts• L220-361 mobile/…/MobileWebShellBridge.kt• L9-32

Subscription flow control

Subscriptions use acknowledgements and bounded windows so a page that stops reading cannot grow an unlimited native queue. Ordinary streams end when the shell cannot deliver a complete event. A screencast can drop an oversized frame and keep the latest view alive with a drop count.

Terminal output uses stricter ordering. The shell holds output while the page catches up, merges adjacent data without crossing metadata boundaries, and retires the stream only when acknowledgements stop, the bounded backlog is full, or an event cannot fit the bridge frame. Each subscription keeps its own backlog and failure state.

References: mobile/…/bridge-host-subscriptions.ts• L24-31 mobile/…/bridge-host-subscriptions.ts• L69-87 mobile/…/bridge-host-subscriptions.ts• L202-263 mobile/…/bridge-host-subscriptions.ts• L344-398 mobile/…/bridge-terminal-output-backlog.ts• L5-18 mobile/…/bridge-terminal-output-backlog.ts• L71-87 mobile/…/bridge-terminal-output-backlog.ts• L155-293

Capability grants

Capabilities are route-scoped permissions. The shell gives the page the intersection of the packaged route's declarations and the shell's supported actions. It advertises that result in init and checks it again for every request and notification, so a page cannot gain a capability by naming it in a frame.

Navigation, external links, Back, terminal key rails, and device verbs use separate grants. Native actions stay on the phone. A route that needs a server execution host carries that scope in its request envelope, and the shell refuses the request when the session does not grant it. Picked media crosses as short-lived handles and bounded reads rather than as one large bridge reply.

References: mobile/…/bridge-host.ts• L30-56 mobile/…/bridge-host.ts• L147-196 mobile/…/bridge-init-frame.ts• L27-31 mobile/…/bridge-native-verbs.ts• L57-63 mobile/…/bridge-native-verbs.ts• L192-217 mobile/…/bridge-host-contract.ts• L62-140

Route and device-state updates

The shell updates same-screen state without replacing the page. Route changes use the same host-scoped validation as the initial route. A different screen goes through native navigation. The page can clear one-shot route parameters after it applies them, while a newer value remains protected from an older clear request.

The WebView runs edge to edge. The shell sends safe-area, fold, keyboard, color, language, storage, and app-active state through the bridge. The page applies these values to its own layout. A page can claim Back while a sheet is open; the claim ends with the document, but it survives a client rebuild under the same session.

References: mobile/…/bridge-host-route.ts• L9-103 mobile/…/bridge-host.ts• L304-344 mobile/…/bridge-host-back.ts• L1-62 mobile/…/bridge-client-inbound-frames.ts• L58-97 mobile/…/MobileWebShellScreen.tsx• L126-147 mobile/…/MobileWebShellScreen.tsx• L269-289

Document and bridge session boundary

The bridge belongs to one WebView document and one shell session. A remount creates a new session identity and fences old frames, requests, subscriptions, readiness, paint proof, and Back claims. Closing a document settles its page work without closing the shared host client used by other native screens.

The shell treats native cleanup as a sequence rather than one all-or-nothing action. Client close, host disposal, and other owned cleanup steps still run when one step fails. This keeps a failed page from leaving an old bridge or active stream attached to the next document.

References: mobile/…/use-mobile-web-shell-bridge.ts• L39-44 mobile/…/use-mobile-web-shell-bridge.ts• L150-220 mobile/…/use-mobile-web-shell-bridge.ts• L241-351 mobile/…/bridge-rpc-client.ts• L291-304 mobile/…/bridge-host.ts• L196-226 mobile/…/MobileWebShellDocument.kt• L147-202

Web-shell security boundaries

The shell treats the packaged build as local content, not as a general browser. It gives each mount a private origin, serves only the active generation, allows only approved navigation, and blocks page-created network paths. Android and iOS implement the same boundary even though their private origin forms differ.

Per-session origin

Each WebView mount gets a fresh session identity and a private origin. iOS uses the orca-mobile-web scheme. Android uses an HTTPS origin under a reserved .invalid host derived from the session. Asset requests must use the current origin and a manifest path through a plain GET; other schemes, hosts, ports, URL fields, encoded paths, ranges, or excessive URL lengths are refused.

References: mobile/…/index.ts• L16-32 mobile/…/MobileWebShellOrigin.swift• L3-67 mobile/…/MobileWebShellOrigin.kt• L5-69 mobile/…/MobileWebShellDocument.kt• L64-105

Bundle asset serving

The native shell maps an accepted path to the active generation's manifest entry and reads that local asset. It never falls through to the device network. A malformed or missing main document produces a refusal and a visible shell failure instead of exposing an error page as a workspace.

The WebView itself has no file access, persistent web storage, content access, mixed-content path, or automatic window creation. Android returns a refusal response for every intercepted request that it cannot serve, which prevents Chromium from handling the request as a network load.

References: mobile/…/MobileWebShellDocument.kt• L204-236 mobile/…/MobileWebShellDocument.kt• L268-323 mobile/…/MobileWebShellView.swift• L463-567 mobile/…/OrcaMobileWebShellModule.kt• L122-147

The entry document is the only main-frame navigation that the shell loads. New windows, downloads, redirects away from the shell, and other targets are rejected. A user-initiated external link can leave the shell only after the bridge parses and normalizes an allowed absolute URL and the native app opens it.

This policy keeps in-app route changes inside the mounted page and sends routes the page cannot render back to native navigation. It also prevents a path from becoming a file read, a network request, or a move to another origin.

References: mobile/…/MobileWebShellDocument.kt• L314-347 mobile/…/MobileWebShellView.swift• L463-567 mobile/…/index.ts• L24-32 mobile/…/MobileWebShellScreen.tsx• L159-191 mobile/…/MobileWebShellScreen.tsx• L355-362

Content-security policy

The entry document receives a content-security policy that permits same-origin scripts and connections, runtime inline styles, manifest reads, and the image and media sources needed by workspace views. It denies frames, workers, objects, forms, base changes, and frame embedding.

The native layer adds a document-start network fence. It blocks HTTP, HTTPS, WebSocket, secure WebSocket, and service-worker access from the page. The bridge listener is installed only for the committed session origin. If the WebView cannot provide the required isolation features, the shell fails closed and asks for an update instead of loading a weaker page.

References: mobile/…/MobileWebShellCsp.swift• L1-26 mobile/…/MobileWebShellNetworkApiBlocker.kt• L8-32 mobile/…/MobileWebShellBridge.kt• L15-50 mobile/…/MobileWebShellDocument.kt• L116-145 mobile/…/ShellStateScreen.tsx• L20-103

Change checklist

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

  • Change the packaged route tree with route collection, web overrides, host-scoped URLs, route grants, layout ownership, and native fallback behavior in mind.
  • Change the manifest or asset transfer contract with desktop replies, compressed-range choice, byte-window checks, hash checks, staging, cache activation, and compatibility gates in mind.
  • Change generation storage with durable roots, legacy cache adoption, active-reader holds, deferred commits, host removal, and retained-host limits in mind.
  • Change session states or recovery with offline fallback, update notices, document load, page ready, first paint, renderer loss, stale-flow fencing, and spare-document claims in mind.
  • Change bridge frames or grants with page readers, native readers, UTF-8 limits, route updates, device state, Back claims, execution-host scope, and older-page negotiation in mind.
  • Change bridge forwarding with native-only verbs, device identity substitution, host-status holds, cancellation, and unclear desktop delivery outcomes in mind.
  • Change WebView setup on one platform with the other platform's private origin, asset response, navigation, document-start network block, and keyboard inset behavior in mind.
  • Change CSP or document-start scripts with same-origin assets, image and media use, no-network behavior, service-worker access, and fail-closed isolation in mind.

Important failure modes

TriggerConsequenceGuard
The host has no compatible manifest or routeThe packaged page does not openStop at the protocol or route boundary and keep the native surface available
A build changes while asset windows are in flightThe phone could assemble bytes from different buildsMatch build, path, offset, length, and hash facts for every window
An asset is short, long, absent, or has the wrong hashAn incomplete or changed page could be activatedVerify the complete stream before staging and write the manifest last
An update fails while a verified page is activeA newer page is unavailableKeep the old generation active and show an update notice
The host is unreachable with no verified generationThe page cannot openShow the offline state rather than serving empty content
The document loads but never sends ready or first paintThe shell could show a blank page as readyBound each proof and recover once before showing failure
A page falls behind during terminal outputTranscript data could be lost or native memory could grow without limitUse acknowledgements, ordered bounded backlog, merge limits, and stream end reasons
A page sends an ungranted native verb or execution-host requestIt could reach a device action or host scope not promised for the routeIntersect route grants with shell grants and enforce them at dispatch
An old document sends a frame after a remountState could reach the wrong page or host sessionFence frames by session and require a new handshake
A request uses another origin, path form, method, range, or navigation targetThe WebView could read outside the generation or leave the shellApply allow-only origin, manifest-path, asset, and main-frame navigation rules
The WebView lacks a required isolation featureThe page could run with a weaker network boundaryFail closed and show the isolation-unavailable state

Key files

FileWhy to read it
mobile/…/index.tsxShows how the packaged page receives init, installs page services, and mounts the host route tree
mobile/…/web-overrides.jsonShows how native-only services and host routes become page-safe web behavior
mobile/…/MobileWebShellScreen.tsxConnects session state, WebView loading, bridge services, native navigation, device state, and user-facing states
mobile/…/use-mobile-web-shell-session.tsCoordinates host gates, cache, download, activation, deadlines, retries, and stale-flow protection
mobile/…/mobile-web-shell-session-contract.tsDefines the session states and the proofs required before display
mobile/…/mobile-web-bundle-fetch.tsShows how the phone reads, reassembles, and verifies bundle assets
mobile/…/generation-store.tsDefines per-host activation, durable generations, reuse, deferred updates, and cache retention
mobile/…/bridge-host.tsDefines the native-side handshake, grants, route updates, requests, subscriptions, and cleanup
mobile/…/bridge-rpc-client.tsDefines the page-side handshake, requests, streams, native verbs, navigation, Back, and lifecycle
mobile/…/bridge-envelope.tsDefines the framed bridge messages and compatibility rules
mobile/…/bridge-init-frame.tsDefines the session, host, route, storage, device-state, and grant data sent at startup
mobile/…/MobileWebShellDocument.ktShows Android document lifecycle, local asset serving, bridge installation, and request refusal
mobile/…/MobileWebShellView.swiftShows the matching iOS WebView boundary and navigation behavior
mobile/…/MobileWebShellNetworkApiBlocker.ktDefines Android's document-start network and service-worker block
mobile/…/MobileWebShellCsp.swiftDefines the response policy for the private bundle origin