Skip to content

Configuration reference

Every key in config.yaml, with its default.

Every key in the configuration file is listed here. Defaults come from config.yaml.example in the v1.0.0-rc.2 repository.

For how to configure Cortrix and for common scenarios, see Configuration. When a key also has an environment variable, the environment variable wins.

server

KeyDefaultDescription
host"127.0.0.1"The address to listen on. Binding to a non-loopback address requires authentication to be on
port8420The HTTP port
thread_count4Worker threads. The recommended value is your CPU core count. Environment variable: CORTRIX_SERVER_THREADS

auth

KeyDefaultDescription
enabledfalseWhether API key authentication is on. With it off, only a loopback bind is accepted
api_keys[].key_hash—The SHA-256 of the key
api_keys[].tenant_id—The tenant the key belongs to
api_keys[].permissions—Permission bits: READ=1, WRITE=2, ADMIN=4. 7 is all of them
api_keys[].expires_at0Expiry time. 0 never expires

log

KeyDefaultDescription
level"info"trace, debug, info, warn, error, critical, or off
format"text"text or json
output"stdout"stdout, stderr, or a file path

namespace

KeyDefaultDescription
data_dir"./build/data"The data root, holding databases, the vector index, and files. A relative path is resolved from the directory of the cortrix-server binary

embedding

KeyDefaultDescription
model_path"./models/bge-m3/model.onnx"The embedding model path. Leave it empty to select the stub explicitly
tokenizer_path"./models/bge-m3/tokenizer.json"The tokenizer path
dimension1024The vector dimension. Fixed at 1024 for bge-m3 and can’t be changed
max_seq_length512The maximum tokens per encode
execution_provider"auto"auto, cpu, coreml, or cuda. Environment variable: CORTRIX_EMBEDDING_EXECUTION_PROVIDER

reranker

KeyDefaultDescription
model_dir"./models/bge-reranker-v2-m3"The reranker model directory. Leave it empty to select the stub explicitly. Environment variable: CORTRIX_RERANKER_MODEL_DIR
execution_provider"auto"auto, cpu, coreml, or cuda. Environment variable: CORTRIX_RERANKER_EXECUTION_PROVIDER

query_complexity

KeyDefaultDescription
model_dir"./models/query-complexity"The directory of the query-complexity classifier. If the model is absent, a heuristic is used instead. Environment variable: CORTRIX_QUERY_COMPLEXITY_MODEL_DIR

retrieval

KeyDefaultDescription
candidate_multiplier3How many times top_k the candidate pool is, at least 1. Environment variable: CORTRIX_RETRIEVAL_CANDIDATE_MULTIPLIER
max_candidates50The hard ceiling on the candidate pool, at least 1. Environment variable: CORTRIX_RETRIEVAL_MAX_CANDIDATES

See Performance tuning.

spc

The Semantic Processing Chain (SPC), the document processing pipeline. It supports PDF, DOCX, TXT, MD, CSV, JSON, and images (through OCR).

KeyDefaultDescription
worker_count2Threads processing in parallel. 2 to 4 is recommended
chunk_size512The target number of tokens per text block
chunk_overlap50Tokens shared between neighboring blocks
embedding_batch_size1Blocks embedded per batch
onnx_intra_threads4Intra-op threads for ONNX inference
onnx_inter_threads1Parallel ONNX inferences
python_bin"./scripts/ocr_venv/bin/python3.12"The Python used by the parsing scripts
parse_pdf_script"./scripts/parse_pdf.py"The PDF parsing script
parse_word_script"./scripts/parse_word.py"The Word parsing script
ocr_script"./scripts/run_ocr.py"The OCR script
parser_timeout_s120Document parsing timeout, in seconds
ocr_timeout_s3600OCR timeout, in seconds

LLM roles

The five roles semantic_llm, vision_llm, agent_llm, doc_summary_llm, and enricher_llm each have their own section with the same fields:

KeyDescription
provideropenai, glm, claude, ollama, deepseek, or mock
api_keyThe provider’s API key
modelThe provider’s model identifier
base_urlThe API address

A role counts as configured only when provider, api_key, and model are all set. See Configuration.

watch_dir

KeyDefaultDescription
data_dir""The absolute path of a local directory to watch. Empty turns it off
namespace_name"local"The namespace files are imported into. It’s created if it doesn’t exist
watch_enabledtrueWhen false, existing files are imported but later changes aren’t watched

To manage watchers through the API, see Watch a directory.

memory

KeyDefaultDescription
default_ttl_seconds0How long memory is kept. 0 keeps it forever
inject_recent_turns5How many recent turns to include when injecting context
inject_max_tokens2000The token ceiling for injected context

rag_fusion

KeyDefaultDescription
default_enabledfalseThe global default for whether it’s on
default_variant_count3How many query variants to generate
default_rrf_k60The rank-fusion constant
default_timeout_ms5000The timeout for the LLM to generate variants
llm_prompt_template_zh"default-zh"The Chinese prompt template
llm_prompt_template_en"default-en"The English prompt template

RAG-Fusion is off by default and runs only when an LLM role is configured. The configuration template notes that the server doesn’t read the keys in this section yet, so the built-in defaults are what’s actually used.

gc

Garbage collection runs in three stages: soft delete, hard delete, and file cleanup.

KeyDefaultDescription
enabledtrueWhether the background garbage collection thread runs
soft_delete_retention_days30Days a soft-deleted item is kept, during which it can be restored
blob_gc_retention_days90Days a file is kept after hard delete before it’s physically removed
scan_interval_hours24The interval between background scans
max_purge_per_run10000The most files cleaned up in one run
max_run_duration_minutes5The longest a single run can take
dry_runfalseScan without deleting, for testing and inspection
immediate_purge_enabledfalseTurns on the immediate-purge API. Leave it false

Environment variables for Docker

See Configuration.

Table reader