Skip to content

Configuration Reference

This document describes all configuration options for Cortex AI components.

Environment Variables

Global Configuration

Variable Description Required Default
VAULT_ADDR Vault address No https://vault.emshvac.internal
VAULT_TOKEN Vault authentication token No (from Kubernetes SA)
LOG_LEVEL Logging level No info
LOG_FORMAT Log format (json, text) No json

Cortex API (cortex-api)

Variable Description Required Default
PORT HTTP server port No 8080
MCP_PORT MCP server port No 3333
QDRANT_URL Qdrant cluster URL Yes -
QDRANT_COLLECTION Default collection name No cortex
ANTHROPIC_API_KEY Anthropic API key No* -
OPENAI_API_KEY OpenAI API key No* -
OLLAMA_URL Ollama endpoint URL No -
REDIS_URL Redis cache URL No -
ZITADEL_ISSUER OIDC issuer URL Yes -

*At least one LLM provider is required

Cortex Context (cortex-context / contextd)

Variable Description Required Default
QDRANT_URL Qdrant cluster URL Yes -
QDRANT_COLLECTION Collection name No cortex
VOYAGE_API_KEY Voyage AI API key Yes -
BM25_INDEX_PATH BM25 index location No /data/bm25
SQLITE_PATH Metadata database No /data/cortex.db
RERANK_ENABLED Enable reranking No true
RERANK_TOP_K Candidates for reranking No 50

Cortex Indexer (cortex-indexer-v2)

Variable Description Required Default
WATCH_DIR Directory to index Yes -
QDRANT_URL Qdrant cluster URL Yes -
VOYAGE_API_KEY Voyage AI API key Yes -
COLLECTION Target collection No cortex
CACHE_DIR Embedding cache No /tmp/cortex-cache
BATCH_SIZE Embedding batch size No 32

Cortex Web (cortex-web)

Variable Description Required Default
PORT HTTP server port No 8081
API_URL Cortex API URL Yes -
ZITADEL_ISSUER OIDC issuer URL Yes -
ZITADEL_CLIENT_ID OIDC client ID Yes -
ZITADEL_CLIENT_SECRET OIDC client secret Yes -

Secrets Management

Cortex AI retrieves secrets from HashiCorp Vault:

Path Keys Used By
secret/cortex/anthropic-api-key api_key cortex-api
secret/cortex/voyage-api-key api_key cortex-context, cortex-indexer
secret/ai/openai api_key cortex-api

Configuration Files

MCP Configuration (Claude Desktop)

Location: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "cortex": {
      "command": "/path/to/cortex-context",
      "args": ["serve", "--port", "3333"]
    }
  }
}

VS Code Extension

Settings in .vscode/settings.json:

{
  "cortex.apiUrl": "https://api.cortex.emshvac.co",
  "cortex.collection": "my-project"
}