Knowledge Base updated: 2026-11-19
Orca knowledge base
Orca is an Electron-based coding-agent workspace with desktop, mobile, cloud relay, CLI, and automation surfaces.
The desktop main process owns native capabilities, persisted local state, runtime coordination, and browser/terminal resources. Renderers and mobile clients consume those capabilities through constrained IPC, relay, and remote transport contracts.
Critical state spans local workspace/session metadata, terminal and agent runtime state, AI Vault data, bot records, credentials, and cloud relay continuity records.
flowchart TD
Desktop[Electron desktop]
Renderer[Renderer UI]
Preload[Preload contracts]
Main[Main process]
Relay[Local relay]
Agents[Agent runtimes]
ACP[ACP sessions]
Terminal[PTY terminal runtime]
Browser[Managed browser]
Vault[AI Vault]
Git[Git and reviews]
Remote[Remote runtime transport]
Mobile[Expo mobile client]
Cloud[Cloud relay and push]
Bots[Bot orchestration]
Renderer --> Preload --> Main
Main --> Relay
Relay --> Agents
Relay --> Terminal
Main --> Browser
Main --> Vault
Main --> Git
Agents --> ACP
Main <--> Remote <--> Cloud
Mobile <--> Cloud
Main <--> Cloud
Bots <--> Main
Bots <--> Cloud
Glossary
- ACP — Agent Protocol Client integration used to acquire and operate structured agent sessions.
- AI Vault — isolated session-data and transcript service used by Orca runtime flows.
- Relay — local protocol server that exposes runtime, filesystem, Git, and stream operations to clients.
- Execution host — local or remote machine selected to run workspace services and agent-capable workloads.
- Worktree — Git working directory managed alongside workspace session ownership and cleanup metadata.
Invariants
- Renderer code reaches privileged desktop capabilities only through preload/shared contracts; evidence:
src/preload/**andsrc/shared/**. - PTY consumers are coordinated through replay, ownership, and flow-control mechanisms; evidence:
src/main/pty/**andsrc/main/relay/**. - Agent session presentation is derived from provider/ACP lifecycle state rather than renderer-owned process control; evidence:
src/main/acp/**andsrc/main/agent-hooks/**. - Workspace and worktree retirement must preserve ownership and cleanup safety; evidence:
src/main/workspaces/**andsrc/main/worktrees/**. - Remote clients reconnect through authenticated transport and continuity mechanisms rather than directly owning local runtime resources; evidence:
src/main/remote/**andcloud/**.
Routing table
src/main/**,src/preload/**,src/shared/**-> docs/desktop-app-platform.mdsrc/renderer/**-> docs/desktop-renderer-experience.mdsrc/main/relay/**,src/shared/relay/**-> docs/relay-protocol-and-transport.mdsrc/main/persistence/**,src/main/lifecycle/**,src/main/state/**-> docs/desktop-persistence-and-lifecycle.mdsrc/main/agent-*/**,src/main/workspaces/**-> docs/agent-workspaces.mdsrc/main/agent-hooks/**,src/main/agent-launch/**-> docs/agent-integrations-and-hooks.mdsrc/main/acp/**-> docs/agent-protocol-client-sessions.mdsrc/main/workspaces/**,src/main/worktrees/**-> docs/workspace-and-worktree-lifecycle.mdsrc/main/ai-vault/**-> docs/ai-vault-sessions.mdsrc/main/terminal/**,src/main/pty/**-> docs/terminal-runtime.mdsrc/main/pty/**,src/main/relay/pty/**-> docs/pty-streaming-and-recovery.mdsrc/main/git/**,src/main/github/**,src/main/bitbucket/**-> docs/source-control-and-reviews.mdsrc/main/git/**,src/shared/git/**,src/main/relay/git/**-> docs/git-operations-and-status.mdsrc/main/source-control/**,src/main/ai-review/**-> docs/source-control-ai-workflows.mdsrc/main/remote/**,src/main/ssh/**-> docs/remote-connectivity.mdsrc/main/pairing/**,src/shared/pairing/**-> docs/pairing-and-device-trust.mdsrc/main/remote/**,src/shared/remote/**-> docs/remote-runtime-transport.mdmobile/**-> docs/mobile-client.mdmobile/**/session/**,mobile/**/terminal/**-> docs/mobile-sessions-and-terminal.mdmobile-web/**,mobile/**/web/**-> docs/mobile-web-delivery.mdcloud/**,infrastructure/**-> docs/cloud-services.mdcloud/**/relay/**,cloud/**/continuity/**-> docs/cloud-relay-admission-and-continuity.mdcloud/**/push/**,mobile/**/notifications/**-> docs/push-notification-delivery.mdcloud/**/ops/**,infrastructure/**,.github/workflows/**-> docs/cloud-operational-deployment-controls.mdsrc/main/native-chat/**,src/main/conversations/**-> docs/native-agent-conversations.mdsrc/cli/**,src/headless/**,src/main/backend/**-> docs/command-line-and-headless-runtime.mdsrc/main/automations/**-> docs/automation-services.mdsrc/main/jira/**,src/renderer/**/jira/**,mobile/**/jira/**-> docs/jira-work-management.mdsrc/main/browser/**,src/main/browser-passwords/**-> docs/browser-automation-and-embedded-web.mdsrc/main/plugins/**,src/shared/plugins/**-> docs/plugin-platform.mdsrc/main/plugins/**,src/renderer/**/plugins/**-> docs/plugin-lifecycle-and-contributions.mdsrc/main/bots/**,src/shared/bots/**-> docs/bot-orchestration.mdsrc/main/bots/**,src/main/automations/**,mobile/**/bots/**-> docs/bot-conversations-and-automation.md