Skip to content

Configuration file ​

The CLI and the TypeScript API read one JSON config file per run — by default ~/.autorag/config.json (or $AUTORAG_HOME/config.json). This page documents every key the loader accepts, its type, default, and meaning, with a minimal and a fully annotated example. For how the path is chosen see CLI commands; for the environment overrides see Environment variables.

Precedence ​

For a given setting, the first source that supplies a value wins:

  1. Command-line flag (--search-paths, --workspace, --memory-path, --languages, --permission-mode, --model-provider/--model-id).
  2. Environment variable (AUTORAG_SEARCH_PATHS, AUTORAG_WORKSPACE, AUTORAG_MEMORY_PATH, AUTORAG_LANGUAGES, AUTORAG_PERMISSION_MODE, AUTORAG_MODEL_PROVIDER/AUTORAG_MODEL_ID).
  3. Config file.
  4. Built-in default.

Relative paths in the config file (and in a migrated legacy config) resolve against the config file's directory; relative memoryPath resolves against the resolved workspacePath. excludePaths entries that look like globs are kept verbatim; other entries resolve against the workspace.

Top-level keys ​

KeyTypeDefaultMeaning
configPathstringresolved pathRead-only; the absolute path of the file the config was resolved from. Never set by hand
searchPathsstring[]["."]Folders to parse, index, and search
workspacePathstringcurrent directoryDirectory that owns .autorag state and the index cache
memoryPathstring$AUTORAG_HOME/memory.jsonRetrieval-memory file
languagesstring[]["ko","en"]OCR and parser languages
modelAgentModelConfignoneLibrarian chat model (see below)
minSyncobject | false{enabled:true,autoInstall:true}MinSync indexing. false and enabled:false are rejected — MinSync is required
jikjiobject | false{}Jikji find-first discovery; false disables
everythingobject | falseenabled on WindowsWindows-only Everything file-name search; false disables
fsearchobject | falseenabled on macOS/Linuxfsearch-cli file-name search; false disables
webSearchobjectenabledweb_search + web_fetch tools
jevobject{backend:<default>}The required decision model
queryDecompositionobject | false{model:<default>}Question decomposition; false lets the session model decompose
permissionMode"auto" | "ask" | "full""auto"Approval gate for file changes by the agent
rerankobject | falseabsent (off)Post-merge reranking; opt-in
parserOptionsobject{}Parser and OCR tuning
dupeyobject{enabled:true}Exact/near-duplicate scan settings
excludeExactDuplicatesbooleantrueDrop exact-duplicate copies from the local index
fileeobjectenabledfilee-cli behind the conversion tools; enabled:false removes them
excludePathsstring[][]Files/dirs (absolute or workspace-relative, or a glob) omitted from local indexing
limitsobjectshipped defaultsHard caps on retrieval, prefetch, and candidate lists
refreshobjectshipped defaultsRefresh limits, retry tuning, and the watch schedule
datasourcesobject{}Datasource skills: name → config or boolean

model ​

FieldTypeDefaultMeaning
providerstringrequiredProvider identity for auth lookup and Model.provider (e.g. openrouter, fireworks)
idstringrequiredWire model id sent to the provider API
namestringidDisplay name
apistringopenai-completionsWire format when baseUrl is set: openai-completions, openai-responses, anthropic-messages, openai-codex-responses, azure-openai-responses
baseUrlstringcatalog endpointEndpoint base URL; overrides only the catalog endpoint for a known provider/id
apiKeyEnvstring${PROVIDER}_API_KEY when baseUrl is setEnvironment variable holding the key (name only). Rejected for provider dazzi
reasoningboolean—Whether the model emits reasoning
input("text"|"image")[]["text"]Accepted input modalities
contextWindowinteger > 0catalogContext window
maxTokensinteger > 0catalogMax output tokens

The same shape is used by jev.sllm.model and queryDecomposition.model.

minSync ​

FieldTypeDefaultMeaning
enabledtruetrueAccepted for compatibility; false is rejected
autoInstallbooleantrueDownload/install the MinSync binary into the workspace cache when missing
workspacePathstringworkspaceOverride where MinSync stores its workspace
maxChunkSizeinteger > 0MinSync defaultChunk size limit
installerobject—Installer tuning forwarded to the MinSync binary fetcher
embedderobjectnative Qwen3-Embedding-0.6BVector embedder (below)

minSync.embedder fields (unknown keys are rejected):

FieldTypeDefaultMeaning
idstringnative:Qwen/Qwen3-Embedding-0.6BEmbedder id; none selects a sparse-only SPLADE index
baseUrlstring—Remote embedder endpoint
apiKeyEnvstring—Env var holding the bearer key (name only)
dimensioninteger > 0—Vector dimension
queryPrefixstring—Prefix added to queries
passagePrefixstring—Prefix added to passages
timeoutMsinteger > 0—Per-request timeout
batchSizeinteger > 0—Batch size
maxRetriesinteger > 0—Retry budget
maxConcurrentinteger > 0—Concurrency

jev ​

The decision model is required; an absent section or {} uses the default backend (dazzi when signed in to Dazzi Models, else openrouter).

FieldTypeDefaultMeaning
backendstringdazzi | openrouterdazzi, a pi provider with decision models (openrouter, openai, typesafe, vercel-ai-gateway, cloudflare-workers-ai, opencode), or sllm
modelstringbackend defaultDecision model id within the backend. Not valid with backend:"sllm"
confidenceThresholdnumber 0–1per-sourceEscalate verdicts below this confidence
sllm.modelAgentModelConfigdecomposition modelThe small chat LLM used with backend:"sllm" or as the fallback
fallbackbooleantrueMove to the sLLM when Jev is unavailable; false fails the session. Ignored with backend:"sllm"

rerank ​

Opt-in: reranking runs only when model is named. A block without a model is treated as off and reported once as a rerank-disabled diagnostic.

FieldTypeDefaultMeaning
enabledboolean— (false disables)Turn the block off without deleting it
provider"openrouter" | "dazzi"openrouterProvider
modelstring— (required to enable)Wire model id
apiKeyEnvstringOPENROUTER_API_KEY for openrouterEnv var holding the key (name only). Rejected for dazzi
baseUrlstringprovider defaultOverride the provider base URL
topNinteger > 025Return only the top N merged results
timeoutMsinteger > 0provider defaultPer-request timeout

everything ​

Windows only; ignored on other platforms.

FieldTypeDefaultMeaning
enabledbooleantrueEnable the bundled file-name search
timeoutMsintegertest seamSearch timeout
startupTimeoutMsintegertest seamStartup timeout
indexTimeoutMsintegertest seamIndex timeout

fsearch ​

macOS/Linux only; ignored on other platforms.

FieldTypeDefaultMeaning
enabledbooleantrueEnable fsearch-cli file-name search
binaryPathstringon PATHPath to the client
timeoutMsintegertest seamSearch timeout
startupTimeoutMsintegertest seamStartup timeout
indexTimeoutMsintegertest seamIndex timeout
watchbooleantrueKeep a fsearch-cli watch daemon live

Without fsearch-cli, name search falls back to a bounded filesystem walk.

webSearch ​

FieldTypeDefaultMeaning
enabledbooleantrueEnable web_search and web_fetch; false disables both
providerstringautoPreferred provider (e.g. gemini, parallel, searxng)
orderstring[]shipped chainProvider order
excludestring[]—Providers to skip
timeoutSecondsinteger 1–30060Per-provider transport timeout
fetch.enabledbooleantrueEnable web_fetch
fetch.timeoutSecondsinteger 1–300—Page fetch/render timeout

The default chain is credential-free: model-native providers reuse the agent's own model credentials; a self-hosted SEARXNG_ENDPOINT is the only env-gated option. Set "fetch": false to disable page fetching alone.

limits ​

FieldTypeDefaultMeaning
mergedEvidenceCeilinginteger > 0shippedCap on merged evidence
singleDatasourceTopKinteger > 0shippedPer-datasource result cap
minSyncTopKinteger > 0shippedMinSync result cap
minSyncScopedQueryTopKinteger > 0shippedMinSync cap for a scoped query
toolDescriptionInstanceScopesinteger > 0shippedInstance scopes listed per tool description
prefetch.jikjiTopKinteger > 0shippedJikji prefetch cap
prefetch.minSyncTopKinteger > 0shippedMinSync prefetch cap
prefetch.datasourceTopKinteger > 0shippedDatasource prefetch cap
prefetch.jikjiPathLimitinteger > 0shippedJikji path cap
prefetch.sectionLimitinteger > 0shippedSection cap
recordCut.enabledbooleanshippedToggle record cutting
recordCut.depthinteger 1–maxshippedFusion depth
recordCut.newRecordSharenumber 0–1shippedNew-record share
recordCut.perRecordFloorinteger > 0shippedPer-record floor
recordCut.perRecordDivisorinteger > 0shippedPer-record divisor
recordCut.resultCharsinteger > 0shippedResult character budget
recordCut.minReadCharsinteger > 0shippedMinimum read characters

Unknown limits.* keys are rejected.

refresh ​

FieldTypeDefaultMeaning
maxDeleteRationumber 0–1shippedDelete-ratio valve for the parsed mirror
maxScannedEntriesinteger > 0shippedWalk cap
maxDepthinteger ≥ 0shippedWalk depth cap
transientRetriesinteger ≥ 03Per-file retries for EMFILE/EBUSY/EIO/ETIMEDOUT
cloudMaxFilesinteger > 0shippedCloud placeholder file cap
cloudMaxBytesinteger > 0shippedCloud placeholder byte cap
cloudEvictAfterParsebooleanshippedEvict a cloud placeholder after parsing
cloudEvictRetriesinteger ≥ 0shippedPlacement retry budget
scheduleobject—Watch schedule: { power, windows, days } (see Scheduling and exclusions)

refresh.schedule drives autorag watch; the --power/--window/--days flags override it. Invalid schedule values raise a ConfigError carrying the underlying validation message.

parserOptions ​

FieldTypeDefaultMeaning
ocrobjectoffOCR tuning; ocr.enabled is the single opt-in
kordocobject—kordoc parser tuning; an explicit kordoc.ocr always wins
languagesstring[]global languagesParser-local language override
fileTimeoutMsinteger120000Hard per-file parse deadline; a parse past it is skipped as parser-failed
maxHeapMbinteger—V8 old-generation heap limit for the parse worker

dupey, filee ​

KeyFieldTypeDefaultMeaning
dupeyenabledbooleantrueEnable duplicate scanning
dupeybinaryPathstringon PATHPath to dupey
dupeytimeoutMsinteger—Scan timeout
fileeenabledbooleantruefalse removes the conversion tools
fileebinaryPathstringon PATHPath to filee/filee-cli
fileeautoInstallbooleantrueDownload the pinned filee-cli into <AUTORAG_HOME>/tools
fileetimeoutMsinteger—Conversion timeout
fileedataDirstringFilee's per-user folderFolder for Filee's own settings and engines

datasources ​

datasources maps a skill name (or connection alias) to a config object or boolean. false and enabled:false skip the entry; a configured name with no matching skill is reported by autorag setup and skipped.

FieldTypeMeaning
enabledbooleanTurn this entry off
descriptionstringOperator-authored context shown to the agent
typestringBuilt-in template used when the key is a connection alias
instanceIdstringStable instance id
pollingIntervalMsintegerPoll interval
tagsstring[]Descriptive tags
connectorobjectConnector-specific options (token env names, repos, feeds, paths)
channels.ids / channels.namesstring[]Chat/channel allowlist; absent means all

Secrets never appear in the config: a connector references a credential by environment-variable name (for example connector.tokenEnv: "SLACK_BOT_TOKEN"). See Connecting datasources and the per-datasource pages for connector keys.

Minimal example ​

json
{
  "searchPaths": ["/path/to/docs"],
  "workspacePath": "/path/to/docs",
  "memoryPath": "/path/to/.autorag/memory.json",
  "languages": ["ko", "en"],
  "minSync": { "enabled": true, "autoInstall": true }
}

Full annotated example ​

json
{
  "searchPaths": ["/path/to/docs", "/path/to/notes"],
  "workspacePath": "/path/to/docs",
  "memoryPath": "/path/to/.autorag/memory.json",
  "languages": ["ko", "en"],
  "excludePaths": ["/path/to/docs/archive", "**/node_modules/**"],

  "model": { "provider": "<provider>", "id": "<model-id>" },
  "minSync": {
    "enabled": true,
    "autoInstall": true,
    "maxChunkSize": 1500,
    "embedder": {
      "id": "native:Qwen/Qwen3-Embedding-0.6B",
      "dimension": 1024,
      "queryPrefix": "Instruct: retrieve\nQuery:",
      "batchSize": 32
    }
  },

  "jikji": { "autoInstall": true, "timeoutMs": 60000 },
  "everything": { "enabled": true },
  "fsearch": { "enabled": true, "watch": true },
  "webSearch": { "enabled": true, "provider": "auto", "timeoutSeconds": 60 },

  "jev": { "backend": "openrouter", "model": "<decision-model-id>", "fallback": true },
  "queryDecomposition": { "model": { "provider": "<provider>", "id": "<model-id>" } },
  "rerank": {
    "provider": "openrouter",
    "model": "<rerank-model-id>",
    "apiKeyEnv": "OPENROUTER_API_KEY",
    "topN": 25
  },
  "permissionMode": "auto",

  "parserOptions": { "ocr": { "enabled": false }, "fileTimeoutMs": 120000 },

  "dupey": { "enabled": true },
  "excludeExactDuplicates": true,
  "filee": { "enabled": true, "autoInstall": true },

  "limits": { "minSyncTopK": 50, "prefetch": { "datasourceTopK": 20 } },
  "refresh": { "transientRetries": 3, "schedule": { "power": "any", "days": ["mon", "tue", "wed", "thu", "fri"] } },

  "datasources": {
    "github": { "enabled": true, "connector": { "repos": ["owner/repo"], "tokenEnv": "GITHUB_TOKEN" } },
    "obsidian": { "enabled": true, "connector": { "vaultPath": "/path/to/vault" } }
  }
}

Validation and rejected values ​

Malformed config fails fast with a ConfigError; the command exits 2. Unknown keys are rejected rather than ignored. Examples of the error classes:

  • Unknown flag: --<name> / Unknown command: <name> — argument parser.
  • Config file not found: <path> — explicit --config/AUTORAG_CONFIG path missing.
  • Config file must be a JSON object — the file is not an object.
  • Config field 'excludePaths' must be a non-empty string array.
  • MinSync is required and cannot be disabled; remove minSync: false/minSync.enabled: false from the config.
  • jev.enabled is no longer supported: ... — the old enabled switch was removed; the decision model is required.
  • --permission-mode must be one of: ask, auto, full.
  • rerank.provider must be one of: openrouter, dazzi.

Secrets

Never put API keys, tokens, or personal paths in the config. The only credential-shaped field is an environment-variable name (apiKeyEnv, connector.tokenEnv, connector.*Env); the value stays in the environment. See Environment variables.

See also ​

Released under the Apache-2.0 license.