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.dbfor persistent storage.
NUMI_CHAT_MODEL_CONFIG_PATH¶
- Type: Path
- Default:
state/models.json(/app/state/models.jsonin 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-Refererattribution header
OPENROUTER_APP_NAME¶
- Type: String
- Default:
Numi Chat - Required: No
- Description: App title sent as OpenRouter
X-OpenRouter-Titleattribution 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, or1h; tool schema isauto,anthropic, oropenai - Description: Configure prompt cache duration, output cap, and tool-schema
dialect.
max_output_tokensis 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. WithDEEP_RESEARCH_CACHE_WARMING=true,5mcaches 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).
keenableruns Keenable pro search, its deepest retrieval and best ranking;keenable:realtimeruns the realtime mode, built for the fastest response and one index point lower. Both use the sameKEENABLE_API_KEYand cost the same.exaruns Exa auto search;exa:literuns Exa lite, which costs about 40% less per search, scores almost as well, and serves only Exa's index, sofreshness="live"does not apply to it. Both use the sameEXA_API_KEY. To save cost, putexa:litein place ofexa, here or in the admin Web search providers card.numi-searchasks several providers at once and ranks their results; list it first, followed by the providers that should answer when it fails, for examplenumi-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 withOPENROUTER_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 asliquid/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 toDECISIONS_URL(see Optional Tool Routing);DECISIONS_ENABLEDdoes not switch this off. Unused whilenumi-searchis disabled.
WEB_FETCH_PROVIDERS¶
- Type: Comma-separated list of
keenable,keenable:realtime,exa,exa:lite,octen,parallel,you,deepseek(exaandexa:litefetch pages the same way, as dokeenableandkeenable:realtime).numi-searchonly 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_KEYinstead.
DIRECT_WEB_FETCH_ENABLED¶
- Type: Boolean
- Default:
false - Required: No
- Description: When enabled,
fetch_web_pagetries local SSRF-safe HTTP fetching andtrafilaturaextraction 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_activationis registered separately unless denied;TOOLS_DENYLISTtakes 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
pillowto an existing override to enable them. Import namesdocx,pptx,pdfminer,sklearnandPILmap to packagespython-docx,python-pptx,pdfminer.six,scikit-learnandpillow. Skills that list a package missing here are left out of the skill index; importingzoneinfoloadstzdataso 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_MBtimes 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, oryesswitch 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.
0means 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
0through1 - 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
ProfileandPreferencesentries 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.
inherituses the memory model (MEMORY_SUMMARY_MODELor 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.
permanentdetails 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 (
1000to24000) and maximum batches (1to40) when importing external memory notes throughPOST /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_MODELis 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_PATHis 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 directENVIRONMENTalias - Deno executable (direct):
DENO_PATHor legacyD_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):
- Explicit arguments passed to settings class constructor
- Environment variables
.envfile values- 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.