# How to Set Up a Development Environment for Orca: Complete Guide > Set up your Orca development environment easily. Clone the stablyai/orca repo, install Node 24 and pnpm, then run pnpm dev to launch the IDE and start coding. - Repository: [Stably/orca](https://github.com/stablyai/orca) - Tags: how-to-guide - Published: 2026-05-25 --- **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`](https://github.com/stablyai/orca/blob/main/package.json). - **Node.js 24**: The `engines` field in [`package.json`](https://github.com/stablyai/orca/blob/main/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`. ```bash # 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`](https://github.com/stablyai/orca/blob/main/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. ```bash # 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`](https://github.com/stablyai/orca/blob/main/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. ```bash pnpm dev ``` This command executes the `dev` script defined in [`package.json`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/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. ```bash # 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`. ```bash # 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`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/./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`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/./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.