Environment Variables

All configuration is done via .env. Copy example.env and fill in your values:

cp example.env .env

Configuration Levels

Each integration has a configuration level indicating its importance:

Level	Meaning	Behavior when not configured
Required	Core system dependency	System will error — chat and primary functions will not work
Recommended	Significant feature enabler	Graceful degradation — the feature is visibly unavailable but the system runs
Optional	Enhancement capability	Transparent degradation — system works fine, capability simply not present

Note: Admin-configured models (Admin → Models page) can substitute for LLM environment variables. The health check considers both sources.

Frontend (Local Dev Only)

The frontend has a separate env file only for local development: frontend/.env.local.

This file is NOT used in Docker. Inside the Docker container, Next.js proxies /api/* to the Python backend internally (port 8000 is container-internal), so no frontend env file is needed.

For local dev, the defaults work out of the box — you do not need to create frontend/.env.local unless your backend runs on a non-default port. If you need to override, create frontend/.env.local manually:

echo 'NEXT_PUBLIC_API_URL=http://localhost:9000' > frontend/.env.local

Variable	Default	Description
`NEXT_PUBLIC_API_URL`	`http://localhost:8000` (auto)	Backend URL the browser uses for direct API calls (OAuth redirects, streaming). Auto-detected from `window.location` if unset — only override if your backend runs on a non-standard port locally.

Build-time note: NEXT_PUBLIC_* variables are baked into the JS bundle at pnpm build time. Changing them at runtime (e.g. via root .env) has no effect — this is why they live in frontend/.env.local for local dev only.

LLM (Required)

Variable	Required	Default	Description
`LLM_API_KEY`	Yes	—	API key for the LLM provider
`LLM_BASE_URL`	No	`https://api.openai.com/v1`	Base URL of any OpenAI-compatible API
`LLM_MODEL`	No	`gpt-4o`	Main model — used for planning, analysis, and ReAct agent
`FAST_LLM_MODEL`	No	(falls back to `LLM_MODEL`)	Fast model — used for DAG step execution (cheaper, faster)
`LLM_TEMPERATURE`	No	`0.7`	Default sampling temperature
`LLM_CONTEXT_SIZE`	No	`128000`	Context window size for the main LLM
`LLM_MAX_OUTPUT_TOKENS`	No	`64000`	Max output tokens per call for the main LLM
`FAST_LLM_API_KEY`	No	(falls back to `LLM_API_KEY`)	API key for the fast model provider. Use when the fast model is hosted by a different provider than the main model
`FAST_LLM_BASE_URL`	No	(falls back to `LLM_BASE_URL`)	Base URL for the fast model provider
`FAST_LLM_TEMPERATURE`	No	(falls back to `LLM_TEMPERATURE`)	Sampling temperature for the fast model
`FAST_LLM_CONTEXT_SIZE`	No	(falls back to `LLM_CONTEXT_SIZE`)	Context window size for the fast LLM
`FAST_LLM_MAX_OUTPUT_TOKENS`	No	(falls back to `LLM_MAX_OUTPUT_TOKENS`)	Max output tokens per call for the fast LLM
`LLM_REASONING_EFFORT`	No	(disabled)	Extended thinking level for supported models (OpenAI o-series, Gemini 2.5+, Claude). Values: `low`, `medium`, `high`. LiteLLM translates this to each provider’s native format automatically. The model’s chain-of-thought is surfaced in the UI “thinking” step.
`LLM_REASONING_BUDGET_TOKENS`	No	(auto from effort)	Explicit token budget for Anthropic thinking (minimum 1024). For OpenAI/Gemini the effort level is used directly. Only effective when `LLM_REASONING_EFFORT` is set.
`FIM_GPT5_RESPONSES_MODE`	No	`native`	Which protocol GPT-5.x models use. `native` talks the OpenAI Responses API directly and replays each turn’s encrypted reasoning, so the model keeps its chain of thought across tool calls. `bridge` uses LiteLLM’s chat-completions translation, which works but re-derives the reasoning every round. `off` forces plain chat completions, where reasoning is disabled whenever tools are present. Leave unset unless you are debugging; endpoints without a `/v1/responses` route fall back on their own. Applies to GPT-5.x only.
`LLM_JSON_MODE_ENABLED`	No	`true`	Global toggle for `response_format=json_object`. Set to `false` if your provider rejects LiteLLM’s assistant prefill injection (e.g. AWS Bedrock relay → `ValidationException` on the 2nd+ agent iteration). When disabled, structured calls skip JSON mode and fall back to plain-text regex extraction — no quality loss. Applies to all models (ENV-configured and Admin-configured).
`LLM_TOOL_CHOICE_ENABLED`	No	`true`	Global toggle for forced `tool_choice` in structured output extraction (Level 1 — Native Function Calling). Set to `false` if your model returns errors with forced tool selection (e.g. thinking-mode models that reject `tool_choice='specified'`). When disabled, structured calls skip native FC and start from JSON Mode. Per-model override available in Settings → Models → Advanced.
`REASONING_LLM_MODEL`	No	(falls back to `LLM_MODEL`)	Model name for the reasoning tier. Used for tasks requiring deep analysis (e.g., DAG planning, plan analysis)
`REASONING_LLM_API_KEY`	No	(falls back to `LLM_API_KEY`)	API key for the reasoning model provider
`REASONING_LLM_BASE_URL`	No	(falls back to `LLM_BASE_URL`)	Base URL for the reasoning model provider
`REASONING_LLM_TEMPERATURE`	No	(falls back to `LLM_TEMPERATURE`)	Sampling temperature for the reasoning model
`REASONING_LLM_CONTEXT_SIZE`	No	(falls back to `LLM_CONTEXT_SIZE`)	Context window size for the reasoning model
`REASONING_LLM_MAX_OUTPUT_TOKENS`	No	(falls back to `LLM_MAX_OUTPUT_TOKENS`)	Max output tokens per call for the reasoning model
`REASONING_LLM_EFFORT`	No	(falls back to `LLM_REASONING_EFFORT`)	Reasoning effort level for the reasoning model tier. Values: `low`, `medium`, `high`
`REASONING_LLM_BUDGET`	No	(falls back to `LLM_REASONING_BUDGET_TOKENS`)	Token budget for reasoning (primarily Anthropic). Overrides the auto-calculated budget for the reasoning tier
`LLM_SUPPORTS_VISION`	No	`true` (optimistic)	Controls whether ENV-mode document OCR (via MarkItDown + `markitdown-ocr`) is attempted. Only applies when no active model group is configured in Admin → Models (pure ENV mode). When the default `true` is in effect, `convert_to_markdown` and RAG ingestion assume `LLM_MODEL` supports vision and call it for image OCR — this is the correct behavior for all common choices (`gpt-4o`, `claude-3-5-sonnet`, `gemini-1.5-pro/flash`). Set this to `false` when your ENV-configured `LLM_MODEL` does not support vision (e.g. `deepseek-v3`, `qwen-chat`, `llama-3.1`, `gpt-3.5-turbo`, `o1-mini`) to skip the failing vision call and go straight to text-only extraction. When an active model group exists in the Admin → Models panel, this flag is ignored and the group’s `supports_vision` flags take over — the admin-curated choice is always the source of truth in DB mode.

Resolution order: User Preference → Admin Models (DB) → ENV Fallback. If an admin model with role “General” is configured in Admin → Models, these ENV vars serve as fallback only. The health check considers both sources.

MarkItDown OCR Resolution

The convert_to_markdown built-in tool and the RAG ingestion pipeline both use Microsoft’s MarkItDown + the official markitdown-ocr plugin to extract text from documents — including OCR on embedded images and scanned PDF pages when a vision-capable LLM is available. Vision LLM resolution order (first match wins):

#	Source	Priority rationale
1	Agent’s primary LLM if `supports_vision=True`	Consistency: same API key, same billing bucket, same rate-limit pool as the conversation.
2	Active ModelGroup → Fast Model if `supports_vision=True`	Fast models (`gpt-4o-mini`, `claude-haiku`, `gemini-1.5-flash`) are the ideal OCR workhorse — cheap, low-latency, usually multimodal.
3	Active ModelGroup → General Model if `supports_vision=True`	Quality fallback when the primary is not in the group.
4	ENV primary LLM (`LLM_MODEL`)	Optimistic fallback for pure ENV mode. Only taken when no active ModelGroup exists. Gated by `LLM_SUPPORTS_VISION`.

Reasoning models are never preferred for OCR. Reasoning tiers (o1, o3-mini, DeepSeek-R1) historically lack vision support and are the wrong tool for OCR anyway — OCR is a perception task, not deliberation. If a workspace has only a reasoning model with supports_vision=True it will still be picked up via the primary-LLM path, but the resolver does not actively rank it above fast/general. Zero-regression fallback: when no vision-capable model is found at any level, OCR is silently disabled and MarkItDown runs in text-only mode. Word/PowerPoint/Excel embedded-image OCR becomes unavailable (same as before this feature shipped), but all other text extraction (headings, tables, paragraph text) continues to work unchanged. There is never a case where adding this feature made extraction worse than the previous behavior. Non-OpenAI providers (Anthropic, Google Gemini, etc.) are supported transparently: the resolved LLM is wrapped in a LiteLLMOpenAIShim that routes chat.completions.create(...) calls through litellm.completion(), which handles the provider-specific message format translation (e.g. Anthropic’s source.type="base64" image block). One shim covers every provider LiteLLM supports — adding a new provider costs zero code changes in FIM One.

Extended Thinking (Reasoning)

When LLM_REASONING_EFFORT is set, FIM One enables the model’s extended thinking capability so the internal chain-of-thought is surfaced in the UI “thinking” step. FIM One uses LiteLLM to translate the reasoning effort parameter into each provider’s native format automatically.

Supported providers

Which providers accept thinking, how each one is switched on, which effort values it takes, and where the reasoning text ends up are recorded once, with code anchors, in Table C of the Provider Capability Matrix. That table is the authoritative list; this page only documents the variables. FIM One resolves the provider from LLM_BASE_URL (plus an explicit provider field when one is configured) and maps the request to the correct API format. Unknown URLs are treated as OpenAI-compatible.

Important caveats

Third-party proxies / custom endpoints are not guaranteed. If your LLM_BASE_URL points to a third-party API proxy (e.g., OpenRouter, one-api, custom gateway), LiteLLM will attempt to route correctly based on the URL. However, if your proxy expects a non-standard format, reasoning may not work as expected. Consult the proxy’s documentation for their expected parameter format.

Temperature constraints with reasoning

Some providers restrict temperature when reasoning is active. All of these are enforced automatically; leave LLM_TEMPERATURE at whatever suits your workload.

Anthropic: requires temperature=1 while extended thinking is enabled. The request builder pins the value on Anthropic routes, so your configured temperature is overridden for those calls rather than rejected.
Anthropic, strict models (Opus 4.7 and 4.8, Fable 5, Mythos 5): reject temperature, top_p and top_k outright, thinking or not. FIM One removes temperature from the request for these models.
OpenAI GPT-5.x: only supports temperature=1. LiteLLM’s drop_params filtering removes unsupported values.

Setting LLM_TEMPERATURE=1 by hand to satisfy Anthropic is unnecessary and costs you the ability to run a lower temperature on every non-thinking call.

How `LLM_REASONING_BUDGET_TOKENS` works

This variable is meaningful only on the legacy Anthropic thinking path (Claude 4.5 and older, routed as anthropic/). There it overrides the auto-calculated budget and is sent as budget_tokens inside the thinking parameter. Adaptive-thinking models (Opus 4.6 and newer, Sonnet 4.6, Fable 5, Mythos 5) take an effort level instead of a budget and ignore this variable entirely. When it is not set, the budget is derived from LLM_MAX_OUTPUT_TOKENS x effort ratio:

`LLM_REASONING_EFFORT`	Budget ratio	Example (max_tokens = 64000)
`low`	20%	12,800 tokens
`medium`	50%	32,000 tokens
`high`	80%	51,200 tokens

The minimum budget is 1,024 tokens (Anthropic’s hard minimum). For OpenAI and Gemini, the provider handles token allocation internally based on the reasoning_effort level — LLM_REASONING_BUDGET_TOKENS has no effect.

Agent Execution

ReAct Agent

Variable	Required	Default	Description
`REACT_MAX_ITERATIONS`	No	`20`	Max tool-call iterations per ReAct request. Higher = more thorough but slower and costlier
`REACT_MAX_TURN_TOKENS`	No	`0`	Emergency circuit-breaker: max cumulative tokens (prompt + completion across all iterations) per single ReAct turn. Default `0` = unlimited. This is NOT for daily token control — use per-user `token_quota` for that. This is a last-resort safety valve for extreme scenarios like an agent stuck in an infinite tool-call loop. Hitting this limit aborts the task mid-execution, wasting all tokens consumed so far and returning an incomplete result. Keep at `0` unless you have a specific runaway-agent problem to contain
`REACT_TOOL_SELECTION_THRESHOLD`	No	`12`	When the total number of registered tools exceeds this threshold, a lightweight LLM call selects the most relevant subset before each request
`REACT_TOOL_SELECTION_MAX`	No	`6`	Max tools to keep after smart selection (only effective when tool count exceeds `REACT_TOOL_SELECTION_THRESHOLD`)
`REACT_SELF_REFLECTION_INTERVAL`	No	`6`	Inject a self-reflection prompt every N tool calls to help the agent course-correct and avoid loops
`REACT_TOOL_OBS_TRUNCATION`	No	`8000`	Max characters per tool observation when synthesizing the final answer. Higher values preserve more structured data (JSON, tables) at the cost of more tokens
`REACT_TOOL_RESULT_BUDGET`	No	`40000`	Aggregate token budget for all tool results in a single session. When total tool-result tokens exceed this cap, new results are truncated with a notice. Prevents context bloat from large API responses (e.g., 5 connector calls returning 8K each). Set to `0` to disable the cap
`REACT_COMPLETION_CHECK_SKIP_CHARS`	No	`800`	Skip the post-answer completion-check LLM call when the agent’s final answer exceeds this many characters. Long detailed answers don’t need a “did I miss anything?” verification round-trip. Set lower to skip more aggressively; set to a very large value to always run the check
`REACT_CYCLE_DETECTION_THRESHOLD`	No	`2`	When the same tool is called with identical arguments this many times in a row, a deterministic warning is injected telling the agent to try a different approach. Unlike self-reflection (which relies on the LLM noticing the loop), this is a hash-based check that cannot be bypassed. Also applies to DAG steps
`REACT_COMPLETION_CHECK_MIN_TOOLS`	No	`3`	Minimum number of tool calls before the completion checklist fires. Simple tasks (1-2 tool calls) skip verification to avoid unnecessary latency. Set to `1` for always-on verification. Also applies to DAG steps
`REACT_TURN_PROFILE_ENABLED`	No	`true`	Emit per-turn phase-level timing logs (`memory_load`, `compact`, `tool_schema_build`, `llm_first_token`, `llm_total`, `tool_exec`). One structured log line per turn. Set to `false` to disable profiling entirely (zero overhead)
`REACT_PLAN_TOOL_ENABLED`	No	`true`	Register the `update_plan` todo tool so the agent writes down and maintains a plan checklist during multi-step tasks. Automatically skipped for DAG step agents and agents with no tools
`REACT_PLAN_REMINDER_INTERVAL`	No	`3`	Tool rounds without an `update_plan` call before a stale-plan reminder (embedding the full checklist) is re-injected into the conversation, so the plan survives context compaction
`REACT_PLAN_REPEAT_THRESHOLD`	No	`4`	Consecutive rounds calling the same tool (with different arguments) before a reminder tells the agent to change approach instead of repeating fruitless calls. Exact-duplicate calls are handled separately by cycle detection
`REACT_PLAN_NUDGE_AFTER`	No	`5`	Tool rounds with no plan recorded before a one-shot nudge suggests writing the plan down. Only applies when the plan tool is enabled
`REACT_FINISH_SIGNAL`	No	`true`	FINAL-first answering on the chat path: the agent ends its tool loop on a `finish` signal and then writes the answer as a genuinely token-streamed turn. Set to `false` to restore inline loop answers with buffered replay
`REACT_MAX_CONTINUATIONS`	No	`3`	Maximum continuation rounds when the model’s answer is cut off by the provider’s output-token limit (`finish_reason=length`). Truncated segments are stitched into one seamless answer, both in the agent loop and in streamed synthesis
`REACT_BACKGROUND_TOOLS_ENABLED`	No	`true`	Offer a `run_in_background` option on slow tools (sandboxed python/shell/node execution). The agent gets a task id immediately and continues working; the result arrives as a `<task_notification>` message when the tool finishes
`REACT_BG_WAIT_TIMEOUT`	No	`300`	Maximum seconds to wait for still-running background tools when the agent wants to finalize its answer. Tasks not finished within the window are cancelled with an explicit timeout notification
`DAG_CHECKPOINT_EVIDENCE_CHARS`	No	`4000`	Per-step evidence cap in the DAG crash-resume checkpoint file (`data/dag_checkpoints/`). Step summaries are stored in full
`DAG_CHECKPOINT_MAX_AGE_HOURS`	No	`24`	DAG checkpoints older than this are ignored on load, so stale crash leftovers never resume into a fresh run
`LLM_RATE_LIMIT_PER_USER`	No	`true`	Use per-user keyed rate-limit buckets instead of a single process-global bucket. Prevents one noisy user from starving all others on the same worker. The underlying rate is hardcoded at 60 requests/min and 100K tokens/min per bucket — this setting only controls whether the bucket is shared (global) or partitioned (per-user). Set to `false` to revert to the legacy global bucket (not recommended)

DAG Planner

Variable	Required	Default	Description
`MAX_CONCURRENCY`	No	`5`	Max parallel steps in DAG executor
`DAG_STEP_MAX_ITERATIONS`	No	`15`	Max tool-call iterations within each DAG step
`DAG_STEP_TIMEOUT`	No	`600`	Step execution timeout in seconds. Steps exceeding this are marked as failed and their dependents are cascade-skipped
`DAG_MAX_REPLAN_ROUNDS`	No	`3`	Max autonomous re-plan attempts when goal is not achieved. User interrupts (inject) are unlimited and do not count against this budget
`DAG_REPLAN_STOP_CONFIDENCE`	No	`0.8`	Applies only when the agent judges the goal unreachable (impossible request, missing capability, dead resource): stop retrying at or above this certainty. A missing or half-finished deliverable is always re-planned regardless of confidence — only `DAG_MAX_REPLAN_ROUNDS` bounds those retries
`DAG_VERIFY_TRUNCATION`	No	`2000`	Max characters of step output sent to the step verifier LLM for quality judgment
`DAG_ANALYZER_TRUNCATION`	No	`10000`	Max characters per step result when formatting for the post-execution analyzer
`DAG_STEP_EVIDENCE_CHARS`	No	`16000`	Max characters of raw tool output (web fetches, search results, file reads) retained per step as authoritative “source evidence”. This is fed to the analyzer and final synthesis alongside the step’s own summary, so the answer’s factual claims (totals, enumerations, severities) can be verified against the source instead of trusting a summary that may have silently dropped or mislabelled items. Set to `0` to disable evidence capture
`DAG_REPLAN_RECENT_TRUNCATION`	No	`500`	Max characters per step result from the most recent round when building re-plan context
`DAG_REPLAN_OLDER_TRUNCATION`	No	`200`	Max characters per step result from older rounds when building re-plan context. Older rounds are more aggressively truncated to save context
`DAG_TOOL_CACHE`	No	`true`	Cache identical tool calls within a single DAG execution. Only tools explicitly marked as `cacheable` (read-only tools like search, knowledge retrieval) are cached. Set to `false` to disable caching entirely
`DAG_STEP_VERIFICATION`	No	`false`	Generic LLM-based quality check after each DAG step. On failure, the step retries once with feedback. Default off — adds latency on every step and is rarely needed; most step outputs are acceptable without re-checking. Use only when you observe frequent low-quality step results
`DAG_CITATION_VERIFICATION`	No	`true`	Citation-accuracy check for specialist-domain steps. Prerequisite: the query must first be classified as a specialist domain by the LLM domain classifier (see `ESCALATION_DOMAINS`). When the domain is detected AND this flag is `true`, each completed step is scanned for legal/medical/financial citations and verified for accuracy — catching hallucinated article numbers, fabricated case references, and incorrect regulatory citations. If domain classification returns `null` (general query), citation verification does not run regardless of this setting
`DAG_CITATION_VERIFY_TRUNCATION`	No	`6000`	Max characters of step result sent to the citation verification prompt

Domain Classification

Controls the independent LLM-based domain detection layer that runs before both ReAct and DAG execution. When a query is classified as a specialist domain, the system activates domain-aware features: model escalation to reasoning model, domain-specific SOP instructions, and citation verification (DAG only).

Variable	Required	Default	Description
`ESCALATION_DOMAINS`	No	`legal,medical,financial,tax,compliance,patent`	Comma-separated list of specialist domains. A fast LLM classifies each query against this list. When matched, the system: (1) upgrades to the reasoning model for higher accuracy, (2) injects domain-specific SOP instructions (e.g. verify citations via search before writing), (3) enables citation verification for DAG steps. Add custom domains as needed (e.g. `legal,education,construction`)

Context Guard

Controls the automatic context window management that prevents conversations from exceeding the model’s limit.

Variable	Required	Default	Description
`CONTEXT_GUARD_DEFAULT_BUDGET`	No	`32000`	Default token budget for context window management. When the conversation exceeds this, older messages are compacted
`CONTEXT_GUARD_MAX_MSG_CHARS`	No	`50000`	Hard character limit on any single message. Messages exceeding this are truncated as a safety net
`CONTEXT_GUARD_KEEP_RECENT`	No	`4`	Number of most recent messages to preserve when compacting conversation history

Content Guardrails

Comma-separated names of guardrails that inspect the content of input or output. Independent of the tool-permission gate (core/hooks/*) and the security layer (core/security/*). See Content Guardrails for the full picture.

Variable	Required	Default	Description
`FIM_GUARDRAILS_INPUT`	No	`jailbreak`	Active input guardrails. The default `jailbreak` regex detector aborts the turn before any LLM tokens are spent when known prompt-override phrases are detected. Set to empty to disable. Unknown names are logged and skipped
`FIM_GUARDRAILS_OUTPUT`	No	(empty)	Active output guardrails. Currently shipped: `max_length` (caps answer character count). Run after the agent produces its final answer
`FIM_GUARDRAIL_MAX_OUTPUT_CHARS`	No	`50000`	Character cap used by the `max_length` output guardrail. Only effective when `max_length` is listed in `FIM_GUARDRAILS_OUTPUT`

Agent Workspace

Variable	Required	Default	Description
`WORKSPACE_OFFLOAD_THRESHOLD`	No	`8000`	When a tool output exceeds this many characters, it is saved to a workspace file and a truncated preview is injected into the conversation context
`WORKSPACE_PREVIEW_CHARS`	No	`2000`	Number of preview characters to include in truncated workspace references
`WORKSPACE_CLEANUP_MAX_HOURS`	No	`72`	Workspace files older than this many hours are eligible for automatic cleanup

System

Variable	Required	Default	Description
~~`SYSTEM_PROMPT_RESERVE`~~	—	—	Removed. Previously subtracted a fixed 4K reserve from the context budget for system prompts. This caused double-counting because ContextGuard already includes the system prompt when estimating message list tokens. The budget formula is now `(context_size - max_output_tokens) × 0.92` (the margin absorbs token-estimation error), and the system prompt’s actual size is accounted for dynamically

Web Tools (Optional)

Variable	Required	Default	Description
`JINA_API_KEY`	No	—	Jina API key. Powers the default search backend, and acts as a shared fallback for fetch, embedding, and reranker when no service-specific key is set. Get yours at jina.ai
`TAVILY_API_KEY`	No	—	Tavily Search API key. Required when `WEB_SEARCH_PROVIDER=tavily`; also used by auto-detect if the provider is unset
`BRAVE_API_KEY`	No	—	Brave Search API key. Required when `WEB_SEARCH_PROVIDER=brave`; also used by auto-detect if the provider is unset
`EXA_API_KEY`	No	—	Exa Search API key. Required when `WEB_SEARCH_PROVIDER=exa`; also used by auto-detect if the provider is unset. See Exa. Get yours at exa.ai
`WEB_SEARCH_PROVIDER`	No	`jina`	Search provider selector: `jina` (default) / `tavily` / `brave` / `exa`. Prefer setting this explicitly when using a non-default provider
`WEB_FETCH_PROVIDER`	No	`jina` (if key set, else `httpx`)	Fetch provider: `jina` (uses Jina Reader API) / `httpx` (direct HTTP request, no API key needed)

Quick start tip: Setting just JINA_API_KEY enables the default web search stack, plus web fetch, embedding, and reranking — one key, four services. Switch search to Tavily, Brave, or Exa with WEB_SEARCH_PROVIDER and the matching API key.

RAG & Knowledge Base (Recommended)

Embedding

Embedding converts text into vectors for knowledge base search. FIM One uses the standard OpenAI-compatible /v1/embeddings endpoint, so it works with any provider that exposes this interface — not just Jina.

Variable	Required	Default	Description
`EMBEDDING_API_KEY`	No	(falls back to `JINA_API_KEY`)	API key for the embedding provider
`EMBEDDING_BASE_URL`	No	`https://api.jina.ai/v1`	Base URL for the embedding provider
`EMBEDDING_MODEL`	No	`jina-embeddings-v3`	Model identifier
`EMBEDDING_DIMENSION`	No	`1024`	Vector dimension

Provider examples — just set the three variables to switch:

Provider	`EMBEDDING_BASE_URL`	`EMBEDDING_MODEL`	`EMBEDDING_DIMENSION`
Jina (default)	`https://api.jina.ai/v1`	`jina-embeddings-v3`	`1024`
OpenAI	`https://api.openai.com/v1`	`text-embedding-3-small`	`1536`
Voyage	`https://api.voyageai.com/v1`	`voyage-3`	`1024`
Ollama (local)	`http://localhost:11434/v1`	`nomic-embed-text`	`768`

Changing the embedding model or dimension invalidates all existing knowledge base vectors. Old vectors were computed in a different embedding space — retrieval accuracy will degrade silently. You must rebuild all knowledge base indexes after switching.

Retrieval

Variable	Required	Default	Description
`RETRIEVAL_MODE`	No	`grounding`	`grounding` (full pipeline with citations and confidence scoring) or `simple` (basic RAG)

Reranker

Reranker re-scores retrieved documents to improve relevance. Three providers are supported — select via RERANKER_PROVIDER or let the system auto-detect from available API keys.

Variable	Required	Default	Description
`RERANKER_PROVIDER`	No	(auto-detect)	`jina` / `cohere` / `openai`. If unset: uses Cohere if `COHERE_API_KEY` set, otherwise Jina
`RERANKER_MODEL`	No	`jina-reranker-v2-base-multilingual`	Model identifier (applies to Jina and OpenAI providers)
`COHERE_API_KEY`	No	—	Cohere API key (auto-selects Cohere reranker when set and `RERANKER_PROVIDER` is unset)
`COHERE_RERANKER_MODEL`	No	`rerank-multilingual-v3.0`	Cohere-specific reranker model

Jina uses JINA_API_KEY (from Web Tools above). OpenAI reuses LLM_API_KEY / LLM_BASE_URL — no extra key needed. Cohere requires its own COHERE_API_KEY.

Reranker is optional — knowledge base search works without it using fusion scoring. Embedding is recommended for knowledge base features.

Vector Store

Variable	Required	Default	Description
`VECTOR_STORE_DIR`	No	`./data/vector_store`	Directory for LanceDB vector store data (file-based, zero external services)

Code Execution

Variable	Required	Default	Description
`CODE_EXEC_BACKEND`	No	`local`	`local` (direct host execution) or `docker` (isolated containers)
`DOCKER_PYTHON_IMAGE`	No	`python:3.11-slim`	Docker image for Python execution
`DOCKER_NODE_IMAGE`	No	`node:20-slim`	Docker image for Node.js execution
`DOCKER_SHELL_IMAGE`	No	`python:3.11-slim`	Docker image for shell execution
`DOCKER_MEMORY`	No	(Docker default)	RAM cap per container (e.g. `256m`, `512m`, `1g`)
`DOCKER_CPUS`	No	(Docker default)	CPU quota per container (e.g. `0.5`, `1.0`)
`SANDBOX_TIMEOUT`	No	`120`	Default execution timeout in seconds
`DOCKER_HOST_DATA_DIR`	No	(not set)	Host-side absolute path of the `./data` volume mount. Required for DooD (Docker-outside-of-Docker) deployments; `docker-compose.yml` auto-sets via `${PWD}/data`.

Security: local mode runs AI-generated code directly on the host. For internet-facing or multi-user deployments, always set CODE_EXEC_BACKEND=docker.

Tool Artifacts

Size limits for files produced by tool execution (code execution, template rendering, image generation).

Variable	Required	Default	Description
`MAX_ARTIFACT_SIZE`	No	`10485760` (10 MB)	Max single artifact file size in bytes
`MAX_ARTIFACTS_TOTAL`	No	`52428800` (50 MB)	Max total artifact size per session in bytes

Document Processing (Optional)

Controls how uploaded PDF/DOCX files are processed for LLM consumption. Vision-capable models (GPT-4o, Claude 3/4, Gemini) can receive PDF pages as rendered images for higher fidelity.

Variable	Required	Default	Description
`DOCUMENT_PROCESSING_MODE`	No	`auto`	`auto` (vision if model supports it), `vision` (always render pages), `text` (always extract text only)
`DOCUMENT_VISION_DPI`	No	`150`	DPI for PDF page rendering. Higher = better quality, more tokens
`DOCUMENT_VISION_MAX_PAGES`	No	`20`	Maximum pages to render as images per PDF

Note: Per-model vision support is configured via the supports_vision toggle in Admin → Models. When not explicitly set, the system auto-detects vision capability from the model name.

Image Generation (Optional)

Variable	Required	Default	Description
`IMAGE_GEN_PROVIDER`	No	`google`	`google` (Gemini native API) or `openai` (OpenAI-compatible `/v1/images/generations`)
`IMAGE_GEN_API_KEY`	No	—	Google AI Studio key (`google`) or proxy/OpenAI API key (`openai`)
`IMAGE_GEN_MODEL`	No	`gemini-3.1-flash-image-preview`	Image generation model (e.g. `dall-e-3`, `gemini-nano-banana-2`)
`IMAGE_GEN_BASE_URL`	No	(per provider)	Google: `https://generativelanguage.googleapis.com/v1beta`; OpenAI: `https://api.openai.com/v1`

Email (SMTP) (Recommended)

Auto-registers the email_send built-in tool when SMTP_HOST, SMTP_USER, and SMTP_PASS are all set.

Variable	Required	Default	Description
`SMTP_HOST`	Cond.	—	SMTP server hostname
`SMTP_PORT`	No	`465`	SMTP port
`SMTP_SSL`	No	`ssl`	TLS mode: `ssl` (port 465) / `tls` (STARTTLS, port 587) / `none` or `""` (plain, credentials sent in cleartext). Any other value is rejected rather than silently falling back to plain.
`SMTP_USER`	Cond.	—	SMTP login username
`SMTP_PASS`	Cond.	—	SMTP login password
`SMTP_FROM`	No	(uses `SMTP_USER`)	Sender address shown in From header
`SMTP_FROM_NAME`	No	—	Display name shown in From header
`SMTP_REPLY_TO`	No	—	Reply-To address; replies go here instead of `SMTP_FROM`
`SMTP_ALLOWED_DOMAINS`	No	—	Comma-separated domain allowlist (e.g. `example.com,corp.io`); blocks recipients outside listed domains
`SMTP_ALLOWED_ADDRESSES`	No	—	Comma-separated exact-address allowlist; combined with `SMTP_ALLOWED_DOMAINS`; leave both unset to allow any recipient (not recommended for shared mailboxes)

Connectors

Variable	Required	Default	Description
`CONNECTOR_RESPONSE_MAX_CHARS`	No	`50000`	Max characters for non-array JSON / plain-text connector responses
`CONNECTOR_RESPONSE_MAX_ITEMS`	No	`10`	Max array items to keep when connector response is a JSON array
`CREDENTIAL_ENCRYPTION_KEY`	No	(unset)	Fernet encryption key for connector credential blobs. When set, auth tokens stored in `connector_credentials` are encrypted at rest. If unset, credentials are stored as plaintext JSON (backward-compatible). Changing this key invalidates all existing encrypted credentials.
`CONNECTOR_TOOL_MODE`	No	`progressive`	How connector tools are exposed to agents. `progressive`: single `ConnectorMetaTool` with `discover`/`execute` subcommands (~30 tokens/connector). `classic`: one tool per action (legacy, ~250 tokens/action).
`DATABASE_TOOL_MODE`	No	`progressive`	How database connector tools are exposed to agents. `progressive`: single `DatabaseMetaTool` with `list_tables`/`discover`/`query` subcommands. `legacy`: one tool per action per database connector (3 tools each).
`MCP_TOOL_MODE`	No	`progressive`	How MCP server tools are exposed to agents. `progressive`: single `MCPServerMetaTool` with `discover`/`call` subcommands. `legacy`: one tool per MCP server action (original individual tools).

Platform

Variable	Required	Default	Description
`DATABASE_URL`	No	`sqlite+aiosqlite:///./data/fim_one.db`	Database connection string. SQLite (zero-config): `sqlite+aiosqlite:///./data/fim_one.db`. PostgreSQL (production): `postgresql+asyncpg://user:pass@localhost:5432/fim_one`. Docker Compose auto-sets PostgreSQL.
`JWT_SECRET_KEY`	No	`CHANGE_ME`	Secret key for JWT token signing. Placeholder value `CHANGE_ME` (or any legacy default) triggers auto-generation of a secure 256-bit random key on first start, which is written back to `.env`. Set explicitly in production to keep tokens valid across restarts and replicas.
`FIM_BCRYPT_COST`	No	`12`	bcrypt work factor for password hashing, clamped to 4-31. Default 12 costs roughly 200ms per hash on modern CPUs; lower it on weak hardware, raise it for security-hardened deployments.
`CORS_ORIGINS`	No	—	Comma-separated list of extra allowed CORS origins beyond the default localhost entries. Required when the frontend runs on a non-localhost domain (e.g. `https://app.example.com`).
`UPLOADS_DIR`	No	`./uploads`	Directory for uploaded files
`EXPORT_FONT_DIR`	No	(auto-detected)	Directory holding `NotoSansSC-Regular.ttf` / `NotoSansSC-Bold.ttf` for PDF export. Fetch with `python scripts/fetch_export_fonts.py`; Docker images already bundle it. Without an embeddable TrueType CJK font, PDF export falls back to a non-embedded CID font with degraded spacing and no bold.
`MAX_UPLOAD_SIZE_MB`	No	`50`	Max file upload size in megabytes (backend enforcement)
`NEXT_PUBLIC_MAX_UPLOAD_SIZE_MB`	No	`50`	Max file upload size shown in frontend UI. Build-time variable — must match `MAX_UPLOAD_SIZE_MB`.
`MCP_SERVERS`	No	—	JSON array of MCP server configs (requires `uv sync --extra mcp`)
`ALLOW_STDIO_MCP`	No	`false`	Allow stdio MCP servers. Set `true` only for trusted local deployments
`ALLOWED_STDIO_COMMANDS`	No	`npx,uvx,node,python,python3,deno,bun`	Comma-separated list of allowed base commands for stdio MCP servers. Only effective when `ALLOW_STDIO_MCP=true`
`LOG_LEVEL`	No	`INFO`	Logging level: `DEBUG` / `INFO` / `WARNING` / `ERROR` / `CRITICAL`
`REDIS_URL`	No	—	Redis connection URL for cross-worker interrupt relay. Required when `WORKERS>1` — without it, mid-stream interrupt/inject requests may hit a different worker and silently fail. Auto-configured by Docker Compose.
`WORKERS`	No	`1`	Uvicorn worker processes. `1` is safe and needs no external services. For production multi-worker, use PostgreSQL (SQLite is single-writer). SQLite works for local dev under light load. Auth, OAuth, and file operations are fully multi-worker safe (JWT-based). Docker Compose auto-configures both PostgreSQL and Redis.

Multi-worker checklist (WORKERS>1):

Stop (abort streaming) — always works, no extra config needed (signal travels on the same TCP connection).
Inject (mid-stream follow-up) — requires REDIS_URL. Without Redis, the inject request may land on a different worker that has no knowledge of the running execution, causing it to silently fail.
Production: use PostgreSQL (DATABASE_URL). SQLite’s single-writer lock can cause contention under concurrent writes.
Local dev: SQLite + multi-worker is fine for light usage; just add REDIS_URL if you use the inject feature.

Workflow Run Retention

Background cleanup task that automatically purges old workflow runs. Per-workflow overrides (configured in the workflow settings UI) take priority over these global defaults.

Variable	Required	Default	Description
`WORKFLOW_RUN_MAX_AGE_DAYS`	No	`30`	Delete workflow runs older than this many days
`WORKFLOW_RUN_MAX_PER_WORKFLOW`	No	`100`	Keep at most this many runs per workflow (oldest deleted first)
`WORKFLOW_RUN_CLEANUP_INTERVAL_HOURS`	No	`24`	How often the background cleanup task runs, in hours

Channel Confirmation Request Expiry

Background sweeper that marks stale pending approval requests (produced by channel hooks like FeishuGateHook or the Approval Playground) as expired. Ensures a click days later on a forgotten card doesn’t flip agent state that has already been torn down.

Variable	Required	Default	Description
`CHANNEL_CONFIRMATION_TTL_MINUTES`	No	`1440`	Pending confirmations older than this are auto-expired (default: 24 hours)
`CHANNEL_CONFIRMATION_SWEEP_INTERVAL_SECONDS`	No	`600`	How often the expiry sweeper runs (default: every 10 minutes)

OAuth (Optional)

When both CLIENT_ID and CLIENT_SECRET are set for a provider, the login page automatically shows the corresponding OAuth button.

Variable	Required	Default	Description
`GITHUB_CLIENT_ID`	No	—	GitHub OAuth App client ID. Create at github.com/settings/developers → OAuth Apps
`GITHUB_CLIENT_SECRET`	No	—	GitHub OAuth App client secret
`GOOGLE_CLIENT_ID`	No	—	Google OAuth client ID. Create at console.cloud.google.com/apis/credentials
`GOOGLE_CLIENT_SECRET`	No	—	Google OAuth client secret
`DISCORD_CLIENT_ID`	No	—	Discord OAuth2 client ID. Create at discord.com/developers
`DISCORD_CLIENT_SECRET`	No	—	Discord OAuth2 client secret
`FEISHU_APP_ID`	No	—	Feishu (Lark) App ID. Create at open.feishu.cn. Requires `contact:user.email:readonly` permission
`FEISHU_APP_SECRET`	No	—	Feishu (Lark) App Secret
`FRONTEND_URL`	Prod	`http://localhost:3000`	Where the browser lands after OAuth completes. Must be set in production (e.g. `https://yourdomain.com`)
`API_BASE_URL`	Prod	`http://localhost:8000`	Externally reachable backend URL, used to build OAuth callback URLs. Must be set in production
`NEXT_PUBLIC_API_URL`	Prod	(auto-detected as `<hostname>:8000`)	Browser-side API base URL for OAuth redirects. This is a frontend build-time variable — set it in `frontend/.env.local` for local dev, or pass it as a Docker build arg for custom production deployments. Auto-detection works for standard reverse-proxy setups (port 80/443).

Prod = optional locally (defaults work), but required for any internet-facing deployment.

OAuth Callback URLs to register with each provider

The backend constructs callback URLs as: {API_BASE_URL}/api/auth/oauth/{provider}/callback

Provider	Callback URL to register
GitHub	`https://yourdomain.com/api/auth/oauth/github/callback`
Google	`https://yourdomain.com/api/auth/oauth/google/callback`
Discord	`https://yourdomain.com/api/auth/oauth/discord/callback`

Cloudflare Tunnel (Optional)

Route all traffic through Cloudflare’s network instead of exposing ports directly. Eliminates the need for Nginx, SSL certificates, and open firewall rules. See the Production Deployment section for setup instructions.

Mainland China users: Cloudflare Free/Pro/Business plans have no PoPs in mainland China. Traffic is routed to overseas edges, causing frequent 502 errors. Do not use this if your primary users are in mainland China unless you have Cloudflare Enterprise with China Network.

Variable	Required	Default	Description
`CLOUDFLARE_TUNNEL_TOKEN`	Yes (if using Tunnel)	—	Token from Cloudflare Zero Trust → Networks → Tunnels → your tunnel → Configure. Starts with `eyJ...`. Required by the `cloudflared` sidecar in `docker-compose.tunnel.yml`.

Analytics (Optional)

All analytics providers are optional. Set any combination — all active providers load simultaneously. Leave all blank to disable analytics entirely (recommended for local dev).

Variable	Required	Default	Description
`NEXT_PUBLIC_GA_MEASUREMENT_ID`	No	—	Google Analytics 4 measurement ID (e.g. `G-XXXXXXXXXX`). Get yours at analytics.google.com
`NEXT_PUBLIC_UMAMI_SCRIPT_URL`	No	—	Umami analytics script URL (e.g. `https://your-umami.com/script.js`). Self-hosted, privacy-friendly alternative — umami.is
`NEXT_PUBLIC_UMAMI_WEBSITE_ID`	No	—	Umami website ID. Required when `NEXT_PUBLIC_UMAMI_SCRIPT_URL` is set
`NEXT_PUBLIC_PLAUSIBLE_DOMAIN`	No	—	Plausible analytics domain (e.g. `yourdomain.com`). Lightweight, privacy-friendly — plausible.io
`NEXT_PUBLIC_PLAUSIBLE_SCRIPT_URL`	No	`https://plausible.io/js/script.js`	Custom Plausible script URL for self-hosted instances

All NEXT_PUBLIC_* analytics variables are build-time — changes require a frontend rebuild to take effect.

Stripe Billing (Optional)

Stripe powers Pro subscriptions. Leave all three variables blank to disable billing — the rest of FIM One works unchanged. Both STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET must be set together; partial config raises an error at first use.

Variable	Required	Default	Description
`STRIPE_SECRET_KEY`	No	—	Stripe API secret key. Must start with `sk_test_` / `sk_live_` (full access) or `rk_test_` / `rk_live_` (restricted key). Get yours from the Stripe Dashboard → Developers → API keys. Never commit a `sk_live_*` key to source.
`STRIPE_WEBHOOK_SECRET`	No	—	Stripe webhook signing secret (`whsec_*`). Created when you register the webhook endpoint in Stripe Dashboard → Developers → Webhooks → Add endpoint. Required to verify inbound webhook payloads.
`STRIPE_BILLING_RETURN_URL`	No	`http://localhost:3000/settings?tab=billing`	URL Stripe redirects users to after Checkout / Customer Portal sessions. Set this to your production billing settings page (e.g. `https://your-domain.com/settings?tab=billing`).

​Configuration Levels

​Frontend (Local Dev Only)

​LLM (Required)

​MarkItDown OCR Resolution

​Extended Thinking (Reasoning)

​Supported providers

​Important caveats

​Temperature constraints with reasoning

​How LLM_REASONING_BUDGET_TOKENS works

​Agent Execution

​ReAct Agent

​DAG Planner

​Domain Classification

​Context Guard

​Content Guardrails

​Agent Workspace

​System

​Web Tools (Optional)

​RAG & Knowledge Base (Recommended)

​Embedding

​Retrieval

​Reranker

​Vector Store

​Code Execution

​Tool Artifacts

​Document Processing (Optional)

​Image Generation (Optional)

​Email (SMTP) (Recommended)

​Connectors

​Platform

​Workflow Run Retention

​Channel Confirmation Request Expiry

​OAuth (Optional)

​OAuth Callback URLs to register with each provider

​Cloudflare Tunnel (Optional)

​Analytics (Optional)

​Stripe Billing (Optional)

Configuration Levels

Frontend (Local Dev Only)

LLM (Required)

MarkItDown OCR Resolution

Extended Thinking (Reasoning)

Supported providers

Important caveats

Temperature constraints with reasoning

How `LLM_REASONING_BUDGET_TOKENS` works

Agent Execution

ReAct Agent

DAG Planner

Domain Classification

Context Guard

Content Guardrails

Agent Workspace

System

Web Tools (Optional)

RAG & Knowledge Base (Recommended)

Embedding

Retrieval

Reranker

Vector Store

Code Execution

Tool Artifacts

Document Processing (Optional)

Image Generation (Optional)

Email (SMTP) (Recommended)

Connectors

Platform

Workflow Run Retention

Channel Confirmation Request Expiry

OAuth (Optional)

OAuth Callback URLs to register with each provider

Cloudflare Tunnel (Optional)

Analytics (Optional)

Stripe Billing (Optional)