#Setup

#Requirements

#Install a release

All assets are on the Releases page together with SHA256SUMS (verify with sha256sum -c SHA256SUMS --ignore-missing or certutil -hashfile <file> SHA256).

#Windows

1. Download ORCA-Agent-<version>-win-x64.zip.
2. Extract anywhere (e.g. C:\Apps\ORCA) and run ORCA.exe. Nothing is installed system-wide; delete the folder to uninstall.

Windows SmartScreen may warn because the executable is not code-signed — choose More info → Run anyway.

#macOS

1. Download ORCA-Agent-<version>-mac-arm64.dmg (Apple Silicon) or ORCA-Agent-<version>-mac-x64.dmg (Intel); the .zip variants contain the same app bundle.
2. Open the image and drag ORCA Agent to Applications.
3. First launch: the app is not notarized, so right-click → Open → Open (once), or run xattr -dr com.apple.quarantine "/Applications/ORCA Agent.app".

#Linux

• AppImage (any distribution): chmod +x ORCA-Agent-<version>-linux-x64.AppImage && ./ORCA-Agent-<version>-linux-x64.AppImage. Needs FUSE 2 (sudo apt install libfuse2 on Ubuntu 22.04+); without it, run with --appimage-extract-and-run.
• tar.gz: tar xzf ORCA-Agent-<version>-linux-x64.tar.gz && ./ORCA-Agent-<version>-linux-x64/orca-agent.
• On hardened kernels that block unprivileged user namespaces, add --no-sandbox.

#Updates

Nobody needs to visit GitHub to stay current. ORCA checks the project's release channel on start and every few hours; when a newer version exists, a banner appears and — with Download updates in the background on (default) — the package for your platform and CPU is fetched while you work. Every download is resumable, falls back to public mirrors when github.com is blocked, and is verified against the release's SHA-256 before anything is touched. Then you press Restart & install:

• Windows (portable folder): the new version is extracted next to the app, the folder is swapped after ORCA exits and the app relaunches. If the swap fails, the previous folder is restored.
• macOS: the .app bundle is replaced in place (quarantine flag cleared) and reopened.
• Linux AppImage: the file is replaced in place and relaunched.
• Linux tar.gz: the app folder is swapped like on Windows.

The next start shows Updated to ORCA x.y.z (or the reason it could not be installed — the old version is kept in that case). Settings → Updates has the full state: installed/latest version, package size, download progress with speed and ETA, the release notes, Cancel/Retry, and switches for automatic checks and background downloads. Chats, files and keys live in the data folder and are never touched by an update. Running from source (npm start, web mode) only downloads and verifies the package and reveals it in the file manager.

#Run from source

git clone https://github.com/Nethyric/orca.git
cd orca
npm install
npm run fetch-bins      # optional: ffmpeg.exe, yt-dlp.exe, OCR language data (needed for media/OCR tools)
npm start               # Electron desktop app
npm run web             # or plain web mode → http://localhost:7860

A source checkout does not include the vault private key, so the built-in models are unavailable until you either add a provider of your own (Settings → Models) or, as a maintainer, export ORCA_VAULT_KEY (see vault.md).

#Folders

Both can be changed: the workspace in Settings → General, the data folder with ORCA_DATA (web mode). The workspace is the only place tools read and write; point it at your project.

#Environment variables

.env.example lists them; ORCA does not read .env itself — export them in your shell or CI.

#Build

npm run fetch-bins                      # once per target platform (ORCA_TARGET=win|mac|linux, ORCA_ARCH=x64|arm64)
ORCA_VAULT_KEY=... npm run dist:win     # → release/ORCA-Agent-<version>-win-x64.zip          (builds on any OS)
ORCA_VAULT_KEY=... npm run dist:mac     # → release/ORCA-Agent-<version>-mac-{x64,arm64}.{zip,dmg}   (macOS only)
ORCA_VAULT_KEY=... npm run dist:linux   # → release/ORCA-Agent-<version>-linux-x64.{AppImage,tar.gz}

scripts/bake.js writes src/build-info.json (vault key, commit, build time) which is git-ignored and packed into the app. The Windows build runs on Linux/macOS too (no Wine needed: signAndEditExecutable is off; scripts/finish-win.js renames the exe and zips the folder). macOS builds are unsigned (identity: null); Linux builds bundle ffmpeg/yt-dlp for x64.

#Maintainers

#One-time

1. Fork/clone, then npm run set-repo -- YourName/your-repo (rewrites repo links).
2. npm run vault:keygen -- --write → prints a private key and writes the public key into orca.config.json. Keep the private key secret.
3. GitHub → Settings → Secrets and variables → Actions:
   • ORCA_VAULT_KEY — the private key from step 2
   • UPSTREAMS — JSON describing the built-in providers/keys (format in vault.md)
4. Actions → Seal vault → Run workflow. It validates each key, encrypts UPSTREAMS to the public key and commits remote/vault.json.

#Release

npm version 0.0.5 --no-git-tag-version   # or edit package.json
git commit -am "0.0.5" && git tag v0.0.5 && git push && git push --tags

The Release workflow builds all three platforms in parallel (Windows on Ubuntu, macOS on macos-14, Linux on Ubuntu), merges one SHA256SUMS, attaches remote/vault.json, and publishes the GitHub Release. Installed apps pick it up on their next check.

#Rotate or replace built-in keys

Edit the UPSTREAMS secret → Actions → Seal vault → Run workflow. Running apps refresh the vault within 15 minutes; nothing else changes and no release is needed. Dead keys are skipped automatically (cool-down and per-key health tracking), so even an exhausted key is not user-visible.