Skip to content

Environment variables ​

AutoRAG keeps all secrets in the environment and reads them at startup; nothing credential-shaped is written to the config file. This page lists every environment variable the shipped code reads, where it is read, what it changes, and its default. For the file half of the same settings see Configuration file; for flags see CLI commands.

Core paths and search settings ​

Read in src/cli/config.ts (via resolveConfig) and src/config/home.ts.

VariableEffectDefault
AUTORAG_HOMEOperator home directory; owns config.json, memory.json, attachments/, automations.json, the MCP owner token, and downloaded tools. Absolute paths resolve as given; relative values resolve against the current directory~/.autorag
AUTORAG_CONFIGExplicit config file path (same effect as --config; marks the path explicit for init --force)unset
AUTORAG_SEARCH_PATHSComma-separated folders to index and search (same as --search-paths)["."]
AUTORAG_WORKSPACEDirectory that owns .autorag state (same as --workspace)current directory
AUTORAG_MEMORY_PATHRetrieval-memory file (same as --memory-path)$AUTORAG_HOME/memory.json
AUTORAG_LANGUAGESComma-separated OCR/parser languages (same as --languages); also read by autorag initko,en
AUTORAG_PERMISSION_MODEApproval gate for file changes: auto, ask, or full (same as --permission-mode)auto
AUTORAG_MODEL_PROVIDERModel provider override (used with AUTORAG_MODEL_ID)from config
AUTORAG_MODEL_IDModel id override (used with AUTORAG_MODEL_PROVIDER)from config

Precedence is flag → environment variable → config file → default. AUTORAG_MODEL_PROVIDER and AUTORAG_MODEL_ID must be set together.

Authentication and cloud ​

VariableRead whereEffectDefault
AUTORAG_AUTH_MODEsrc/cloud/credential.ts, src/cli/config.ts, src/agent/local-model.ts, src/agent/decision-backends.tsWhen set to environment, stored credentials (pi auth.json, OAuth, the Dazzi /login token) are ignored, and external model-config discovery is disabled; only environment variables authenticateunset
AUTORAG_BASE_URLsrc/cloud/config.tsServer root for the hosted Dazzi Models plan; the API is served under <root>/v1https://api.dazziapp.com

Update check ​

VariableRead whereEffectDefault
AUTORAG_NO_UPDATE_CHECKsrc/cli/update-check.tsAny non-empty value other than 0 skips the npm version lookupunset (check runs)
AUTORAG_UPDATE_CHECK_URLsrc/cli/update-check.tsRegistry endpoint override for the latest versionhttps://registry.npmjs.org/@autorag/librarian/latest

Model and decision-model credentials ​

Chat and decision credentials are read through pi-ai's provider environment conventions (findEnvKeys/getEnvApiKey) and by the Jev backend resolver; a configured endpoint with a baseUrl instead reads the variable named by model.apiKeyEnv (which defaults to ${PROVIDER}_API_KEY).

VariableEffect
OPENROUTER_API_KEYCredential for the openrouter provider (chat and Jev backend)
OPENAI_API_KEYCredential for the openai provider
ANTHROPIC_API_KEYCredential for the anthropic provider
GEMINI_API_KEY, GOOGLE_API_KEYCredential for the Google/Gemini provider
XAI_API_KEYCredential for the xai provider
TYPESAFE_API_KEYCredential for the typesafe Jev backend
AI_GATEWAY_API_KEYCredential for the vercel-ai-gateway Jev backend
CLOUDFLARE_API_KEYCredential for the cloudflare-workers-ai Jev backend
OPENCODE_API_KEYCredential for the opencode Jev backend
<PROVIDER>_API_KEYGeneric convention for a configured endpoint's provider
the var named by minSync.embedder.apiKeyEnvBearer key for a remote embedder; passed to the MinSync child as OPENAI_API_KEY

A provider is "available" exactly when its documented variable holds a non-empty value; autorag health and autorag models list --available report this without printing the value.

Web search and page fetch ​

VariableRead whereEffectDefault
SEARXNG_ENDPOINTsrc/web/search/providers/searxng.tsBase URL of a self-hosted SearXNG instance — the only env-gated search providerunset (provider unavailable)
SEARXNG_TOKENsameOptional bearer tokenunset
SEARXNG_BASIC_USERNAME, SEARXNG_BASIC_PASSWORDsameOptional Basic auth; both are required togetherunset
SEARXNG_ENGINESsameRestrict SearXNG enginesunset
SEARXNG_CATEGORIESsameRestrict SearXNG categoriesunset
SEARXNG_SAFESARCHsameSafe-search level: 0 off, 1 moderate, 2 strictunset
ANTHROPIC_SEARCH_MODELsrc/web/search/providers/anthropic.tsOverride the model used for Anthropic's built-in web searchprovider default
GEMINI_SEARCH_MODELsrc/web/search/providers/gemini.tsOverride the model used for Gemini groundingprovider default
FIRECRAWL_API_KEYsrc/web/fetch/html-renderer.tsKey for the Firecrawl HTML rendererunset (renderer skipped)
JINA_API_KEYsrc/web/fetch/html-renderer.tsOptional key for the Jina reader (https://r.jina.ai/, keyless without it)unset
AUTORAG_WEB_BROWSER_PATHsrc/web/search/browser-loader.tsPath to a browser binary for bot-challenge escalationunset
CHROME_PATH, PUPPETEER_EXECUTABLE_PATHsameFallback browser paths, checked after AUTORAG_WEB_BROWSER_PATHunset

MCP server (autorag-mcp) ​

Read in src/mcp/index.ts.

VariableEffectDefault
AUTORAG_MCP_TOKENOwner token every HTTP request must present as Authorization: Bearer <token> (at least 32 characters). When unset, a random token is generated and stored owner-only at $AUTORAG_HOME/mcp-http-tokengenerated token file
AUTORAG_MCP_TOOLSComma-separated allowlist of tools to exposeall tools
AUTORAG_MCP_READ_ONLYstdio transport only: 1/true restricts the server to read-only tools; unset exposes read-write tools. The HTTP transport ignores it and uses --allow-write (which defaults to read-only)unset (read-write)
AUTORAG_MCP_PUBLIC_URLhttps origin a cloud agent reaches the HTTP server at (tunnel/proxy); enables the OAuth endpoints connector-only clients needunset

Datasource CLIs ​

AutoRAG's connector-backed datasources run an external CLI that owns its own credentials and cache. These variables are read by that CLI (AutoRAG forwards them) or by AutoRAG when locating/pointing it.

VariableRead whereEffect
HISTER_CONFIGsrc/datasource/skills/hister/setup.tsPath to Hister's config.yml when it is not at a standard location
MAILCRAWL_DATA_DIRsrc/datasource/skills/mailcrawl/client.tsmailcrawl archive/data directory
WOMBAT_DATA_DIRsrc/datasource/skills/wombat/agents.ts, client.tswombat data directory (~/.wombat by default)
WOMBAT_EMBEDDERsrc/datasource/skills/wombat/client.tsEmbedder selector passed to wombat
MINSYNC_SERVERsrc/datasource/skills/wombat/client.tsMinSync server mode forwarded to the wombat child
CLAWGALLERY_CONFIG_DIRsrc/datasource/skills/clawgallery/client.tsClawGallery config directory
KATOK_EMBED_API_KEYsrc/datasource/embedding-env.tsEmbedder key for the lazykatok child when it embeds for itself

Each crawler CLI also reads its own SLACRAWL_*, MAILCRAWL_*, WOMBAT_*, CLAWGALLERY_*, HISTER_*, and KATOK_* variables for authentication and transport; see the datasource pages for the connector-specific names.

Embedder key for external CLIs

When mailcrawl or lazykatok embeds for itself, AutoRAG points it at the same backend as the rest of AutoRAG by setting that CLI's documented *_EMBED_* / KATOK_EMBED_* variables in the child environment. The remote key travels as the value of the variable named by minSync.embedder.apiKeyEnv; you only need to set that one variable yourself.

Standard variables the code reads ​

AutoRAG also reads conventional variables for platform and home discovery — they are not AutoRAG-specific and need no setup:

VariableRead whereEffect
HOME, USERPROFILEsrc/config/home.tsBase for ~/.autorag; an absolute HOME/USERPROFILE wins, else os.homedir()
PATHbinary resolution in src/minsync, src/jikji, src/cli/setup.ts, src/automation/service.tsLocates minsync, jikji, crawler CLIs, and the automation service
CARGO_HOMEsrc/datasource/skills/wombat/binary.ts, jikji installercargo install location when auto-installing a Rust tool
XDG_DATA_HOME, XDG_CONFIG_HOMEsrc/cli/setup.ts, src/automation/service.ts, src/datasource/skills/hister/setup.tsXDG paths for tools and the automation service on Linux
LOCALAPPDATA, APPDATAsrc/embedding/daemon.ts, src/datasource/skills/hister/setup.tsWindows per-user data locations
NODE_ENVinstallers in src/convert, src/minsyncInstaller behavior in non-production runs

Variables that exist only for the repository's QA and live-E2E scripts (for example AUTORAG_EMBED_ENDPOINT, AUTORAG_CALC_QA_*, E2E_*, MINSYNC_BINARY, AUTORAG_OPENAI_API_KEY) are not read by the shipped CLI and are intentionally omitted here.

Released under the Apache-2.0 license.