App & Backend

Core server settings — URLs, sign-up, sessions, directories, logging, Ollama and OpenAI connections, task models, code execution, tool servers and caching.

These variables are set on the Hrida.ai container. Variables marked ConfigVar are saved to the database on first start — see how ConfigVar works before changing them later.

The following environment variables are used by backend/hridaai/config.py to provide Hrida.ai startup configuration. Please note that some variables may have different default values depending on whether you're running Hrida.ai directly or via Docker. For more information on logging environment variables, see our logging documentation.

General

`HRIDAAI_URL`

Type: str
Default: http://localhost:3000
Description: Specifies the URL where your Hrida.ai installation is reachable. Needed for search engine support and OAuth/SSO.
Persistence: This environment variable is a ConfigVar variable.

warning

This variable has to be set before you start using OAuth/SSO for authentication. Since this is a persistent config environment variable, you can only change it through one of the following options:

Temporarily disabling persistent config using ENABLE_PERSISTENT_CONFIG
Changing HRIDAAI_URL in the admin panel > settings and changing "Hrida.ai URL".

Failure to set HRIDAAI_URL before using OAuth/SSO will result in failure to log in.

`ENABLE_SIGNUP`

Type: bool
Default: True
Description: Toggles user account creation.
Persistence: This environment variable is a ConfigVar variable.

`ENABLE_SIGNUP_PASSWORD_CONFIRMATION`

Type: bool
Default: False
Description: If set to True, a "Confirm Password" field is added to the sign-up page to help users avoid typos when creating their password.

`HRIDAAI_ADMIN_EMAIL`

Type: str
Default: Empty string (' ')
Description: Specifies the email address for an admin account to be created automatically on first startup when no users exist. This enables headless/automated deployments without manual account creation. When combined with HRIDAAI_ADMIN_PASSWORD, the admin account is created during application startup, and ENABLE_SIGNUP is automatically disabled to prevent unauthorized account creation.

info

This variable is designed for automated/containerized deployments where manual admin account creation is impractical. The admin account is only created if:

No users exist in the database (fresh installation)
Both HRIDAAI_ADMIN_EMAIL and HRIDAAI_ADMIN_PASSWORD are configured

After the admin account is created, sign-up is automatically disabled for security. You can re-enable it later via the Admin Panel if needed.

`HRIDAAI_ADMIN_PASSWORD`

Type: str
Default: Empty string (' ')
Description: Specifies the password for the admin account to be created automatically on first startup when no users exist. Must be used in conjunction with HRIDAAI_ADMIN_EMAIL. The password is securely hashed before storage using the same mechanism as manual account creation.

danger

Security Considerations

Use a strong, unique password for production deployments
Consider using secrets management (Docker secrets, Kubernetes secrets, environment variable injection) rather than storing the password in plain text configuration files
After initial setup, change the admin password through the UI for enhanced security
Never commit this value to version control

`HRIDAAI_ADMIN_NAME`

Type: str
Default: Admin
Description: Specifies the display name for the automatically created admin account. This is used when HRIDAAI_ADMIN_EMAIL and HRIDAAI_ADMIN_PASSWORD are configured for headless admin creation.

`ENABLE_LOGIN_FORM`

Type: bool
Default: True
Description: Toggles email, password, sign-in and "or" (only when ENABLE_OAUTH_SIGNUP is set to True) elements.
Persistence: This environment variable is a ConfigVar variable.

`ENABLE_PASSWORD_CHANGE_FORM`

Type: bool
Default: True
Description: Controls visibility of the password change UI in Settings > Account. When set to False, users do not see the password update form, which is useful for SSO-focused deployments where password changes should not be presented in the UI.
Persistence: This environment variable is a ConfigVar variable.

`ENABLE_PASSWORD_AUTH`

Type: bool
Default: True
Description: Allows both password and SSO authentication methods to coexist when set to True. When set to False, it disables all password-based login attempts on the /signin and /ldap endpoints, enforcing strict SSO-only authentication. Disable this setting in production environments with fully configured SSO to prevent credential-based account takeover attacks; keep it enabled if you require password authentication as a backup or have not yet completed SSO configuration. Should never be disabled if OAUTH/SSO is not being used. This setting controls backend authentication behavior, while ENABLE_PASSWORD_CHANGE_FORM controls UI visibility of password-change controls.

tip

This SHOULD be set to False if you only use SSO/OAUTH for Login and expose your Hrida.ai publicly as to prevent password based logins.

danger

This should only ever be set to False when ENABLE_OAUTH_SIGNUP is also being used and set to True. Never disable this if OAUTH/SSO is not being used. Failure to do so will result in the inability to login.

`DEFAULT_LOCALE`

Type: str
Default: en
Description: Sets the default locale for the application.
Persistence: This environment variable is a ConfigVar variable.

`DEFAULT_MODELS`

Type: str
Default: Empty string (' '), since None.
Description: Sets a default Language Model.
Persistence: This environment variable is a ConfigVar variable.

`DEFAULT_PINNED_MODELS`

Type: str
Default: Empty string (' ')
Description: Comma-separated list of model IDs to pin by default for new users who haven't customized their pinned models. This provides a pre-selected set of frequently used models in the model selector for new accounts.
Example: gpt-4,claude-3-opus,llama-3-70b
Persistence: This environment variable is a ConfigVar variable.

`DEFAULT_MODEL_METADATA`

Type: dict (JSON object)
Default: {}
Description: Sets global default metadata (capabilities and other model info) for all models. These defaults act as a baseline — per-model overrides always take precedence. For capabilities, the defaults and per-model values are merged (per-model wins on conflicts). For other metadata fields, the default is only applied if the model has no value set. Configurable via Admin Settings → Models.
Persistence: This environment variable is a ConfigVar variable. Stored at config key models.default_metadata.

info

DEFAULT_MODEL_METADATA is read from the environment as a JSON string at startup.

Use valid JSON (for example: {"capabilities":{"vision":true,"web_search":true}})
If parsing fails, Hrida.ai logs the error and falls back to {}
The parsed value is then applied even when persistent config is disabled, so configured defaults are honored at startup.

`DEFAULT_MODEL_PARAMS`

Type: dict (JSON object)
Default: {}
Description: Sets global default parameters (temperature, top_p, max_tokens, seed, etc.) for all models. These defaults are applied as a baseline at chat completion time — per-model parameter overrides always take precedence. Configurable via Admin Settings → Models.
Persistence: This environment variable is a ConfigVar variable. Stored at config key models.default_params.

info

DEFAULT_MODEL_PARAMS is read from the environment as a JSON string at startup.

Use valid JSON (for example: {"temperature":0.7,"function_calling":"native"})
If parsing fails, Hrida.ai logs the error and falls back to {}

`DEFAULT_USER_ROLE`

Type: str
Options:
- pending - New users are pending until their accounts are manually activated by an admin.
- user - New users are automatically activated with regular user permissions.
- admin - New users are automatically activated with administrator permissions.
Default: pending
Description: Sets the default role assigned to new users.
Persistence: This environment variable is a ConfigVar variable.

`DEFAULT_GROUP_ID`

Type: str
Default: Empty string (' ')
Description: Sets the default group ID to assign to new users upon registration.
Persistence: This environment variable is a ConfigVar variable.

`DEFAULT_GROUP_SHARE_PERMISSION`

Type: str
Options: members, true, false
Default: members
Description: Controls the default "Who can share to this group" setting for newly created groups. members means only group members can share to the group, true means anyone can share, and false means no one can share to the group. This applies both to groups created manually and groups created automatically (e.g. via SCIM or OAuth group sync). Existing groups are not affected — this only sets the initial default for new groups.

`PENDING_USER_OVERLAY_TITLE`

Type: str
Default: Empty string (' ')
Description: Sets a custom title for the pending user overlay.
Persistence: This environment variable is a ConfigVar variable.

`PENDING_USER_OVERLAY_CONTENT`

Type: str
Default: Empty string (' ')
Description: Sets a custom text content for the pending user overlay.
Persistence: This environment variable is a ConfigVar variable.

`ENABLE_CALENDAR`

Type: bool
Default: True
Description: Enables or disables the Calendar feature. When enabled, users can create calendars, manage events, and share calendars with other users or groups via access grants. Active automations are automatically surfaced as virtual events on a dedicated "Scheduled Tasks" calendar. Requires the features.calendar user permission (admins always pass).
Persistence: This environment variable is a ConfigVar variable.

`ENABLE_ARTIFACTS`

Type: bool
Default: True
Description: Enables or disables the Artifacts workspace. Requires the features.artifacts user permission (admins always pass).
Persistence: This environment variable is a ConfigVar variable. It can be configured in Admin Panel > Settings > Artifacts.

`ENABLE_ARTIFACT_SKILLS`

Type: bool
Default: False
Description: Enables AI document skills: users edit, generate and convert real PowerPoint, Word, Excel and PDF files with any configured model, using the office-skills repository run on the server. Off by default because the file goes to the chosen model's provider and model-written scripts run on the server. Requires the features.artifact_skills user permission (admins always pass) and the office-skills repository, uploaded in the admin settings or mounted at OFFICE_SKILLS_DIR.
Persistence: This environment variable is a ConfigVar variable. It can be configured in Admin Panel > Settings > Artifacts > Enable AI document skills.

`ARTIFACT_SKILLS_MODELS`

Type: str (comma-separated model IDs)
Default: ("") empty string (every model)
Description: Limits which models are offered for AI document skills.
Persistence: This environment variable is a ConfigVar variable. It can be configured in Admin Panel > Settings > Artifacts > Limit to specific models.

`ARTIFACT_SKILLS_MAX_TURNS`

Type: int
Default: 40
Description: Maximum model turns (tool-call rounds) for one AI document skills job. Allowed range 4–100.
Persistence: This environment variable is a ConfigVar variable.

`ARTIFACT_SKILLS_MAX_JOBS_PER_USER`

Type: int
Default: 2
Description: How many AI document skills jobs one user can run at the same time. Allowed range 1–10.
Persistence: This environment variable is a ConfigVar variable.

`OFFICE_SKILLS_DIR`

Type: str
Default: /opt/office-skills
Description: Where a mounted copy of the office-skills repository is found (it must contain scripts/skill_tools.py). An office-skills zip uploaded in Admin Panel > Settings > Artifacts takes priority over this folder.

`API_GATEWAY_CALL_LOG_RETENTION_DAYS`

Type: int
Default: 30
Description: How many days the API Builder gateway keeps raw call log rows (1–365). Older UTC days are archived to storage first (when API_GATEWAY_CALL_ARCHIVE_ENABLED is on) and then deleted in batches. History stays available as summaries for API Analytics.
Persistence: This environment variable is a ConfigVar variable. It can be configured in API Builder > Gateway settings > Call log retention & archive.

`API_ANALYTICS_HOURLY_RETENTION_DAYS`

Type: int
Default: 90
Description: How many days hourly analytics summaries are kept (2–400). Hourly charts reach this far back; older ranges are shown per day.
Persistence: This environment variable is a ConfigVar variable.

`API_ANALYTICS_DAILY_RETENTION_DAYS`

Type: int
Default: 730
Description: How many days daily analytics summaries are kept (30–3650, at least as long as the hourly ones).
Persistence: This environment variable is a ConfigVar variable.

`API_GATEWAY_CALL_ARCHIVE_ENABLED`

Type: bool
Default: True
Description: Archive each finished UTC day of raw gateway calls to storage (gzip JSON Lines, under api-gateway-call-archive/ in STORAGE_PROVIDER's storage) before deleting it. When off, raw rows older than the retention are deleted without a copy.
Persistence: This environment variable is a ConfigVar variable.

`API_GATEWAY_CALL_ARCHIVE_RETENTION_DAYS`

Type: int
Default: 365
Description: How many days call log archives are kept; 0 keeps them forever.
Persistence: This environment variable is a ConfigVar variable.

`API_GATEWAY_CALL_LOG_JOBS_HOUR_UTC`

Type: int
Default: 1
Description: The UTC hour after which the daily call log archive and clean-up run. Set an off-peak hour for your users, for example 21 for 02:30 in India. The 5-minute summary job is not affected.

`API_GATEWAY_CALL_ARCHIVE_DIR`

Type: str
Default: ${DATA_DIR}/api-gateway-call-archive
Description: Where call log archives are written when STORAGE_PROVIDER is local.

`API_BUILDER_SELF_URL`

Type: str
Default: http://localhost:${PORT}
Description: Where Studio's agents send their API Builder tool calls. To send them to the dedicated gateway service, set its internal URL, for example http://hrida-ai-gateway:8080. Studio moves existing tool-server registrations to the current URL when it starts.

`API_GATEWAY_CACHE_SECONDS`

Type: int
Default: 15
Description: How long each gateway process caches API definitions, the versions environments serve, mappers, consumer keys and gateway settings. A change made in Studio clears the caches at once, in other processes through Redis; without Redis, other processes see it when this period ends. 0 turns caching off.

`API_GATEWAY_POOL_CONNECTIONS`

Type: int
Default: 200
Description: Open upstream connections each gateway process keeps, across all upstreams.

`API_GATEWAY_POOL_CONNECTIONS_PER_HOST`

Type: int
Default: 50
Description: Open connections each gateway process keeps per upstream host and port.

`API_GATEWAY_DNS_CACHE_SECONDS`

Type: int
Default: 60
Description: How long the gateway reuses an upstream's DNS answer. Every answer is checked against internal addresses before it is used.

`API_GATEWAY_KEEPALIVE_SECONDS`

Type: int
Default: 4
Description: How long an idle upstream connection is kept open for the next call. Keep it below the upstreams' own keep-alive timeouts (5 seconds is common), so calls aren't sent on connections the upstream is closing.

`API_GATEWAY_MAX_CONCURRENT_CALLS`

Type: int
Default: 100
Description: Default for the gateway policy's Calls at once: upstream calls to one API in progress at once, per gateway worker. Beyond it, calls wait up to API_GATEWAY_QUEUE_TIMEOUT_MS, then get 503 upstream_busy. 0 means no limit. See Concurrency and overload.

`API_GATEWAY_MAX_IN_FLIGHT`

Type: int
Default: 1000
Description: Gateway calls in progress at once per worker, across all APIs. Beyond it, calls get 503 overloaded at once instead of queueing. 0 means no limit.

`API_GATEWAY_QUEUE_TIMEOUT_MS`

Type: int
Default: 1000
Description: How long a gateway call waits for one of its API's slots (see API_GATEWAY_MAX_CONCURRENT_CALLS) before 503 upstream_busy.

`API_GATEWAY_RETRY_BUDGET_RATIO`

Type: float
Default: 0.2
Description: How much of a retry each gateway call earns: 0.2 allows one retry per five calls, per API and environment, so retries can't multiply the load on a failing upstream.

`API_GATEWAY_STREAM_THRESHOLD_BYTES`

Type: int
Default: 1048576
Description: A gateway response that no mapper, masking or validation changes is streamed to the caller when it is larger than this, or doesn't declare its length.

`API_GATEWAY_AUTH_FAILURES_PER_MINUTE`

Type: int
Default: 30
Description: Failed logins (a wrong consumer key, gateway secret or partner token) per client address and minute before further failures get 429 auth_throttled and aren't logged. Valid credentials keep working. 0 means no limit. See Failed logins.

`API_GATEWAY_CLIENT_CERT_HEADER`

Type: str
Default: Empty string (' ')
Description: The request header in which your TLS-terminating proxy passes the client certificate, for consumer keys bound to a certificate: a URL-encoded PEM (nginx $ssl_client_escaped_cert, AWS ALB), Envoy's X-Forwarded-Client-Cert, or a hex SHA-256 fingerprint.

`API_GATEWAY_BREAKER_SYNC_SECONDS`

Type: float
Default: 1
Description: How long a gateway worker trusts that an upstream's circuit breaker is healthy before checking the shared state in Redis again. Failures are always recorded at once. 0 checks on every call.

`API_GATEWAY_JWKS_CACHE_SECONDS`

Type: int
Default: 600
Description: How long the signing keys of partners' identity providers are kept, for APIs that accept partner access tokens. A token signed with an unknown key fetches them again early.

`SAFE_EVAL_MAX_STEPS`

Type: int
Default: 250000
Description: Steps one mapper expression may take. An expression that needs more fails its mapping instead of holding up the worker.

`SMTP_HOST`

Type: str
Default: Empty string (' ')
Description: The SMTP server Studio sends email through: API alert emails and demo requests. Email is sent only when SMTP_HOST, SMTP_USER and SMTP_PASSWORD are all set.

`SMTP_PORT`

Type: int
Default: 587
Description: The SMTP server's port. Port 465 uses implicit TLS; any other port uses STARTTLS.

`SMTP_USER`

Type: str
Default: Empty string (' ')
Description: The SMTP login. Messages are sent from this address unless SMTP_FROM is set.

`SMTP_PASSWORD`

Type: str
Default: Empty string (' ')
Description: The SMTP password, or an app password for providers such as Gmail.

`SMTP_FROM`

Type: str
Default: Empty string (' ')
Description: The sender address, when the SMTP login isn't one (Amazon SES, SendGrid and Mailgun use access keys or apikey as the login). Defaults to SMTP_USER.

`ENABLE_CHANNELS`

Type: bool
Default: False
Description: Enables or disables channel support.
Persistence: This environment variable is a ConfigVar variable.

`ENABLE_FOLDERS`

Type: bool
Default: True
Description: Enables or disables the folders feature, allowing users to organize their chats into folders in the sidebar.
Persistence: This environment variable is a ConfigVar variable.

`FOLDER_MAX_FILE_COUNT`

Type: int
Default: ("") empty string
Description: Sets the maximum number of files processing allowed per folder.
Persistence: This environment variable is a ConfigVar variable. It can be configured in the Admin Panel > Settings > General > Folder Max File Count. Default is none (empty string) which is unlimited.

`ENABLE_AUTOMATIONS`

Type: bool
Default: True
Description: Enables or disables the Automations feature globally. When disabled, the scheduler skips automation processing, the automation API endpoints return 403 Forbidden, automation builtin tools are not injected, and the Automations entry is hidden from the sidebar. Requires the features.automations user permission (admins always pass).
Persistence: This environment variable is a ConfigVar variable.

`AUTOMATION_MAX_COUNT`

Type: int
Default: ("") empty string (unlimited)
Description: Sets the maximum number of automations a non-admin user can create. When set to a positive integer, users who reach this limit will receive a 403 Forbidden error when attempting to create additional automations. Admins bypass this limit.
Persistence: This environment variable is a ConfigVar variable.

`AUTOMATION_MIN_INTERVAL`

Type: int (seconds)
Default: ("") empty string (no minimum)
Description: Sets the minimum allowed interval in seconds between automation recurrences for non-admin users. When set, any automation schedule that recurs more frequently than this value will be rejected with a 400 Bad Request error. One-time automations (COUNT=1) are exempt from this check. Admins bypass this limit.
Persistence: This environment variable is a ConfigVar variable.

Common values for AUTOMATION_MIN_INTERVAL

Value	Meaning
`60`	Minimum 1 minute between runs
`300`	Minimum 5 minutes between runs
`900`	Minimum 15 minutes between runs
`3600`	Minimum 1 hour between runs

`SCHEDULER_POLL_INTERVAL`

Type: int (seconds)
Default: 10
Description: Sets the interval in seconds between scheduler ticks. The unified scheduler handles both automation run and calendar event alerts. Accepts AUTOMATION_POLL_INTERVAL as a legacy fallback.

`CALENDAR_ALERT_LOOKAHEAD_MINUTES`

Type: int (minutes)
Default: 10
Description: Default lookahead window in minutes for calendar event alerts. Events starting within this window from the current time will trigger toast and webhook notifications. Individual events can override this via the Reminder setting in the event editor (meta.alert_minutes).

`ENABLE_NOTES`

Type: bool
Default: True
Description: Enables or disables the notes feature, allowing users to create and manage personal notes within Hrida.ai.
Persistence: This environment variable is a ConfigVar variable.

`ENABLE_MEMORIES`

Type: bool
Default: True
Description: Enables or disables the memory feature, allowing models to store and retrieve long-term information about users.
Persistence: This environment variable is a ConfigVar variable.

`WEBHOOK_URL`

Type: str
Persistence: This environment variable is a ConfigVar variable.

Admin posture toggles vs. security boundaries

The ENABLE_ADMIN_* and BYPASS_ADMIN_ACCESS_CONTROL toggles in this section control what the admin sees and does through Hrida.ai's admin product surfaces (admin panel pages, the chat model selector, workspace lists, the export action). They do not establish a security boundary against the admin themselves.

Hrida.ai is single-tenant by architecture and the admin role is root-equivalent on the deployment by deliberate design. Admins inherently retain unconstrained access to all data via direct database access, environment-variable inspection, server access, admin-only Functions (which execute arbitrary Python at module-import inside the application process), and Tools with the workspace.tools permission (which the admin can grant to themselves and which run exec() on the server).

These toggles are appropriate for:

Performance — keeping admin-facing list/selector surfaces fast on large multi-user deployments where loading every user's items is a hard performance problem.
UI clutter reduction — keeping those same surfaces usable when populated with thousands of items from other users.
Compliance posture — meeting requirements (especially in jurisdictions with stronger labour-protection law, e.g. DE / AT / EU) that admins not be casually presented with other users' data, even though they remain technically able to reach it via the routes above.

These toggles are not appropriate for:

Cross-tenant data isolation between admins. There is no cryptographic per-tenant isolation, no multi-database split, and no per-admin scope on the underlying data store. For genuine tenant separation, the supported pattern is separate Hrida.ai instances per tenant.
A security boundary against an admin who is determined to read data they aren't shown in their UI surfaces.

Treat anything in this cluster as what the admin sees and does in the product UI and API, not what the admin technically can reach on the deployment.

`ENABLE_ADMIN_EXPORT`

Type: bool
Default: True
Description: Controls whether the admin-panel export action is available (data, chats, and database export). When disabled, the export endpoints reject requests. Database exports only work for SQLite databases for now. Note that admin retains the underlying ability to dump the database directly via deployment access — this toggle controls the in-product export surface, see the admin-posture-toggles note above. Requires a restart to take effect.

`ENABLE_ADMIN_CHAT_ACCESS`

Type: bool
Default: True
Description: Controls whether the admin-panel other-users-chats access surface is available. When disabled, admins can no longer access other users' chats in the admin panel and the corresponding endpoints reject the request. If you disable this, consider also disabling ENABLE_ADMIN_EXPORT (especially on SQLite), since exports include user chats and would re-open the same data on a different surface. Note that admin retains underlying database access regardless — this toggle controls the in-product surface, see the admin-posture-toggles note above.

`ENABLE_ADMIN_ANALYTICS`

Type: bool
Default: True
Description: Controls whether the admin-panel Analytics tab is visible and the analytics API router is mounted. When set to False, the tab is hidden and the corresponding endpoints are not registered. Disabling does not stop the underlying data being collected, and admin retains the ability to query that data directly from the database — this toggle controls the in-product surface, see the admin-posture-toggles note above. Requires a restart to take effect.

`BYPASS_ADMIN_ACCESS_CONTROL`

Type: bool
Default: True
Description: Controls whether admin users see other users' workspace items in list and selector UI surfaces (workspace tabs for models / knowledge / prompts / tools / notes / skills, the chat model selector, the file browser list, etc.). When set to True (default), those surfaces show every item from every user — convenient for single-admin / small-team deployments. When set to False, those same surfaces show only the admin's own items plus items explicitly shared with them, matching what a regular user would see.

Per-id direct-access endpoints (GET /api/v1/{'<resource>'}/id/{id} and the corresponding update / delete / access-update routes) are intentionally not gated by this flag and were never designed to be — gating them would protect against nothing the admin couldn't trivially do via the database query they used to obtain the resource ID in the first place, while breaking legitimate flows where an admin operates on a known item ID. See the admin-posture-toggles note above for the full architectural reasoning.

This environment variable deprecates ENABLE_ADMIN_WORKSPACE_CONTENT_ACCESS. If you are still using ENABLE_ADMIN_WORKSPACE_CONTENT_ACCESS, switch to BYPASS_ADMIN_ACCESS_CONTROL.

`ENABLE_USER_WEBHOOKS`

Type: bool
Default: False
Description: Enables or disables user webhooks (each user can set a URL their notifications are POSTed to). For SSRF safety, webhook URLs that resolve to private or reserved IPs are blocked unless ENABLE_RAG_LOCAL_WEB_FETCH is true.
Persistence: This environment variable is a ConfigVar variable.

`RESPONSE_WATERMARK`

Type: str
Default: Empty string (' ')
Description: Sets a custom text that will be included when you copy a message in the chat. e.g., "This text is AI generated" -> will add "This text is AI generated" to every message, when copied.
Persistence: This environment variable is a ConfigVar variable.

`IFRAME_CSP`

Type: str
Default: Empty string (no CSP injected)
Description: Sets a Content-Security-Policy applied to all srcdoc iframes rendered in the UI — Artifacts, code/HTML previews, file previews, and citation modals. When set, a {'<meta http-equiv="Content-Security-Policy">'} tag is injected at the top of the iframe document, restricting what LLM-generated or user-uploaded HTML can load and execute (network connections, scripts, styles, fonts, frames). The sandbox attribute on the iframe still provides the baseline isolation; this CSP is an additional defense-in-depth layer for deployments that need to constrain outbound network requests from rendered HTML. Example value: default-src 'self' 'unsafe-inline' 'unsafe-eval' data: blob:; connect-src 'none'. Leave unset to keep the existing behavior (sandbox-only).

`THREAD_POOL_SIZE`

Type: int
Default: 0 (unset — the AnyIO default limit of 40 applies)
Description: Sets the maximum number of concurrent blocking operations that may run in the AnyIO worker thread pool at once. Hrida.ai offloads synchronous/blocking work (many DB calls, file I/O, sync route handlers, some library calls) to this pool via run_in_threadpool. The value is a concurrency ceiling (a token limit), not a fixed pool of pre-spawned OS threads and not a CPU-core/thread count: worker threads are created lazily only when needed and reused, so a high value does not by itself create that many threads, consume CPU, or cause CPU contention while idle. It only raises how many blocking operations can be in flight simultaneously before the rest must queue.

Set this high on any real server (2000+); never lower it

The AnyIO default of 40 is far too low for production. When more than THREAD_POOL_SIZE blocking operations are needed at once (many users acting at the same time, or a few users each triggering several blocking calls), every further request waits for a free slot. The symptom is the whole app appearing to hang / freeze / stop responding under load, even though CPU and memory look fine — it is pool starvation, not resource exhaustion.

Normal servers / production: 2000 or higher. 2000 is a lower bound for very large multi-user instances — going higher is fine and is not a CPU or contention risk (it is a ceiling, not a preallocation).
Never decrease below the default. An idle high ceiling costs effectively nothing; a low ceiling causes freezes.
Exception — weak hardware (Raspberry Pi, tiny VPS, containers capped at ~250m CPU / very low RAM): do not set 2000 here. Each genuinely concurrent blocking op still uses a real OS thread (stack memory), so on a tiny device an enormous ceiling lets a traffic burst spawn enough threads to exhaust RAM. Leave it at the default, or set a modest value (e.g. a few hundred) matched to what the device can actually absorb. This caveat applies only to constrained single-board / micro deployments — any normal server should use 2000+.

`ENABLE_CUSTOM_MODEL_FALLBACK`

Type: bool
Default: False
Description: Controls whether custom models should fall back to a default model if their assigned base model is missing. When set to True, if a custom model's base model is not found, the system will use the first model from the configured DEFAULT_MODELS list instead of returning an error.

`SHOW_ADMIN_DETAILS`

Type: bool
Default: True
Description: Toggles whether to show admin user details in the interface.
Persistence: This environment variable is a ConfigVar variable.

`ENABLE_PUBLIC_ACTIVE_USERS_COUNT`

Type: bool
Default: True
Description: Controls whether the active user count is visible to all users or restricted to administrators only. When set to False, only admin users can see how many users are currently active, reducing backend load and addressing privacy concerns in large deployments.
Persistence: This environment variable is a ConfigVar variable.

`ENABLE_USER_STATUS`

Type: bool
Default: True
Description: Globally enables or disables user status functionality. When disabled, the status UI (including blinking active/away indicators and status messages) is hidden across the application, and user status API endpoints are restricted.
Persistence: This environment variable is a ConfigVar variable. It can be toggled in the Admin Panel > Settings > General > User Status.

`ENABLE_EASTER_EGGS`

Type: bool
Default: True
Description: Enables or disables easter egg features in the UI, such as special themes (e.g., the "Her" theme option in the theme selector). Set to False to hide these optional novelty features from users.

`ADMIN_EMAIL`

Type: str
Description: Sets the admin email shown by SHOW_ADMIN_DETAILS
Persistence: This environment variable is a ConfigVar variable.

`ENV`

Type: str
Options:
- dev - Enables the FastAPI API documentation on /docs
- prod - Automatically configures several environment variables
Default:
- Backend Default: dev
- Docker Default: prod
Description: Environment setting.

`ENABLE_PERSISTENT_CONFIG`

Type: bool
Default: True
Description: Controls whether the system prioritizes configuration saved in the database over environment variables.
- True (Default): Values saved in the database (via the Admin UI) take precedence. If a value is set in the UI, the environment variable is ignored for that setting.
- False: Environment variables take precedence. The system will not load configuration from the database at startup if an environment variable is present (or it will use the default).
  - CRITICAL WARNING: When set to False, you can still seemingly "change" settings in the Admin UI. These changes will apply to the current running session but will be lost upon restart. The system will revert to the values defined in your environment variables (or defaults) every time it boots up.
  - Use Case: Set this to False if you want to strictly manage configuration via a docker-compose.yaml or .env file and prevent UI changes from persisting across restarts.

`PERSISTENT_CONFIG_CACHE_SECONDS`

Type: float
Default: 1
Description: With Redis, how long each process trusts its copy of a setting before checking Redis for a value another replica saved. A change made on one replica reaches the others within this time; the replica that made it has it at once. 0 checks Redis on every read, as before this setting existed, which cost a Redis round trip, blocking the server, for each setting a request read. If Redis can't be reached, each process keeps serving its own copy.

`CUSTOM_NAME`

Type: str
Description: Sets HRIDAAI_NAME but polls api.hrida.ai for metadata.

`HRIDAAI_NAME`

Type: str
Default: Hrida.ai
Description: Sets the main Hrida.ai name. Appends (Hrida.ai) if overridden.

`PORT`

Type: int
Default: 8080
Description: Sets the port to run Hrida.ai from.

`ENABLE_REALTIME_CHAT_SAVE`

Type: bool
Default: False
Description: When enabled, the system saves each individual chunk of streamed chat data to the database in real time.

EXTREME PERFORMANCE RISK: DO NOT ENABLE IN PRODUCTION

It is strongly recommended to NEVER enable this setting in production or multi-user environments.

Enabling ENABLE_REALTIME_CHAT_SAVE causes every single token generated by the LLM to trigger a separate database write operation. In a multi-user environment, this will:

Exhaust Database Connection Pools: Rapid-fire writes will quickly consume all available database connections, leading to "QueuePool limit reached" errors and application-wide freezes.
Severe Performance Impact: The overhead of thousands of database transactions per minute will cause massive latency for all users.
Hardware Strain: It creates immense I/O pressure on your storage system.

Keep this set to False (the default). Chats are still saved automatically once generation is complete. This setting is only intended for extreme debugging scenarios or single-user environments where sub-second persistence of every token is more important than stability.

`ENABLE_CHAT_RESPONSE_BASE64_IMAGE_URL_CONVERSION`

Type: bool
Default: False
Description: When set to true, it automatically uploads base64-encoded images exceeding 1KB in markdown and converts them into image file URLs to reduce the size of response text. Some multimodal models directly output images as Base64 strings within the Markdown content. This results in larger response bodies, placing strain on CPU, network, Redis, and database resources.

`ENABLE_IMAGE_CONTENT_TYPE_EXTENSION_FALLBACK`

Type: bool
Default: False
Description: When enabled, uses a hardcoded extension-to-MIME dictionary as a last-resort fallback when both the system MIME database and the file's stored content type metadata fail to determine the content type of an image. This is primarily useful on minimal container images (e.g., wolfi-base) that lack /etc/mime.types and have legacy files without stored content type metadata. Supported extensions include .webp, .png, .jpg, .jpeg, .gif, .svg, .bmp, .tiff, .ico, .heic, .heif, and .avif.

`ENABLE_PROFILE_IMAGE_URL_FORWARDING`

Type: bool
Default: True
Description: Controls whether the user and model profile-image endpoints honor an external http(s):// URL stored in profile_image_url by issuing a 302 Found redirect to the original origin. When False, the redirect is suppressed and the endpoint falls through to the bundled default image instead. Set to False to prevent client-side IP, User-Agent, and Referer leaks to attacker-controlled origins via attacker-stored profile URLs (data URIs and same-origin/static images continue to load normally). Existing deployments that legitimately rely on external profile image URLs (e.g. Gravatar redirects served by upstream identity providers) should keep the default. This variable is read once at startup — it is not a ConfigVar and cannot be changed from the Admin UI.

`PROFILE_IMAGE_ALLOWED_MIME_TYPES`

Type: str (comma-separated MIME types)
Default: image/png,image/jpeg,image/gif,image/webp
Description: Allowlist of MIME types accepted when serving a base64 data: URI as a profile image. The MIME type is parsed from the data URI prefix and checked against this list before the response is streamed; non-allowlisted types fall through to the bundled default image. Responses also set X-Content-Type-Options: nosniff to prevent the browser from sniffing the body into an executable type. SVG is intentionally not in the default list because it can carry inline {'<script>'} tags. The same allowlist drives the Pydantic data-URI prefix validator, so adding a type here both serves it on the read path and accepts it on the write path. This variable is read once at startup — it is not a ConfigVar and cannot be changed from the Admin UI.

`CHAT_RESPONSE_STREAM_DELTA_CHUNK_SIZE`

Type: int
Default: 1
Description: Sets a system-wide minimum value for the number of tokens to batch together before sending them to the client during a streaming response. This allows an administrator to enforce a baseline level of performance and stability across the entire system by preventing excessively small chunk sizes that can cause high CPU load. The final chunk size used for a response will be the highest value set among this global variable, the model's advanced parameters, or the per-chat settings. The default is 1, which applies no minimum batching at the global level.

`CHAT_RESPONSE_STREAM_UPDATE_INTERVAL_MS`

Type: int (milliseconds)
Default: 50
Description: How often a streaming answer is sent to the browser while the model writes it. Each update carries the whole answer so far, so one update per token cost O(n²) bytes and server CPU for an answer of n tokens: about 6 MB over the socket and 2 seconds of CPU for 1,500 tokens. Updates now go out at most this often and are built only when sent. The first words go out at once, and other events (sources, tool calls, token usage, errors) are never held back behind an update. 0 sends one update per token, as before. CHAT_RESPONSE_STREAM_DELTA_CHUNK_SIZE still applies on top: an update also waits for that many tokens.

`CHAT_STREAM_RESPONSE_CHUNK_MAX_BUFFER_SIZE`

Type: int
Default: Empty string (' '), which disables the limit (equivalent to None)
Description: Sets the maximum buffer size in bytes for handling stream response chunks. When a single chunk exceeds this limit, the system returns an empty JSON object and skips subsequent oversized data until encountering normally-sized chunks. This prevents memory issues when dealing with extremely large responses from certain providers (e.g., models like gemini-2.5-flash-image or services returning extensive web search data exceeding). Set to an empty string or a negative value to disable chunk size limitations entirely. Recommended values are 16-20 MB (16777216) or larger depending on the image size of the image generation model (4K images may need even more).

info

It is recommended to set this to a high single-digit or low double-digit value if you run Hrida.ai with high concurrency, many users, and very fast streaming models.

`CHAT_RESPONSE_MAX_TOOL_CALL_RETRIES`

Type: int
Default: 30
Description: Caps how many sequential tool-calling rounds the agentic loop runs within a single assistant response when Native Function Calling is enabled. Each round in which the model emits tool calls counts as one toward the limit, and the counter resets for every new message. When the cap is reached, the loop stops and the response ends without further tool calls. Read once at startup; it is not a ConfigVar and cannot be changed from the Admin UI. An empty or invalid value falls back to 30.

`ENABLE_RESPONSES_API_STATEFUL`

Type: bool
Default: False
Description: Enables stateful session handling for the Responses API by forwarding previous_response_id to the upstream endpoint. When enabled, Hrida.ai anchors each response to the previous one, allowing the upstream provider to maintain conversation state server-side.

Only enable this if your upstream Responses API endpoint supports stateful sessions (i.e., server-side response storage with previous_response_id anchoring). Most proxies and third-party endpoints are stateless and will break if this is enabled. This is intended for direct connections to providers like OpenAI that natively support the Responses API with session state.

`BYPASS_MODEL_ACCESS_CONTROL`

Type: bool
Default: False
Description: Bypasses model access control. When set to true, all users (and admins alike) will have access to all models, regardless of the model's privacy setting (Private, Public, Shared with certain groups). This is useful for smaller or individual Hrida.ai installations where model access restrictions may not be needed.

`BYPASS_RETRIEVAL_ACCESS_CONTROL`

Type: bool
Default: False
Description: Bypasses access control during RAG retrieval. By default (false), Hrida.ai checks that the requesting user can read a file or knowledge collection before searching its vectors, so a crafted request cannot pull chunks from files or collections the user does not own. This never blocks legitimate retrieval (you can still retrieve anything you already have access to), so the default is right for essentially every deployment and you should not need to change it. Set true only to restore the old permissive behavior (per-file read checks skipped and client-supplied collection references trusted, including legacy knowledge-base collection_names), on a fully trusted single-tenant instance that relied on it.

`ENABLE_RETRIEVAL_UNSCOPED_COLLECTIONS`

Type: bool
Default: False
Description: Controls how RAG retrieval treats a collection name that matches no known collection (not a file-*, user-memory-*, web-search-*, or an existing knowledge base). By default (false), such unknown names are denied for non-admin users, which closes the legacy "unscoped" collection namespace. Set true to let them through as legacy or ephemeral collections, restoring the older behavior. Like BYPASS_RETRIEVAL_ACCESS_CONTROL, the default is the safe choice and you should not need to change it.

`HRIDAAI_BUILD_HASH`

Type: str
Default: dev-build
Description: Used for identifying the Git SHA of the build for releases.

`HRIDAAI_BANNERS`

Type: list of dict
Default: []
Description: List of banners to show to users. The format for banners are:

json

[{"id": "string", "type": "string [info, success, warning, error]", "title": "string", "content": "string", "dismissible": false, "timestamp": 1000}]

Persistence: This environment variable is a ConfigVar variable.

info

When setting this environment variable in a .env file, make sure to escape the quotes by wrapping the entire value in double quotes and using escaped quotes (\") for the inner quotes. Example:

HRIDAAI_BANNERS="[{\"id\": \"1\", \"type\": \"warning\", \"title\": \"Your messages are stored.\", \"content\": \"Your messages are stored and may be reviewed by human people. LLM's are prone to hallucinations, check sources.\", \"dismissible\": true, \"timestamp\": 1000}]"

`USE_CUDA_DOCKER`

Type: bool
Default: False
Description: Builds the Docker image with NVIDIA CUDA support. Enables GPU acceleration for local Whisper and embeddings.

`DOCKER`

Type: bool
Default: False
Description: Indicates whether Hrida.ai is running inside a Docker container. Used internally for environment detection.

`USE_CUDA`

Type: bool
Default: False
Description: Controls whether to use CUDA acceleration for local models. When set to true, attempts to detect and use available NVIDIA GPUs. The code reads the environment variable USE_CUDA_DOCKER to set this internal boolean variable.

`DEVICE_TYPE`

Type: str
Default: cpu
Description: Specifies the device type for model run. Automatically set to cuda if CUDA is available and enabled, or mps for Apple Silicon.

`EXTERNAL_PWA_MANIFEST_URL`

Type: str
Default: Empty string (' '), since None is set as default.
Description: When defined as a fully qualified URL (e.g., https://path/to/manifest.webmanifest), requests sent to /manifest.json will use the external manifest file. When not defined, the default manifest.json file will be used.

`ENABLE_TITLE_GENERATION`

Type: bool
Default: True
Description: Enables or disables chat title generation.
Persistence: This environment variable is a ConfigVar variable.

`LICENSE_KEY`

Type: str
Default: None
Description: Specifies the license key to use (for Enterprise users only).
Persistence: This environment variable is a ConfigVar variable.

`SSL_ASSERT_FINGERPRINT`

Type: str
Default: Empty string (' '), since None is set as default.
Description: Specifies the SSL assert fingerprint to use.
Persistence: This environment variable is a ConfigVar variable.

`ENABLE_COMPRESSION_MIDDLEWARE`

Type: bool
Default: True
Description: Enables gzip compression middleware for HTTP responses, reducing bandwidth usage and improving load times.

`DEFAULT_PROMPT_SUGGESTIONS`

Type: list of dict
Default: [] (which means to use the built-in default prompt suggestions)
Description: Sets global default prompt suggestions shown to users when starting a new chat. These apply when no model-specific prompt suggestions are configured. Prompt suggestions can also be configured per-model via the Model Editor (see Prompt Suggestions), or globally for all models using the Global Model Defaults feature. The format is:

json

[{"title": ["Title part 1", "Title part 2"], "content": "prompt"}]

AIOHTTP Client

`AIOHTTP_CLIENT_TIMEOUT`

Type: int
Default: 300
Description: Specifies the timeout duration in seconds for the AIOHTTP client. This impacts things such as connections to Ollama and OpenAI endpoints.

info

This is the maximum amount of time the client will wait for a response before timing out. If set to an empty string (' '), the timeout will be set to None, effectively disabling the timeout and allowing the client to wait indefinitely.

`AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST`

Type: int
Default: 10
Description: Sets the timeout in seconds for fetching the model list from Ollama and OpenAI endpoints. This affects how long Hrida.ai waits for each configured endpoint when loading available models.

When to Adjust This Value

Lower the timeout (e.g., 3) if:

You have multiple endpoints configured and want faster failover when one is unreachable
You prefer the UI to load quickly even if some slow endpoints are skipped

Increase the timeout (e.g., 30) if:

Your model servers are slow to respond (e.g., cold starts, large model loading)
You're connecting over high-latency networks
You're using providers like OpenRouter that may have variable response times

Database Persistence

Connection URLs configured via the Admin Settings UI are persisted in the database and take precedence over environment variables. If you save an unreachable URL and the UI becomes unresponsive, you may need to use one of these recovery options:

RESET_CONFIG_ON_START=true - Resets database config to environment variable values on next startup
ENABLE_PERSISTENT_CONFIG=false - Always use environment variables (UI changes won't persist)

See the Model List Loading Issues troubleshooting guide for detailed recovery steps.

`AIOHTTP_CLIENT_TIMEOUT_OPENAI_MODEL_LIST`

Type: int
Description: Sets the timeout in seconds for fetching the model list. This can be useful in cases where network latency requires a longer timeout duration to successfully retrieve the model list.

`AIOHTTP_CLIENT_TIMEOUT_TOOL_SERVER`

Type: int
Default: Inherits AIOHTTP_CLIENT_TIMEOUT when unset
Description: Sets the timeout in seconds for executing tool server API calls (OpenAPI/MCP proxy calls made by Hrida.ai). Use this to control how long Hrida.ai waits for actual tool run responses.

info

If this variable is unset or invalid, Hrida.ai falls back to AIOHTTP_CLIENT_TIMEOUT.

`AIOHTTP_CLIENT_SESSION_SSL`

Type: bool
Default: True
Description: Controls SSL/TLS verification for AIOHTTP client sessions when connecting to external APIs (e.g., Ollama Embeddings, and — since v1.0.0 — Speech-to-Text / Text-to-Speech audio endpoints). Set to False to allow self-signed or custom CA certificates on these upstream services.

`AIOHTTP_CLIENT_ALLOW_REDIRECTS`

Type: bool
Default: False
Description: Controls whether outbound HTTP requests across the application follow 3xx redirects. When False (the default since v1.0.0), redirects are not followed — this closes a class of SSRF where a public, validated URL 302-redirects to an internal address (RFC 1918, loopback 127.0.0.1, cloud-metadata 169.254.169.254) that bypasses the original allowlist check. Affected call sites include the RAG web loader, image loading and base64 conversion, OAuth pre-flight, code-interpreter login, and tool-server run. Set to True only if your deployment legitimately requires redirect following (e.g. shortlink-style URLs) AND you have other SSRF protections in place — typically an egress firewall or WEB_FETCH_FILTER_LIST covering your internal ranges.

`USER_AGENT`

Type: str
Default: "" (unset — falls back to the underlying library default, typically python-requests/2.x)
Description: Overrides the User-Agent header that the web loader (SafeWebBaseLoader) sends on outbound fetches for web search and the fetch_url tool. The default Python library UA is aggressively blocked by Cloudflare, Wikipedia, and similar bot-detection layers, which manifests as empty results or 403s when scraping or searching the public web. Set this to a real browser-like UA (e.g. Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0 Safari/537.36) to restore access. Applies to both the synchronous _scrape() and the async _fetch() code paths.

`AIOHTTP_CLIENT_TIMEOUT_TOOL_SERVER_DATA`

Type: int
Default: 10
Description: Sets the timeout in seconds for retrieving tool server metadata/configuration (for example, loading server data/spec information).

`AIOHTTP_CLIENT_SESSION_TOOL_SERVER_SSL`

Type: bool
Default: True
Description: Controls SSL/TLS verification specifically for tool server connections via AIOHTTP client.

`AIOHTTP_POOL_CONNECTIONS`

Type: int
Default: unset (unlimited)
Description: Maximum number of total concurrent connections in the shared AIOHTTP client pool used for outbound requests (Ollama, OpenAI-compatible endpoints, etc.). When unset, there is no total cap. Lower this if you need to bound total upstream concurrency.

`AIOHTTP_POOL_CONNECTIONS_PER_HOST`

Type: int
Default: unset (unlimited)
Description: Maximum number of concurrent connections to any single host in the shared AIOHTTP pool. When unset, there is no per-host cap. Useful for staying under provider-side rate or connection limits.

`AIOHTTP_POOL_DNS_TTL`

Type: int
Default: 300
Description: DNS cache TTL in seconds for the shared AIOHTTP pool. Negative or invalid values fall back to 300. Increase for stable infrastructure; decrease if upstream hosts change IPs frequently.

info

Hrida.ai reuses a single long-lived AIOHTTP client session for outbound HTTP traffic, enabling TCP/TLS connection reuse, a shared DNS cache, and bounded concurrency. The three variables above tune this pool; they do not need to be set in typical deployments.

`REQUESTS_VERIFY`

Type: bool
Default: True
Description: Controls SSL/TLS verification for synchronous requests (e.g., Tika, External Reranker). Set to False to bypass certificate verification for self-signed certificates.

Directories

`DATA_DIR`

Type: str
Default: ./data
Description: Specifies the base directory for data storage, including uploads, cache, vector database, etc.

`FONTS_DIR`

Type: str
Description: Specifies the directory for fonts.

`FRONTEND_BUILD_DIR`

Type: str
Default: ../build
Description: Specifies the location of the built frontend files.

`STATIC_DIR`

Type: str
Default: ./static
Description: Specifies the directory for static files, such as the favicon.

Logging

`GLOBAL_LOG_LEVEL`

Type: str
Default: INFO
Description: Sets the global logging level for all Hrida.ai components. Valid values: DEBUG, INFO, WARNING, ERROR, CRITICAL.

`LOG_FORMAT`

Type: str
Default: Not set (plain-text logging)
Description: Controls the log output format. Set to json to switch all stdout logging to single-line JSON objects, suitable for log aggregators like Loki, Fluentd, CloudWatch, and Datadog. When set to json, the ASCII startup banner is also suppressed to keep the log stream parseable. Any other value (or unset) uses the default plain-text format. See the JSON Logging documentation for details on log fields and examples.

`ENABLE_AUDIT_STDOUT`

Type: bool
Default: False
Description: Controls whether audit logs are output to stdout (console). Useful for containerized environments where logs are collected from stdout.

`ENABLE_AUDIT_LOGS_FILE`

Type: bool
Default: True
Description: Controls whether audit logs are written to a file. When enabled, logs are written to the location specified by AUDIT_LOGS_FILE_PATH.

`AUDIT_LOGS_FILE_PATH`

Type: str
Default: ${DATA_DIR}/audit.log
Description: Configures where the audit log file is stored. Enables storing logs in separate volumes or custom locations for better organization and persistence.
Example: /var/log/hridaai/audit.log, /mnt/logs/audit.log

`AUDIT_LOG_FILE_ROTATION_SIZE`

Type: str
Default: 10MB
Description: Specifies the maximum size of the audit log file before rotation occurs (e.g., 10MB, 100MB, 1GB).

`AUDIT_UVICORN_LOGGER_NAMES`

Type: str
Default: uvicorn.access
Description: Comma-separated list of logger names to capture for audit logging. Defaults to Uvicorn's access logger.

`AUDIT_LOG_LEVEL`

Type: str
Default: NONE
Options: NONE, METADATA, REQUEST, REQUEST_RESPONSE
Description: Controls the verbosity level of audit logging. METADATA logs basic request info, REQUEST includes request bodies, REQUEST_RESPONSE includes both requests and responses.

`MAX_BODY_LOG_SIZE`

Type: int
Default: 2048
Description: Sets the maximum size in bytes for request/response bodies in audit logs. Bodies larger than this are truncated.

`AUDIT_EXCLUDED_PATHS`

Type: str
Default: /chats,/chat,/folders
Description: Comma-separated list of URL paths to exclude from audit logging (blacklist mode). Paths are matched without leading slashes against /api/ and /api/v1/ prefixed routes. Ignored when AUDIT_INCLUDED_PATHS is set.

`AUDIT_INCLUDED_PATHS`

Type: str
Default: Empty string (disabled)
Description: Comma-separated list of URL paths to include in audit logging (whitelist mode). When set, only matching paths are audited and AUDIT_EXCLUDED_PATHS is ignored. Paths are matched without leading slashes against /api/ and /api/v1/ prefixed routes. Auth endpoints (signin, signout, signup) are always logged regardless of filtering mode.

Whitelist vs Blacklist

By default, audit logging uses blacklist mode — all paths are logged except those in AUDIT_EXCLUDED_PATHS. If you set AUDIT_INCLUDED_PATHS, it switches to whitelist mode — only the specified paths are logged. If both are set, whitelist mode takes precedence and a warning is logged at startup.

Ollama

`ENABLE_OLLAMA_API`

Type: bool
Default: True
Description: Enables the use of Ollama APIs.
Persistence: This environment variable is a ConfigVar variable.

`OLLAMA_BASE_URL` (`OLLAMA_API_BASE_URL` is deprecated)

Type: str
Default: http://localhost:11434
Docker Default:
- If K8S_FLAG is set: http://ollama-service.hrida-ai.svc.cluster.local:11434
- If USE_OLLAMA_DOCKER=True: http://localhost:11434
- Else http://host.docker.internal:11434
Description: Configures the Ollama backend URL.

`OLLAMA_BASE_URLS`

Type: str
Description: Configures load-balanced Ollama backend hosts, separated by ;. See OLLAMA_BASE_URL. Takes precedence overOLLAMA_BASE_URL.
Example: http://host-one:11434;http://host-two:11434
Persistence: This environment variable is a ConfigVar variable.

`USE_OLLAMA_DOCKER`

Type: bool
Default: False
Description: Builds the Docker image with a bundled Ollama instance.

`K8S_FLAG`

Type: bool
Default: False
Description: If set, assumes Helm chart deployment and sets OLLAMA_BASE_URL to http://ollama-service.hrida-ai.svc.cluster.local:11434

OpenAI

`ENABLE_OPENAI_API`

Type: bool
Default: True
Description: Enables the use of OpenAI APIs.
Persistence: This environment variable is a ConfigVar variable.

`OPENAI_API_BASE_URL`

Type: str
Default: https://api.openai.com/v1
Description: Configures the OpenAI base API URL.
Persistence: This environment variable is a ConfigVar variable.

`OPENAI_API_BASE_URLS`

Type: str
Description: Supports balanced OpenAI base API URLs, semicolon-separated.
Example: http://host-one:11434;http://host-two:11434
Persistence: This environment variable is a ConfigVar variable.

`OPENAI_API_KEY`

Type: str
Description: Sets the OpenAI API key.
Example: sk-124781258123
Persistence: This environment variable is a ConfigVar variable.

Provider Key Scope (Important)

For OpenAI-compatible backends and proxies (including LiteLLM), configure least-privilege keys for regular user traffic whenever possible.

Do not use provider management/master keys unless your deployment explicitly requires that trust level.

`OPENAI_API_KEYS`

Type: str
Description: Supports multiple OpenAI API keys, semicolon-separated.
Example: sk-124781258123;sk-4389759834759834
Persistence: This environment variable is a ConfigVar variable.

`ENABLE_OPENAI_API_PASSTHROUGH`

Type: bool
Default: False
Description: When enabled, the OpenAI proxy's catch-all endpoint (/{path:path}) forwards any request to the upstream OpenAI-compatible API using the admin-configured API key and without additional access control. When disabled (default), the catch-all returns 403 Forbidden. Other routers (Ollama, Responses) do not have catch-all proxies.

danger

Keep this disabled unless you explicitly need it. The catch-all proxy forwards requests to the upstream API using the admin's API key with no model-level access control. Any authenticated user can reach any upstream endpoint — including endpoints not natively handled by Hrida.ai — using the admin's credentials. Only enable this if you understand and accept these implications.

Tasks

`TASK_MODEL`

Type: str
Description: The default model to use for tasks such as title and web search query generation when using Ollama models.
Persistence: This environment variable is a ConfigVar variable.

`TASK_MODEL_EXTERNAL`

Type: str
Description: The default model to use for tasks such as title and web search query generation when using OpenAI-compatible endpoints.
Persistence: This environment variable is a ConfigVar variable.

`TITLE_GENERATION_PROMPT_TEMPLATE`

Type: str
Description: Prompt to use when generating chat titles.
Default: The value of DEFAULT_TITLE_GENERATION_PROMPT_TEMPLATE environment variable.

DEFAULT_TITLE_GENERATION_PROMPT_TEMPLATE:

### Task:
Generate a concise, 3-5 word title with an emoji summarizing the chat history.

### Guidelines:
- The title should clearly represent the main theme or subject of the conversation.
- Use emojis that enhance understanding of the topic, but avoid quotation marks or special formatting.
- Write the title in the chat's primary language; default to English if multilingual.
- Prioritize accuracy over excessive creativity; keep it clear and simple.

### Output:
JSON format: { "title": "your concise title here" }

### Examples:
- { "title": "📉 Stock Market Trends" },
- { "title": "🍪 Perfect Chocolate Chip Recipe" },
- { "title": "Evolution of Music Streaming" },
- { "title": "Remote Work Productivity Tips" },
- { "title": "Artificial Intelligence in Healthcare" },
- { "title": "🎮 Video Game Development Insights" }

### Chat History:
<chat_history>
{{MESSAGES:END:2}}
</chat_history>

Persistence: This environment variable is a ConfigVar variable.

`ENABLE_FOLLOW_UP_GENERATION`

Type: bool
Default: True
Description: Enables or disables follow up generation.
Persistence: This environment variable is a ConfigVar variable.

`FOLLOW_UP_GENERATION_PROMPT_TEMPLATE`

Type: str
Description: Prompt to use for generating several relevant follow-up questions.
Default: The value of DEFAULT_FOLLOW_UP_GENERATION_PROMPT_TEMPLATE environment variable.

DEFAULT_FOLLOW_UP_GENERATION_PROMPT_TEMPLATE:

### Task:
Suggest 3-5 relevant follow-up questions or prompts that the user might naturally ask next in this conversation as a **user**, based on the chat history, to help continue or deepen the discussion.

### Guidelines:
- Write all follow-up questions from the user’s point of view, directed to the assistant.
- Make questions concise, clear, and directly related to the discussed topic(s).
- Only suggest follow-ups that make sense given the chat content and do not repeat what was already covered.
- If the conversation is very short or not specific, suggest more general (but relevant) follow-ups the user might ask.
- Use the conversation's primary language; default to English if multilingual.
- Response must be a JSON array of strings, no extra text or formatting.

### Output:
JSON format: { "follow_ups": ["Question 1?", "Question 2?", "Question 3?"] }

### Chat History:
<chat_history>
{{MESSAGES:END:6}}
</chat_history>"

Persistence: This environment variable is a ConfigVar variable.

`TOOLS_FUNCTION_CALLING_PROMPT_TEMPLATE`

Type: str
Description: Prompt to use when calling tools.
Default: The value of DEFAULT_TOOLS_FUNCTION_CALLING_PROMPT_TEMPLATE environment variable.

DEFAULT_TOOLS_FUNCTION_CALLING_PROMPT_TEMPLATE:

Available Tools: {{TOOLS}}

Your task is to choose and return the correct tool(s) from the list of available tools based on the query. Follow these guidelines:

- Return only the JSON object, without any additional text or explanation.

- If no tools match the query, return an empty array:
   {
     "tool_calls": []
   }

- If one or more tools match the query, construct a JSON response containing a "tool_calls" array with objects that include:
   - "name": The tool's name.
   - "parameters": A dictionary of required parameters and their corresponding values.

The format for the JSON response is strictly:
{
  "tool_calls": [
    {"name": "toolName1", "parameters": {"key1": "value1"}},
    {"name": "toolName2", "parameters": {"key2": "value2"}}
  ]
}

Persistence: This environment variable is a ConfigVar variable.

Code Run

`ENABLE_CODE_EXECUTION`

Type: bool
Default: True
Description: Enables or disables code run.
Persistence: This environment variable is a ConfigVar variable.

`CODE_EXECUTION_ENGINE`

Type: str
Default: pyodide
Description: Specifies the code run engine to use.
Persistence: This environment variable is a ConfigVar variable.

`CODE_EXECUTION_JUPYTER_URL`

Type: str
Default: None
Description: Specifies the Jupyter URL to use for code run.
Persistence: This environment variable is a ConfigVar variable.

`CODE_EXECUTION_JUPYTER_AUTH`

Type: str
Default: None
Description: Specifies the Jupyter authentication method to use for code run.
Persistence: This environment variable is a ConfigVar variable.

`CODE_EXECUTION_JUPYTER_AUTH_TOKEN`

Type: str
Default: None
Description: Specifies the Jupyter authentication token to use for code run.
Persistence: This environment variable is a ConfigVar variable.

`CODE_EXECUTION_JUPYTER_AUTH_PASSWORD`

Type: str
Default: None
Description: Specifies the Jupyter authentication password to use for code run.
Persistence: This environment variable is a ConfigVar variable.

`CODE_EXECUTION_JUPYTER_TIMEOUT`

Type: str
Default: Empty string (' '), since None is set as default.
Description: Specifies the timeout for Jupyter code run.
Persistence: This environment variable is a ConfigVar variable.

Code Interpreter

`ENABLE_CODE_INTERPRETER`

Type: bool
Default: True
Description: Enables or disables code interpreter.
Persistence: This environment variable is a ConfigVar variable.

`CODE_INTERPRETER_ENGINE`

Type: str
Default: pyodide
Description: Specifies the code interpreter engine to use.
Persistence: This environment variable is a ConfigVar variable.

`CODE_INTERPRETER_PROMPT_TEMPLATE`

Type: str
Default: None
Description: Specifies the prompt template to use for code interpreter.
Persistence: This environment variable is a ConfigVar variable.

`CODE_INTERPRETER_JUPYTER_URL`

Type: str
Default: Empty string (' '), since None is set as default.
Description: Specifies the Jupyter URL to use for code interpreter.
Persistence: This environment variable is a ConfigVar variable.

`CODE_INTERPRETER_JUPYTER_AUTH`

Type: str
Default: Empty string (' '), since None is set as default.
Description: Specifies the Jupyter authentication method to use for code interpreter.
Persistence: This environment variable is a ConfigVar variable.

`CODE_INTERPRETER_JUPYTER_AUTH_TOKEN`

Type: str
Default: Empty string (' '), since None is set as default.
Description: Specifies the Jupyter authentication token to use for code interpreter.
Persistence: This environment variable is a ConfigVar variable.

`CODE_INTERPRETER_JUPYTER_AUTH_PASSWORD`

Type: str
Default: Empty string (' '), since None is set as default.
Description: Specifies the Jupyter authentication password to use for code interpreter.
Persistence: This environment variable is a ConfigVar variable.

`CODE_INTERPRETER_JUPYTER_TIMEOUT`

Type: str
Default: Empty string (' '), since None is set as default.
Description: Specifies the timeout for the Jupyter code interpreter.
Persistence: This environment variable is a ConfigVar variable.

Direct Connections (OpenAPI/MCPO Tool Servers)

`ENABLE_DIRECT_CONNECTIONS`

Type: bool
Default: True
Description: Enables or disables direct connections.
Persistence: This environment variable is a ConfigVar variable.

`TOOL_SERVER_CONNECTIONS`

Type: str (JSON array)
Default: []
Description: Specifies a JSON array of tool server connection configurations. Each connection should define the necessary parameters to connect to external tool servers that implement the OpenAPI/MCPO protocol. For mcpo-backed routes, path should point at the mounted tool route. The JSON must be properly formatted or it will fallback to an empty array.
Field reference:
- url: the server base URL.
- path: the specific tool route exposed by the server.
- auth_type: the authentication mode for the connection.
- key: the API key or token used by the selected auth mode.
- config: per-connection configuration object, such as { "enable": true }.
- info: optional metadata shown in the UI, such as the connection name and description.
- spec_type / spec: OpenAPI spec location details when the connection is backed by a spec URL or file.
Entries in this array are also created automatically — not only via the Admin "Add Tool Server" modal — whenever an API Builder API definition is published; see Tool Server Publishing.
Example:

json

[
  {
    "type": "openapi",
    "url": "example-url",
    "spec_type": "url",
    "spec": "",
    "path": "openapi.json",
    "auth_type": "none",
    "key": "",
    "config": { "enable": true },
    "info": {
      "id": "",
      "name": "example-server",
      "description": "MCP server description."
    }
  }
]

Persistence: This environment variable is a ConfigVar variable.

warning

The JSON data structure of TOOL_SERVER_CONNECTIONS might evolve over time as new features are added.

Terminal Server

`TERMINAL_SERVER_CONNECTIONS`

Type: str (JSON array)
Default: []
Description: Specifies a JSON array of terminal server connection configurations. Each connection defines the parameters needed to connect to an Hrida Terminal instance. Unlike user-level tool server connections, these are admin-configured and proxied through Hrida.ai, which means the terminal URL and API key are never exposed to the browser. Supports group-based access control via access_grants.
Example (direct Hrida Terminal connection):

json

[
  {
    "id": "unique-id",
    "url": "http://hrida-terminal:8000",
    "key": "your-api-key",
    "name": "Dev Terminal",
    "auth_type": "bearer",
    "config": {
      "access_grants": []
    }
  }
]

Persistence: This environment variable is a ConfigVar variable.

warning

The JSON data structure of TERMINAL_SERVER_CONNECTIONS might evolve over time as new features are added.

`TERMINAL_PROXY_HEADERS`

Type: str (JSON object)
Default: {}
Description: Custom HTTP response headers to inject into responses returned by the terminal proxy. The terminal proxy strips a fixed set of hop-by-hop and security-sensitive headers from the upstream response; entries in this object are merged in afterward and take precedence on conflicts, so admins can set deployment-specific headers on proxied terminal content without touching the application. Invalid JSON falls back to {} with no headers added.

Security note. The default of {} means the proxy forwards upstream content (HTML, JS, anything) verbatim under the Hrida.ai same origin. This is intentional — many legitimate hrida-terminal use cases (dev servers, internal tooling, web UIs the admin runs through the terminal) depend on JavaScript executing in the proxy response. For multi-user deployments where mutually-trusted users share a single terminal-server connection, this is fine. For deployments where users in the same trust group should be additionally isolated from each other's proxied content (or where the terminal-server feature is exposed to less-trusted users on top of the documented multi-user setup tiers), set this to a sandbox CSP that locks proxied JS into an opaque origin while still allowing it to run for legitimate workflows:
bash
```
TERMINAL_PROXY_HEADERS='{"Content-Security-Policy": "sandbox allow-scripts; default-src '\''none'\''; img-src '\''self'\'' data:; style-src '\''unsafe-inline'\''", "X-Content-Type-Options": "nosniff", "Referrer-Policy": "no-referrer", "X-Frame-Options": "DENY"}'
```
Note: do not add allow-same-origin to the sandbox directive. That keyword nullifies the origin-isolation that makes the sandbox effective against localStorage exfiltration. The example above intentionally omits it.

Autocomplete

`ENABLE_AUTOCOMPLETE_GENERATION`

Type: bool
Default: True
Description: Enables or disables autocomplete generation.
Persistence: This environment variable is a ConfigVar variable.

info

When enabling ENABLE_AUTOCOMPLETE_GENERATION, ensure that you also configure AUTOCOMPLETE_GENERATION_INPUT_MAX_LENGTH and AUTOCOMPLETE_GENERATION_PROMPT_TEMPLATE accordingly.

`AUTOCOMPLETE_GENERATION_INPUT_MAX_LENGTH`

Type: int
Default: -1
Description: Sets the maximum input length for autocomplete generation.
Persistence: This environment variable is a ConfigVar variable.

`AUTOCOMPLETE_GENERATION_PROMPT_TEMPLATE`

Type: str
Default: The value of the DEFAULT_AUTOCOMPLETE_GENERATION_PROMPT_TEMPLATE environment variable.

DEFAULT_AUTOCOMPLETE_GENERATION_PROMPT_TEMPLATE:

### Task:
You are an autocompletion system. Continue the text in `<text>` based on the **completion type** in `<type>` and the given language.

### **Instructions**:
1. Analyze `<text>` for context and meaning.
2. Use `<type>` to guide your output:
   - **General**: Provide a natural, concise continuation.
   - **Search Query**: Complete as if generating a realistic search query.
3. Start as if you are directly continuing `<text>`. Do **not** repeat, paraphrase, or respond as a model. Simply complete the text.
4. Ensure the continuation:
   - Flows naturally from `<text>`.
   - Avoids repetition, overexplaining, or unrelated ideas.
5. If unsure, return: `{ "text": "" }`.

### **Output Rules**:
- Respond only in JSON format: `{ "text": "<your_completion>" }`.

### **Examples**:

#### Example 1:
Input:
<type>General</type>
<text>The sun was setting over the horizon, painting the sky</text>
Output:
{ "text": "with vibrant shades of orange and pink." }

#### Example 2:
Input:
<type>Search Query</type>
<text>Top-rated restaurants in</text>
Output:
{ "text": "New York City for Italian cuisine." }

---

### Context:
<chat_history>
{{MESSAGES:END:6}}
</chat_history>
<type>{{TYPE}}</type>
<text>{{PROMPT}}</text>

#### Output:

Description: Sets the prompt template for autocomplete generation.
Persistence: This environment variable is a ConfigVar variable.

Evaluation Arena Model

`ENABLE_EVALUATION_ARENA_MODELS`

Type: bool
Default: True
Description: Enables or disables evaluation arena models.
Persistence: This environment variable is a ConfigVar variable.

`ENABLE_MESSAGE_RATING`

Type: bool
Default: True
Description: Enables message rating feature.
Persistence: This environment variable is a ConfigVar variable.

`ENABLE_COMMUNITY_SHARING`

Type: bool
Default: True
Description: Controls whether users can share content with the Zlabs Innovation and access resources. When enabled, this setting shows the following UI elements across the application:
- Prompts Workspace: "Made by Zlabs Innovation" section with a link to discover prompts, and a "Share" button in the prompt menu dropdown
- Tools Workspace: "Made by Zlabs Innovation" section with a link to discover tools, and a "Share" button in the tool menu dropdown
- Models Workspace: "Made by Zlabs Innovation" section with a link to discover community model presets, and a "Share" button in the model menu dropdown
- Functions Admin: "Made by Zlabs Innovation" section with a link to discover functions
- Share Chat Modal: "Share to Zlabs Innovation" button when sharing a chat conversation
- Evaluation Feedbacks: "Share to Zlabs Innovation" button for contributing feedback history to users leaderboard
- Stats Sync Modal: Enables syncing usage statistics with users
Persistence: This environment variable is a ConfigVar variable.

info

When ENABLE_COMMUNITY_SHARING is set to False, all community sharing buttons and community resource discovery sections will be hidden from the UI. Users will still be able to export content locally, but the option to share directly to the Zlabs Innovation will not be available.

Tags Generation

`ENABLE_TAGS_GENERATION`

Type: bool
Default: True
Description: Enables or disables tag generation.
Persistence: This environment variable is a ConfigVar variable.

`TAGS_GENERATION_PROMPT_TEMPLATE`

Type: str
Default: The value of DEFAULT_TAGS_GENERATION_PROMPT_TEMPLATE environment variable.

DEFAULT_TAGS_GENERATION_PROMPT_TEMPLATE:

### Task:
Generate 1-3 broad tags categorizing the main themes of the chat history, along with 1-3 more specific subtopic tags.

### Guidelines:
- Start with high-level domains (e.g., Science, Technology, Philosophy, Arts, Politics, Business, Health, Sports, Entertainment, Education)
- Consider including relevant subfields/subdomains if they are strongly represented throughout the conversation
- If content is too short (less than 3 messages) or too diverse, use only ["General"]
- Use the chat's primary language; default to English if multilingual
- Prioritize accuracy over specificity

### Output:
JSON format: { "tags": ["tag1", "tag2", "tag3"] }

### Chat History:
<chat_history>
{{MESSAGES:END:6}}
</chat_history>

Description: Sets the prompt template for tag generation.
Persistence: This environment variable is a ConfigVar variable.

API Key Endpoint Restrictions

`ENABLE_API_KEYS`

Type: bool
Default: False
Description: Enables the API key creation feature, allowing users to generate API keys for programmatic access to Hrida.ai.
Persistence: This environment variable is a ConfigVar variable.

info

This variable replaces the deprecated ENABLE_API_KEY environment variable.

info

For API Key creation (and the API keys themselves) to work:

Enable API keys globally using this setting (ENABLE_API_KEYS)
For non-admin users, grant the "API Keys" permission via Default Permissions or User Groups

Note: Administrators can generate API keys whenever ENABLE_API_KEYS is enabled, even without features.api_keys.

`ENABLE_API_KEYS_ENDPOINT_RESTRICTIONS`

Type: bool
Default: False
Description: Enables API key endpoint restrictions for added security and configurability, allowing administrators to limit which endpoints can be accessed using API keys.
Persistence: This environment variable is a ConfigVar variable.

info

This variable replaces the deprecated ENABLE_API_KEY_ENDPOINT_RESTRICTIONS environment variable.

`API_KEYS_ALLOWED_ENDPOINTS`

Type: str
Description: Specifies a comma-separated list of allowed API endpoints when API key endpoint restrictions are enabled.
Example: /api/v1/messages,/api/v1/channels,/api/v1/chat/completions
Persistence: This environment variable is a ConfigVar variable.

note

The value of API_KEYS_ALLOWED_ENDPOINTS should be a comma-separated list of endpoint URLs, such as /api/v1/messages, /api/v1/channels.

info

This variable replaces the deprecated API_KEY_ALLOWED_ENDPOINTS environment variable.

`CUSTOM_API_KEY_HEADER`

Type: str
Default: x-api-key
Description: Name of the HTTP header the auth middleware checks for API-key credentials. Useful when Hrida.ai sits behind a reverse proxy or API gateway that consumes the Authorization header for its own authentication — set this to a distinct header (for example X-Hrida.ai-Key) so clients can deliver their Hrida.ai API key without colliding with the proxy's own auth.
Read at startup from the process environment (not a ConfigVar).

How the auth middleware picks up a credential, in order:

Authorization: Bearer {'<token>'} (most common — API key or JWT)
token cookie (Bearer — used by the Hrida.ai itself)
The header named by CUSTOM_API_KEY_HEADER (default x-api-key)

If none of the three is present, the request falls through as anonymous.

Behind a proxy that eats Authorization?

Many corporate gateways (basic auth, mutual TLS adapters, SSO sidecars) consume the Authorization header and never forward it upstream. In that case, point your clients at the custom header instead:

bash

curl -H "X-Hrida.ai-Key: sk-..." http://hridaai.internal/api/models

And set on the Hrida.ai container:

CUSTOM_API_KEY_HEADER=X-Hrida.ai-Key

The header name is matched case-insensitively by the ASGI layer, so pick whatever fits your naming convention.

Model Caching

`ENABLE_BASE_MODELS_CACHE`

Type: bool
Default: False
Description: When enabled, caches the list of base models from connected Ollama and OpenAI-compatible endpoints in memory. This reduces the number of API calls made to external model providers when loading the model selector, improving performance particularly for deployments with many users or slow connections to model endpoints. Can also be configured from Admin Panel > Settings > Connections > "Cache Base Model List".
Persistence: This environment variable is a ConfigVar variable.

How the cache works:

Initialization: When enabled, base models are fetched and cached during application startup.
Storage: The cache is stored in application memory (app.state.BASE_MODELS).
Cache Hit: Subsequent requests for models return the cached list without contacting external endpoints.
Cache Refresh: The cache is refreshed when:
- The application restarts
- The connection settings are saved in the Admin Panel > Settings > Connections (clicking the Save button on the bottom right will trigger a refresh and update the cache with the newly fetched models)
No TTL: There is no automatic time-based expiration.

Performance Consideration

Enable this setting in production environments where model lists are relatively stable. For development environments or when frequently adding/removing models from Ollama, you may prefer to leave it disabled for real-time model discovery.

`MODELS_CACHE_TTL`

Type: int
Default: 1
Description: How long, in seconds, a user's model list from the OpenAI-compatible and Ollama connections and pipe functions counts as fresh. An older list is still returned at once, for up to five minutes, while one background request asks the providers again, so page loads don't wait for the providers once a user's list has been fetched. Saving the connection settings, or changing a model or a function, drops the lists on every server, so the next load fetches a fresh one. 0 keeps no list: every page load waits for the providers. An empty value keeps a list until such a change.

This caches the external model lists retrieved from configured OpenAI-compatible and Ollama API endpoints. Hrida.ai's own model settings (workspace models, functions and their valves) are kept per server too, and reloaded the moment one of them changes. A model added on a provider shows up on the second page load after the TTL: the first one starts the refresh.

High-Traffic Recommendation

In high-traffic scenarios, increasing this value (e.g., to 300 seconds) reduces the background requests to the providers. Page loads don't wait either way.

Two Caching Mechanisms

Hrida.ai has two model caching mechanisms that work independently:

Setting	Type	Default	Refresh Trigger
`ENABLE_BASE_MODELS_CACHE`	In-memory	`False`	App restart OR Admin Save
`MODELS_CACHE_TTL`	Per user, refreshed in the background	`1` second	In the background after the TTL; at once on a connection, model or function change

With the background refresh, page loads use a user's last list while it's refreshed. ENABLE_BASE_MODELS_CACHE=True additionally shares one list across all users and stops the background requests.

`JWT_EXPIRES_IN`

Type: str
Default: 4w
Description: Sets the JWT expiration time in seconds. Valid time units: s, m, h, d, w or -1 for no expiration.
Persistence: This environment variable is a ConfigVar variable.

warning

Setting JWT_EXPIRES_IN to -1 disables JWT expiration, making issued tokens valid forever. This is extremely dangerous in production and exposes your system to severe security risks if tokens are leaked or compromised.

Always set a reasonable expiration time in production environments (e.g., 3600s, 1h, 7d etc.) to limit the lifespan of authentication tokens.

NEVER use -1 in a production environment.

If you have already deployed with JWT_EXPIRES_IN=-1, you can rotate or change your HRIDAAI_SECRET_KEY to immediately invalidate all existing tokens.

Public Tutor (landing page)

The anonymous HRIDA TUTOR chat widget on the landing page. See Public Tutor.

`ENABLE_PUBLIC_TUTOR`

Type: bool
Default: True
Description: Shows the HRIDA TUTOR widget on the landing page and lets it answer visitors' questions.
Persistence: This environment variable is a ConfigVar variable.

`PUBLIC_TUTOR_MODEL_ID`

Type: str
Default: hrida-tutor
Description: The model that answers visitors' questions.
Persistence: This environment variable is a ConfigVar variable.

`PUBLIC_TUTOR_API_KEY`

Type: str
Default: empty
Description: The API key of the account the tutor answers as. It only identifies the account: the tutor works whether or not ENABLE_API_KEYS is on.
Persistence: This environment variable is a ConfigVar variable.

`HRIDAAI_INTERNAL_URL`

Type: str
Default: empty
Description: Leave it empty and the tutor asks the model inside the Studio process. Set it (for example http://localhost:8080) to make the tutor call Studio over HTTP at that address instead.

General​

HRIDAAI_URL​

ENABLE_SIGNUP​

ENABLE_SIGNUP_PASSWORD_CONFIRMATION​

HRIDAAI_ADMIN_EMAIL​

HRIDAAI_ADMIN_PASSWORD​

HRIDAAI_ADMIN_NAME​

ENABLE_LOGIN_FORM​

ENABLE_PASSWORD_CHANGE_FORM​

ENABLE_PASSWORD_AUTH​

DEFAULT_LOCALE​

DEFAULT_MODELS​

DEFAULT_PINNED_MODELS​

DEFAULT_MODEL_METADATA​

DEFAULT_MODEL_PARAMS​

DEFAULT_USER_ROLE​

DEFAULT_GROUP_ID​

DEFAULT_GROUP_SHARE_PERMISSION​

PENDING_USER_OVERLAY_TITLE​

PENDING_USER_OVERLAY_CONTENT​

ENABLE_CALENDAR​

ENABLE_ARTIFACTS​

ENABLE_ARTIFACT_SKILLS​

ARTIFACT_SKILLS_MODELS​

ARTIFACT_SKILLS_MAX_TURNS​

ARTIFACT_SKILLS_MAX_JOBS_PER_USER​

OFFICE_SKILLS_DIR​

API_GATEWAY_CALL_LOG_RETENTION_DAYS​

API_ANALYTICS_HOURLY_RETENTION_DAYS​

API_ANALYTICS_DAILY_RETENTION_DAYS​

API_GATEWAY_CALL_ARCHIVE_ENABLED​

API_GATEWAY_CALL_ARCHIVE_RETENTION_DAYS​

API_GATEWAY_CALL_LOG_JOBS_HOUR_UTC​

API_GATEWAY_CALL_ARCHIVE_DIR​

API_BUILDER_SELF_URL​

API_GATEWAY_CACHE_SECONDS​

API_GATEWAY_POOL_CONNECTIONS​

API_GATEWAY_POOL_CONNECTIONS_PER_HOST​

API_GATEWAY_DNS_CACHE_SECONDS​

API_GATEWAY_KEEPALIVE_SECONDS​

API_GATEWAY_MAX_CONCURRENT_CALLS​

API_GATEWAY_MAX_IN_FLIGHT​

API_GATEWAY_QUEUE_TIMEOUT_MS​

API_GATEWAY_RETRY_BUDGET_RATIO​

API_GATEWAY_STREAM_THRESHOLD_BYTES​

API_GATEWAY_AUTH_FAILURES_PER_MINUTE​

API_GATEWAY_CLIENT_CERT_HEADER​

API_GATEWAY_BREAKER_SYNC_SECONDS​

API_GATEWAY_JWKS_CACHE_SECONDS​

SAFE_EVAL_MAX_STEPS​

SMTP_HOST​

SMTP_PORT​

SMTP_USER​

SMTP_PASSWORD​

SMTP_FROM​

ENABLE_CHANNELS​

ENABLE_FOLDERS​

FOLDER_MAX_FILE_COUNT​

ENABLE_AUTOMATIONS​

AUTOMATION_MAX_COUNT​

AUTOMATION_MIN_INTERVAL​

SCHEDULER_POLL_INTERVAL​

CALENDAR_ALERT_LOOKAHEAD_MINUTES​

ENABLE_NOTES​

ENABLE_MEMORIES​

WEBHOOK_URL​

ENABLE_ADMIN_EXPORT​

ENABLE_ADMIN_CHAT_ACCESS​

ENABLE_ADMIN_ANALYTICS​

BYPASS_ADMIN_ACCESS_CONTROL​

ENABLE_USER_WEBHOOKS​

RESPONSE_WATERMARK​

IFRAME_CSP​

THREAD_POOL_SIZE​

ENABLE_CUSTOM_MODEL_FALLBACK​

SHOW_ADMIN_DETAILS​

ENABLE_PUBLIC_ACTIVE_USERS_COUNT​

ENABLE_USER_STATUS​

ENABLE_EASTER_EGGS​

ADMIN_EMAIL​

General

`HRIDAAI_URL`

`ENABLE_SIGNUP`

`ENABLE_SIGNUP_PASSWORD_CONFIRMATION`

`HRIDAAI_ADMIN_EMAIL`

`HRIDAAI_ADMIN_PASSWORD`

`HRIDAAI_ADMIN_NAME`

`ENABLE_LOGIN_FORM`

`ENABLE_PASSWORD_CHANGE_FORM`

`ENABLE_PASSWORD_AUTH`

`DEFAULT_LOCALE`

`DEFAULT_MODELS`

`DEFAULT_PINNED_MODELS`

`DEFAULT_MODEL_METADATA`

`DEFAULT_MODEL_PARAMS`

`DEFAULT_USER_ROLE`

`DEFAULT_GROUP_ID`

`DEFAULT_GROUP_SHARE_PERMISSION`

`PENDING_USER_OVERLAY_TITLE`

`PENDING_USER_OVERLAY_CONTENT`

`ENABLE_CALENDAR`

`ENABLE_ARTIFACTS`

`ENABLE_ARTIFACT_SKILLS`

`ARTIFACT_SKILLS_MODELS`

`ARTIFACT_SKILLS_MAX_TURNS`

`ARTIFACT_SKILLS_MAX_JOBS_PER_USER`

`OFFICE_SKILLS_DIR`

`API_GATEWAY_CALL_LOG_RETENTION_DAYS`

`API_ANALYTICS_HOURLY_RETENTION_DAYS`

`API_ANALYTICS_DAILY_RETENTION_DAYS`

`API_GATEWAY_CALL_ARCHIVE_ENABLED`

`API_GATEWAY_CALL_ARCHIVE_RETENTION_DAYS`

`API_GATEWAY_CALL_LOG_JOBS_HOUR_UTC`

`API_GATEWAY_CALL_ARCHIVE_DIR`

`API_BUILDER_SELF_URL`

`API_GATEWAY_CACHE_SECONDS`

`API_GATEWAY_POOL_CONNECTIONS`

`API_GATEWAY_POOL_CONNECTIONS_PER_HOST`

`API_GATEWAY_DNS_CACHE_SECONDS`

`API_GATEWAY_KEEPALIVE_SECONDS`

`API_GATEWAY_MAX_CONCURRENT_CALLS`

`API_GATEWAY_MAX_IN_FLIGHT`

`API_GATEWAY_QUEUE_TIMEOUT_MS`

`API_GATEWAY_RETRY_BUDGET_RATIO`

`API_GATEWAY_STREAM_THRESHOLD_BYTES`

`API_GATEWAY_AUTH_FAILURES_PER_MINUTE`

`API_GATEWAY_CLIENT_CERT_HEADER`

`API_GATEWAY_BREAKER_SYNC_SECONDS`

`API_GATEWAY_JWKS_CACHE_SECONDS`

`SAFE_EVAL_MAX_STEPS`

`SMTP_HOST`

`SMTP_PORT`

`SMTP_USER`

`SMTP_PASSWORD`

`SMTP_FROM`

`ENABLE_CHANNELS`

`ENABLE_FOLDERS`

`FOLDER_MAX_FILE_COUNT`

`ENABLE_AUTOMATIONS`

`AUTOMATION_MAX_COUNT`

`AUTOMATION_MIN_INTERVAL`

`SCHEDULER_POLL_INTERVAL`

`CALENDAR_ALERT_LOOKAHEAD_MINUTES`

`ENABLE_NOTES`

`ENABLE_MEMORIES`

`WEBHOOK_URL`

`ENABLE_ADMIN_EXPORT`

`ENABLE_ADMIN_CHAT_ACCESS`

`ENABLE_ADMIN_ANALYTICS`

`BYPASS_ADMIN_ACCESS_CONTROL`

`ENABLE_USER_WEBHOOKS`

`RESPONSE_WATERMARK`

`IFRAME_CSP`

`THREAD_POOL_SIZE`

`ENABLE_CUSTOM_MODEL_FALLBACK`

`SHOW_ADMIN_DETAILS`

`ENABLE_PUBLIC_ACTIVE_USERS_COUNT`

`ENABLE_USER_STATUS`

`ENABLE_EASTER_EGGS`

`ADMIN_EMAIL`