Desktop App Deployment

Build and distribute the Cortexa desktop application using Tauri v2, with platform-specific installers for Windows and macOS.

Prerequisites

Requirement	Purpose
Rust 1.77+ via rustup	Backend compilation
Node.js 18+ and npm	Frontend toolchain (Vite + React)
Windows: WebView2 Runtime (preinstalled on Win11)	Tauri webview
Linux: webkit2gtk-4.1, libsoup-3, librsvg2, build essentials	Tauri runtime
macOS: Xcode command-line tools	Tauri runtime

NSIS (for Windows installers) is bundled by Tauri at build time -- no separate installation needed.

Building

Development Build

npm install
npm run tauri dev

This starts Vite with HMR for the React frontend and auto-rebuilds the Rust backend on changes. The app launches with full debug logging.

Release Build

npm install
npm run tauri build

This produces optimized binaries and platform-specific installers. First build pulls and compiles ~150 crates and may take 5-15 minutes. Incremental rebuilds are seconds when only the frontend or a single Rust file changes.

Build Outputs

After npm run tauri build:

File	Purpose
target/release/cortexa.exe	Standalone app binary (Windows)
target/release/cortexa-cli.exe	CLI binary
target/release/cortexa-hive.exe	Hive relay server
target/release/bundle/nsis/Cortexa_<version>_x64-setup.exe	NSIS installer (Windows x64)
target/release/bundle/dmg/Cortexa_<version>_aarch64.dmg	DMG (macOS Apple Silicon)
target/release/bundle/dmg/Cortexa_<version>_x64.dmg	DMG (macOS Intel)

Building Individual Crates

# CLI binary only
cargo build -p cortexa-cli --release

# Hive server only
cargo build -p cortexa-hive --release

# MCP stdio bridge only
cargo build -p cortexa-mcp --release

Platform Installers

Windows (NSIS)

Tauri bundles NSIS automatically. The generated installer:

• Installs per-user to %LocalAppData%\Cortexa\ (no admin rights required).
• Creates a Start menu entry.
• Registers an uninstaller accessible via Settings > Apps.
• Supports silent installation with /S flag.

Users download either:

• Cortexa_<version>_x64-setup.exe for Intel/AMD (x64)
• Cortexa_<version>_arm64-setup.exe for Windows on ARM (ARM64)

macOS (DMG)

The DMG contains the Cortexa.app bundle. Users drag it to /Applications. Two variants are built:

• Cortexa_<version>_aarch64.dmg for Apple Silicon (M1/M2/M3/M4)
• Cortexa_<version>_x64.dmg for Intel Macs

Linux

Linux builds produce AppImage or .deb packages depending on configuration. Requirements: WebKit2GTK 4.1, libsoup-3, librsvg2.

CI Targets

The GitHub Actions workflow builds four platform targets on every tagged release:

Platform	Runner	Target	Installer
Windows x64	windows-latest	(default)	_x64-setup.exe / .msi
Windows ARM64	windows-11-arm	aarch64-pc-windows-msvc	_arm64-setup.exe
macOS Apple Silicon	macos-latest	aarch64-apple-darwin	_aarch64.dmg
macOS Intel	macos-latest	x86_64-apple-darwin	_x64.dmg

See the CI/CD page for the full workflow configuration.

Upgrading In Place

To upgrade an existing installation:

Windows

Run the new .exe installer. Tauri's NSIS handles the upgrade in place:

1. The old version is uninstalled silently.
2. The new version is installed to the same location.
3. All user data persists (SQLite database, blobs, settings, salt).

No need to uninstall first.

macOS

Replace the .app bundle in /Applications with the new version from the DMG. User data lives in ~/Library/Application Support/com.cortexa.app/ and is not affected.

Data Migration

Schema migrations run automatically on startup. The PRAGMA user_version mechanism ensures each migration runs exactly once. See the Storage page for migration details.

If upgrading across many versions causes a schema error (e.g., "no such column"), the troubleshooting step is to delete cortexa.db (blob files survive) or open an issue.

Upgrading from a version before SQLCipher encrypts cortexa.db once, at the first start whose vault key verifies (see Encryption). It runs in the background behind an "Encrypting your vault…" progress screen (about 50 s for a 2.5 GB vault) and needs free disk of twice the database size; without it the vault keeps working unencrypted and Cortexa says so. Quitting mid-way is safe: the next start discards the partial copy and begins again. Backups made before the upgrade still hold a plaintext database.

Version Management

Version is set in two files that must stay in sync:

File	Field
src-tauri/tauri.conf.json	"version"
src-tauri/Cargo.toml	version

To create a new release:

1. Bump version in both files.
2. Commit and tag: git tag v0.8.3.
3. Push the tag: git push origin v0.8.3.
4. The CI workflow builds and publishes the release automatically.

Code Signing (Future)

Windows (Authenticode)

Authenticode signing avoids Windows SmartScreen warnings for new downloads. To enable:

1. Obtain an EV or standard code-signing certificate.
2. Install the certificate on the build machine.
3. Set in tauri.conf.json:

   {
     "bundle": {
       "windows": {
         "certificateThumbprint": "<thumbprint>",
         "digestAlgorithm": "sha256",
         "timestampUrl": "http://timestamp.digicert.com"
       }
     }
   }

This is not currently configured. Without signing, users see a SmartScreen prompt on first run that they must click through.

macOS (Notarization)

macOS notarization requires an Apple Developer account and involves:

1. Code signing with a Developer ID certificate.
2. Submitting the signed app to Apple's notarization service.
3. Stapling the notarization ticket to the DMG.

Tauri supports this via the tauri-plugin-macos-sign configuration. Not currently configured.

Troubleshooting

Build Failures

Missing WebView2 on Windows: Install WebView2 Runtime from Microsoft. Preinstalled on Windows 11.

Missing system libraries on Linux:

# Ubuntu/Debian
sudo apt install libwebkit2gtk-4.1-dev libsoup-3.0-dev librsvg2-dev build-essential

# Fedora
sudo dnf install webkit2gtk4.1-devel libsoup3-devel librsvg2-devel

Rust version too old: rustup update to get Rust 1.77+.

Runtime Issues

Window stays hidden after launch: Expected -- the app starts hidden in tray-only mode. Use the hotkey (default Ctrl+Shift+P) or click the tray icon.

Tray icon doesn't appear on Windows: Check the notification area overflow. Windows sometimes hides new tray icons by default.

Hotkey not firing: Another app may own the key combination. Change it in Settings > Capture > Hotkey. Note that Win+L is OS-reserved.