Skip to content

Configuration Reference

Jump to bottom
Doug Gerard edited this page May 14, 2026 · 1 revision

Configuration Reference

SaddleRAG is configured through appsettings.json in the installation directory (%ProgramFiles%\SaddleRAG\SaddleRAG.Mcp\appsettings.json when installed as a service). Settings changed at runtime via MCP tools are written to runtime-overrides.json in the same directory, which shadows appsettings.json for the settings it contains.

Environment-specific overlays are supported: appsettings.Development.json is loaded when ASPNETCORE_ENVIRONMENT=Development.

MongoDB

Controls database connections and profile management.

"MongoDB": {
  "ActiveProfile": "local",
  "BootstrapAllProfilesAtStartup": true,
  "ConnectionString": "mongodb://localhost:27017",
  "DatabaseName": "SaddleRAG",
  "Profiles": {
    "local": {
      "ConnectionString": "mongodb://localhost:27017",
      "DatabaseName": "SaddleRAG",
      "Description": "Local developer index"
    }
  }
}
Setting Default Description
ActiveProfile "local" Name of the profile to use when no profile is specified in a tool call. Overridden by SADDLERAG_MONGODB_PROFILE environment variable.
BootstrapAllProfilesAtStartup true When true, loads vector indexes for all profiles at startup. Set to false on a developer machine with only one profile to reduce startup time.
ConnectionString (required if no profiles) Direct connection string for single-profile mode
DatabaseName (required if no profiles) Database name for single-profile mode
Profiles (empty) Named profiles dictionary. When present, takes precedence over bare ConnectionString/DatabaseName.
Profiles[name].ConnectionString — MongoDB connection string for this profile
Profiles[name].DatabaseName — Database name for this profile
Profiles[name].Description — Human-readable description (shown in list_profiles)

Environment variable override: SADDLERAG_MONGODB_PROFILE overrides ActiveProfile at runtime.

Ollama

Controls connection to Ollama and the models used for classification and reconnaissance.

"Ollama": {
  "Endpoint": "http://localhost:11434",
  "EmbeddingModel": "nomic-embed-text",
  "EmbeddingDimensions": 768,
  "ClassificationModels": [
    { "Name": "phi4-mini" }
  ],
  "ActiveClassificationModel": "",
  "ReconModels": [
    { "Name": "phi4-mini" }
  ],
  "ActiveReconModel": "",
  "ReconMinConfidence": 0.6,
  "ModelPullTimeoutSeconds": 600,
  "WarmModelTimeoutSeconds": 30
}
Setting Default Description
Endpoint "http://localhost:11434" Ollama API base URL
EmbeddingModel "nomic-embed-text" Model name for Ollama-based embedding (only used when Onnx.EmbeddingEnabled=false)
EmbeddingDimensions 768 Expected output dimensions for the Ollama embedding model
ClassificationModels [{Name: "phi4-mini"}] Ordered list of classification model entries. Each entry has a Name field (Ollama model name).
ActiveClassificationModel "" Name of the active classification model. Empty string uses the first entry in ClassificationModels.
ReconModels [{Name: "phi4-mini"}] Models available for library reconnaissance fallback
ActiveReconModel "" Active recon model; empty = first in list
ReconMinConfidence 0.6 Minimum confidence score (0.0–1.0) for a recon result to be persisted as a LibraryProfile
ModelPullTimeoutSeconds 600 Timeout for ollama pull operations at startup
WarmModelTimeoutSeconds 30 Timeout for the model warm-up ping at startup

Onnx

Controls ONNX Runtime for in-process embedding and reranking.

"Onnx": {
  "Enabled": true,
  "EmbeddingEnabled": true,
  "ActiveEmbeddingModel": "",
  "ActiveRerankerModel": "",
  "ModelsDir": "%ProgramData%\\SaddleRAG\\models\\onnx",
  "GraphOptimizationLevel": "Basic",
  "IntraOpNumThreads": 0,
  "RerankBatchSize": 64,
  "ExecutionProvider": "Cpu",
  "EmbeddingModels": [
    {
      "Name": "nomic-embed-text-v1.5",
      "Dimensions": 768,
      "HuggingFaceRepoId": "nomic-ai/nomic-embed-text-v1.5",
      "ModelFileName": "model.onnx",
      "VocabFileName": "vocab.txt",
      "TaskPrefixDocument": "search_document: ",
      "TaskPrefixQuery": "search_query: "
    }
  ],
  "RerankerModels": [
    {
      "Name": "mxbai-rerank-base-v1",
      "HuggingFaceRepoId": "mixedbread-ai/mxbai-rerank-base-v1",
      "ModelFileName": "onnx/model_quantized.onnx",
      "MaxSequenceLength": 512
    }
  ]
}
Setting Default Description
Enabled true Master switch. When false, Ollama is used for embeddings and reranking is unavailable.
EmbeddingEnabled true Enables ONNX embedding. Can be false while Enabled is true (disables embedding but keeps reranker)
ActiveEmbeddingModel "" Name of the active embedding model. Empty = first in EmbeddingModels.
ActiveRerankerModel "" Name of the active reranker model. "none" = reranking disabled. Empty = first in RerankerModels.
ModelsDir %ProgramData%\SaddleRAG\models\onnx Root directory for downloaded ONNX model files. Each model gets a subdirectory named after the model.
GraphOptimizationLevel "Basic" ONNX Runtime graph optimization: Disable, Basic, Extended, All. Do not set to All — it triggers a fusion bug in ORT 1.26 with fp16 models.
IntraOpNumThreads 0 Thread count for ONNX Runtime. 0 = let ORT auto-detect.
RerankBatchSize 64 Number of (query, document) pairs sent to the reranker per ONNX inference call.
ExecutionProvider "Cpu" Hardware execution provider: Cpu, DirectMl (GPU on Windows), or Cuda (NVIDIA GPU).

EmbeddingModels entries

Each entry in EmbeddingModels describes one embedding model:

Field Description
Name Identifier used in ActiveEmbeddingModel and stored in LibraryVersionRecord
Dimensions Output vector size (768 for nomic-embed-text-v1.5)
HuggingFaceRepoId Hugging Face repo for automatic download
ModelFileName File path within the repo for the .onnx file
VocabFileName File path for the tokenizer vocabulary
TaskPrefixDocument Prefix prepended to text at index time
TaskPrefixQuery Prefix prepended to text at query time

RerankerModels entries

Field Description
Name Identifier
HuggingFaceRepoId Hugging Face repo for automatic download
ModelFileName Path to the .onnx file within the repo
MaxSequenceLength Maximum token sequence length for the cross-encoder (typically 512)

Ranking

Controls hybrid search scoring and reranking behavior.

"Ranking": {
  "Bm25Weight": 0.4,
  "VectorCandidateMultiplier": 5,
  "MinVectorCandidateCount": 25,
  "MaxReRankCandidates": 12,
  "ProseMentionThreshold": 3,
  "ReRankerStrategy": "Off"
}
Setting Default Description
Bm25Weight 0.4 Weight given to BM25 score in hybrid blending. 0.0 = pure vector search, 1.0 = pure BM25.
VectorCandidateMultiplier 5 Vector search retrieves max(requested, MinVec) × multiplier candidates for hybrid blending and reranking.
MinVectorCandidateCount 25 Floor on vector candidates even if fewer results were requested.
MaxReRankCandidates 12 Top-N hybrid candidates passed to the cross-encoder reranker.
ProseMentionThreshold 3 Minimum prose occurrence count for the symbol backstop to include a symbol candidate.
ReRankerStrategy "Off" "Off" or "Onnx". Can be changed at runtime via set_rerank_strategy without restart.

Kestrel (HTTP server)

"Kestrel": {
  "Endpoints": {
    "Http": {
      "Url": "http://localhost:6100"
    }
  }
}

To run on a different port:

"Kestrel": {
  "Endpoints": {
    "Http": {
      "Url": "http://localhost:7200"
    }
  }
}

To enable HTTPS (e.g., for a team server accessible over the network):

"Kestrel": {
  "Endpoints": {
    "Http": {
      "Url": "http://0.0.0.0:6100"
    },
    "Https": {
      "Url": "https://0.0.0.0:6101",
      "Certificate": {
        "Path": "cert.pfx",
        "Password": "..."
      }
    }
  }
}

Logging

"Logging": {
  "LogLevel": {
    "Default": "Information",
    "Microsoft.AspNetCore": "Warning"
  }
}

Log files are written to %LocalAppData%\SaddleRAG\logs\saddlerag-{date}.log (rolling daily, 7 files retained). When running as a Windows service, events are also written to the Windows Event Log.

The log level can be changed at runtime via the toggle_logging MCP tool without restarting the service.

Runtime overrides

Settings changed via MCP tools (set_active_embedding_model, set_active_reranker_model, set_execution_provider) are written to runtime-overrides.json in the installation directory. This file is read at startup and its values shadow appsettings.json.

The file follows the same JSON structure as appsettings.json. Settings not present in runtime-overrides.json fall back to appsettings.json.

To reset a runtime override, delete the relevant entry from runtime-overrides.json, or delete the file entirely to reset all overrides.

Environment variables

Variable Effect
SADDLERAG_MONGODB_PROFILE Overrides MongoDB.ActiveProfile at runtime
ASPNETCORE_ENVIRONMENT When Development: loads appsettings.Development.json, disables reranking, enables detailed error messages

Clone this wiki locally