Skip to content

Configuration Reference

Set server environment variables in your deployment configuration and restart Numi after changing them. Defaults below come from src/numi_chat/core/config.py, except for the separately listed process and Compose settings. They describe application defaults, not the values on a particular instance. Docker can override paths and network bindings.

Use the admin Models page for the live model catalog and background-model choices. Use Settings for account instructions and memory. Provider credentials and server limits remain environment configuration.

The API keys card on the admin page can replace a provider key without a restart: PARALLEL_API_KEY, OCTEN_API_KEY, EXA_API_KEY, KEENABLE_API_KEY, YOU_API_KEY, DEEPSEEK_API_KEY, OPENROUTER_API_KEY, CROWBOT_API_KEY, Z_AI_API_KEY, OPENAI_API_KEY, RESPONSES_API_KEY, ANTHROPIC_API_KEY, ANTHROPIC_COMPAT_API_KEY, INCEPTION_API_KEY and MISTRAL_API_KEY. An override applies to the next request and survives restarts. It is stored in the database encrypted with a key derived from AUTH_SECRET_KEY; the page only shows the last four characters. Use config removes the override and returns to the environment value. If AUTH_SECRET_KEY changes, stored overrides can no longer be decrypted and the environment values apply until you save them again.

Settings you can change while Numi runs

The admin pages list the settings below under Behavior (Memory, Conversations, Deep research) and in the Tool suggestions card on Automation. A change applies at once and survives restarts; the environment value is the starting point and stays untouched. Reset returns a setting to its environment value. Every other variable in this reference still needs a restart.

Admin page Variables
Memory MEMORY_ENABLED, MEMORY_AGGREGATION_ENABLED, MEMORY_EXCLUDE_SENSITIVE, MEMORY_EXTRACTION_COOLDOWN_MINUTES, MEMORY_EMBEDDINGS_ENABLED, MEMORY_EMBEDDING_MODEL, MEMORY_USER_PROFILE_TOKEN_BUDGET, MEMORY_MAINTENANCE_ENABLED, MEMORY_UPKEEP_MODEL, MEMORY_SLOW_TTL_DAYS, MEMORY_SEASONAL_TTL_DAYS
Conversations AGENT_MAX_TURN_SECONDS, AGENT_MAX_ITERATIONS, AGENT_MAX_TOOL_CALLS, COMPACT_ENABLED, COMPACT_KEEP_RECENT, COMPACT_BUFFER_TOKENS
Deep research DEEP_RESEARCH_ENABLED, DEEP_RESEARCH_MAX_CONCURRENT_AGENTS, DEEP_RESEARCH_MAX_AGENTS_PER_TURN, DEEP_RESEARCH_CACHE_WARMING
Automation, Tool suggestions DECISIONS_TOOL_GROUP_THRESHOLD, DECISIONS_TOOL_GATE_TIMEOUT_SECONDS

Values are checked against the same limits as the environment variables. Turn limits apply from the next message; a turn already running keeps the limits it started with.

Where to find a setting

Configure Settings
Models and provider connections Providers, catalog path, background models
Storage and access Database, authentication, CORS
Tools and files Tools, image generation, uploads, Deno
Conversation context Prompt limits, compaction, memory
Resource use Agent limits, WebSocket limits, rate limits
Deployment details Server process, instance metadata, logging, configuration precedence

For setup instructions, start with Configure providers or Run with Docker.

Database Settings

DB_URL

  • Type: String
  • Default: sqlite:///chats.db
  • Required: No
  • Description: Database connection URL. The Docker deployment sets sqlite:////app/state/chats.db for persistent storage.

NUMI_CHAT_MODEL_CONFIG_PATH

  • Type: Path
  • Default: state/models.json (/app/state/models.json in Docker)
  • Required: No
  • Description: Optional complete private model catalog. If absent, Numi uses the packaged models.default.json. This file contains no credentials.

AI Provider Settings

OPENROUTER_* Settings (OpenRouter Provider)

OpenRouter provider settings are managed by the OpenRouterSettings class.

OPENROUTER_API_KEY

  • Type: String
  • Default: "" (empty)
  • Required: When using OpenRouter models or image generation
  • Description: OpenRouter API key for authentication

OPENROUTER_BASE_URL

  • Type: String
  • Default: https://openrouter.ai/api/v1
  • Required: No
  • Description: OpenRouter API base URL

OPENROUTER_SITE_URL

  • Type: String
  • Default: https://github.com/EvickaStudio/numi-chat
  • Required: No
  • Description: App URL sent as OpenRouter HTTP-Referer attribution header

OPENROUTER_APP_NAME

  • Type: String
  • Default: Numi Chat
  • Required: No
  • Description: App title sent as OpenRouter X-OpenRouter-Title attribution header

CROWBOT_* Settings (Crowbot Provider)

Crowbot provider settings are managed by the CrowbotSettings class.

CROWBOT_API_KEY

  • Type: String
  • Default: "" (empty)
  • Required: Yes (for Crowbot provider)
  • Description: Crowbot 16-digit account number used as the Bearer token; internal spaces are stripped automatically

CROWBOT_BASE_URL

  • Type: String
  • Default: https://api.crowbot.sh/v1
  • Required: No
  • Description: Crowbot OpenAI-compatible API base URL

Z_AI_* Settings (Z.AI Provider)

AI provider settings are managed by the AISettings class.

Z_AI_API_KEY

  • Type: String
  • Default: "" (empty)
  • Required: Yes (for Z.AI provider)
  • Description: Z.AI API key for authentication

Z_AI_BASE_URL

  • Type: String
  • Default: https://api.z.ai/api/coding/paas/v4
  • Required: No
  • Description: Z.AI API base URL

Z_AI_MODEL

  • Type: String
  • Default: glm-5.3
  • Required: No
  • Description: Legacy setting still accepted by the settings class. The current agent selects models from the catalog and does not read this value; set the default model on the admin Models page.

Z_AI_TEMPERATURE

  • Type: Float
  • Default: 0.7
  • Required: No
  • Description: Sampling temperature used by the agent across providers that accept explicit sampling. Omitted for direct OpenAI models and local model IDs beginning with gpt-5.

Z_AI_TOP_P

  • Type: Float
  • Default: 1.0
  • Required: No
  • Description: Top-p sampling used alongside Z_AI_TEMPERATURE, with the same provider/model exclusions.

OPENAI_* Settings (OpenAI Provider)

OpenAI provider settings are managed by the OpenAISettings class.

OPENAI_API_KEY

  • Type: String
  • Default: "" (empty)
  • Required: Yes (for OpenAI provider)
  • Description: OpenAI API key for authentication

OPENAI_BASE_URL

  • Type: String
  • Default: https://api.openai.com/v1
  • Required: No
  • Description: OpenAI API base URL

OPENAI_PROMPT_CACHE_RETENTION

  • Type: String
  • Default: in_memory
  • Required: No
  • Values: off, in_memory, 24h
  • Description: Retention requested for OpenAI prompt caching

RESPONSES_* Settings (OpenAI Responses-Compatible Provider)

Use these for a generic endpoint that implements the OpenAI Responses API. Catalog entries use provider="responses" and wire_api="openai_responses".

RESPONSES_API_KEY / RESPONSES_BASE_URL

  • Type: String
  • Default: empty
  • Required: Yes for this provider
  • Description: Credentials and base URL for the compatible endpoint

RESPONSES_PROMPT_CACHE_RETENTION

  • Type: String
  • Default: in_memory
  • Values: off, in_memory, 24h
  • Description: Retention requested for compatible prompt caching

ANTHROPIC_* Settings (Anthropic Provider)

ANTHROPIC_API_KEY / ANTHROPIC_BASE_URL

  • Type: String
  • Defaults: "" / https://api.anthropic.com
  • Required: API key required for this provider
  • Description: Credentials and base URL for Anthropic Messages API models

ANTHROPIC_CACHE_TTL / ANTHROPIC_MAX_OUTPUT_TOKENS / ANTHROPIC_TOOL_SCHEMA

  • Defaults: 5m, 128000, auto
  • Values: cache TTL is off, 5m, or 1h; tool schema is auto, anthropic, or openai
  • Description: Configure prompt cache duration, output cap, and tool-schema dialect. max_output_tokens is not a context-window setting. With caching on, chat requests mark the system prompt and the newest message, so each request reads the whole earlier conversation from cache. One-off background requests such as titles and memory are not cached. With DEEP_RESEARCH_CACHE_WARMING=true, 5m caches are kept alive while the deep research lead waits for sub-agents.

ANTHROPIC_VERSION / ANTHROPIC_TIMEOUT

  • Defaults: 2023-06-01, 120.0
  • Description: Anthropic API version header and fallback request timeout in seconds. Normal chat requests instead use AGENT_MODEL_TIMEOUT_SECONDS, bounded by the remaining turn deadline.

ANTHROPIC_COMPAT_* Settings (Anthropic Messages-Compatible Provider)

Use these for a compatible /v1/messages endpoint. The same value constraints as ANTHROPIC_* apply, but the compatible base URL must be configured.

Variable Default Meaning
ANTHROPIC_COMPAT_API_KEY "" API key for this endpoint
ANTHROPIC_COMPAT_BASE_URL "" Base URL for the compatible endpoint
ANTHROPIC_COMPAT_VERSION 2023-06-01 API version header
ANTHROPIC_COMPAT_CACHE_TTL 5m Requested prompt cache duration
ANTHROPIC_COMPAT_MAX_OUTPUT_TOKENS 128000 Output token cap
ANTHROPIC_COMPAT_TOOL_SCHEMA auto Tool-schema dialect
ANTHROPIC_COMPAT_TIMEOUT 120.0 Fallback request timeout; normal chat requests use the agent deadline as above

INCEPTION_* Settings (Inception Provider)

Inception provider settings are managed by the InceptionSettings class.

INCEPTION_API_KEY

  • Type: String
  • Default: "" (empty)
  • Required: Yes (for Inception provider)
  • Description: Inception API key for authentication

INCEPTION_BASE_URL

  • Type: String
  • Default: https://api.inceptionlabs.ai/v1
  • Required: No
  • Description: Inception API base URL

MISTRAL_* Settings (Mistral Provider)

Mistral provider settings are managed by the MistralSettings class.

MISTRAL_API_KEY

  • Type: String
  • Default: "" (empty)
  • Required: Yes (for Mistral provider)
  • Description: Mistral AI API key for authentication

MISTRAL_BASE_URL

  • Type: String
  • Default: https://api.mistral.ai/v1
  • Required: No
  • Description: Mistral API base URL

LOCAL_AI_* Settings (Local AI Provider)

Local AI provider settings are managed by the LocalSettings class.

LOCAL_AI_BASE_URL

  • Type: String
  • Default: http://localhost:8080/v1
  • Required: No
  • Description: Base URL for OpenAI-compatible local server

LOCAL_AI_API_KEY

  • Type: String
  • Default: sk-no-key-required
  • Required: No
  • Description: API key for local server authentication

Web search and fetch providers

web_search and fetch_web_page use the same provider set but have separate orders. Search providers are tried in WEB_SEARCH_PROVIDERS order; fetch providers are tried in WEB_FETCH_PROVIDERS order, which defaults to the search order when unset. Providers without a key are skipped. When a provider fails (invalid key, no credits, rate limit, network error) or finds nothing, the next one answers. For fetch_web_page, only the URLs a provider could not read are retried on the next provider. Options a provider does not support are ignored for that provider: objective steers Parallel and Exa highlights, Exa search uses dynamic highlights that share one budget across all results instead of max_characters per result, freshness="live" is not available for Exa lite, Octen or You.com search, Octen's freshest page cache is 5 minutes, and You.com page highlights are the start of the page because its Contents API has no focus query. Keenable has no objective and no live switch for search (freshness="live" applies to its page fetches), caps excerpts at 10,000 characters per result, sends a single include_domains entry as its site filter and several as site: query operators, and leaves out its own answer cards because their links expire after one day. With start_published_date, Keenable drops pages that have no known publish date. For focused page highlights it asks Keenable to quote the passages that match the focus query, and uses the start of the page when there is none. It fetches each URL with its own request. DeepSeek folds include_domains and start_published_date into site: and after: query operators, has no live-cache switch, and has no focus query for Fetch. Its query is limited to 128 characters including those operators, so long search terms are shortened to make room for them. When the filters would leave fewer than 32 characters for the search terms (many include_domains), DeepSeek steps aside and the next provider answers with the filters applied; filters are never silently dropped. DeepSeek returns at most 50 results per query and fetches each URL with its own request.

Numi Search (numi-search, experimental) is a meta provider for search only. Instead of asking one provider, it sends every search to several search providers at the same time. A small OpenRouter chat model or decision model then reads the objective, the queries, today's date and the start of every excerpt, and picks the best results across all queries, best first. When several providers return the same page (www, http and trailing-slash variants of a URL count as the same page), the copy with the most excerpt text is kept. The ranking returns up to the requested number of results. An LLM can leave out weak, off-topic or repeated pages, so fewer can come back. It is off by default: enable it in the admin Web search providers card or put it first in WEB_SEARCH_PROVIDERS. It needs OPENROUTER_API_KEY and at least one search provider with a key.

Decision ranking assesses one question per candidate page. Drex Max Finance groups up to 64 assessments into one request. Its OpenRouter endpoint rejects larger groups with a validation error specifying 64. Ordinary Drex Max retains 16 because its hosted OpenRouter endpoint rejects larger groups. These hosted limits differ from the 512 documented for Nace's direct API. Other decision models receive all candidate questions together unless a specific count limit is known. There is no universal 16-question cap. Model and provider context and request-size limits still apply.

Pools larger than the selected model's group size use several requests in parallel, even for one web_search tool call. Every request includes the full candidate context; only the questions are split. Each request is billed separately, so several entries for the ranking model in OpenRouter's activity log can belong to the same search. Changing the grouping can also change model scores; benchmark results from another group size are not a quality guarantee.

Which providers it asks is set in the admin Numi Search providers card, independently of the search order. The default is Parallel, Keenable and Exa when all three have a key; in a comparison of nine combinations on 25 searches this set gave the best results, better than all five providers together at about 60% of the cost. Parallel with Keenable alone was nearly as good at a sixth of the cost. A provider of the three without a key is left out; only when none of them has a key, the default is every provider of WEB_SEARCH_PROVIDERS that has one. Every search is billed by each of those providers plus the ranking requests. It waits for the slowest provider and then for the ranking. A provider that fails is skipped and shows its error in the admin card. When the ranking fails, Numi Search counts as failed and the search is answered with the results of its first provider that found something, without asking it again. When none of its providers finds anything, the search ends empty. Only when all of them fail does the search order continue with the next provider. The ranking request sends the objective, the queries and the titles, URLs and excerpt starts of all results to the configured OpenRouter model.

A decision model rates every result on a four-level scale instead of writing a list, with one question per result and the request grouping described above. Numi Search keeps the best-rated results up to the requested number; ties go to the page more providers found. When some of these requests fail, the rated results still count; when none of them returns a rating, the ranking fails.

The admin page has separate Web search providers, Page fetch providers and Numi Search providers cards. Each overrides its own order, disables providers, tests each provider with one small request of that kind, and shows its last success or error since the server started. Use config removes that card's override: search returns to WEB_SEARCH_PROVIDERS, fetch to WEB_FETCH_PROVIDERS or, when that is unset, to following the search order again. While fetch follows search, its card says so, and changing the order there saves a separate fetch order. In the Numi Search card, Use config returns to its default set. Keys can be replaced in the API keys card.

WEB_SEARCH_PROVIDERS

  • Type: Comma-separated list of keenable, keenable:realtime, exa, exa:lite, octen, parallel, you, deepseek, numi-search
  • Default: keenable,exa,octen,parallel,you,deepseek
  • Required: No
  • Description: Search provider priority order. Unknown names are ignored; omitted providers are disabled. The default follows the Artificial Analysis Search Index (November 2026). keenable runs Keenable pro search, its deepest retrieval and best ranking; keenable:realtime runs the realtime mode, built for the fastest response and one index point lower. Both use the same KEENABLE_API_KEY and cost the same. exa runs Exa auto search; exa:lite runs Exa lite, which costs about 40% less per search, scores almost as well, and serves only Exa's index, so freshness="live" does not apply to it. Both use the same EXA_API_KEY. To save cost, put exa:lite in place of exa, here or in the admin Web search providers card. numi-search asks several providers at once and ranks their results; list it first, followed by the providers that should answer when it fails, for example numi-search,parallel,keenable,exa.

NUMI_SEARCH_RANK_MODEL

  • Type: String (OpenRouter chat model ID from the catalog, or OpenRouter decision model ID)
  • Default: deepseek/deepseek-v4.1-flash-1017
  • Required: No
  • Description: Model that picks and orders the merged results of numi-search, called through OpenRouter with OPENROUTER_API_KEY. A small, fast model is enough; a chat model answers with a short list of result numbers. The admin Models page can override it with any OpenRouter model from the catalog or any decision model OpenRouter lists, such as liquid/d1.1 (see Background Model Settings). Reasoning is switched off for a chat model's ranking request. A catalog model that always reasons gets its lowest reasoning effort instead, which makes every search slower and more expensive; the request allows up to 8,000 output tokens so such a model can still finish its answer. A model ID that is not in the catalog counts as a decision model and is sent to DECISIONS_URL (see Optional Tool Routing); DECISIONS_ENABLED does not switch this off. Unused while numi-search is disabled.

WEB_FETCH_PROVIDERS

  • Type: Comma-separated list of keenable, keenable:realtime, exa, exa:lite, octen, parallel, you, deepseek (exa and exa:lite fetch pages the same way, as do keenable and keenable:realtime). numi-search only searches; it is left out of the fetch order, also while that order follows the search order
  • Default: unset (an empty value counts as unset), which follows the effective search order (including an admin search override)
  • Required: No
  • Description: Page-fetch provider priority order. Unknown names are ignored; omitted providers are disabled. Set this when fetch quality or speed ranks providers differently from search, for example exa,parallel,octen,deepseek,you. While the fetch order is inherited, the admin fetch card displays the search order without a Use config button.

OCTEN_API_KEY

  • Type: String
  • Default: None
  • Required: No
  • Description: Octen API key for web search (highlights) and extract (get key at octen.ai).

PARALLEL_API_KEY

  • Type: String
  • Default: None
  • Required: No
  • Description: Parallel API key for web search (advanced mode) and extract (get key at platform.parallel.ai).

EXA_API_KEY

  • Type: String
  • Default: None
  • Required: No
  • Description: Exa API key for web search (auto) and contents (get key at exa.ai).

KEENABLE_API_KEY

  • Type: String
  • Default: None
  • Required: No
  • Description: Keenable API key for web search (pro or realtime) and page fetch (get key at app.keenable.ai). Every organization gets 100,000 free requests a month; after that, pay as you go costs $4 per 1,000 requests. When the allowance and purchased credits run out, Keenable answers with HTTP 402 and the next provider takes over.

YOU_API_KEY

  • Type: String
  • Default: None
  • Required: No
  • Description: You.com API key for web search (highlights) and contents (get key at you.com/platform). YDC_API_KEY, the name You.com's own docs use, is accepted too.

DEEPSEEK_API_KEY

  • Type: String
  • Default: None
  • Required: No
  • Description: DeepSeek API key for the Search and Fetch APIs (get key at platform.deepseek.com). Search returns ranked results with summaries; Fetch returns one page as Markdown. Both are billed at $0.75 per 1,000 successful requests. DeepSeek models routed through OpenRouter use OPENROUTER_API_KEY instead.

DIRECT_WEB_FETCH_ENABLED

  • Type: Boolean
  • Default: false
  • Required: No
  • Description: When enabled, fetch_web_page tries local SSRF-safe HTTP fetching and trafilatura extraction before falling back to the configured web fetch providers for ordinary web pages. Native PDF, arXiv, and YouTube handlers are unchanged.

Authentication Settings

AUTH_* Settings

Authentication settings are managed by the AuthSettings class.

AUTH_SECRET_KEY

  • Type: String
  • Default: Not set (required)
  • Required: Yes
  • Description: JWT secret key (minimum 32 characters)

AUTH_ALGORITHM

  • Type: String
  • Default: HS256
  • Required: No
  • Description: JWT algorithm to use

AUTH_ACCESS_TOKEN_EXPIRE_MINUTES

  • Type: Integer
  • Default: 30
  • Required: No
  • Description: Access token expiration time in minutes

AUTH_REFRESH_TOKEN_EXPIRE_DAYS

  • Type: Integer
  • Default: 7
  • Required: No
  • Description: Refresh token expiration time in days

AUTH_BCRYPT_ROUNDS

  • Type: Integer
  • Default: 13
  • Required: No
  • Description: Number of rounds for bcrypt password hashing

AUTH_PASSWORD_MIN_LENGTH

  • Type: Integer
  • Default: 12
  • Required: No
  • Description: Minimum password length requirement

AUTH_PASSWORD_REQUIRE_COMPLEXITY

  • Type: Boolean
  • Default: True
  • Required: No
  • Description: Whether to require complex passwords (uppercase, lowercase, numbers, symbols)

AUTH_MAX_FAILED_LOGIN_ATTEMPTS

  • Type: Integer
  • Default: 5
  • Required: No
  • Description: Number of failed account attempts before progressive login delays begin

AUTH_ACCOUNT_LOCKOUT_MINUTES

  • Type: Integer
  • Default: 15
  • Required: No
  • Description: Database-backed account-attempt tracking window in minutes

AUTH_IP_LOGIN_ATTEMPTS_PER_MINUTE

  • Type: Integer
  • Default: 20
  • Required: No
  • Description: Maximum login attempts per client IP and minute

AUTH_MAX_LOGIN_DELAY_SECONDS

  • Type: Integer
  • Default: 60
  • Required: No
  • Description: Maximum progressive account delay after repeated failures

AUTH_THROTTLE_RETENTION_HOURS

  • Type: Integer
  • Default: 24
  • Required: No
  • Description: Retention period for hashed account and IP throttle buckets

Tool Settings

TOOLS_* Settings

Tool settings are managed by the ToolSettings class.

TOOLS_ALLOWLIST

  • Type: String
  • Default: web_search,fetch_web_page,weather_fetch,code_interpreter,codemode,remember_fact,forget_fact,recall_memory,past_chats,view,create_file,generate_image,read_skill,numi_docs,grocery_search_stores,grocery_profile,grocery_get_offers,chefkoch_search,chefkoch_recipe,kleinanzeigen_search,kleinanzeigen_listing,academic_search,wiki_lookup,ebay_search,ebay_listing,mydealz_search,mydealz_deal
  • Required: No
  • Description: Comma-separated list of tools allowed at registry startup. An explicit value replaces the whole default list. Optional tool groups also need activation in each chat. request_tool_activation is registered separately unless denied; TOOLS_DENYLIST takes precedence.

TOOLS_DENYLIST

  • Type: String
  • Default: empty
  • Required: No
  • Description: Comma-separated list of tools denied even when allowlisted.

TOOLS_CODE_INTERPRETER_DEPS_ALLOWLIST

  • Type: String
  • Default: numpy,pandas,matplotlib,scipy,seaborn,sympy,scikit-learn,openpyxl,xlsxwriter,python-docx,python-pptx,reportlab,pypdf,pdfminer.six,mpmath,pint,statsmodels,networkx,tzdata,pillow
  • Required: No
  • Description: Comma-separated list of allowed dependencies for code interpreter. Explicit overrides replace the defaults; add the office packages and pillow to an existing override to enable them. Import names docx, pptx, pdfminer, sklearn and PIL map to packages python-docx, python-pptx, pdfminer.six, scikit-learn and pillow. Skills that list a package missing here are left out of the skill index; importing zoneinfo loads tzdata so IANA time zones work in Pyodide.

TOOLS_CODE_INTERPRETER_IMPORT_ALLOWLIST

  • Type: String
  • Default: math,statistics,random,itertools,functools,collections,datetime,re,json,typing,os,sys,pathlib,io,csv,textwrap,decimal,fractions,zoneinfo,heapq,bisect,operator,string,struct,hashlib,base64,copy,pprint,enum,dataclasses,abc,contextlib,warnings,html,xml,wave,zipfile,gzip,zlib,binascii,calendar,colorsys,difflib,uuid,time,unicodedata,array,numbers,codecs
  • Required: No
  • Description: Comma-separated list of allowed Python modules for code interpreter

TOOLS_CODE_INTERPRETER_IMPORT_DENYLIST

  • Type: String
  • Default: requests,httpx,urllib,urllib3,socket,ssl,ftplib,xmlrpc,pyodide,micropip,subprocess,shutil,signal,ctypes,multiprocessing,threading,webbrowser,smtplib,telnetlib
  • Required: No
  • Description: Comma-separated list of denied Python modules for code interpreter

TOOLS_CODE_INTERPRETER_TIMEOUT

  • Type: Integer
  • Default: 90
  • Required: No
  • Description: Code interpreter execution timeout in seconds

TOOLS_CODE_INTERPRETER_ALLOW_NETWORKING

  • Type: Boolean
  • Default: False
  • Required: No
  • Description: Allow outbound networking from sandboxed code

TOOLS_CODE_INTERPRETER_MAX_MEMORY_MB

  • Type: Integer (256 to 4096)
  • Default: 1024
  • Required: No
  • Description: Memory cap for one Pyodide sandbox run. Code that needs more gets a Python MemoryError. Without a cap Pyodide grows to 4 GB per run.

TOOLS_CODE_INTERPRETER_MAX_CONCURRENT

  • Type: Integer
  • Default: 2
  • Required: No
  • Description: How many Pyodide sandbox runs may execute at once. Further runs wait up to the execution timeout, then report the sandbox as busy. Worst-case sandbox memory is about MAX_MEMORY_MB times this value.

TOOLS_CODE_INTERPRETER_UNSANDBOXED

  • Type: Boolean
  • Default: False
  • Required: No
  • Description: Disable ALL sandboxing for code interpreter (WARNING: dangerous - allows full OS access)
  • Warning: Only enable on a personal instance with a model you fully trust

TOOLS_SCHEMA_MODE

  • Type: String
  • Default: compact
  • Required: No
  • Description: Schema mode for tool descriptions

TOOLS_SCHEMA_DESCRIPTION_MAX_LEN

  • Type: Integer
  • Default: 160
  • Required: No
  • Description: Maximum length for schema descriptions

TOOLS_SCHEMA_STRIP_PARAM_DESCRIPTIONS

  • Type: Boolean
  • Default: False
  • Required: No
  • Description: Whether to strip parameter descriptions from tool schemas

Optional Tool Routing (private beta)

The default router uses Jev through OpenRouter. Numi Route Alpha is an opt-in local CPU classifier with privately supplied weights. They are not public, bundled, or downloaded automatically. See Docker setup for the required files and mount layout.

Variable Default Meaning
DECISIONS_ENABLED true Enable tool-group decision calls and the local tool-group router; Numi Search ranking with a decision model ignores it.
DECISIONS_TOOL_GROUP_ROUTER jev Choose jev or the private-beta numi_route_alpha.
DECISIONS_URL https://openrouter.ai/api/alpha/decisions OpenRouter Decisions API endpoint used by the jev router and by Numi Search ranking with a decision model.
DECISIONS_MODEL ~typesafe/jev-latest Decision model requested for jev tool-group routing.
DECISIONS_TIMEOUT_SECONDS 6.0 HTTP timeout in seconds for remote decision requests (1.0 to 30.0).
DECISIONS_LOCAL_TOOL_GROUP_MODEL_PATH state/tool_group_router/numi_route_alpha Directory containing the private ONNX release and tokenizer; relative paths resolve from the app root.
DECISIONS_TOOL_GROUP_THRESHOLD 0.55 Probability threshold for Jev suggestions; the local model uses its release's calibrated thresholds.
DECISIONS_TOOL_GATE_TIMEOUT_SECONDS 10.0 Maximum wait for the user's activation-card answer.

The local router only suggests disabled candidate groups. Low confidence, truncation, missing files, or inference errors use Jev fallback when a usable OPENROUTER_API_KEY is configured. Without that fallback, no pre-turn suggestion is offered. The router never enables tools by itself.

Image Generation Settings

IMAGE_GEN_* Settings

These settings control generate_image, which requires OPENROUTER_API_KEY. The image-generation model is separate from the current chat model.

IMAGE_GEN_MODEL

  • Type: String
  • Default: openai/gpt-image-2.6-sunburst
  • Required: No
  • Description: OpenRouter model slug used for image generation. Must be available through OpenRouter's Images API (/api/v1/images).

IMAGE_GEN_ASPECT_RATIO

  • Type: String
  • Default: 1:1
  • Required: No
  • Description: Default aspect ratio when the agent does not pass one. Allowed: 1:1, 2:3, 3:2, 3:4, 4:3, 9:16, 16:9, 21:9.

IMAGE_GEN_QUALITY

  • Type: String
  • Default: high
  • Required: No
  • Description: Default render quality when the agent does not pass one. Allowed: low, medium, high, xhigh. Higher quality costs more per image.

IMAGE_GEN_MAX_PROMPT_CHARS

  • Type: Integer
  • Default: 4000
  • Required: No
  • Description: Upper bound on prompt length; longer prompts are truncated.

IMAGE_GEN_TIMEOUT_CONNECT

  • Type: Float
  • Default: 10.0
  • Required: No
  • Description: Connect timeout (seconds) for the OpenRouter request.

IMAGE_GEN_TIMEOUT_READ

  • Type: Float
  • Default: 240.0
  • Required: No
  • Description: Read timeout (seconds) for the OpenRouter request. Image generation calls can be slow; keep this generous.

Prompt Settings

PROMPT_* Settings

These limits bound the context sent to a model. Saved account instructions and memory are attached as user context; they do not modify a chat's stored system message. See Customize instructions.

PROMPT_MAX_HISTORY_MESSAGES

  • Type: Integer
  • Default: 1000
  • Description: Maximum recent messages loaded into active history, keeping complete turns. If the latest turn alone exceeds this budget, loading fails with an error asking for a new chat or a larger history budget.

PROMPT_MAX_HISTORY_CHARS

  • Type: Integer
  • Default: 400000
  • Description: Character budget for serialized recent message data loaded from the database, with the same complete-turn behavior and errors as PROMPT_MAX_HISTORY_MESSAGES.

PROMPT_MAX_PDF_CONTEXT_CHARS

  • Type: Integer
  • Default: 12000
  • Required: No
  • Description: Shared PDF context budget. Text is included in document/page order and clipped; this does not retrieve pages based on the question.

PROMPT_MAX_PREFERENCE_CHARS

  • Type: Integer
  • Default: 2500
  • Required: No
  • Description: Maximum saved instruction characters included in the dynamic user-context block

PROMPT_MAX_MEMORY_ITEMS

  • Type: Integer
  • Default: 20
  • Required: No
  • Description: Maximum recent explicit saved facts considered for user context. The adaptive profile has a separate token budget.

PROMPT_MAX_MEMORY_ITEM_CHARS

  • Type: Integer
  • Default: 220
  • Required: No
  • Description: Maximum characters per memory item

PROMPT_MAX_PRESET_CHARS

  • Type: Integer
  • Default: 2500
  • Required: No
  • Description: Legacy field accepted by configuration but not read by the current prompt builder. It does not impose a runtime limit.

PROMPT_MAX_USER_CONTEXT_CHARS

  • Type: Integer
  • Default: 8000
  • Required: No
  • Description: Legacy field accepted by configuration but not read by the current context builder. Its assembled block currently has a fixed 12,000-character cap in context_layers.py.

CORS Settings

CORS_* Settings

CORS settings are managed by the CORSSettings class.

CORS_ALLOW_ORIGINS

  • Type: String
  • Default: http://localhost:4567,http://127.0.0.1:4567,http://localhost:3000,http://localhost:5173
  • Required: No
  • Description: Comma-separated list of allowed HTTP and credentialed WebSocket browser origins
  • Note: WebSocket origins are matched exactly. * does not authorize credentialed WebSocket connections; configure production origins explicitly.

CORS_ALLOW_CREDENTIALS

  • Type: Boolean
  • Default: True
  • Required: No
  • Description: Whether to allow credentials (cookies, authorization headers)

CORS_ALLOW_METHODS

  • Type: List
  • Default: ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"]
  • Required: No
  • Description: HTTP methods allowed for CORS

CORS_ALLOW_HEADERS

  • Type: List
  • Default: ["Content-Type", "Authorization", "X-Requested-With", "X-Request-ID"]
  • Required: No
  • Description: Headers allowed in CORS requests

CORS_EXPOSE_HEADERS

  • Type: List
  • Default: ["X-Request-ID"]
  • Required: No
  • Description: Headers exposed to the browser

CORS_MAX_AGE

  • Type: Integer
  • Default: 600
  • Required: No
  • Description: How long preflight requests can be cached (in seconds)

Upload Settings

UPLOAD_* Settings

Upload settings are managed by the UploadSettings class.

UPLOAD_MAX_UPLOAD_BYTES

  • Type: Integer
  • Default: 26214400 (25 MiB)
  • Required: No
  • Description: Maximum file upload size in bytes

UPLOAD_MAX_AVATAR_BYTES

  • Type: Integer
  • Default: 2097152 (2 MiB)
  • Required: No
  • Description: Maximum avatar image size in bytes

UPLOAD_MAX_IMAGE_PIXELS

  • Type: Integer
  • Default: 16000000 (16 MP)
  • Required: No
  • Description: Maximum image pixel count for uploads

UPLOAD_MAX_REQUEST_IMAGE_BYTES

  • Type: Integer
  • Default: 33554432 (32 MiB)
  • Description: Shared image-byte budget when preparing a model request. Newer image attachments take precedence.

PDF extraction limits

These apply to uploaded PDFs and PDFs fetched through a tool. OCR shares the same time budget. See PDF processing for installation and troubleshooting.

Variable Default Purpose
UPLOAD_MAX_PDF_WORKERS 2 Concurrent extraction workers
UPLOAD_MAX_PDF_PAGES 500 Maximum pages per PDF
UPLOAD_MAX_PDF_TEXT_CHARS 2000000 Maximum extracted characters per PDF
UPLOAD_PDF_TIMEOUT_SECONDS 45 Total extraction and OCR time in seconds
UPLOAD_PDF_MEMORY_MEGABYTES 768 Memory limit per extraction worker

Agent Resource Limits

These AGENT_* settings bound each model/tool turn. Limits apply even when compaction is disabled.

When a quarter of the iterations or of the turn time is left, the model gets a hidden reminder with each request to wrap up and answer with what it has. The reminder is never stored or shown in the chat. Once every iteration is used, one more request asks for the final answer; tool calls in it do not run.

Variable Default Purpose
AGENT_MODEL_TIMEOUT_SECONDS 120 Maximum time for a model request, also bounded by the remaining turn deadline
AGENT_MAX_TURN_SECONDS 1200 Total turn deadline in seconds
AGENT_MAX_ITERATIONS 48 Maximum model iterations that may run tools in a turn
AGENT_MAX_TOOL_CALLS 16 Maximum tool calls returned in one model iteration
AGENT_MAX_TOOL_OUTPUT_CHARS 64000 Maximum tool output before returning a bounded preview
AGENT_MAX_OUTPUT_CHARS 400000 Combined streamed answer and reasoning character limit
AGENT_TOOL_WORKERS 16 Shared tool-execution worker pool size

Deep Research Settings

These DEEP_RESEARCH_* settings control deep research mode, which the user turns on per message with the telescope button in the composer. The chat model is asked to survey the topic with a quick web search, then plans the research and always starts at least one wave of sub-agents on the same model, each researching its own angle or part of the question in parallel. It collects their reports and writes the final report. A research turn uses these limits instead of AGENT_MAX_TURN_SECONDS and AGENT_MAX_ITERATIONS. Deep research needs web_search; the button stays hidden when it is unavailable or the user's access tier does not include it.

Variable Default Purpose
DEEP_RESEARCH_ENABLED true Turn deep research on or off for the whole server
DEEP_RESEARCH_MAX_TURN_SECONDS 2400 Total deadline of a research turn
DEEP_RESEARCH_MAX_ITERATIONS 160 Model iterations of the lead agent in a research turn
DEEP_RESEARCH_MAX_CONCURRENT_AGENTS 4 Sub-agents that run at the same time; the rest wait in a queue
DEEP_RESEARCH_MAX_AGENTS_PER_TURN 12 Sub-agents one turn may start across all waves
DEEP_RESEARCH_AGENT_MAX_STEPS 40 Model steps of one sub-agent before it must write its report
DEEP_RESEARCH_AGENT_MAX_SECONDS 900 Wall time of one sub-agent
DEEP_RESEARCH_AGENT_MAX_TOOL_CALLS_PER_STEP 6 Tool calls a sub-agent may run from one step
DEEP_RESEARCH_AGENT_TOOL_RESULT_CHARS 20000 Characters of one tool result a sub-agent reads
DEEP_RESEARCH_REPORT_MAX_CHARS 9000 Size cap of one sub-agent report
DEEP_RESEARCH_AGENT_TOOLS * Tools a sub-agent may call, comma-separated; * means every installed tool the user's tier allows
DEEP_RESEARCH_CACHE_WARMING false Keep the lead's 5-minute prompt cache alive while it waits for sub-agents; see Deep research

Sub-agents never see the chat, the user's memory, or the main system prompt: only their assignment and a short research brief. They use the chat's model and reasoning level. Tools that act on the chat itself (generate_image, create_file, view, grocery_profile, the memory tools, request_tool_activation, and the research tools) are never offered to a sub-agent, whatever this setting says. Optional tool groups such as Scientific Research are offered without being switched on in the chat.

Sub-agent usage counts toward the turn's cost. Each research_poll result carries the sub-agents' spend since the previous poll and stores it on its tool message; spend after the last poll is added to the final answer. As for the chat itself, only OpenRouter reports inference cost. Web search and fetch requests also contribute estimated provider charges, separately from inference tokens and model request counts.

Cancellation and failed requests retain known usage; requests without a final provider usage record make the total a lower bound. Unpolled usage is persisted when a turn exits, including failures. Worker deadlines include report writing; the lead reserves the final 150 seconds for synthesis. Already running tool functions cannot be forcibly killed in Python, but their queue is bounded and they cannot start another model request after cancellation.

Skills Settings

These SKILLS_* settings control skills: task instruction folders the model reads with read_skill. They load once at startup. Admins can also switch all skills, or single skills, on and off on the Models admin page without a restart.

Variable Default Purpose
SKILLS_ENABLED true false removes every skill and the read_skill tool
SKILLS_PRIVATE_DIR state/skills Folder for your own skills; a folder with a built-in's name replaces it
SKILLS_DENYLIST empty Comma-separated skill names to hide

read_skill must stay in TOOLS_ALLOWLIST when you set that list yourself.

ChatGPT Settings

These CHATGPT_* settings control how an admin connects their own ChatGPT subscription. The connection itself is made on the Admin page; see Use your ChatGPT subscription.

Variable Default Purpose
CHATGPT_ENABLED true false hides the feature and stops all subscription requests
CHATGPT_REDIRECT_PORT 4567 Port in the sign-in callback http://127.0.0.1:<port>/auth/callback; use the port your browser reaches Numi on
CHATGPT_APP_NAME Numi Chat Name ChatGPT shows when Numi registers on first sign-in
CHATGPT_SIGN_IN_TIMEOUT_MINUTES 10 How long a started sign-in stays valid (1–60)

Schedule Settings

These SCHEDULE_* settings control scheduled chats and their notifications.

Variable Default Purpose
SCHEDULE_ENABLED true Run due schedules; false stops all runs (runs missed by more than 12 hours are skipped when it is turned back on)
SCHEDULE_NOTIFY_IDLE_DAYS 5 Days without opening Numi after which Web Push notifications pause until the user turns them back on
SCHEDULE_PUSH_CONTACT mailto:admin@example.com VAPID contact sent to push services (mailto: or https:)

The Web Push signing key is generated on first use in state/push_vapid.pem.

Rate Limiting Settings

RATE_LIMIT_* Settings

Rate limiting settings control API request rates per IP address.

RATE_LIMIT_DEFAULT

  • Type: String
  • Default: "200/hour"
  • Required: No
  • Description: Default rate limit for all endpoints (format: "requests/period")

RATE_LIMIT_AUTH

  • Type: String
  • Default: "20/minute"
  • Required: No
  • Description: Rate limit for authentication endpoints

RATE_LIMIT_UPLOAD

  • Type: String
  • Default: "10/hour"
  • Required: No
  • Description: Rate limit for file upload endpoints

WebSocket Resource Limits

The WEBSOCKET_* defaults are active without additional deployment configuration. Connection counts, active turns, and queues are bounded per Numi process. These are not shared limits across several worker processes.

Setting Default Purpose
WEBSOCKET_MAX_MESSAGE_BYTES 262144 Maximum WebSocket JSON frame size
WEBSOCKET_MAX_MESSAGE_CHARS 65536 Maximum user-message length
WEBSOCKET_MAX_VISION_FILES 20 Maximum image references per turn
WEBSOCKET_MAX_ATTACHED_FILES 20 Maximum attachment references per turn
WEBSOCKET_SUBSCRIBER_QUEUE_SIZE 512 Maximum pending events per subscriber
WEBSOCKET_HISTORY_SIZE 256 Reconnect events retained during an active turn
WEBSOCKET_MAX_CONNECTIONS_PER_USER 8 Simultaneous connections per authenticated user
WEBSOCKET_MAX_CONNECTIONS_PER_IP 32 Simultaneous connections per client IP
WEBSOCKET_MAX_ACTIVE_TURNS_PER_USER 2 Simultaneous model/tool turns per user
WEBSOCKET_MAX_TURNS_PER_MINUTE 10 New turns allowed per user per minute
WEBSOCKET_BUFFER_BYTES 2097152 Byte budget for event buffers
WEBSOCKET_SNAPSHOT_BYTES 1048576 Byte limit for an active-turn reconnect snapshot
WEBSOCKET_SNAPSHOT_EVENTS 4096 Event limit for that snapshot
WEBSOCKET_MAX_CONNECTIONS 512 Simultaneous connections across the process
WEBSOCKET_MAX_ACTIVE_TURNS 32 Simultaneous turns across the process; a message beyond it waits up to 30 s for a free slot before it is rejected
WEBSOCKET_AUTH_CHECK_SECONDS 30 Interval between authentication rechecks
WEBSOCKET_SHUTDOWN_SECONDS 15 Grace period for stopping active producers

Environment Settings

ENVIRONMENT

  • Type: String
  • Default: development
  • Required: No
  • Description: Logging environment. This is the explicit alias for the logging settings environment field.
  • Values: "development" or "production"
  • Note: Set to "development" for enhanced log formatting and colored output

Server Process and Compose Settings

These variables are read directly from the process environment, outside the settings classes. For local runs, export them in the launching shell or prefix the command, for example NUMI_CHAT_HOST=0.0.0.0 uv run numi-chat-web. Putting them in .env alone does not export them to a local process. The supplied Compose file injects .env through env_file.

Variable Default Meaning
NUMI_CHAT_HOST 127.0.0.1 Server bind address; Compose sets 0.0.0.0 inside the container
FORWARDED_ALLOW_IPS 127.0.0.1 Uvicorn trusted proxy addresses; set it to your reverse proxy address when the proxy runs on another host
NUMI_CHAT_STATIC_DIR Package web/static directory Static asset directory
NUMI_CHAT_GENERATED_FILES_DIR generated_files Generated-file directory; Compose sets /app/state/generated_files
DISABLE_AUTO_COMPACT Unset Overrides compaction when 1, true, or yes
TOOLS_CHEFKOCH_ENABLED true Recipe tool availability switch
TOOLS_GEIZHALS_ENABLED true Geizhals tool availability switch
TOOLS_GEIZHALS_API_BASE_URL http://127.0.0.1:8000 Geizhals sidecar URL
SEMANTIC_SCHOLAR_API_KEY Unset Optional academic-search API key

The three tool availability switches accept false, 0, or no to disable the integration, case-insensitively. They do not bypass the allowlist or chat activation. See Tools for integration requirements.

The supplied Compose deployment also accepts these settings:

Variable Default Meaning
NUMI_CHAT_PORT 4567 Published host port; the application still listens on port 4567
HOST_UID 1000 User ID used by the container entrypoint for writable files
HOST_GID 1000 Group ID used by the container entrypoint for writable files
TZ UTC Container time zone

Logging Settings

LOG_* Settings

Logging settings are managed by the LoggingSettings class.

LOG_ENVIRONMENT

This variable is not read. Use ENVIRONMENT instead; the explicit alias overrides the LOG_ prefix for this field.

LOG_LEVEL

  • Type: String
  • Default: INFO
  • Required: No
  • Description: Logging level threshold

LOG_FILE_PATH

  • Type: String
  • Default: logs/app.log
  • Required: No
  • Description: Path to log file

LOG_ROTATION

  • Type: String
  • Default: 10 MB
  • Required: No
  • Description: Log rotation size threshold

LOG_RETENTION

  • Type: String
  • Default: 30 days
  • Required: No
  • Description: Log retention period

LOG_COMPRESSION

  • Type: String
  • Default: zip
  • Required: No
  • Description: Log compression format

LOG_SERIALIZE

  • Type: Boolean
  • Default: False
  • Required: No
  • Description: Whether to serialize logs to JSON

LOG_BACKTRACE

  • Type: Boolean
  • Default: True
  • Required: No
  • Description: Whether to include backtrace in logs

LOG_DIAGNOSE

  • Type: Boolean
  • Default: False
  • Required: No
  • Description: Whether to include diagnostic information in logs

LOG_ENQUEUE

  • Type: Boolean
  • Default: True
  • Required: No
  • Description: Whether to enqueue log messages

Compaction Settings

COMPACT_* Settings

Compaction summarizes older complete turns when enabled. The request budget is max(1, context_window - COMPACT_BUFFER_TOKENS), using the model catalog's context_window first and the provider fallback below otherwise.

Even with COMPACT_ENABLED=false, the request builder drops older complete turns to fit that budget. It fails if the latest turn and tool schemas cannot fit. See Configure compaction for examples.

COMPACT_ENABLED

  • Type: Boolean
  • Default: False
  • Required: No
  • Description: Enable automatic summarization. The legacy DISABLE_AUTO_COMPACT=1, true, or yes switch overrides it.

COMPACT_KEEP_RECENT

  • Type: Integer
  • Default: 12
  • Required: No
  • Description: Minimum number of recent non-system messages preserved. The split moves back to a user message to keep complete turns, so more messages can be retained.

COMPACT_BUFFER_TOKENS

  • Type: Integer
  • Default: 13000
  • Required: No
  • Description: Reserved tokens below the configured context window. Increasing the buffer triggers compaction earlier and reduces the request budget.

COMPACT_MAX_FAILURES

  • Type: Integer
  • Default: 3
  • Required: No
  • Description: Consecutive failures before compaction stops for the current run. Failure counts and a five-minute retry cooldown are saved with the chat; a later turn can retry after that cooldown expires.

COMPACT_CONTEXT_WINDOW_ZAI

  • Type: Integer
  • Default: 128000
  • Required: No
  • Description: Z.AI provider fallback context window in tokens

COMPACT_CONTEXT_WINDOW_OPENROUTER

  • Type: Integer
  • Default: 256000
  • Required: No
  • Description: OpenRouter provider fallback context window in tokens

COMPACT_CONTEXT_WINDOW_CROWBOT

  • Type: Integer
  • Default: 1000000
  • Required: No
  • Description: Crowbot provider fallback context window in tokens

COMPACT_CONTEXT_WINDOW_OPENAI

  • Type: Integer
  • Default: 128000
  • Required: No
  • Description: OpenAI provider fallback context window in tokens

COMPACT_CONTEXT_WINDOW_RESPONSES

  • Type: Integer
  • Default: 128000
  • Required: No
  • Description: Responses-compatible provider fallback context window in tokens

COMPACT_CONTEXT_WINDOW_ANTHROPIC / COMPACT_CONTEXT_WINDOW_ANTHROPIC_COMPAT

  • Type: Integer
  • Default: 1000000
  • Required: No
  • Description: Direct and compatible Anthropic Messages provider fallback context window in tokens

COMPACT_CONTEXT_WINDOW_INCEPTION

  • Type: Integer
  • Default: 32000
  • Required: No
  • Description: Inception provider fallback context window in tokens

COMPACT_CONTEXT_WINDOW_MISTRAL

  • Type: Integer
  • Default: 128000
  • Required: No
  • Description: Mistral provider fallback context window in tokens

COMPACT_CONTEXT_WINDOW_LOCAL

  • Type: Integer
  • Default: 32000
  • Required: No
  • Description: Local provider fallback context window in tokens

Adaptive Memory Settings

MEMORY_* Settings

These settings control background extraction and the profile shared across a user's chats. They are separate from conversation compaction. See Review and configure memory for user controls.

MEMORY_ENABLED

  • Type: Boolean
  • Default: True
  • Required: No
  • Description: Enable background extraction and consolidation. Disabling this does not clear saved memory, prevent existing memory from entering prompts, or disable the explicit memory tools.

MEMORY_SUMMARY_MODEL

  • Type: String
  • Default: deepseek/deepseek-v4.1-flash-1017
  • Required: No
  • Description: Model for background memory jobs when no admin override is stored. See Background model settings.

MEMORY_EXTRACTION_COOLDOWN_MINUTES

  • Type: Integer
  • Default: 90
  • Required: No
  • Description: How long a chat must be idle before it is read for memory. Extraction runs once per finished conversation, not per turn. A chat that is resumed later is re-read in full and its previous pending observations are superseded.

MEMORY_EXTRACTION_CONSOLIDATION_THRESHOLD

  • Type: Integer
  • Default: 5
  • Required: No
  • Description: Pending observations needed to trigger consolidation. Aged smaller queues are also consolidated by the idle sweep.

MEMORY_EXTRACTION_IDLE_FLUSH_MINUTES

  • Type: Integer
  • Default: 90
  • Required: No
  • Description: Age at which a small pending observation queue becomes eligible for consolidation. The worker checks every five minutes and processes bounded batches.

MEMORY_EXTRACTION_IDLE_FLUSH_MAX_AGE_HOURS

  • Type: Integer
  • Default: 0
  • Required: No
  • Description: Age cutoff for idle chats. 0 means no maximum age; a positive value excludes chats whose last activity is older than that many hours.

MEMORY_EXTRACTION_IDLE_BATCH_SIZE

  • Type: Integer
  • Default: 4
  • Description: Maximum idle extraction attempts and maximum consolidation attempts per sweep, applied separately. Allowed range: 1–20.

MEMORY_EXTRACTION_MESSAGE_LIMIT

  • Type: Integer
  • Default: 1000
  • Description: Maximum message rows fetched when building a chat's Q/A pairs.

MEMORY_EXTRACTION_CONVERSATION_TOKEN_BUDGET

  • Type: Integer
  • Default: 24000
  • Description: Token budget for one conversation sent to the extraction model. User messages are kept whole for as long as possible; assistant text is shortened first, and only a very long chat is reduced to its opening and most recent turns.

MEMORY_EXTRACTION_ASSISTANT_CHAR_CAP

  • Type: Integer
  • Default: 1500
  • Description: Starting per-turn cap on assistant text. Assistant replies are reference context; only user messages can establish a fact.

MEMORY_DUPLICATE_SIMILARITY

  • Type: Float from 0 through 1
  • Default: 0.8
  • Required: No
  • Description: Word-overlap threshold above which a new observation is treated as restating an existing detail and confirmed in place, with no model call.

MEMORY_AGGREGATION_ENABLED

  • Type: Boolean
  • Default: True
  • Required: No
  • Description: Enable the cross-chat pass that rebuilds the Profile and Preferences entries from the corpus of per-chat summaries. This is the only layer that can see a pattern spanning many separate conversations.

MEMORY_AGGREGATION_INTERVAL_HOURS

  • Type: Integer
  • Default: 168
  • Required: No
  • Description: Minimum interval between cross-chat passes for one user.

MEMORY_AGGREGATION_CHAT_LIMIT / MEMORY_AGGREGATION_SUMMARY_CHAR_CAP

  • Type: Integer
  • Defaults: 200, 420
  • Required: No
  • Description: How many recent chat summaries the cross-chat pass reads, and how much of each. One pass is a single model call.

MEMORY_CONSOLIDATION_OBSERVATION_LIMIT

  • Type: Integer
  • Default: 100
  • Description: Maximum pending observations read for one consolidation. The implementation caps this at 100 even if configured higher.

MEMORY_CONSOLIDATION_RETRY_COOLDOWN_MINUTES

  • Type: Integer
  • Default: 60
  • Required: No
  • Description: Minimum delay before retrying failed automatic extraction or consolidation.

MEMORY_USER_PROFILE_TOKEN_BUDGET

  • Type: Integer
  • Default: 2500
  • Required: No
  • Description: Estimated token budget per stored context addition. Explicit facts also respect their individual PROMPT_MAX_MEMORY_* limits. Unchanged context is not appended again.

MEMORY_EMBEDDINGS_ENABLED / MEMORY_EMBEDDING_MODEL

  • Types: Boolean, string
  • Defaults: false, openai/text-embedding-3-large
  • Description: Optional multilingual search through the configured OpenRouter account. Indexes only active details and validates ownership, content hashes and model identity. Disabled, unavailable or incomplete search uses the existing word search. The existing background sweep updates 64 subjects per user per batch. See Memory for data handling, cache behavior and model choice.

MEMORY_MAINTENANCE_ENABLED

  • Type: Boolean
  • Default: false
  • Description: Enable one daily review per account by a tool-using agent on the configured memory model. It merges duplicates, retires one-off details, writes subject summaries and tidies the profile; it cannot add facts. Protects manual/imported data, preserves evidence dates and expiry, and records before/after snapshots when it changes something. It requires MEMORY_ENABLED=true; it is independent of semantic search.

MEMORY_UPKEEP_MODEL

  • Type: String
  • Default: deepseek/deepseek-v4.1-flash-1017
  • Required: No
  • Description: Model for the daily upkeep agent. inherit uses the memory model (MEMORY_SUMMARY_MODEL or its admin override). The admin Models page can override it as Daily memory upkeep.

MEMORY_ENTRY_INDEX_LIMIT / MEMORY_ENTRY_EXPAND_LIMIT

  • Type: Integer
  • Defaults: 60, 4
  • Required: No
  • Description: How many entries are listed by name in the subject list, and how many matching entries have their details expanded per turn. The agent can fetch other details with recall_memory.

MEMORY_SLOW_TTL_DAYS / MEMORY_SEASONAL_TTL_DAYS

  • Type: Integer
  • Defaults: 180, 21
  • Required: No
  • Description: Lifetime of a detail by its durability. permanent details never expire. An expired detail becomes stale and leaves automatic context and normal recall. Hand-written details never expire.

MEMORY_MEMORY_LANGUAGE

  • Type: String
  • Default: English
  • Required: No
  • Description: The single language all stored memory is written in, whatever language the chat itself uses. A mixed-language profile cannot be deduplicated: the same fact in two languages shares no words, so every similarity check in the pipeline treats it as two facts. Changing this later does not translate entries that already exist.

MEMORY_EXCLUDE_SENSITIVE

  • Type: Boolean
  • Default: True
  • Required: No
  • Description: Instruct the extraction and aggregation models never to record health, sexual orientation, gender identity, religion, ethnicity, political affiliation or precise financial figures.

MEMORY_IMPORT_BATCH_CHARS / MEMORY_IMPORT_MAX_BATCHES

  • Type: Integer
  • Defaults: 9000, 12
  • Required: No
  • Description: Maximum characters per batch (1000 to 24000) and maximum batches (1 to 40) when importing external memory notes through POST /api/v1/me/memory/import.

Background Model Settings

The admin Models page can store a live override for the chat-title, memory, daily memory upkeep and Numi Search ranking models. These overrides take precedence over the environment fallback and do not require a server restart. Use config removes an override. The ranking picker separates LLM and Decision. LLMs come from the OpenRouter entries in your chat-model catalog, with DeepSeek V4.1 Flash as the initial choice when switching to LLM. Decision models use a separate built-in shortlist, ordered from useful alternatives to the strongest relevance candidates; Drex Max Finance is preselected when switching to Decision. No chat-catalog entry is needed for these choices. The shortlist loads and saves without provider discovery.

Switching type only stages a choice. Save override applies it; Cancel restores the saved type and model. A saved model outside the shortlist remains visible. Additional decision IDs submitted through the API are checked against OpenRouter. Use config restores NUMI_SEARCH_RANK_MODEL, whose default remains DeepSeek. This setting does not change tool suggestions.

CHAT_TITLE_MODEL

  • Type: String
  • Default: deepseek/deepseek-v4.1-flash-1017
  • Description: Model for automatically naming chats when there is no admin override. MEMORY_SUMMARY_MODEL is the corresponding memory fallback.

Both settings accept a catalog model ID. An empty value or inherit resolves to the catalog default. Background jobs currently require a supported model using wire_api="openai_chat"; credentials come from that model's provider settings. See Manage models.

Grocery Provider Settings

LIDL_* Settings

Lidl Plus integration settings are managed by the LidlSettings class. No credentials are required.

LIDL_COUNTRY

  • Type: String
  • Default: DE
  • Required: No
  • Description: Country code for Lidl Plus store lookup

LIDL_LANGUAGE

  • Type: String
  • Default: None
  • Required: No
  • Description: Optional language code filter

LIDL_LATITUDE

  • Type: Float
  • Default: None
  • Required: No
  • Description: Optional latitude for default location

LIDL_LONGITUDE

  • Type: Float
  • Default: None
  • Required: No
  • Description: Optional longitude for default location

LIDL_TIMEOUT

  • Type: Float
  • Default: 20.0
  • Required: No
  • Description: HTTP request timeout in seconds

KAUFLAND_* Settings

Kaufland Plus integration settings are managed by the KauflandSettings class. Requires Basic auth credentials.

KAUFLAND_APP_BASIC_USER

  • Type: String
  • Default: ""
  • Required: Yes (to query Kaufland)
  • Description: Basic auth user for the Kaufland app API

KAUFLAND_APP_BASIC_PASSWORD

  • Type: String
  • Default: ""
  • Required: Yes (to query Kaufland)
  • Description: Basic auth password for the Kaufland app API

KAUFLAND_LANGUAGE

  • Type: String
  • Default: de
  • Required: No
  • Description: App language code

KAUFLAND_TIMEOUT

  • Type: Float
  • Default: 20.0
  • Required: No
  • Description: HTTP request timeout in seconds

EDEKA_* Settings

EDEKA needs application OAuth credentials for offers. Store lookup creates an anonymous application session automatically on first use; no personal EDEKA login or manually configured Valuephone hashes are needed.

Setting Default Purpose
EDEKA_CLIENT_ID Empty Application OAuth client ID; required
EDEKA_CLIENT_SECRET Empty Application OAuth client secret; required
EDEKA_TIMEOUT 25.0 HTTP request timeout in seconds; must be positive
EDEKA_SESSION_PATH state/edeka/session.json Private persistent anonymous session

Keep the client credentials in environment variables or .env, outside version control. Restart Numi after configuring them, then enable the Grocery tool group. EDEKA appears in store search once both OAuth values are configured.

The first store search registers a technical anonymous session with EDEKA's Valuephone service. The installation ID and issued credentials are saved atomically with file mode 0600. All server workers must share this path; initialization uses a Unix file lock. The default state/ directory is already persistent in Docker Compose and excluded from Git and Docker image builds. Offer requests do not need this session and never register one.

There is no guessed expiry or automatic re-registration after authentication errors. An ambiguous registration timeout leaves a pending marker and stops further setup attempts. An unexpected response is retained privately beside the session as session.response.xml; successful validation removes that raw file. Do not publish either file. Review pending state before retrying. Only after confirming that a session cannot be recovered or is invalid, stop all workers, move its JSON and any raw response aside privately, then restart to permit one replacement on the next store search. A generic 403 or SOAP fault does not by itself prove the session is invalid.

KLEINANZEIGEN_* Settings

German classifieds (Kleinanzeigen) integration settings are managed by the KleinanzeigenSettings class.

KLEINANZEIGEN_APP_BASIC

  • Type: String
  • Default: ""
  • Required: No
  • Description: Legitimate Basic auth credentials (user:password) for app API access

KLEINANZEIGEN_API_BASE

  • Type: String
  • Default: https://api.kleinanzeigen.de
  • Required: No
  • Description: Base URL of the API

KLEINANZEIGEN_ENABLED

  • Type: Boolean
  • Default: True
  • Required: No
  • Description: Enable or disable the Kleinanzeigen toolset

EBAY_* Settings

The official, read-only eBay Browse API integration is managed by EbaySettings. It is unavailable until both credentials are configured.

Connection setting Default Meaning
EBAY_API_BASE https://api.ebay.com Browse API origin
EBAY_TOKEN_URL https://api.ebay.com/identity/v1/oauth2/token OAuth token endpoint
EBAY_SCOPE https://api.ebay.com/oauth/api_scope Requested OAuth scope
EBAY_TIMEOUT 20.0 Request timeout in seconds

EBAY_CLIENT_ID / EBAY_CLIENT_SECRET

  • Type: String
  • Default: ""
  • Required: Yes, when enabling the eBay tools
  • Description: Production App ID and Cert ID used for client-credentials OAuth

EBAY_MARKETPLACE_ID / EBAY_LANGUAGE

  • Type: String
  • Defaults: EBAY_DE / de-DE
  • Description: eBay marketplace and response locale

EBAY_DELIVERY_COUNTRY / EBAY_DELIVERY_POSTAL_CODE

  • Type: String
  • Defaults: DE / ""
  • Description: Delivery destination used for filtering and shipping estimates

EBAY_CURRENCY

  • Type: String
  • Default: EUR
  • Description: Currency used with price filters

EBAY_MAX_SEARCH_RESULTS / EBAY_MAX_DESCRIPTION_CHARS

  • Types: Integer
  • Defaults: 50 / 3000
  • Description: Hard output limits that keep tool responses compact

EBAY_ENABLED

  • Type: Boolean
  • Default: True
  • Description: Enable or disable the eBay toolset

MYDEALZ_* Settings

The compact read-only MyDealz integration needs no user credentials. Static Android guest signing values are part of the tool transport.

MYDEALZ_LANGUAGE

  • Type: String
  • Default: de-DE
  • Description: Response locale sent to MyDealz

MYDEALZ_MAX_SEARCH_RESULTS / MYDEALZ_MAX_DESCRIPTION_CHARS / MYDEALZ_MAX_COMMENT_CHARS

  • Types: Integer
  • Defaults: 30 / 2400 / 600
  • Description: Hard output limits for deal lists, descriptions, and comments

MYDEALZ_ENABLED

  • Type: Boolean
  • Default: True
  • Description: Enable or disable the MyDealz toolset

MYDEALZ_TIMEOUT

  • Type: Float
  • Default: 20.0
  • Description: Request timeout in seconds; must be greater than zero

Instance Metadata and Favicons

The instance metadata fields are returned by GET /api/v1/instance for the deployment's privacy information. Unset optional fields are returned as null.

Variable Default Meaning
INSTANCE_NAME Numi Chat Public instance name
OPERATOR_NAME None Instance operator name
OPERATOR_ADDRESS None Instance operator address
PRIVACY_CONTACT_EMAIL None Contact email for privacy questions
PRIVACY_POLICY_URL None Link to the deployment's privacy policy
FAVICON_DIRECT_FALLBACK False Try the requested domain's /favicon.ico if Google's favicon service fails

Deno Settings

Deno executable

Deno settings are managed by the DenoSettings class.

DENO_PATH

  • Type: String
  • Default: None
  • Required: No
  • Description: Path to the Deno executable or its containing directory. If unset, Numi searches PATH. Used by the Pyodide sandbox path; simple Monty execution does not require Deno.
  • Compatibility: Legacy D_AI_DENO_PATH is still accepted

Configuration Patterns

Environment Variable Prefixes

Each configuration class uses a specific prefix for environment variables:

  • AI Settings: Z_AI_
  • Web search providers (direct): OCTEN_API_KEY, PARALLEL_API_KEY, EXA_API_KEY, KEENABLE_API_KEY, YOU_API_KEY, DEEPSEEK_API_KEY, WEB_SEARCH_PROVIDERS, WEB_FETCH_PROVIDERS, NUMI_SEARCH_RANK_MODEL
  • OpenRouter Settings: OPENROUTER_
  • Crowbot Settings: CROWBOT_
  • OpenAI Settings: OPENAI_
  • Responses-Compatible Settings: RESPONSES_
  • Anthropic Settings: ANTHROPIC_
  • Anthropic-Compatible Settings: ANTHROPIC_COMPAT_
  • Inception Settings: INCEPTION_
  • Mistral Settings: MISTRAL_
  • Local AI Settings: LOCAL_AI_
  • Database Settings: DB_
  • Authentication Settings: AUTH_
  • Tool Settings: TOOLS_
  • CORS Settings: CORS_
  • Upload Settings: UPLOAD_
  • Logging Settings: LOG_, except the direct ENVIRONMENT alias
  • Deno executable (direct): DENO_PATH or legacy D_AI_DENO_PATH
  • Lidl Plus Settings: LIDL_
  • Kaufland Settings: KAUFLAND_
  • EDEKA Settings: EDEKA_
  • Kleinanzeigen Settings: KLEINANZEIGEN_
  • eBay Settings: EBAY_
  • Compaction Settings: COMPACT_
  • Memory Settings: MEMORY_
  • Chat title model: CHAT_TITLE_
  • Agent limits: AGENT_
  • WebSocket limits: WEBSOCKET_
  • Rate limits: RATE_LIMIT_
  • Prompt limits: PROMPT_
  • Image generation: IMAGE_GEN_
  • MyDealz: MYDEALZ_
  • Favicons: FAVICON_
  • Instance metadata: direct names from the metadata table

Priority Order

Environment-backed settings are resolved in this order (highest to lowest):

  1. Explicit arguments passed to settings class constructor
  2. Environment variables
  3. .env file values
  4. Default values

Environment File Support

All settings classes support loading from .env files. The extra="ignore" setting means that extra variables not defined in the class are ignored. This does not load the separate process settings into the local process environment.

Catalog entries and database-backed settings follow their own rules: a private catalog replaces packaged defaults, and admin background-model overrides take precedence over their environment fallback. Account instructions are saved through Settings or the settings API; they are not environment variables.