# How to Build Orca From Source Code: A Complete Guide

> Build Orca from source code with this complete guide. Learn how to install dependencies, compile TypeScript, and build native binaries and the Electron renderer.

- Repository: [Stably/orca](https://github.com/stablyai/orca)
- Tags: how-to-guide
- Published: 2026-05-25

---

**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`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/package.json).

Install the specific version globally before proceeding:

```bash
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:

```bash
pnpm install

```

The `pnpm` configuration (`onlyBuiltDependencies` and `patchedDependencies` in [`package.json`](https://github.com/stablyai/orca/blob/main/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:

```bash
pnpm typecheck

```

This executes type checking against [`config/tsconfig.node.json`](https://github.com/stablyai/orca/blob/main/config/tsconfig.node.json), [`config/tsconfig.cli.json`](https://github.com/stablyai/orca/blob/main/config/tsconfig.cli.json), and [`config/tsconfig.web.json`](https://github.com/stablyai/orca/blob/main/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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/stablyai/orca/blob/main/vite.web.config.ts) to generate static assets.

### CLI Tool

Compile the TypeScript CLI entry point into the output directory:

```bash
pnpm run build:cli

```

This runs `tsc -p config/tsconfig.cli.json`, emitting JavaScript to [`out/cli/index.js`](https://github.com/stablyai/orca/blob/main/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:

```bash
pnpm run build

```

This script, defined in [`package.json`](https://github.com/stablyai/orca/blob/main/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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/config/tsconfig.node.json), [`cli.json`](https://github.com/stablyai/orca/blob/main/cli.json), and [`web.json`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/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.