How to Set Up a Development Environment for Orca: Complete Guide

Clone the stablyai/orca repository, install Node 24 and pnpm@10, run pnpm install to compile native dependencies, and launch the Electron IDE with pnpm dev to start developing.

Orca is an open-source, Electron-based IDE developed by Stability AI that runs on macOS, Linux, and Windows. Setting up a development environment for Orca requires specific toolchain versions to handle its monorepo architecture, native binaries, and Vite-powered build system. This guide provides the exact steps to configure your local machine using the source code from stablyai/orca.

Prerequisites and Toolchain Versions

Before cloning the repository, ensure your system meets the hard requirements defined in package.json.

• Node.js 24: The engines field in package.json explicitly requires Node 24. Earlier versions will fail during dependency resolution or native compilation.
• pnpm 10: The repository uses pnpm as its package manager, locked to version 10 via the packageManager field. This ensures consistent dependency trees and proper handling of native modules.
• Git: Required for cloning and submodule management.

Step 1: Clone the Repository and Install Dependencies

Retrieve the source tree and install all production and development dependencies, including native binaries like better-sqlite3 and @xterm/headless.

# Clone the repository

git clone https://github.com/stablyai/orca.git
cd orca

# Install pnpm globally (if not already installed)

npm i -g pnpm@10

# Install all dependencies and compile native binaries

pnpm install

The pnpm install command automatically handles native dependencies listed in the onlyBuiltDependencies section of package.json, ensuring platform-specific binaries are compiled for your host architecture.

Step 2: Configure the Development Environment

Orca provides a helper script to isolate your development configuration from your personal Orca installation. This is critical for testing onboarding flows and first-run logic.

# Run with a temporary, clean profile (recommended for first-time setup)

./config/scripts/dev-fresh-profile.sh

# Or keep the temporary profile after exit for inspection

./config/scripts/dev-fresh-profile.sh --keep

The dev-fresh-profile.sh script sets the ORCA_DEV_USER_DATA_PATH environment variable to a temporary directory, forcing Electron to use a fresh userData folder. This mimics a first-time install without persisted repositories or saved sessions.

Step 3: Launch the Development Server

Start the Electron application with Vite hot-reloading enabled.

pnpm dev

This command executes the dev script defined in package.json, which runs run-electron-vite-dev.mjs to bootstrap the native runtime check and launch Electron. The renderer process loads from http://localhost:5173 (Vite dev server), with the entry point defined in electron.vite.config.ts at the @renderer alias (src/renderer/src).

Understanding the Monorepo Structure

Orca’s codebase is organized into distinct processes orchestrated by Vite and Electron:

• Main Process: The Electron main entry point is src/main/index.ts, which loads the renderer and sets up IPC handlers.
• Renderer Process: A React application using Tailwind CSS and shadcn components, located in src/renderer/src/.
• Mobile Companion: Separate build targets for the mobile app (not activated during standard pnpm dev).

Telemetry and Privacy in Development

According to the configuration in electron.vite.config.ts, local development builds automatically disable telemetry. The compile-time constants ORCA_BUILD_IDENTITY, ORCA_POSTHOG_WRITE_KEY, and ORCA_DIAGNOSTICS_TOKEN_URL are substituted with null during the Vite build process. This prevents accidental data transmission to analytics servers while you iterate on the codebase.

Testing Your Setup

Verify your development environment by running the test suites.

# Run unit tests with Vitest

pnpm test

# Run end-to-end tests with Playwright (headless Electron)

pnpm test:e2e

The unit tests validate core logic using Vitest, while the e2e suite uses Playwright to automate the Electron binary and verify UI workflows.

Building for Production

When ready to create distributable binaries, use the build scripts which invoke electron-builder.

# Build for current platform

pnpm build

# Build for specific platforms (examples)

pnpm build:mac     # Creates signed .dmg/.pkg

pnpm build:win     # Creates .exe installer

pnpm build:linux   # Creates AppImage/deb/rpm

The pnpm build command runs type-checking, bundles the main and renderer processes, builds the CLI components, and packages platform-specific binaries.

Summary

• Node 24 and pnpm@10 are mandatory requirements specified in package.json for compatibility with the monorepo's native dependencies.
• Native modules compile automatically during pnpm install via the onlyBuiltDependencies configuration, handling packages like better-sqlite3 and node-pty.
• Use ./config/scripts/dev-fresh-profile.sh to test onboarding and first-run experiences in an isolated Electron user-data directory.
• Telemetry is disabled by default in development through compile-time constants set to null in electron.vite.config.ts.
• Code changes hot-reload instantly via Vite when running pnpm dev, with the main process entry at src/main/index.ts and renderer at src/renderer/src/.

Frequently Asked Questions

What Node.js version is required for Orca development?

Orca requires Node.js 24, as explicitly defined in the engines field of package.json. Using earlier versions will cause dependency resolution failures or errors during native module compilation.

Why does Orca use pnpm instead of npm or yarn?

The repository specifies pnpm version 10 in the packageManager field of package.json. This ensures deterministic dependency trees and enables proper handling of native binaries through the onlyBuiltDependencies configuration, which automatically compiles platform-specific addons like better-sqlite3.

How can I test the first-time onboarding experience without clearing my data?

Run the ./config/scripts/dev-fresh-profile.sh script before starting the app. This launches pnpm dev with the ORCA_DEV_USER_DATA_PATH environment variable pointing to a temporary directory, simulating a fresh install. Add the --keep flag to preserve the temporary profile for debugging purposes.

Do the end-to-end tests run in a real Electron window?

Yes, the pnpm test:e2e command executes Playwright tests against a headless Electron instance. These tests automate the actual binary built from your current source code, validating UI interactions and IPC communication between the main and renderer processes.

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