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.
| Boundary | Purpose | Result |
|---|---|---|
| Main process | Owns startup, OS access, windows, services, and privileged handlers | Native work has one trusted owner |
| Preload | Exposes typed methods and events to page code | The UI uses approved capabilities without raw Electron access |
| Renderer | Owns views, user intent, and visible state | Users work through one product surface |
| Shared contracts | Define request shapes, results, limits, identity, and compatibility | Local and remote callers follow the same rules |
| Runtime and relay | Connect the product surface to the service that executes work | Local and paired work use one product model |
| Browser guests | Host web content under narrower policies | Web 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
Related pages
- Desktop renderer experience
- Relay protocol and transport
- Desktop persistence and lifecycle
- Browser automation and embedded web
- Command-line and headless runtime
Change checklist
When these files or sections are changed, remember to consider these:
- Keep a new or changed capability aligned across its preload method,
PreloadApitype, 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
webContentswhen adding host-to-renderer request and reply flows.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A preload method has no matching host handler or shared schema | The UI request fails or sends data the host cannot parse | Treat the preload type, bridge, handler, and schema as one contract |
| A web client treats an optional desktop capability as present | The UI offers an action that cannot own a window, profile, or native resource | Use absent or degraded results for host-only capabilities |
| An extension or preview call skips manifest, frame, grant, or sender checks | Guest code can invoke an API or receive an event outside its authority | Recheck guest identity and context in the host |
| A paired browser or file request loses its environment identity | Work can run on the wrong host or use the wrong browser profile | Carry the owning environment through the shared request and host route |
| A browser host or page generation becomes stale | A paired command changes a replaced page or retired guest | Match the lease, host generation, page generation, renderer identity, and page authority |
| A terminal, agent, or browser command uses stale identity | The host changes a replaced terminal, old session, or closed page | Require handles, incarnation or revision data, page ownership, and host-side rechecks |
| A remote response has the wrong identity or cannot be validated | The request is rejected and the client reports a remote runtime failure | Validate the frame and match the response ID and runtime identity |
| A runtime event is treated as a direct state update without ownership | A client shows state from another environment or stale host | Scope events and make clients re-read authoritative state |
| A provider process tree is killed without an ownership verdict | A child can remain alive or a later process can be killed by mistake | Prove process identity and inspect the teardown verdict |
| An ACP provider closes before output drains | A final response is lost or an active call remains unresolved | Wait for bounded output drain and then report the provider exit |
| A desktop browser bridge runs while the host route is not prepared | A remote host can reach the desktop's network or a forbidden page | Require negotiated capability, routed browsing, workspace scope, and the method allowlist |
| A browser or event listener survives its owner | Stale pages receive events or old helper work keeps running | Close on reload, replacement, disconnect, revocation, and quit |
| Headless mode reports browser support before its backend is ready | Automation starts against a provider that cannot serve a page | Publish readiness only after the browser backend is usable |
| Saved window bounds are too small or no longer visible | The main window can open without a reachable title bar | Validate saved bounds and use a safe display-sized default |
| Main-window loading fails without an observer result | Startup or recovery can wait for a state that never arrives | Observe both load success and failure and record a bounded failure state |
| OS-opened documents arrive before the renderer listener | The user loses the file-open action during startup | Buffer the paths until listener readiness and restore them after delivery failure |
| A renderer reply comes from a replacement window | An old host request can accept an unrelated answer | Match both the request ID and the targeted webContents |
Key files
| File | Why to read it |
|---|---|
| src/…/index.ts | Shows app activation, OS-opened document handling, startup recovery, and readiness. |
| src/…/main-process-ready-foundation.ts | Shows profile, browser-session, and host foundation setup. |
| src/…/main-process-ready-runtime.ts | Shows runtime, browser automation, and service startup after the foundation. |
| src/…/main-process-runtime-service.ts | Shows how the desktop runtime owns local work and paired browser state. |
| src/…/main-process-relay-startup.ts | Shows how the desktop relay is installed and fenced. |
| src/…/electron-native-services.ts | Shows which native services exist only in the Electron host. |
| src/…/createMainWindow.ts | Shows the main renderer trust boundary, preload setup, window recovery, and load lifecycle. |
| src/…/main-window-webview-security.ts | Shows admission and hardening for browser, preview, extension, and plugin guests. |
| src/…/renderer-reply-request.ts | Shows request identity and renderer lifetime checks for host-to-UI requests. |
| src/…/index.ts | Shows how named desktop capabilities become window.api. |
| src/…/api-types.ts | Defines the page-facing capability shape and optional desktop services. |
| src/…/runtime-api.ts | Defines local and paired runtime calls, subscriptions, and capability fallbacks. |
| src/…/browser-api.ts | Defines the browser guest, session, extension, and page-control boundary. |
| src/…/rpc-params-catalog.generated.ts | Maps runtime methods to the schemas used by the host. |
| src/…/host-runtime-capabilities.ts | Defines capabilities published by paired hosts. |
| src/…/electron-remote-runtime-client-capabilities.ts | Defines desktop client capabilities during runtime negotiation. |
| src/…/web-runtime-client-capabilities.ts | Defines the reduced web client capability set. |
| src/…/runtime-browser-contracts.ts | Defines browser results, page identity, snapshots, and failure codes. |
| src/…/desktop-browser-bridge-protocol.ts | Defines the narrow browser bridge for remote hosts. |
| docs/desktop-renderer-experience.md | Explains the renderer's product views and user flows. |
| docs/relay-protocol-and-transport.md | Explains remote framing and relay session behavior. |
| docs/desktop-persistence-and-lifecycle.md | Explains saved desktop state and lifecycle rules. |
| docs/browser-automation-and-embedded-web.md | Explains browser providers, guests, and automation. |
| docs/command-line-and-headless-runtime.md | Explains headless startup and readiness. |