Environment Variables

Audience: developer or operator configuring a Cortex instance.

All variables are read from the process environment at startup by cortex/config/env.ts. Variables marked required will cause a fatal error in production if missing. In development mode, missing required variables default to empty strings.

---

API server

Name	Required	Default	Description
PORT	no	3000	HTTP server port.
NODE_ENV	no	development	Environment: development, production, or test.
CORS_ORIGIN	no	*	Allowed CORS origins for the main API.
CORS_ORIGIN_PUBLIC	no	CORS_ORIGIN value	Allowed CORS origins for public routes.
CORTEX_API_KEYS	prod	—	Comma-separated API keys for authentication. Required in production.
CORTEX_MODE	no	full	API mode: full (all routes) or lib (read-only catalogue).
HCM_DATA_DIR	no	.hcm	Local data directory for seed data and exports.

---

SurrealDB

Name	Required	Default	Description
SURREAL_URL	no	ws://localhost:8000/rpc	SurrealDB WebSocket URL. Use http://surrealdb:8000 in Docker.
SURREAL_NS	no	hcm	SurrealDB namespace.
SURREAL_DB	no	main	SurrealDB database name.
SURREAL_USER	prod	—	SurrealDB root username. Required in production.
SURREAL_PASS	prod	—	SurrealDB root password. Required in production.

---

PostgreSQL

Name	Required	Default	Description
PG_HOST	no	localhost	PostgreSQL host. Use postgres in Docker.
PG_PORT	no	5432	PostgreSQL port.
PG_DATABASE	no	hcm	PostgreSQL database name.
PG_USER	prod	—	PostgreSQL username. Required in production.
PG_PASSWORD	prod	—	PostgreSQL password. Required in production.

---

MeiliSearch

Name	Required	Default	Description
MEILI_URL	no	http://localhost:7700	MeiliSearch URL. Use http://meilisearch:7700 in Docker.
MEILI_MASTER_KEY	prod	—	MeiliSearch master key. Required in production.

---

MinIO (S3)

Name	Required	Default	Description
S3_ENDPOINT	no	http://localhost:9000	S3-compatible endpoint. Use http://minio:9000 in Docker.
S3_ACCESS_KEY_ID	prod	—	S3 access key ID. Required in production.
S3_SECRET_ACCESS_KEY	prod	—	S3 secret access key. Required in production.
S3_BUCKET	no	hcm-files	S3 bucket name.

---

Ollama (embeddings and LLM)

Name	Required	Default	Description
OLLAMA_URL	no	http://localhost:11434	Ollama server URL. Use http://ollama:11434 in Docker.
OLLAMA_MODEL	no	bge-m3	Embedding model name (1024 dimensions).
OLLAMA_LLM_MODEL	no	mistral	LLM model name for enrichment tasks.
OLLAMA_TIMEOUT	no	30000	Ollama request timeout in milliseconds. Must be >= 1000.
RESONANCE_THRESHOLD	no	0.3	Minimum score for resonance edges. Range: 0.0 to 1.0.

---

Ingestion pipeline

Name	Required	Default	Description
INGESTION_EMBEDDING_TIMEOUT_MS	no	10000	Timeout per embedding request during ingestion. Must be >= 1000.
INGESTION_EMBEDDING_MAX_INPUT_CHARS	no	8000	Maximum input length for embedding. Must be >= 100.
INGESTION_EMBEDDING_RETRY_MAX	no	3	Maximum embedding retry attempts. Must be >= 1.
INGESTION_BATCH_MAX_BLOCS	no	200	Maximum blocs per batch ingestion request. Must be >= 1.

---

Encryption

Name	Required	Default	Description
ENCRYPTION_KEY	prod	—	AES-256-GCM encryption key (32 bytes, base64-encoded). Used for provider credentials. Required in production.

---

Snapshot / Divergence

Name	Required	Default	Description
INSTANCE_ID	no	default	Unique instance identifier for snapshot comparison.
INSTANCE_LABEL	no	HCM Instance	Human-readable instance label.
HCM_VERSION	no	3.3.0	Cortex version tag included in snapshots.
SOUCHE_VERSION	no	3.3.0-base	Souche (baseline) version tag.

---

MCP server

The MCP server reads the same environment variables as the API server, plus:

Name	Required	Default	Description
MCP_TRANSPORT	no	http	Transport type: http (StreamableHTTP) or stdio.
MCP_PORT	no	3001	MCP server port (when transport is http).
MCP_VARIANT	no	main	Tool variant: main, claude-code, cloud, praxis, or public.

---

Docker Compose port overrides

These variables are used in docker-compose.example.yml to override default host-side ports:

Name	Default	Service
SURREAL_PORT	8000	SurrealDB
PG_PORT	5432	PostgreSQL
MEILI_PORT	7700	MeiliSearch
S3_PORT	9000	MinIO API
S3_CONSOLE_PORT	9001	MinIO console
OLLAMA_PORT	11434	Ollama
API_PORT	9096	Cortex API
MCP_PORT	3001	Cortex MCP
UI_PORT	8080	Cortex UI

---

Production validation

In production (NODE_ENV=production), the following variables are required and validated at startup:

• SURREAL_PASS
• PG_PASSWORD
• MEILI_MASTER_KEY
• S3_SECRET_ACCESS_KEY
• CORTEX_API_KEYS
• ENCRYPTION_KEY

The application will exit with an error if any of these are missing or empty.

Additional numeric validations:

• PORT: 1-65535
• PG_PORT: 1-65535
• OLLAMA_TIMEOUT: >= 1000
• RESONANCE_THRESHOLD: 0.0-1.0
• INGESTION_EMBEDDING_TIMEOUT_MS: >= 1000
• INGESTION_EMBEDDING_MAX_INPUT_CHARS: >= 100
• INGESTION_EMBEDDING_RETRY_MAX: >= 1
• INGESTION_BATCH_MAX_BLOCS: >= 1