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 / desktop-app-platform

Desktop application platform

The desktop application platform gives Orca one product surface for local work, paired runtimes, embedded web pages, and headless use. The Electron main process owns native authority. The preload bridge exposes approved capabilities to the renderer. Shared contracts keep local and remote work aligned.

Platform boundaries

The platform separates visible product work from native authority and external web content. The renderer states user intent. The main process checks that intent and connects it to local services, paired runtimes, or browser guests.

BoundaryPurposeResult
Main processOwns startup, OS access, windows, services, and privileged handlersNative work has one trusted owner
PreloadExposes typed methods and events to page codeThe UI uses approved capabilities without raw Electron access
RendererOwns views, user intent, and visible stateUsers work through one product surface
Shared contractsDefine request shapes, results, limits, identity, and compatibilityLocal and remote callers follow the same rules
Runtime and relayConnect the product surface to the service that executes workLocal and paired work use one product model
Browser guestsHost web content under narrower policiesWeb content does not inherit app authority

The main process decides whether a caller may perform privileged work. The renderer presents the result. This lets local, paired, web, and headless clients share product behavior while native-only actions remain absent or degraded where they do not apply.

This diagram shows the main paths from a UI request to local work, paired work, or a controlled browser page.

flowchart LR
    UI[Renderer intent] --> P[Typed preload bridge]
    P --> M[Electron main process]
    M --> C[Shared contract]
    C --> L[Local runtime]
    C --> R[Paired runtime]
    R --> T[Authenticated relay]
    M --> B[Browser guest]

Process build products

The desktop build keeps the main process, preload bridge, renderer, and worker code as separate execution products. Native work stays in the host. Page work stays in the renderer. Only the approved preload surface crosses between them.

References: electron.vite.config.ts• L209-317

Main process

The main process is the trusted host for the desktop application. It controls activation, startup, windows, local services, runtime connections, browser guests, and shutdown.

Startup and activation

Startup prepares profile state and host services before the application accepts work. It handles deep links, OS-opened files, duplicate launches, background or headless modes, and recovery when saved state is unsafe.

Readiness has ordered stages. The host prepares the profile and browser foundations before it starts runtime services. It waits for required barriers before the renderer restores saved work. OS-opened documents wait for renderer listener readiness, so a cold launch does not lose a file-open request. A duplicate headless launch does not create a desktop window.

References: src/…/index.ts• L90-147 src/…/index.ts• L183-217 src/…/main-process-ready-foundation.ts• L69-181 src/…/main-process-ready-runtime.ts• L62-107

Native capability ownership

Native capability ownership means that page code asks the host to perform work that needs the OS, credentials, files, processes, or native windows. The host checks the caller and maps each named request to the service that owns it.

The capability surface covers workspaces, repositories, Git, terminals, agents, accounts, settings, browsers, plugins, updates, diagnostics, and system actions. The renderer does not choose private host paths or bypass the service that applies policy.

References: src/…/index.ts• L115-216 src/…/api-types.ts• L99-207 src/…/electron-native-services.ts• L18-34

Window and guest isolation

The application renderer and embedded web content are different trust zones. The main window uses a sandboxed renderer and a dedicated preload. Browser pages, document previews, plugin frames, and extension pages receive narrower bridges or no application bridge.

The host admits a guest only when its source, partition, identity, and context match an allowed policy. It removes inherited preload and Node access from browsing guests. A guest cannot replace the application renderer or gain unrestricted native calls.

References: src/…/createMainWindow.ts• L126-173 src/…/main-window-webview-security.ts• L85-117 src/…/main-window-webview-security.ts• L123-209

Window lifecycle

The host creates the main window from validated saved state and loads the renderer with an observed success or failure result. It keeps privileged UI actions tied to the current renderer and removes window-scoped handlers and listeners when that renderer closes.

Reload, system resume, native resource cleanup, and close follow the same ownership rule. A renderer that disappears cannot leave a pending host request or an old window claim active.

References: src/…/createMainWindow.ts• L55-80 src/…/createMainWindow.ts• L82-181 src/…/createMainWindow.ts• L205-266 src/…/attach-main-window-services.ts• L199-203

Preload bridge

The preload bridge is the narrow interface between trusted host code and page code. src/…/index.ts assembles domain APIs and exposes the typed window.api object through contextBridge when context isolation is active.

Capability surface

The surface groups related actions behind domain names. Each method carries product data instead of a raw IPC channel. Event methods return an unsubscribe function so the renderer can end long-lived listeners.

The groups cover these product areas:

  • Workspaces, repositories, files, Git, terminals, and runtimes.
  • Agent sessions, accounts, credentials, skills, hooks, and automations.
  • Browser pages, sessions, profiles, extensions, downloads, and DevTools.
  • Settings, hosted review, issue work, telemetry, updates, diagnostics, and UI controls.
  • Desktop-only services such as WSL, SSH, shells, virtual machines, and native chat.

Optional members and safe fallbacks let web or paired clients keep the shared API shape without claiming desktop authority. A client can detect that a desktop-only method is absent instead of assuming that every host supports it.

References: src/…/index.ts• L102-226 src/…/api-types.ts• L99-207 src/…/runtime-api.ts• L39-204

Capability safety

Capability safety comes from a narrow method shape and a host-side check. The preload sends serializable request data. The main process remains responsible for caller admission, target checks, credentials, paths, and final policy.

Subscriptions and streams have a defined end. Reloads, destroyed renderers, disconnected runtimes, changed pairings, and quit retire old listeners and work instead of sending data to stale UI.

References: src/…/index.ts• L218-226 src/…/runtime-api.ts• L34-55 src/…/renderer-reply-request.ts• L8-63

Specialized guest bridges

Specialized guest bridges preserve useful browser behavior without exposing the main application API. Extension pages receive a browser-shaped surface. Document previews receive a grant-bound surface that cannot become a general browsing caller.

The host still checks the extension manifest, calling frame, request context, preview grant, and document identity. A preview can report an approved external link, but it does not become a network-capable browser tab by default.

References: src/…/browser-extension-api-surface.ts• L14-35 src/…/main-window-webview-security.ts• L152-209 src/…/doc-preview-guest-policy.ts• L80-172

Renderer boundary

The renderer is the user-facing product surface. It turns user intent into calls on window.api, combines results with visible state, and does not need to know whether execution is local, paired, or headless.

The renderer boundary keeps presentation separate from execution location. For workspace views, navigation, editor state, and user flows, see Desktop renderer experience.

Web capability fallback

Web clients use the same product ideas through a reduced capability surface. A web client can route supported work to a runtime. Desktop-only actions return a safe absence or degraded result.

This fallback is a client boundary, not a second native authority. It prevents a browser page from pretending that it owns an Electron guest, local profile, extension, or native window.

References: src/…/electron-remote-runtime-client-capabilities.ts• L24-50 src/…/web-runtime-client-capabilities.ts• L25-46 src/…/api-types.ts• L187-205

Shared contracts

Shared contracts define the meaning of requests and results that cross IPC or a runtime connection. They keep clients and hosts aligned on identity, target, limits, mutation intent, and compatibility.

Request and result contracts

Contracts validate the shape of work before the host acts. They favor stable selectors and explicit scope over private paths or client-selected credentials. The host still resolves the final path, resource owner, and policy.

The contract catalog spans the main product flows:

  • Files, staged saves, downloads, uploads, previews, and workspace paths.
  • Git inspection and mutation, hosted review, and worktree creation.
  • Terminal handles, viewport bounds, shell choices, and terminal limits.
  • Agent identity, execution location, mutation envelopes, and revisions.
  • Browser navigation, input, tabs, cookies, profiles, screenshots, and storage.

The generated catalog maps each runtime method to the schema that parses its parameters. Clients use shared types without rewriting wire data before the host validates it.

References: src/…/rpc-params-catalog.generated.ts• L1035-1045 src/…/rpc-params-catalog.generated.ts• L1317-1409 src/…/rpc-params-catalog.generated.ts• L1445-1509

Capability and compatibility signals

Capability signals tell a client which work a host can perform. Limits and degraded results let the client hide an action or explain its absence instead of guessing from missing data.

Runtime responses carry request identity and runtime identity. Keepalive frames and additive fields let independently updated peers remain connected while still rejecting a response meant for another runtime. Desktop, web, and host capability lists make differences explicit during pairing.

References: src/…/host-runtime-capabilities.ts• L10-44 src/…/account-runtime-capabilities.ts• L1-41 src/…/electron-remote-runtime-client-capabilities.ts• L24-50

Runtime and relay boundary

The runtime boundary separates the product surface from the service that owns terminals, workspaces, browser sessions, agent work, and host state. The local path stays in the desktop host. The paired path reaches a named runtime through an authenticated connection.

Local and paired execution

Local requests use the host service behind the preload bridge. Paired requests name a saved environment and carry the identity needed to reach its owner. The result model remains product-facing, so the renderer does not change its core behavior based on execution location.

The desktop runtime service owns host-local state and exposes the same product operations to paired clients. It can restore client-hosted browser pages and connect browser actions to the owning runtime rather than to the calling UI.

References: src/…/main-process-runtime-service.ts• L67-177 src/…/runtime-api.ts• L39-190 src/…/electron-native-services.ts• L18-34

Relay transport role

The relay carries authenticated remote traffic. It is not a second product authority. The runtime host owns work and state. The relay moves control, data, file, Git, terminal, browser, and event traffic between paired peers.

Capability negotiation and runtime identity keep mixed client and host versions explicit. Runtime events tell a paired client to re-read changed state instead of granting the event ownership of that state.

For framing, request dispatch, backpressure, and session transport, see Relay protocol and transport.

References: src/…/main-process-relay-startup.ts• L8-22 src/…/host-runtime-capabilities.ts• L28-44 src/…/runtime-rpc-call-queue.ts• L1-160

Renderer request lifetime

Host-to-renderer requests use a request ID and accept a reply only from the targeted window. The request ends when the renderer replies, the window closes, the renderer disappears, or the timeout expires.

This rule matters for native prompts, browser handoffs, and other work that needs a visible UI answer. It prevents a replacement renderer from answering an old request after reload or window replacement.

References: src/…/renderer-reply-request.ts• L8-63 src/…/main-process-ipc-bootstrap.ts• L79-132

Provider process boundary

Provider processes are external execution services. The host treats their lifetime as observed state instead of assuming that a sent stop signal proves that the process tree stopped.

This boundary preserves distinct outcomes for a clean stop, a missing executable, a lost connection, an unverified descendant tree, and an orphaned supervised group. The agent UI and later cleanup can then follow what the host actually knows.

References: src/…/acp-agent-connection.ts• L106-220 src/…/provider-process-teardown.ts• L14-18 src/…/provider-group-orphan-guard.ts• L45-77

Desktop browser bridge

The desktop browser bridge lets an opted-in paired or SSH-hosted runtime control approved browser actions in a desktop workspace. It is a narrow browser path, not a general desktop relay.

The desktop checks the negotiated capability, method allowlist, browser route, workspace scope, page ownership, cancellation, and host revocation before dispatch. It removes desktop identity and placement choices from tab creation. It refuses actions that would widen host authority, such as local-file access, clipboard paste, and profile changes.

For relay framing and attachment behavior, see Relay protocol and transport.

References: src/…/desktop-browser-bridge-protocol.ts• L1-128 src/…/desktop-browser-bridge-executor.ts• L70-192

Browser host delegation

Browser host delegation lets a paired runtime use browser pages owned by this desktop when the desktop holds the required host role. The lease, host generation, page generation, and page identity keep commands tied to the current owner.

The desktop admits only approved browser commands through this path. It rejects stale authority, retired pages, changed renderers, unsupported file routes, and revoked access. Cleanup retires the guest and automation session when the page closes or its renderer changes.

References: src/…/browser-client-page-command-execution.ts• L20-115 src/…/browser-client-page-automation-runtime.ts• L47-123

Browser automation boundary

Browser automation is a host capability that lets Orca inspect and control web pages. Desktop guests use controlled browser sessions. Paired clients can use a host browser through the runtime without receiving Electron objects or process access.

Embedded web guests

Embedded web guests are external or preview content, not application code. The host keeps their navigation, profiles, permissions, downloads, prompts, DevTools actions, and page events inside a browser-specific boundary.

The browser bridge exposes guest registration, page interaction, session profiles, cookies, extensions, and UI events. It also carries agent focus and cursor events so automation acts on the right page without turning page code into a native caller.

For browser sessions, navigation, network routes, extensions, and preview behavior, see Browser automation and embedded web.

References: src/…/browser-api.ts• L82-116 src/…/browser-api.ts• L167-215 src/…/main-window-webview-security.ts• L211-239

Browser automation contracts

Automation requests use explicit page targets and bounded inputs. The shared contract covers navigation, element actions, keyboard and mouse input, waits, screenshots, screencasts, cookies, storage, device settings, network controls, and tab selection.

Results report page identity and clear failure states. They can also describe page changes, new tabs, popups, downloads, console errors, and whether the page settled. This gives clients useful state without exposing browser internals.

References: src/…/runtime-browser-contracts.ts• L11-57 src/…/runtime-browser-contracts.ts• L59-132 src/…/runtime-browser-contracts.ts• L258-279

Extension and preview contexts

Extensions receive a browser-compatible API only when their manifest and context permit it. The host validates calls and events rather than trusting the surface list in the preload. Content scripts and workers use filtered paths so one extension or document cannot act as another.

Document previews use a separate file grant and do not inherit the application bridge. Preview navigation stays bound to that grant. External links require a trusted preload report and do not turn the document into a network-capable browser tab by default.

References: src/…/browser-extension-api-surface.ts• L14-35 src/…/main-window-webview-security.ts• L58-83 src/…/doc-preview-guest-policy.ts• L80-172

Headless browser support

Headless mode exposes browser automation only after its browser backend is usable. If the host cannot provide the required display or browser provider, the runtime reports an unavailable capability instead of claiming that automation works.

Headless automation still uses bounded output and target-aware dispatch. This keeps command-line work aligned with desktop work while avoiding a desktop window requirement. For command-line startup, readiness, and headless execution, see Command-line and headless runtime.

References: src/…/runtime-browser-contracts.ts• L260-279 src/…/remote-runtime-client-capabilities.ts• L28-54 src/…/headless-dispatch.ts• L9-85

Change checklist

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

  • Keep a new or changed capability aligned across its preload method, PreloadApi type, main handler, shared request schema, capability signal, and web fallback.
  • Keep browser guest, extension, preview, and browser-host surfaces aligned with host checks for origin, frame, manifest, profile, grant, lease, and page lifetime.
  • Keep optional desktop-only methods absent or degraded on clients that do not host native windows or browser guests.
  • Keep staged file saves, terminal handles, agent mutations, worktree creation, and browser commands bounded by shared limits and target identity rules.
  • Regenerate rpc-params-catalog.generated.ts when a shared method or schema changes.
  • Keep paired browser and file operations tied to the owning environment rather than the calling client.
  • Preserve listener unsubscribe, socket close, and browser-session retirement paths when adding an event or subscription.
  • Keep OS-opened document buffering and startup activation behavior aligned with renderer readiness.
  • Keep main, preload, renderer, and worker entry points aligned when changing the Electron build so a capability does not move into the wrong trust zone.
  • Keep the main window's sandbox, preload entry point, and trusted-renderer checks aligned when changing privileged UI actions or window creation.
  • Keep provider exit, sign-in, spawn-absence, and output-drain results distinct when changing agent process or ACP handling.
  • Keep provider-tree cleanup tied to proof of process ownership. A delivered kill signal is not proof that every descendant exited.
  • Keep runtime response identity, capability negotiation, and event compatibility aligned when changing a remote method or stream.
  • Keep desktop browser bridge method allowlists, routing rules, workspace scope, cancellation, and host revocation aligned.
  • Keep renderer request IDs tied to the targeted webContents when adding host-to-renderer request and reply flows.

Important failure modes

TriggerConsequenceGuard
A preload method has no matching host handler or shared schemaThe UI request fails or sends data the host cannot parseTreat the preload type, bridge, handler, and schema as one contract
A web client treats an optional desktop capability as presentThe UI offers an action that cannot own a window, profile, or native resourceUse absent or degraded results for host-only capabilities
An extension or preview call skips manifest, frame, grant, or sender checksGuest code can invoke an API or receive an event outside its authorityRecheck guest identity and context in the host
A paired browser or file request loses its environment identityWork can run on the wrong host or use the wrong browser profileCarry the owning environment through the shared request and host route
A browser host or page generation becomes staleA paired command changes a replaced page or retired guestMatch the lease, host generation, page generation, renderer identity, and page authority
A terminal, agent, or browser command uses stale identityThe host changes a replaced terminal, old session, or closed pageRequire handles, incarnation or revision data, page ownership, and host-side rechecks
A remote response has the wrong identity or cannot be validatedThe request is rejected and the client reports a remote runtime failureValidate the frame and match the response ID and runtime identity
A runtime event is treated as a direct state update without ownershipA client shows state from another environment or stale hostScope events and make clients re-read authoritative state
A provider process tree is killed without an ownership verdictA child can remain alive or a later process can be killed by mistakeProve process identity and inspect the teardown verdict
An ACP provider closes before output drainsA final response is lost or an active call remains unresolvedWait for bounded output drain and then report the provider exit
A desktop browser bridge runs while the host route is not preparedA remote host can reach the desktop's network or a forbidden pageRequire negotiated capability, routed browsing, workspace scope, and the method allowlist
A browser or event listener survives its ownerStale pages receive events or old helper work keeps runningClose on reload, replacement, disconnect, revocation, and quit
Headless mode reports browser support before its backend is readyAutomation starts against a provider that cannot serve a pagePublish readiness only after the browser backend is usable
Saved window bounds are too small or no longer visibleThe main window can open without a reachable title barValidate saved bounds and use a safe display-sized default
Main-window loading fails without an observer resultStartup or recovery can wait for a state that never arrivesObserve both load success and failure and record a bounded failure state
OS-opened documents arrive before the renderer listenerThe user loses the file-open action during startupBuffer the paths until listener readiness and restore them after delivery failure
A renderer reply comes from a replacement windowAn old host request can accept an unrelated answerMatch both the request ID and the targeted webContents

Key files

FileWhy to read it
src/…/index.tsShows app activation, OS-opened document handling, startup recovery, and readiness.
src/…/main-process-ready-foundation.tsShows profile, browser-session, and host foundation setup.
src/…/main-process-ready-runtime.tsShows runtime, browser automation, and service startup after the foundation.
src/…/main-process-runtime-service.tsShows how the desktop runtime owns local work and paired browser state.
src/…/main-process-relay-startup.tsShows how the desktop relay is installed and fenced.
src/…/electron-native-services.tsShows which native services exist only in the Electron host.
src/…/createMainWindow.tsShows the main renderer trust boundary, preload setup, window recovery, and load lifecycle.
src/…/main-window-webview-security.tsShows admission and hardening for browser, preview, extension, and plugin guests.
src/…/renderer-reply-request.tsShows request identity and renderer lifetime checks for host-to-UI requests.
src/…/index.tsShows how named desktop capabilities become window.api.
src/…/api-types.tsDefines the page-facing capability shape and optional desktop services.
src/…/runtime-api.tsDefines local and paired runtime calls, subscriptions, and capability fallbacks.
src/…/browser-api.tsDefines the browser guest, session, extension, and page-control boundary.
src/…/rpc-params-catalog.generated.tsMaps runtime methods to the schemas used by the host.
src/…/host-runtime-capabilities.tsDefines capabilities published by paired hosts.
src/…/electron-remote-runtime-client-capabilities.tsDefines desktop client capabilities during runtime negotiation.
src/…/web-runtime-client-capabilities.tsDefines the reduced web client capability set.
src/…/runtime-browser-contracts.tsDefines browser results, page identity, snapshots, and failure codes.
src/…/desktop-browser-bridge-protocol.tsDefines the narrow browser bridge for remote hosts.
docs/desktop-renderer-experience.mdExplains the renderer's product views and user flows.
docs/relay-protocol-and-transport.mdExplains remote framing and relay session behavior.
docs/desktop-persistence-and-lifecycle.mdExplains saved desktop state and lifecycle rules.
docs/browser-automation-and-embedded-web.mdExplains browser providers, guests, and automation.
docs/command-line-and-headless-runtime.mdExplains headless startup and readiness.