Understanding the Orca Model Architecture: Electron-Based AI Development Environment

The Orca model architecture is a cross-platform desktop application built on Electron that separates the React-based UI (renderer process) from a Node.js agent runtime via a typed relay message bus, enabling both local and remote AI agent execution.

The stablyai/orca repository implements a sophisticated architecture for AI-enhanced software development. Its design combines the cross-platform capabilities of Electron with a multi-process runtime system that manages workspace sessions, agent orchestration, and model selection across local and remote environments.

Core Architectural Layers

Electron Main Process

The main process serves as the application entry point and system integration layer. It boots the application, creates the browser window, and handles native OS features such as menus and file associations.

• src/main/main.ts – Bootstraps the Electron application and initializes the browser window (source)
• src/main/menu.ts – Defines platform-aware accelerators and native menu structures

Renderer Process (React UI)

The renderer process presents the user interface as a React application running inside Electron's Chromium environment. It manages workspaces, terminals, and browser panes while communicating with the main process through the shared runtime.

• src/renderer/App.tsx – Root React component that mounts the application UI (source)
• src/renderer/src/assets/main.css – Contains canonical design tokens and styling variables

Shared Runtime Layer

The shared runtime contains TypeScript logic used by both the main and renderer processes. It defines core data structures, agent specifications, and bootstrap utilities that ensure type safety across process boundaries.

Key files include:

• src/shared/workspace-session-schema.ts – Defines the workspace session schema for persistence and state management (source)
• src/shared/types.ts – Core TypeScript interfaces including model selection and thinking effort levels (low/medium/high)
• src/shared/runtime-bootstrap.ts – Bootstrap utilities for initializing the runtime environment (source)
• src/shared/agents-orchestration-steps.ts – Logic for coordinating multi-step agent workflows (source)

Relay and Communication Layer

The relay layer establishes a bidirectional message bus between the UI and agent runtime. It handles protocol translation, streaming data management, and pseudo-terminal (PTY) operations for interactive subprocesses.

• src/relay/relay.ts – Core message bus implementation routing commands between processes (source)
• src/relay/protocol.ts – Streaming protocol definitions for agent communication
• src/relay/pty-handler.ts – Manages PTY subprocesses for interactive terminal sessions (source)

Agent Runtime Environment

The agent runtime executes AI agents in isolated Node.js subprocesses. It discovers available models, validates capabilities against task requirements, and streams execution results back to the UI.

• src/cli/runtime-client.ts – CLI client that interfaces with the agent runtime (source)
• src/shared/commit-message-agent-spec.ts – Specification for the commit-message agent and static model registry (source)
• src/shared/task-providers.ts – Typed task definitions for agent invocations

Remote Runtime Support (SSH)

Orca extends its architecture to remote workspaces via SSH, allowing agents to execute on remote machines while presenting a unified local interface.

• src/shared/ssh-types.ts – TypeScript definitions for SSH connections and remote workspace management (source)
• src/shared/remote-runtime-request-websocket.ts – WebSocket proxy for remote runtime communication

Execution Flow: From UI to Agent

Understanding the Orca model architecture requires tracing how user actions propagate through the system:

1. Application Startup – src/main/main.ts launches the Electron main process, which loads the renderer entry point (src/renderer/index.html)

2. Workspace Initialization – User actions create a workspace session defined in workspace-session-schema.ts, persisted across processes via the shared runtime

3. Agent Request – When invoking an AI feature (e.g., "Generate commit message"), the renderer sends a request through the relay (relay.ts)

4. Model Resolution – The runtime consults commit-message-agent-spec.ts to determine model availability and validates against the thinking effort selection (low/medium/high) defined in types.ts

5. Subprocess Execution – The agent runs in an isolated subprocess managed by pty-handler.ts, streaming output through the relay back to the UI

6. Remote Execution – For SSH workspaces, ssh-types.ts proxies the protocol over WebSocket, making remote agents appear identical to local ones

7. Telemetry and Features – Events emit through telemetry-events.ts, potentially triggering feature prompts via feature-wall-tiles.ts

Key Implementation Files

Component	Purpose	GitHub Link
src/main/main.ts	Main process entry point	View source
src/renderer/App.tsx	React root component	View source
src/shared/workspace-session-schema.ts	Workspace state definition	View source
src/shared/runtime-bootstrap.ts	Runtime initialization	View source
src/relay/relay.ts	Message bus core	View source
src/relay/pty-handler.ts	PTY subprocess management	View source
src/cli/runtime-client.ts	Agent CLI client	View source
src/shared/commit-message-agent-spec.ts	Agent model registry	View source
src/shared/ssh-types.ts	Remote runtime types	View source

Practical Code Examples

Running an Agent Command from the Renderer

Invoke the commit-message agent using the bootstrap utility:

import { runAgentCommand } from '@/shared/runtime-bootstrap';

// Generate a commit message using the "sonnet" model
await runAgentCommand({
  agentId: 'commit-message',
  model: 'sonnet',
  args: ['--prompt', 'Add login flow'],
});

Opening a Remote Workspace via SSH

Connect to remote environments using the SSH abstraction layer:

import { openRemoteWorkspace } from '@/shared/ssh-types';

await openRemoteWorkspace({
  host: 'example.com',
  user: 'dev',
  path: '/home/dev/project',
});

Listening to Agent Output in React

Subscribe to real-time agent streams in the UI:

function AgentOutput() {
  const [output, setOutput] = useState('');

  useEffect(() => {
    const unsub = window.__orcaRuntime?.on('agent-output', (data) => {
      setOutput((prev) => prev + data);
    });
    return unsub;
  }, []);

  return <pre>{output}</pre>;
}

Summary

• The Orca model architecture separates concerns across Electron main/renderer processes, a shared TypeScript runtime, and a relay message bus
• AI agents execute in isolated subprocesses managed by the runtime client and PTY handler, enabling safe execution of arbitrary code
• Model selection and validation occur through typed specifications that check against thinking effort levels and capability requirements
• Remote workspaces extend the local architecture via SSH and WebSocket proxies without changing the agent execution interface
• Workspace sessions persist through schemas defined in the shared layer, ensuring consistency between UI state and runtime state

Frequently Asked Questions

What technology stack powers the Orca model architecture?

The architecture is built on Electron for the desktop shell, React for the user interface, and Node.js for the agent runtime. TypeScript provides type safety across all layers, with a custom relay protocol handling inter-process communication between the renderer and agent subprocesses.

How does the relay layer facilitate communication between components?

The relay layer acts as a bidirectional message bus that routes commands between the React UI and the agent runtime. It manages streaming protocols for real-time output, handles PTY (pseudo-terminal) sessions for interactive processes, and proxies requests to remote runtimes via WebSocket when using SSH connections.

Can Orca execute AI agents on remote machines?

Yes. The architecture includes a remote runtime mode that uses SSH to execute agents on external servers. The ssh-types.ts module abstracts connection details, while remote-runtime-request-websocket.ts tunnels the relay protocol over WebSocket, making remote agents appear functionally identical to local ones in the UI.

Where is the workspace session state defined and managed?

Workspace session state is defined in src/shared/workspace-session-schema.ts, which provides the canonical TypeScript interfaces for workspace configuration. This schema is shared between the main and renderer processes, ensuring type-safe persistence and synchronization of session data across the application.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}