Installation

Get Cortexa running on your platform of choice, then pull the LLM models it needs.

One-Line Install (recommended)

The installer detects your OS and CPU, downloads the right build from GitHub Releases, and installs it — no Rust or Node toolchain required.

Desktop app

# macOS — installs Cortexa.app into /Applications
curl -fsSL https://cortexalabs.github.io/cortexa/install.sh | bash

# Windows (PowerShell)
irm https://cortexalabs.github.io/cortexa/install.ps1 | iex

Hive relay server (Linux)

# Downloads the relay binary (x86_64 or arm64) to /usr/local/bin
curl -fsSL https://cortexalabs.github.io/cortexa/install.sh | bash -s -- hive

The script prints a ready-to-paste systemd unit so you can run it as a service. See Hive Server for the full deployment guide.

MCP bridge

# macOS / Linux
curl -fsSL https://cortexalabs.github.io/cortexa/install.sh | bash -s -- mcp

# Windows (PowerShell)
& ([scriptblock]::Create((irm https://cortexalabs.github.io/cortexa/install.ps1))) mcp

Then point your agent at it, e.g. claude mcp add cortexa -- cortexa-mcp. See MCP Setup.

Other ways

Method	Command
Direct download	GitHub Releases — pick your platform's asset
cargo install (server/CLI bits)	cargo install --git https://github.com/cortexalabs/cortexa cortexa-hive (or cortexa-mcp, cortexa-cli)
Build from source	See Build from Source below

Heads up: the Linux Hive/MCP binaries are published starting from the first release cut after this feature landed. If a one-liner reports the asset isn't available yet, grab the binary from Releases or build from source in the meantime.

Windows

Download the installer from GitHub Releases:

Installer	Architecture
Cortexa_<version>_x64-setup.exe	Intel / AMD (most PCs)
Cortexa_<version>_arm64-setup.exe	Windows on ARM (Surface Pro X, etc.)

The NSIS installer runs per-user into %LocalAppData%\Cortexa\ and adds a Start menu entry. No admin rights needed.

After install:

1. Launch Cortexa from the Start menu. A tray icon appears in the notification area.
2. Press Ctrl+Shift+P (default hotkey) to summon the capture window.

To upgrade: run the new setup .exe over the old one. Tauri's NSIS handles the upgrade in place and your data persists.

To uninstall: Settings > Apps > Cortexa > Uninstall, or run the uninstaller in the install directory.

macOS

Download the DMG from GitHub Releases:

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

Open the .dmg and drag Cortexa to Applications. On first launch, macOS may show a Gatekeeper prompt since the app is not yet notarized -- right-click > Open to bypass.

The encryption passphrase is stored in the macOS Keychain. Data lives at ~/Library/Application Support/com.cortexa.app/.

Linux

Cortexa requires WebKit2GTK 4.1 and related system libraries. Install them before running the app.

Ubuntu / Debian

sudo apt install libwebkit2gtk-4.1-0 libsoup-3.0-0 librsvg2-2

Fedora

sudo dnf install webkit2gtk4.1 libsoup3 librsvg2

Arch

sudo pacman -S webkit2gtk-4.1 libsoup3 librsvg

There is no pre-built Linux package yet -- build from source (below) to produce the binary. Data lives at ~/.local/share/com.cortexa.app/.

Set Up an LLM Provider

Cortexa needs at least one chat provider (for summaries, Deep Think, re-ranking) and one embedding provider (for semantic search and knowledge graph).

Ollama (quickest path -- free, fully local)

Install Ollama, then pull the two required models:

ollama pull llama3.2          # chat / summarize / thesis (~2 GB)
ollama pull nomic-embed-text  # embeddings, 768 dims (~270 MB)

Ollama is the default provider. No API key needed -- it talks to http://localhost:11434 out of the box.

You can swap models any time in Settings > LLM:

Purpose	Recommended models
Chat	llama3.2, llama3.1:8b, qwen2.5:7b, phi3
Embeddings	nomic-embed-text, all-minilm, bge-m3 (multilingual)

Cloud providers

Each cloud provider has its own section in Settings > LLM with an API-key field and a Fetch models button that pulls the live model list from the provider's endpoint:

Provider	Chat	Embeddings	Notes
Ollama	yes	yes	Default. No API key required
Anthropic	yes	--	claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5
OpenAI	yes	yes	gpt-5, gpt-4.1, o3. Embeddings: text-embedding-3-small/large
Google Gemini	yes	yes	gemini-2.5-pro, text-embedding-004
MiniMax	yes	--	abab6.5-chat. Needs both API key and group ID
Voyage	--	yes	voyage-3, voyage-3-lite, voyage-multilingual-2

You can mix providers -- for example, Anthropic for chat with Voyage for embeddings. Pick the embedding provider in LLM > Embedding provider.

Test connection buttons in the LLM panel send a tiny probe and report latency or the exact error before you save anything.

Embedding model migration

Switching your embedding model or provider invalidates every existing vector. Click Re-embed all in the LLM panel to regenerate them. Per-item progress is emitted as embedding-migration-progress events so you can track it in the Activity panel.

Build from Source

Prerequisites

Tool	Why
Rust 1.77+	Backend compilation
Node.js 18+ and npm	Frontend toolchain (Vite + React)
Windows: WebView2 Runtime	Tauri webview (preinstalled on Windows 11)
Linux: webkit2gtk-4.1, libsoup-3, librsvg2, build essentials	Tauri runtime
macOS: Xcode command-line tools (xcode-select --install)	Tauri runtime

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

Clone and build

git clone https://github.com/cortexalabs/cortexa.git
cd cortexa
npm install

# Dev mode with Vite HMR + Rust auto-rebuild
npm run tauri dev

# Full release build: standalone binary + platform installer
npm run tauri build

Build individual binaries

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

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

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

Build outputs

File	Purpose
target/release/cortexa.exe	Standalone app binary
target/release/cortexa-cli.exe	CLI
target/release/cortexa-mcp.exe	MCP stdio bridge
target/release/cortexa-hive.exe	Hive relay server
target/release/bundle/nsis/Cortexa_<version>_x64-setup.exe	Windows installer (x64)

First release 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.

Run the tests

# Rust workspace tests (37 tests)
cargo test --workspace --features cortexa/test-support

# TypeScript type-check
npx tsc --noEmit

Dev secrets file (debug builds only)

If ~/.cortexa-dev.key exists, development builds (cargo run, npm run tauri dev) read secrets from this file instead of the OS keychain -- useful to avoid repeated keychain prompts when the Rust process restarts often. Release builds never read this file.

{
  "passphrase": "your-vault-passphrase",
  "api_token": "optional-bearer-token-for-local-API"
}

Restrict permissions: chmod 600 ~/.cortexa-dev.key on macOS/Linux.

Where Data Lives

Path	Contents
%APPDATA%\com.cortexa.app\settings.json	All non-secret config
%APPDATA%\com.cortexa.app\salt.bin	KDF salt (16 bytes, random)
%APPDATA%\com.cortexa.app\dbkey.bin	The database key, wrapped under the vault key. Keep it with salt.bin: the database can't be opened without it
%APPDATA%\com.cortexa.app\cortexa.db	SQLCipher-encrypted SQLite: items, jobs, theses, links, briefings
%APPDATA%\com.cortexa.app\blobs\<id>.bin	AES-GCM encrypted item content
%APPDATA%\com.cortexa.app\audios\<id>.bin	AES-GCM encrypted briefing audio
OS keychain cortexa/encryption-passphrase	Random 32-byte hex (per-install)
OS keychain cortexa/api-token	Random 32-byte hex (per-install)

On macOS, replace %APPDATA% with ~/Library/Application Support. On Linux, use ~/.local/share.

What's Next

• Quick Start -- capture your first thought in 5 minutes
• Thoughts & Captures -- capture types, metadata, and session grouping
• Search -- hybrid semantic + keyword search