CortexDB Production Configuration

Server: CortexProd (ssh CortexProd) Binary: /root/cortex/target/release/cortexdb Service: systemctl restart cortexdb.service Service file: /etc/systemd/system/cortexdb.service Env file: /root/cortex/.env Runtime overrides: /etc/systemd/system/cortexdb.service.d/cohere.conf Data dir: /root/cortex/cortexdb_data/ Log file: /var/log/cortexdb.log Mode: Single-node (no CLI args) Listen: 0.0.0.0:3141 (behind nginx on :443 → api-v1.cortexdb.ai)

Effective Runtime Configuration

Secrets (stored in `/root/cortex/.env`, redacted here)

OPENAI_API_KEY=<redacted>
COHERE_API_KEY=<redacted>
CORTEX_API_KEY=<redacted>
CORTEX_SUPERKEY=<redacted>
TURSO_DATABASE_URL=<redacted>
TURSO_AUTH_TOKEN=<redacted>

Embedding Service

CORTEX_EMBEDDING_PROVIDER=cohere
CORTEX_EMBEDDING_MODEL=embed-english-v3.0
CORTEX_EMBEDDING_DIMS=1024

LLM (entity extraction, query classification)

CORTEX_LLM_URL=https://api.openai.com/v1
CORTEX_LLM_MODEL=gpt-4o-mini

Enrichment (fact augmentation)

CORTEX_ENRICHMENT_MODEL=gpt-4o
CORTEX_ENRICHMENT_URL=https://api.openai.com/v1

Reranker (cross-encoder confidence scoring)

CORTEX_RERANKER_PROVIDER=cohere
CORTEX_RERANKER_MODEL=rerank-v3.5
CORTEX_RERANKER_MODEL_PATH=

Authentication

CORTEX_API_KEY=<redacted>
CORTEX_SUPERKEY=<redacted>

CORTEX_API_KEY — Bootstrap key for the "default" tenant. Used when Turso auth is not available.
CORTEX_SUPERKEY — Bypasses all rate limits and tier gates. Used for benchmarks and admin.

Turso (customer API key database)

TURSO_DATABASE_URL=<redacted>
TURSO_AUTH_TOKEN=<redacted>

When TURSO_DATABASE_URL is set, the server uses Turso for API key auth.
This is the same DB the website (cortexdb.ai) writes keys to on user signup.
Without it, the server falls back to in-memory bootstrap key (CORTEX_API_KEY only).

v1 Token Minter (PASETO)

The v1 API surface (/v1/*) authenticates with PASETO v4 public tokens. POST /v1/auth/tokens mints them; the dashboard (app.cortexdb.ai) and SDK examples are the main consumers.

CORTEX_V1_API_ADDR=0.0.0.0:3142
CORTEX_V1_AUDIENCE=cortexdb:tenant:<your-tenant>
CORTEX_V1_MINTER_ENABLE=1
CORTEX_V1_MINTER_KEY_DIR=/root/cortex/minter_keys
CORTEX_V1_MINTER_ISSUER=https://api-v1.cortexdb.ai/issuer

CORTEX_V1_API_ADDR — bind addr for the v1 surface. Without this set, the v1 router is not mounted. The legacy :3141 surface is independent.
CORTEX_V1_AUDIENCE — must match cortexdb:tenant:<tenant_id>. Used as the aud claim and verified on every request.
CORTEX_V1_MINTER_ENABLE — 1 turns on POST /v1/auth/tokens. Default is on for the dev_local preset and off everywhere else.
CORTEX_V1_MINTER_KEY_DIR — directory containing secret.key (64 raw bytes) and public.key (32 raw bytes). Without this, the minter falls back to an ephemeral keypair (tokens become invalid on restart — dev only). Production must point at a real on-disk pair.
CORTEX_V1_MINTER_ISSUER — issuer string used in the iss claim. Must be on the deployment's issuer allowlist for the verifier to accept the resulting tokens.

Generate a production keypair:

./build.sh cargo build --release -p cortex-auth --bin gen_minter_keys
./target/release/gen_minter_keys /root/cortex/minter_keys
chmod 600 /root/cortex/minter_keys/secret.key

The generator refuses to overwrite existing files — if you need to rotate, move the old pair aside first and revoke outstanding jtis via POST /v1/auth/revoke.

Capability gate. The mint endpoint requires auth.mint. Pass an optional scope in the request body to make the check scope-aware (caller must hold auth.mint on that scope). Omit scope for a deployment-wide check — used by operators minting service tokens.

Benchmark note

The best LoCoMo runs also depend on benchmark-harness choices such as --mode session, superkey usage, answer-prompt selection, and judge configuration. Those are not production server env settings and are documented separately from the runtime config above.

Implicit Defaults (no CLI args = single-node mode)

Setting	Value	Source
Mode	Single-node	No `--node-id` / `--rpc-addr` / `--gossip-addr`
Port	`3141`	Default in `parse_config()`
Listen address	`0.0.0.0:3141`	Hardcoded
Data directory	`cortexdb_data`	Default in `parse_config()`
Node ID	`1`	Default
Replication factor	`3`	Default (unused in single-node)
Log format	Text	No `CORTEX_LOG_FORMAT=json`
Log level	`info`	Default `RUST_LOG` filter

CLI Args (cluster mode — not used in prod today)

cortexdb --node-id=1 \
         --rpc-addr=0.0.0.0:3142 \
         --gossip-addr=0.0.0.0:3143 \
         --seed-nodes=10.0.0.2:3143,10.0.0.3:3143 \
         --rf=3 \
         --port=3141 \
         --data-dir=cortexdb_data_1

Data Directory (`cortexdb_data/`)

Path	Purpose
`wal/`	Write-ahead log (RocksDB) — source of truth
`content/`	Content store (RocksDB)
`fulltext/`	Tantivy fulltext index
`vector/`	HNSW vector index
`graph/`	Knowledge graph (RocksDB)
`temporal/`	Temporal index (RocksDB)
`resolver/`	Entity resolution store
`api_metrics.json`	Persisted API request metrics
`tenant_usage.json`	Persisted per-tenant usage counters

Systemd Service

[Unit]
Description=CortexDB Server
After=network.target

[Service]
Type=simple
WorkingDirectory=/root/cortex
EnvironmentFile=/root/cortex/.env
ExecStart=/root/cortex/target/release/cortexdb
Restart=always
RestartSec=3
StandardOutput=append:/var/log/cortexdb.log
StandardError=append:/var/log/cortexdb.log

[Install]
WantedBy=multi-user.target

Useful Commands

# Restart server
systemctl restart cortexdb.service

# Check status
systemctl status cortexdb.service

# Tail logs
tail -f /var/log/cortexdb.log

# Rebuild and deploy
cd /root/cortex && git pull origin main && source ~/.cargo/env && cargo build --release -p cortexdb && systemctl restart cortexdb.service

# Health check
curl https://api-v1.cortexdb.ai/v1/admin/health

# Test with superkey
curl -H "Authorization: Bearer cx_super_BenchmarkRunner2026_NoRateLimit" https://api-v1.cortexdb.ai/v1/admin/usage

PyPI (cortexdb-mcp)

Package: cortexdb-mcp Account: cortexdbai Token: pypi-AgEIcHlwaS5vcmcCJGRmNzlmNGNlLTU1ZWQtNGM0Mi1iOTRiLTgyNGI3MTczOGVlMgACKlszLCJkMmQyNzNlNi00NTQ5LTQ4ZGUtYjA5ZC1hMzAyZTkyZWU1YWQiXQAABiCcJezZsJobe684nMrFOa7abzc-i8BLBEtYc9nB3r_bZw

# Publish new version
cd mcp-server
# bump version in pyproject.toml
python3 -m build
TWINE_USERNAME=__token__ TWINE_PASSWORD="pypi-AgEI..." python3 -m twine upload dist/*