How to Deploy Orca in a Production Environment: Build, Package, and Distribute Guide

Deploy Orca in a production environment by running pnpm run build to compile the Electron IDE and native Relay daemon, then execute platform-specific packaging commands (build:mac, build:win, build:linux) to generate distributable DMG, EXE, or AppImage installers.

Orca is an Electron-based IDE maintained by stablyai/orca that enables remote development through SSH worktrees across macOS, Windows, and Linux. Deploying Orca in a production environment requires compiling application binaries, creating OS-specific installers, and ensuring the SSH Relay daemon deploys automatically to remote hosts. This guide provides the exact commands and source file references needed for a complete production release.

Prerequisites for Production Deployment

Before building Orca, ensure your environment meets the following requirements:

• Node.js version 24 or higher
• pnpm package manager installed globally
• Git for cloning the repository

Install dependencies by running:

pnpm install

Build Production Binaries

The build process compiles the Electron application, the web UI, the CLI entry point, and the native Orca Relay daemon. The Relay must be built before the Electron packaging step so it can be embedded into the final installer.

Compile the Electron Application

Run the following command sequence defined in package.json:

1. pnpm run typecheck – Validates TypeScript using tsgo or tsc.
2. pnpm run build:electron-vite – Executes the Vite-based build pipeline, outputting the unpacked app to out/.
3. pnpm run build:web – Bundles the renderer process UI.
4. pnpm run build:cli – Emits the CLI entry point to out/cli/index.js.

Build the SSH Relay Daemon

The Relay requires separate compilation:

pnpm run build:relay

This command, defined in src/main/ssh/ssh-relay-deploy.ts, compiles the lightweight Node script that runs on remote machines. The output must be version-hashed and placed under ~/.orca-remote/relay-vX.Y.Z before packaging to prevent the in-app updater from redeploying on every launch.

Execute the Full Build Pipeline

Instead of running steps individually, execute the complete pipeline:

pnpm run build

This runs all sub-tasks in order: type checking, Relay compilation, macOS computer integration (via config/scripts/build-computer-macos.mjs), Electron Vite build, web bundling, and CLI emission. After completion, out/main/ contains the compiled Electron app and out/relay/ contains the ready-to-ship Relay binary.

Package Orca for Production Distribution

Orca uses electron-builder (version 26) configured in config/electron-builder.config.cjs to generate installers. The build scripts handle code signing, asar packaging, and platform-specific artifacts.

Generate macOS, Windows, and Linux Installers

Run the platform-specific script from package.json:

• macOS: pnpm run build:mac produces Orca-<version>.dmg. Use build:mac:release for notarized builds suitable for distribution outside the Mac App Store.
• Windows: pnpm run build:win generates Orca Setup <version>.exe using the NSIS installer framework, which registers the application in Add/Remove Programs.
• Linux: pnpm run build:linux creates .AppImage and .deb packages depending on the electron-builder configuration targets.

The artifacts appear in the dist/ directory.

Configure Homebrew Cask Updates

For macOS distribution via Homebrew, the cask definition in Casks/orca.rb pins the version, defines the DMG URL, and sets auto_updates true. This flag ensures Homebrew defers to Orca's built-in auto-updater rather than overwriting the application.

Users can install via:

brew install --cask stablyai/orca/orca

To remove all user data during uninstallation, the cask includes a zap array that cleans the ~/.orca directory and standard Electron userData paths.

Deploy the SSH Relay for Remote Worktrees

When users connect to remote hosts, Orca automatically deploys the Relay binary. This process is built into the application and requires no manual intervention, but understanding the flow is critical for troubleshooting production deployments.

Automated Relay Installation Flow

The deployment logic resides in src/main/ssh/ssh-relay-deploy.ts and follows this sequence:

1. Connection establishment: src/main/ssh/ssh-connection.ts creates an SSH client using ssh2.
2. Binary upload: The system performs an SCP-like transfer via execCommand to write the Relay to ~/.orca-remote/relay-vX.Y.Z on the remote host.
3. Execution: The module runs chmod +x followed by the binary launch command through the same SSH session.
4. Protocol handshake: src/main/ssh/relay-protocol.ts establishes a multiplexed channel for RPC calls between the Electron main process and the remote Relay, forwarding commands via agent-hook-server.ts.

The session lifecycle is managed by src/main/ssh/ssh-relay-session.ts, which tracks states from idle to deploying to ready.

Version Control and Idempotent Updates

The Relay uses a version-hashed filename (e.g., relay-v0.1.0) stored in src/main/ssh/ssh-relay-versioned-install.ts. This design ensures idempotent deployments: the system compares the local binary hash against the remote file and only uploads when versions differ. This prevents unnecessary network traffic and guarantees that the running Relay matches the client's expected version.

Automate Production Releases with CI/CD

Embed the following script into your CI/CD pipeline to produce production-ready artifacts for all platforms:

#!/usr/bin/env bash
set -euo pipefail

# Install Node.js 24 and pnpm

curl -fsSL https://fnm.vercel.app/install | bash
fnm install 24
fnm use 24
npm i -g pnpm

# Clone and build

git clone --depth 1 https://github.com/stablyai/orca.git
cd orca
pnpm install
pnpm run lint
pnpm run build

# Package for all platforms

pnpm run build:mac   # dist/Orca-*.dmg

pnpm run build:win   # dist/Orca Setup *.exe

pnpm run build:linux # dist/*.AppImage

# Optional: Publish to GitHub Releases

# gh release upload v$(pnpm pkg get version) dist/*

The script runs pnpm run build once to compile shared assets, then generates platform-specific installers. The Relay binary is baked into each installer, ensuring end users never manually configure remote components.

Summary

• Build Orca using pnpm run build to compile the Electron app, web UI, CLI, and Relay daemon in the correct dependency order.
• Package production installers with pnpm run build:mac, build:win, or build:linux, referencing config/electron-builder.config.cjs for signing and target options.
• Distribute via Homebrew using Casks/orca.rb, ensuring auto_updates true preserves the built-in updater functionality.
• Deploy the SSH Relay automatically via src/main/ssh/ssh-relay-deploy.ts, which uses version-hashed filenames in ssh-relay-versioned-install.ts to ensure idempotent, one-time uploads to remote hosts.

Frequently Asked Questions

What Node.js version is required to build Orca?

Orca requires Node.js 24 or higher. The build pipeline uses modern Node features for the Electron Vite compiler and the Relay daemon compilation.

How does Orca prevent redundant SSH Relay uploads?

The system uses version-hashed filenames implemented in src/main/ssh/ssh-relay-versioned-install.ts. It checks ~/.orca-remote/relay-vX.Y.Z on the remote host and only uploads the binary if the version hash differs from the local build, making deployments idempotent.

Can I distribute Orca through Homebrew?

Yes. The repository includes Casks/orca.rb, which defines the DMG download URL, version pinning, and auto_updates true to integrate with Orca's internal update mechanism. Users install via brew install --cask stablyai/orca/orca.

Where is the Electron-builder configuration stored?

Platform targets, code signing options, and packaging settings are defined in config/electron-builder.config.cjs, referenced by the build:* scripts in package.json.

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