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.

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

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.

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

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

PARALLEL_API_KEY

  • Type: String
  • Default: None
  • Required: No
  • Description: Parallel API key for web_search and fetch_web_page (get key at platform.parallel.ai)

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 Parallel 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,remember_fact,forget_fact,view,create_file,generate_image,grocery_search_stores,grocery_profile,grocery_get_offers,chefkoch_search,chefkoch_recipe,chefkoch_recipe_of_the_day,kleinanzeigen_search,kleinanzeigen_listing,kleinanzeigen_categories,academic_search,wiki_lookup,ebay_search,ebay_listing,mydealz_search,mydealz_deal,mydealz_discover
  • 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,reportlab,pypdf
  • Required: No
  • Description: Comma-separated list of allowed dependencies for code interpreter. Explicit overrides replace the defaults; add the office packages to an existing override to enable them. Import names docx and sklearn map to packages python-docx and scikit-learn.

TOOLS_CODE_INTERPRETER_IMPORT_ALLOWLIST

  • Type: String
  • Default: math,statistics,random,itertools,functools,collections,datetime,re,json,typing,os,sys,pathlib,io,csv
  • 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
  • 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_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

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: google/gemini-3.1-flash-lite-image
  • Required: No
  • Description: OpenRouter model slug used for image generation. Must list image in its output modalities.

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, 4:5, 5:4, 9:16, 16:9, 21:9, plus 1:4, 4:1, 1:8, 8:1.

IMAGE_GEN_IMAGE_SIZE

  • Type: String
  • Default: 1K
  • Required: No
  • Description: Default resolution tier. Allowed: 0.5K, 1K, 2K, 4K. 0.5K is only for legacy models that accept it.

IMAGE_GEN_IMAGE_CONFIG_ENABLED

  • Type: Boolean
  • Default: False
  • Required: No
  • Description: Send the provider image configuration block. Leave disabled unless the selected model explicitly supports it.

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: 120.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.

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 600 Total turn deadline in seconds
AGENT_MAX_ITERATIONS 24 Maximum model iterations 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

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 128 Simultaneous connections across the process
WEBSOCKET_MAX_ACTIVE_TURNS 16 Simultaneous turns across the process
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 * Uvicorn trusted proxy addresses; Compose defaults to 127.0.0.1
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_BASH_ENABLED true Bash availability switch; Windows remains unsupported
TOOLS_BASH_TIMEOUT 120 Default Bash timeout in seconds
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: 128000
  • Required: No
  • Description: OpenRouter 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_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
  • Required: No
  • Description: Model for background memory jobs when no admin override is stored. See Background model settings.

MEMORY_EXTRACTION_GATE_ENABLED

  • Type: Boolean
  • Default: False
  • Required: No
  • Description: Enable the OpenRouter Decisions API pre-filter for automatic memory extraction. Only confidently negative decisions skip extraction; failures continue through the configured memory model.

MEMORY_EXTRACTION_GATE_SKIP_BELOW

  • Type: Float from 0 through 1
  • Default: 0.15
  • Required: No
  • Description: Skip the normal extractor when Jev's memory-candidate probability is below this value.

MEMORY_EXTRACTION_TRIGGER_EVERY_N_TURNS

  • Type: Integer
  • Default: 2
  • Required: No
  • Description: Completed pending turns required to trigger extraction. Intermediate tool-call messages are not separate turns; idle flush can process a single completed turn.

MEMORY_EXTRACTION_CONSOLIDATION_THRESHOLD

  • Type: Integer
  • Default: 5
  • Required: No
  • Description: Pending observations needed to trigger consolidation. Aged smaller queues can also be consolidated by idle flush; deferred observations are excluded from ordinary automatic retries.

MEMORY_EXTRACTION_IDLE_FLUSH_MINUTES

  • Type: Integer
  • Default: 60
  • Required: No
  • Description: Age at which complete pending turns in inactive chats, and small pending observation queues, become eligible. 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 completed turn 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 pending message rows fetched when selecting complete turns for extraction.

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: 1500
  • Required: No
  • Description: Estimated token budget for adaptive profile facts included in user context. Explicit saved facts have separate PROMPT_MAX_MEMORY_* limits.

MEMORY_TOP_OF_MIND_TTL_DAYS / MEMORY_RECENT_HISTORY_TTL_DAYS / MEMORY_EARLIER_CONTEXT_TTL_DAYS

  • Type: Integer
  • Defaults: 21, 14, 90
  • Required: No
  • Description: Expiry windows for active goals, recent events, and earlier context. Expired profile facts are excluded until reconfirmed; manually saved facts remain non-expiring.

Background Model Settings

The admin Models page can store a live override for the chat-title and memory models. These overrides take precedence over the environment fallback and do not require a server restart. Use config removes an override.

CHAT_TITLE_MODEL

  • Type: String
  • Default: deepseek/deepseek-v4.1-flash
  • 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

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_
  • Parallel Settings (direct): PARALLEL_API_KEY
  • OpenRouter Settings: OPENROUTER_
  • OpenAI Settings: OPENAI_
  • Responses-Compatible Settings: RESPONSES_
  • Anthropic Settings: ANTHROPIC_
  • Anthropic-Compatible Settings: ANTHROPIC_COMPAT_
  • Inception Settings: INCEPTION_
  • 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_
  • 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.