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

> Deploy Orca in a production environment with this guide. Build the Electron IDE and Relay daemon, then package for Mac, Windows, or Linux distributable installers.

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

---

**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:

```bash
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`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/out/cli/index.js).

### Build the SSH Relay Daemon

The Relay requires separate compilation:

```bash
pnpm run build:relay

```

This command, defined in [`src/main/ssh/ssh-relay-deploy.ts`](https://github.com/stablyai/orca/blob/main/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:

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

```bash
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`](https://github.com/stablyai/orca/blob/main/src/main/ssh/ssh-relay-deploy.ts) and follows this sequence:

1. **Connection establishment**: [`src/main/ssh/ssh-connection.ts`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/agent-hook-server.ts).

The session lifecycle is managed by [`src/main/ssh/ssh-relay-session.ts`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/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:

```bash
#!/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`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/src/main/ssh/ssh-relay-deploy.ts), which uses version-hashed filenames in [`ssh-relay-versioned-install.ts`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/package.json).