Skip to content

Setup

Jump to bottom
Chuyue Wang edited this page May 19, 2026 · 4 revisions

Setup

DMG Install (Recommended)

  1. Download Cortex.dmg from Releases
  2. Drag Cortex.app to /Applications
  3. Strip the quarantine attribute: 
    xattr -cr /Applications/Cortex.app
  4. Open Cortex from Applications
  5. Follow the setup wizard to configure your LLM backend and grant permissions
  6. Use the in-app Connect Chrome/Edge button to install the browser extension

The desktop app bundles the daemon, dashboard, and system tray. No Python, Node.js, or terminal setup required.

Developer Setup (from source)

Prerequisites

Requirement Install
macOS 13+ (Ventura or later) Required — Linux/Windows not supported
Python 3.11 or 3.12 brew install python@3.11 or python.org
Node.js 18+ brew install node or nodejs.org
pnpm npm install -g pnpm
LLM backend AWS Bedrock (default), GCP Vertex, or direct Anthropic API — see Provider Setup
Redis (optional) brew install redis && brew services start redis — auto-falls back to in-memory

Apple Silicon: Use native ARM Python, not Rosetta. Verify: python3 -c "import platform; print(platform.machine())" should print arm64.

1. Clone & Virtual Environment

git clone https://github.com/StevenWang-CY/cortex.git
cd cortex   # repo root

python3 -m venv .venv
source .venv/bin/activate

2. Configuration

Copy the example config:

cp cortex/.env.example .env

Cortex talks to Claude exclusively via the Anthropic SDK. Three transport providers ship today, all selected with a single env var:

CORTEX_LLM__PROVIDER=bedrock   # default — AWS Bedrock
# CORTEX_LLM__PROVIDER=vertex  # GCP Vertex AI
# CORTEX_LLM__PROVIDER=direct  # Anthropic API (ANTHROPIC_API_KEY)

The same value is mirrored into ANTHROPIC_PROVIDER at startup so the underlying SDK picks the right transport.

Option A — AWS Bedrock (default)

CORTEX_LLM__PROVIDER=bedrock
CORTEX_LLM__BEDROCK__AWS_REGION=us-east-2

The bearer token lives in macOS Keychain — never in .env:

security add-generic-password -s cortex.bedrock -a bearer_token -w YOUR_BEDROCK_TOKEN
# CORTEX_LLM__USE_KEYCHAIN=true is the default; the daemon reads
# from Keychain and exports AWS_BEARER_TOKEN_BEDROCK for the SDK.

Option B — GCP Vertex AI

CORTEX_LLM__PROVIDER=vertex

Authenticate Vertex per the standard gcloud flow (gcloud auth application-default login). The Anthropic SDK reads the resulting credentials directly.

Option C — Direct Anthropic API

CORTEX_LLM__PROVIDER=direct
export ANTHROPIC_API_KEY=sk-ant-...

Useful when you have an Anthropic API key and want to bypass the Bedrock / Vertex transports.

If every transport fails the daemon falls back to a deterministic rule-based plan (CORTEX_LLM__FALLBACK_MODE=rule_based, the default), so a missing key never crashes the session — you just lose the LLM-generated copy until the provider comes back.

Camera Configuration

Leave CORTEX_CAPTURE__DEVICE_ID commented out for automatic selection. Cortex will:

  • Enumerate cameras via AVFoundation
  • Skip iPhone/iPad Continuity Camera devices
  • Prefer the MacBook's built-in camera
  • Probe only non-Continuity indices as fallback
  • Reject any camera it cannot verify by name

Camera selection runs once at daemon startup. Restart the daemon after turning off an iPhone.

To override:

CORTEX_CAPTURE__DEVICE_ID=0   # or 1, 2, etc.

3. Install Python Dependencies

pip install -e "./cortex[dev]"

Verify:

python -c "from cortex.libs.config.settings import get_config; print(f'LLM provider: {get_config().llm.provider}')"

4. Initialize Storage

python -m cortex.scripts.seed_config --root .

Creates the storage/ directory tree and a default baseline profile.

5. macOS Permissions

Cortex needs two permissions, both prompted automatically on first use:

Camera — macOS asks when the daemon first opens the webcam. Click Allow.

Input Monitoring — required for keyboard/mouse telemetry: System Settings → Privacy & Security → Input Monitoring → add your terminal app

If you launch the daemon from the browser extension, it runs via Terminal.app — grant permission to Terminal.app specifically.

6. Start the Daemon

From terminal

source .venv/bin/activate
cortex-dev

Starts:

  • REST API on http://127.0.0.1:9472
  • WebSocket on ws://127.0.0.1:9473
  • All capture, signal processing, state engine, and intervention services

Webcam-only test

cortex-capture

Opens a window showing the webcam feed with face detection overlays and FPS counter. Press q to quit.

7. Browser Extension

cd cortex/apps/browser_extension
pnpm install
Browser Build Load from
Chrome npx plasmo build chrome://extensions → Developer mode → Load unpacked → build/chrome-mv3-prod/
Edge npx plasmo build --target=edge-mv3 edge://extensions → Developer mode → Load unpacked → build/edge-mv3-prod/

For development with hot reload: pnpm dev

Native Messaging (one-click Start/Stop from browser)

cd /path/to/repo-root
python -m cortex.scripts.install_native_host

This auto-detects all installed Chromium browsers and patches native_host.py with the absolute venv Python path. No manual extension ID needed.

Then fully restart your browser (Cmd+Q, reopen). Native messaging manifests only load at browser startup.

First-time dialogs:

  1. macOS: "Chrome/Edge wants to control Terminal. Allow?" — click Allow (one-time)
  2. A Terminal window opens when the daemon starts — this is normal

8. Calibration (recommended)

cortex-calibrate --duration 120

Sit relaxed for 2 minutes while Cortex learns your resting heart rate, HRV, blink rate, and posture. Results saved to storage/baselines/. See Calibration for details.

9. VS Code Extension (optional)

cd cortex/apps/vscode_extension
npm install && npm run compile
code --install-extension cortex-somatic-0.1.0.vsix

Provides editor context (open file, diagnostics, cursor position) to the daemon for more accurate interventions.

10. Running Tests

pytest                                      # all tests
pytest tests/unit/                          # unit tests only
pytest tests/integration/                   # integration tests
pytest --cov=cortex --cov-report=html       # with coverage
pytest -m "not requires_webcam"             # skip hardware tests

Clone this wiki locally