How to Build Orca From Source Code: A Complete Guide

You can build Orca from source code by installing pnpm 10, running pnpm install to fetch dependencies, and executing pnpm run build to compile the TypeScript codebase, native binaries, and Electron renderer.

Orca is a cross-platform Electron-based IDE developed by Stably AI that bundles JavaScript/TypeScript code with native modules and agent-CLI integrations. Building it locally requires following the same workflow used by the CI pipelines, beginning with the exact package manager version pinned in package.json and ending with the electron-builder packaging step.

Prerequisites: Install pnpm 10

Orca strictly requires pnpm 10 to ensure reproducible native dependency builds. The exact version is pinned in the packageManager field of package.json.

Install the specific version globally before proceeding:

npm i -g pnpm@10.24.0

Clone and Install Dependencies

After cloning the stablyai/orca repository, install all Node-side packages and native modules—including node-pty, better-sqlite3, and sherpa-onnx—using the lockfile-defined resolution:

pnpm install

The pnpm configuration (onlyBuiltDependencies and patchedDependencies in package.json) ensures native binaries are automatically rebuilt for your host platform during this step.

Run the Type Checker

The repository enforces strict TypeScript checking across three separate pipelines before compilation. Run the typecheck script to validate against the separate tsconfig entry points:

pnpm typecheck

This executes type checking against config/tsconfig.node.json, config/tsconfig.cli.json, and config/tsconfig.web.json simultaneously.

Build the Runtime Layers

Orca consists of five distinct build targets that must be compiled in sequence. While pnpm run build orchestrates the entire chain, understanding the individual layers helps with debugging and selective rebuilding.

WebSocket Relay

The relay acts as the bridge between the Electron main process and the renderer thread. Build it using the dedicated script:

pnpm run build:relay

This executes config/scripts/build-relay.mjs, bundling the WebSocket server code required for agent communication.

macOS Computer-Use Helper

For macOS targets, compile the native helper binary that enables computer-use automation features:

pnpm run build:computer-macos

This invokes config/scripts/build-computer-macos.mjs, which produces the platform-specific binary shipped inside the final .app bundle.

Electron Renderer and Web Assets

Build the UI layer and web-facing assets using Vite through a memory-safe wrapper script:

pnpm run build:electron-vite
pnpm run build:web

The build:electron-vite command runs config/scripts/run-electron-vite-build.mjs, which injects an increased NODE_OPTIONS heap size (--max-old-space-size) to prevent out-of-memory errors during the webpack bundling phase before forwarding arguments to the electron-vite CLI. The web build processes vite.web.config.ts to generate static assets.

CLI Tool

Compile the TypeScript CLI entry point into the output directory:

pnpm run build:cli

This runs tsc -p config/tsconfig.cli.json, emitting JavaScript to out/cli/index.js for command-line usage outside the Electron environment.

Orchestrate the Full Build

Rather than running individual steps, use the top-level build command that mirrors the CI pipeline:

pnpm run build

This script, defined in package.json, automatically runs typecheck first, then chains the relay, computer-macos, electron-vite, web, and CLI builds in the correct order. After completion, the out/ directory contains the Electron application bundle, CLI binary, and WebSocket relay ready for execution.

Verify Code Quality

Before packaging, verify lint rules and unit tests pass:

pnpm lint
pnpm test

These commands ensure the codebase meets the repository's quality gates and that native module bindings function correctly on your platform.

Package the Application (Optional)

To produce distributable installers (.dmg, .exe, or .AppImage) rather than just development builds, use the electron-builder configuration. The build outputs in out/ are automatically consumed by config/electron-builder.config.cjs, which handles:

• Platform-specific packaging with target-specific unpack rules
• Native dependency inclusion from node_modules
• Code signing (macOS only, configured via environment variables)

Run the package command after a successful build:

pnpm run dist

Build for End-to-End Testing

End-to-end tests require the renderer to expose its internal store for test harness access. Build with the e2e mode flag to enable this:

pnpm exec electron-vite build --mode e2e

Setting VITE_EXPOSE_STORE=true (handled automatically by the E2E mode) produces an out/ tree where window.__store is available on the global scope, allowing automated tests to inspect application state.

Summary

• Orca requires pnpm 10 exactly as specified in package.json's packageManager field.
• Run pnpm install to fetch dependencies and rebuild native binaries for your platform.
• Execute pnpm run build to compile all five layers: relay, computer-macos helper, electron-vite renderer, web assets, and CLI.
• Type checking spans three tsconfig files (config/tsconfig.node.json, cli.json, and web.json) and runs automatically before compilation.
• Memory management during the Electron build is handled by config/scripts/run-electron-vite-build.mjs, which increases Node's heap size to avoid CI failures.
• E2E builds require --mode e2e to expose the internal store for testing automation.

Frequently Asked Questions

What version of pnpm is required to build Orca?

You must use pnpm 10, specifically the version declared in the packageManager field of package.json (currently pnpm@10.24.0). Using npm, yarn, or a different pnpm version will result in incompatible native module builds and potential lockfile conflicts.

Where are the build scripts located in the Orca repository?

Build orchestration scripts live in config/scripts/, including build-relay.mjs for the WebSocket bridge, build-computer-macos.mjs for the native macOS helper, and run-electron-vite-build.mjs for the renderer process. The electron-builder configuration resides at config/electron-builder.config.cjs.

Can I build Orca without compiling the native macOS helper?

Yes. If you do not require the computer-use automation features specific to macOS, you can skip pnpm run build:computer-macos and run the other build steps individually. However, the full pnpm run build command will attempt all steps, and missing native dependencies may cause runtime errors when those features are invoked.

How do I run the Orca CLI after building from source?

After running pnpm run build:cli, the compiled CLI entry point is available at out/cli/index.js. You can execute it directly with Node (node out/cli/index.js) or package it using the electron-builder configuration to produce a standalone binary for your platform.

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