Configuration

Complete reference for the CortexPrism configuration system.

Config File Location

Default: ~/.cortex/config.json

Override with:

--config / -c flag
CORTEX_CONFIG environment variable

Full Configuration Schema

{
  "version": 1,
  "defaultProvider": "anthropic",
  "providers": {
    "anthropic":  { "kind": "anthropic",  "model": "claude-sonnet-4-5",                      "apiKey": "sk-..." },
    "openai":     { "kind": "openai",     "model": "gpt-4o",                                  "apiKey": "sk-..." },
    "google":     { "kind": "google",     "model": "gemini-2.0-flash",                        "apiKey": "..." },
    "mistral":    { "kind": "mistral",    "model": "mistral-large-latest",                    "apiKey": "..." },
    "groq":       { "kind": "groq",       "model": "llama-3.3-70b-versatile",                 "apiKey": "gsk_..." },
    "deepseek":   { "kind": "deepseek",   "model": "deepseek-chat",                           "apiKey": "sk-..." },
    "openrouter": { "kind": "openrouter", "model": "openai/gpt-4o",                           "apiKey": "..." },
    "xai":        { "kind": "xai",        "model": "grok-2-latest",                           "apiKey": "..." },
    "together":   { "kind": "together",   "model": "meta-llama/Llama-3.3-70B-Instruct-Turbo", "apiKey": "..." },
    "bedrock":    { "kind": "bedrock",    "model": "anthropic.claude-3-5-sonnet-20240620-v1:0","apiKey": "AKIA...", "secretKey": "...", "baseUrl": "us-east-1" },
    "cohere":     { "kind": "cohere",     "model": "command-r-plus",                          "apiKey": "..." },
    "ollama":     { "kind": "ollama",     "model": "llama3.2",                                "baseUrl": "http://localhost:11434" },
    "cerebras":   { "kind": "cerebras",   "model": "llama-3.3-70b",                           "apiKey": "..." },
    "fireworks":  { "kind": "fireworks",  "model": "accounts/fireworks/models/llama-v3p3-70b-instruct", "apiKey": "..." },
    "perplexity": { "kind": "perplexity", "model": "sonar-pro",                               "apiKey": "..." },
    "nvidia":     { "kind": "nvidia",     "model": "meta/llama-3.3-70b-instruct",             "apiKey": "..." },
    "moonshot":   { "kind": "moonshot",   "model": "moonshot-v1-8k",                          "apiKey": "..." },
    "novita":     { "kind": "novita",     "model": "meta-llama/llama-3.1-8b-instruct",        "apiKey": "..." },
    "lmstudio":   { "kind": "lmstudio",   "model": "local-model",                             "baseUrl": "http://localhost:1234" },
    "litellm":    { "kind": "litellm",    "model": "gpt-4o",                                  "baseUrl": "http://localhost:4000" },
    "huggingface":{ "kind": "huggingface","model": "meta-llama/Llama-3.3-70B-Instruct",       "apiKey": "..." },
    "alibaba":    { "kind": "alibaba",    "model": "qwen-max",                                "apiKey": "..." },
    "venice":     { "kind": "venice",     "model": "dolphin-2.9.2-qwen2-72b",                 "apiKey": "..." },
    "kilo":       { "kind": "kilo",       "model": "kilo/sonnet",                             "apiKey": "..." }
  },
  "agent": {
    "name": "My Agent",
    "maxTurns": 50,
    "streamOutput": true
  },
  "router": {
    "enabled": false,
    "strategy": "cascade",
    "confidenceThreshold": 0.7,
    "cascade": [
      { "provider": "ollama", "model": "llama3.2:3b" },
      { "provider": "ollama", "model": "llama3.1:8b" },
      { "provider": "anthropic", "model": "claude-sonnet-4-5" }
    ]
  },
  "update": {
    "channel": "stable",
    "checkOnStartup": true,
    "autoUpdate": false,
    "checkIntervalHours": 24,
    "githubToken": "",
    "gpgKeyPath": ""
  }
}

Router Configuration

Strategy

Value	Description
`cascade`	Try providers in order, falling through each level
`threshold`	Route based on complexity scoring threshold

The cascade strategy attempts each provider in sequence: if the first provider fails or returns low confidence, the router falls through to the next. The threshold strategy evaluates task complexity and routes directly to the appropriate provider tier.

Confidence Threshold

Controls how strictly the router evaluates LLM responses before cascading to the next provider. Higher values (0.8+) enforce stricter quality gates; lower values (0.5) cascade less aggressively.

Update Configuration

The update section controls Cortex's self-update behavior:

Field	Type	Description	Default
`channel`	`string`	Update channel: `stable` or `pre-release`	`stable`
`checkOnStartup`	`boolean`	Check for updates on startup	`true`
`autoUpdate`	`boolean`	Automatically apply updates	`false`
`checkIntervalHours`	`number`	Periodic check interval	`24`
`githubToken`	`string`	GitHub token for API rate limits	`""`
`gpgKeyPath`	`string`	Path to GPG key for signature verification	`""`

Update Channels

Channel	Description
`stable`	Production-ready releases with full testing
`pre-release`	Pre-release builds with latest features

Binary vs Source Mode

Binary mode: Downloads pre-built binaries with SHA-256 verification and optional GPG signature validation
Source mode: Pulls latest source and rebuilds (when running from source or binary unavailable)

Environment Variables

Variable	Description	Default
`CORTEX_CONFIG`	Path to config file	`~/.cortex/config.json`
`CORTEX_DATA_DIR`	Data directory path	`~/.cortex/`
`CORTEX_VAULT_KEY`	Vault encryption passphrase	—
`OPENAI_API_KEY`	OpenAI API key	—
`ANTHROPIC_API_KEY`	Anthropic API key	—
`GOOGLE_API_KEY`	Google AI API key	—

Data Directory Structure

~/.cortex/
├── config.json
└── data/
    ├── cortex.db        → Core: sessions, jobs, policy rules
    ├── memory.db         → 5-tier memory + FTS5 + embeddings
    ├── lens.db           → Audit log
    ├── vault.db          → Encrypted credentials
    ├── plugins.db        → Plugin registry
    └── sess_*.db         → Per-session message history

Provider Configuration Details

OpenAI-Compatible Providers

Providers like Groq, DeepSeek, OpenRouter, xAI, and Together AI use the openai compatible API format with custom baseUrl:

{
  "groq": { "kind": "openai", "model": "llama-3.3-70b-versatile", "apiKey": "gsk_...", "baseUrl": "https://api.groq.com/openai/v1" }
}

AWS Bedrock

Bedrock requires secretKey in addition to apiKey, with baseUrl set to the AWS region:

{
  "bedrock": { "kind": "bedrock", "model": "anthropic.claude-3-5-sonnet-20240620-v1:0", "apiKey": "AKIA...", "secretKey": "...", "baseUrl": "us-east-1" }
}

Ollama (Local)

Ollama runs locally and doesn't need an API key, just a baseUrl pointing to the Ollama server:

{
  "ollama": { "kind": "ollama", "model": "llama3.2", "baseUrl": "http://localhost:11434" }
}

Memory & Embeddings

The embeddings section configures the embedding provider used for vector memory:

{
  "embeddings": {
    "provider": "openai",
    "model": "text-embedding-3-small",
    "apiKey": "sk-..."
  }
}

Supported providers: openai, ollama (local), stub (basic, no external dependency).

The memory section configures the vector store backend:

{
  "memory": {
    "vectorStore": {
      "kind": "sqlite",
      "collection": "cortex"
    }
  }
}

Supported backends:

Kind	Type	Configuration
`sqlite`	Built-in	No additional config needed
`qdrant`	Self-hosted or cloud	`url` (e.g. `http://localhost:6333`), optional `apiKey`, `collection`
`chromadb`	Open-source	`url` (e.g. `http://localhost:8000`), optional `apiKey`, `collection`
`pinecone`	Managed cloud	`url` (index host), `apiKey`, `collection`, optional `namespace`

Chrome Bridge (Browser Automation)

Chrome Bridge integrates browser automation via the MCP protocol:

{
  "chromeBridge": {
    "enabled": true,
    "nodePath": "node",
    "serverPath": "/path/to/chrome-bridge-server.js",
    "port": 9222,
    "autoStart": true,
    "autoRegisterTools": true,
    "toolPrefix": "chrome"
  }
}

Voice / Speech

Configure speech-to-text (STT) and text-to-speech (TTS):

{
  "voice": {
    "enabled": true,
    "sttProvider": "openai",
    "ttsProvider": "openai",
    "sttModel": "whisper-1",
    "ttsModel": "tts-1",
    "defaultVoice": "alloy",
    "autoTTS": false,
    "language": "en"
  }
}

TTS providers: openai (OpenAI TTS), elevenlabs (requires elevenLabsApiKey).

Server Configuration

{
  "server": {
    "corsOrigin": "same-origin",
    "maxBodyBytes": 10485760,
    "https": {
      "enabled": true,
      "certFile": "/path/to/cert.pem",
      "keyFile": "/path/to/key.pem"
    }
  }
}

Channel Integrations

Channels are configured under plugins.channels:

{
  "plugins": {
    "channels": {
      "enabled": ["web", "discord", "slack"],
      "credentials": {
        "discord": { "token": "..." },
        "slack": { "botToken": "xoxb-...", "appSecret": "..." }
      }
    }
  }
}

Supported channels: web, discord, slack, telegram, teams, mattermost, rocketchat, whatsapp, google-chat, lark.

Telemetry & Logging

{
  "logging": {
    "level": "info",
    "fileEnabled": true,
    "fileMaxBytes": 10485760,
    "fileMaxFiles": 5,
    "otlp": { "endpoint": "http://localhost:4318", "headers": {} },
    "langfuse": { "publicKey": "...", "secretKey": "..." },
    "grafana": { "otlpEndpoint": "...", "authToken": "..." }
  }
}