# Installation

> Platform packages (onOrca.dev, Homebrew, AUR), Node 24/pnpm prerequisites for source builds, CLI registration, and mobile companion app install links.

- Repository: stablyai/orca
- GitHub: https://github.com/stablyai/orca
- Human docs: https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c
- Complete Markdown: https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c/llms-full.txt

## Source Files

- `README.md`
- `package.json`
- `config/electron-builder.config.cjs`
- `config/scripts/install-dev-cli.mjs`
- `config/scripts/orca-dev`
- `.github/CONTRIBUTING.md`

---

---
title: "Installation"
description: "Platform packages (onOrca.dev, Homebrew, AUR), Node 24/pnpm prerequisites for source builds, CLI registration, and mobile companion app install links."
---

Orca ships as a packaged Electron desktop app (`com.stablyai.orca`) with a bundled `orca` shell command that runs the compiled CLI via `ELECTRON_RUN_AS_NODE` against the app’s own Electron binary—no separate Node/npm CLI install for end users. Desktop installers come from [onOrca.dev](https://onOrca.dev), [GitHub Releases](https://github.com/stablyai/orca/releases/latest), Homebrew, or the Arch AUR; contributors build from source with **Node 24** and **pnpm 10.24.0**.

## Desktop packages

| Channel | Command or URL | Artifact / notes |
| --- | --- | --- |
| Website | [onOrca.dev](https://onOrca.dev) | Primary download for macOS, Windows, and Linux |
| GitHub Releases | `https://github.com/stablyai/orca/releases/latest` | Same desktop builds as the site |
| Homebrew (macOS) | `brew install --cask stablyai/orca/orca` | Tap `stablyai/homebrew-orca`; cask installs `Orca.app` |
| AUR (Arch) | `yay -S stably-orca-bin` | Precompiled binary package |
| AUR (Arch, source) | `yay -S stably-orca-git` | Builds from GitHub source |

Stable desktop releases publish artifacts including `orca-macos-arm64.dmg`, `orca-macos-x64.dmg`, `Orca-<version>-arm64-mac.zip`, `orca-windows-setup.exe`, `orca-linux.AppImage`, and `orca-ide_<version>_amd64.deb`. The Homebrew cask tracks GA desktop tags only (not `mobile-v*` or `-rc.*` releases) and sets `auto_updates true` so in-app `electron-updater` is not competing with `brew upgrade`.

<Tabs>
  <Tab title="macOS">

```bash
brew install --cask stablyai/orca/orca
```

The cask requires macOS Big Sur or newer, installs `Orca.app`, and documents zap paths for `~/.orca` and standard Electron user-data locations.

  </Tab>
  <Tab title="Linux">

Download **AppImage** or **`.deb`** from Releases. Packaged Linux uses executable name `orca-ide` and Debian package name `orca-ide` so the install does not collide with Ubuntu’s GNOME **Orca** screen reader (`/usr/bin/orca`).

The `.deb` declares runtime dependencies: `python3`, `python3-gi`, `gir1.2-atspi-2.0`, `at-spi2-core`, `xdotool`, `xclip` (computer-use support).

  </Tab>
  <Tab title="Windows">

Download `orca-windows-setup.exe` from Releases. NSIS creates a desktop shortcut; the packaged app executable is `Orca.exe`.

  </Tab>
</Tabs>

<Note>
Bring your own CLI agent subscriptions (Claude Code, Codex, Grok, etc.). Orca does not require an Orca account to run the desktop app.
</Note>

## Build from source

Source development targets the repo toolchain pinned in `package.json`:

| Requirement | Value |
| --- | --- |
| Node.js | `24` (`engines.node`) |
| Package manager | `pnpm@10.24.0` (`packageManager`) |

<Steps>
  <Step title="Install dependencies">

```bash
pnpm install
```

`postinstall` runs `config/scripts/rebuild-native-deps.mjs` to rebuild native modules (`better-sqlite3`, `node-pty`, etc.) for Electron. On Windows, optional `cpu-features` is skipped when the MSVC toolchain is absent; `ssh2` falls back to pure JS.

  </Step>
  <Step title="Run the app">

```bash
pnpm dev
```

`pnpm dev` ensures the Electron native runtime, then starts electron-vite dev.

  </Step>
  <Step title="Optional: compile the CLI">

```bash
pnpm run build:cli
```

Compiles `src/cli` to `out/cli/index.js` and runs `config/scripts/install-dev-cli.mjs`, which symlinks `orca-dev` into `/usr/local/bin` on macOS/Linux when permissions allow.

  </Step>
</Steps>

Full build graphs (`pnpm build`, platform release targets, native relay/computer artifacts) live on the develop-and-build page. CI and release workflows read Node version from `package.json` via `node-version-file`.

<Warning>
`pnpm install` on Windows may require Visual C++ build tools for some native modules. If install fails on `cpu-features`, the repo’s rebuild script already documents the Windows skip path; other node-gyp failures usually mean installing the desktop C++ workload.
</Warning>

## CLI registration (`orca` on PATH)

Packaged Orca exposes a **Shell command** toggle under **Settings → Orca CLI**. Registration is implemented in `CliInstaller` and uses platform-specific launchers shipped under `resources/{darwin,linux,win32}/bin/`, copied into the app bundle as `resources/bin/orca` (or `orca.cmd` on Windows).

```text
  Terminal: orca …
       │
       ▼
  Registered command (symlink or .cmd wrapper)
       │
       ▼
  resources/bin/orca  →  Electron binary + app.asar.unpacked/out/cli/index.js
       │
       └── ELECTRON_RUN_AS_NODE=1
```

| Platform | Default command path | Method |
| --- | --- | --- |
| macOS | `/usr/local/bin/orca` | Symlink to bundled launcher; may prompt for admin via `osascript` if `/usr/local/bin` is not writable |
| Linux | `~/.local/bin/orca` | Symlink (user-scoped; avoids needing a global privileged bin dir) |
| Windows | `%LOCALAPPDATA%\Programs\Orca\bin\orca.cmd` | Wrapper forwarder; installer adds that directory to the **user** `Path` |

The launcher clears `NODE_OPTIONS` / `NODE_REPL_EXTERNAL_MODULE` (stashing them in `ORCA_NODE_*`) and invokes:

`ELECTRON_RUN_AS_NODE=1 <Electron> <app.asar.unpacked/out/cli/index.js> "$@"`

<ParamField body="ORCA_CLI_INSTALL_PATH" type="string">
Override the install target path for CLI registration (used by tests and advanced setups).
</ParamField>

Install states returned to the UI include `installed`, `not_installed`, `stale`, `conflict`, and `unsupported`. Orca refuses to replace a non-Orca binary at the command path (`conflict`).

<Tip>
On Windows with WSL, **Settings → Orca CLI** also offers **WSL shell command** registration so `orca` works inside your default WSL distro, separate from the host `orca.cmd` registration.
</Tip>

### Development CLI (`orca-dev`)

For local repo work, use the dev wrapper after `pnpm run build:cli`:

| Item | Detail |
| --- | --- |
| Binary | `orca-dev` (`package.json` `bin.orca-dev` → `config/scripts/orca-dev`) |
| Entry | `out/cli/index.js` (must exist; build first) |
| User data | Separate from production: `orca-dev` under Application Support / XDG config / `%APPDATA%` |
| Override | `ORCA_DEV_USER_DATA_PATH` |
| Global symlink | `install-dev-cli.mjs` → `/usr/local/bin/orca-dev` (or manual `sudo ln -s`) |

`orca-dev` sets `ORCA_APP_EXECUTABLE` to the repo’s Electron binary when available so CLI commands that open the app target the dev build.

### Verify CLI registration

```bash
orca --help
orca status
```

If the command is missing, open **Settings → Orca CLI**, enable **Shell command**, and confirm the status line shows the registered path. On macOS permission errors, follow the sudo hint from `install-dev-cli.mjs` or approve the elevated symlink prompt.

## Mobile companion app

The mobile app pairs to a running Orca desktop runtime; enable **Settings → Mobile** (`experimentalMobile`) on desktop for QR pairing.

| Platform | Install link |
| --- | --- |
| iOS | [App Store — Orca IDE](https://apps.apple.com/us/app/orca-ide/id6766130217) |
| Android | [GitHub release `mobile-v0.0.9`](https://github.com/stablyai/orca/releases/tag/mobile-v0.0.9) (APK on the mobile release tag; Google Play noted as coming in settings copy) |

Mobile builds use their own release tags (`mobile-v*`), separate from desktop `v*` tags. Protocol compatibility is versioned in `src/shared/protocol-version.ts`; outdated mobile clients may be blocked with `mobile-too-old` when the desktop runtime requires a newer build.

## What gets installed where

```text
Packaged desktop (example paths)
├── macOS: Orca.app  (CLI launcher → Contents/Resources/bin/orca)
├── Linux: orca-ide binary + resources/bin/orca
├── Windows: Orca.exe + resources/bin/orca.cmd
└── User data: ~/.orca, Electron app userData (worktrees, settings)

Dev checkout
├── node_modules/ + out/cli/index.js after build:cli
└── orca-dev userData (isolated from production Orca)
```

## Related pages

<CardGroup>
  <Card title="Quickstart" href="/quickstart">
    First session after install: repo, worktree, agent terminal, and `orca status`.
  </Card>
  <Card title="Develop and build" href="/develop-and-build">
    `pnpm dev`, typecheck, native rebuilds, and platform release builds.
  </Card>
  <Card title="CLI core reference" href="/cli-core-reference">
    `open`, `status`, `worktree`, `terminal`, and other command groups after PATH registration.
  </Card>
  <Card title="Runtime environments" href="/runtime-environments">
    Headless `orca serve`, pairing codes, and remote `--environment` targeting.
  </Card>
  <Card title="Troubleshooting" href="/troubleshooting">
    Runtime reachability, CLI selector issues, and native dependency failures.
  </Card>
</CardGroup>