Skip to main content

Security

Secret keys, JWT and session lifetimes, cookies, CORS, API keys and other settings that harden a Hrida.ai deployment.

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.

ENABLE_FORWARD_USER_INFO_HEADERS​

  • type: bool
  • Default: False
  • Description: Forwards user and session information as HTTP headers to OpenAI API, Ollama API, MCP servers, and Tool servers. If enabled, the following headers are forwarded:
    • X-Hrida.ai-User-Name
    • X-Hrida.ai-User-Id
    • X-Hrida.ai-User-Email
    • X-Hrida.ai-User-Role
    • X-Hrida.ai-Chat-Id
    • X-Hrida.ai-Message-Id

This enables per-user authorization, auditing, rate limiting, and request tracing on external services. The chat and message ID headers are also required for external tool event emitting.

FORWARD_USER_INFO_HEADER_USER_NAME​

  • Type: str
  • Default: X-Hrida.ai-User-Name
  • Description: Customizes the header name used to forward the user's display name. Change this if your infrastructure requires a specific header prefix.

FORWARD_USER_INFO_HEADER_USER_ID​

  • Type: str
  • Default: X-Hrida.ai-User-Id
  • Description: Customizes the header name used to forward the user's ID.

FORWARD_USER_INFO_HEADER_USER_EMAIL​

  • Type: str
  • Default: X-Hrida.ai-User-Email
  • Description: Customizes the header name used to forward the user's email address.

FORWARD_USER_INFO_HEADER_USER_ROLE​

  • Type: str
  • Default: X-Hrida.ai-User-Role
  • Description: Customizes the header name used to forward the user's role.

FORWARD_SESSION_INFO_HEADER_CHAT_ID​

  • Type: str
  • Default: X-Hrida.ai-Chat-Id
  • Description: Customizes the header name used to forward the current chat/session ID.

FORWARD_SESSION_INFO_HEADER_MESSAGE_ID​

  • Type: str
  • Default: X-Hrida.ai-Message-Id
  • Description: Customizes the header name used to forward the current message ID. This header is required for external tool event emitting.
Custom Header Prefix

Use these variables when integrating with services that require specific header naming conventions. For example, AWS Bedrock AgentCore requires headers prefixed with X-Amzn-Bedrock-AgentCore-Runtime-Custom-:

bash
FORWARD_USER_INFO_HEADER_USER_NAME=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Name
FORWARD_USER_INFO_HEADER_USER_ID=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Id
FORWARD_USER_INFO_HEADER_USER_EMAIL=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Email
FORWARD_USER_INFO_HEADER_USER_ROLE=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Role
FORWARD_SESSION_INFO_HEADER_CHAT_ID=X-Amzn-Bedrock-AgentCore-Runtime-Custom-Chat-Id
FORWARD_SESSION_INFO_HEADER_MESSAGE_ID=X-Amzn-Bedrock-AgentCore-Runtime-Custom-Message-Id

ENABLE_WEB_LOADER_SSL_VERIFICATION​

  • Type: bool
  • Default: True
  • Description: Bypass SSL Verification for RAG on Websites.
  • Persistence: This environment variable is a ConfigVar variable.
  • Type: str
  • Options:
    • lax - Sets the SameSite attribute to lax, allowing session cookies to be sent with requests initiated by third-party websites.
    • strict - Sets the SameSite attribute to strict, blocking session cookies from being sent with requests initiated by third-party websites.
    • none - Sets the SameSite attribute to none, allowing session cookies to be sent with requests initiated by third-party websites, but only over HTTPS.
  • Default: lax
  • Description: Sets the SameSite attribute for session cookies.
warning

When ENABLE_OAUTH_SIGNUP is enabled, setting HRIDAAI_SESSION_COOKIE_SAME_SITE to strict can cause login failures. This is because Hrida.ai uses a session cookie to validate the callback from the OAuth provider, which helps prevent CSRF attacks.

However, a strict session cookie is not sent with the callback request, leading to potential login issues. If you experience this problem, use the default lax value instead.

  • Type: bool
  • Default: False
  • Description: Sets the Secure attribute for session cookies if set to True.
  • Type: str
  • Options:
    • lax - Sets the SameSite attribute to lax, allowing auth cookies to be sent with requests initiated by third-party websites.
    • strict - Sets the SameSite attribute to strict, blocking auth cookies from being sent with requests initiated by third-party websites.
    • none - Sets the SameSite attribute to none, allowing auth cookies to be sent with requests initiated by third-party websites, but only over HTTPS.
  • Default: lax
  • Description: Sets the SameSite attribute for auth cookies.
info

If the value is not set, HRIDAAI_SESSION_COOKIE_SAME_SITE will be used as a fallback.

  • Type: bool
  • Default: False
  • Description: Sets the Secure attribute for auth cookies if set to True.
info

If the value is not set, HRIDAAI_SESSION_COOKIE_SECURE will be used as a fallback.

HRIDAAI_AUTH​

  • Type: bool
  • Default: True
  • Description: This setting enables or disables authentication.
danger

If set to False, authentication will be disabled for your Hrida.ai instance. However, it's important to note that turning off authentication is only possible for fresh installations without any existing users. If there are already users registered, you cannot disable authentication directly. Ensure that no users are present in the database if you intend to turn off HRIDAAI_AUTH.

ENABLE_PASSWORD_VALIDATION​

  • Type: bool
  • Default: False
  • Description: Enables password complexity validation for user accounts. When enabled, passwords must meet the complexity requirements defined by PASSWORD_VALIDATION_REGEX_PATTERN during signup, password updates, and user creation operations. This helps enforce stronger password policies across the application.
info

Password validation is applied to:

  • New user registration (signup)
  • Password changes through user settings
  • Admin-initiated user creation
  • Password resets

Existing users with passwords that don't meet the new requirements are not automatically forced to update their passwords, but will need to meet the requirements when they next change their password.

PASSWORD_VALIDATION_REGEX_PATTERN​

  • Type: str
  • Default: ^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[^\w\s]).{8,}$
  • Description: Regular expression pattern used to validate password complexity when ENABLE_PASSWORD_VALIDATION is enabled. The default pattern requires passwords to be at least 8 characters long and contain at least one uppercase letter, one lowercase letter, one digit, and one special character.
warning

Custom Pattern Considerations

When defining a custom regex pattern, ensure it:

  • Is a valid regular expression that Python's re module can compile
  • Balances security requirements with user experience
  • Is thoroughly tested before deployment to avoid locking users out

Invalid regex patterns will cause password validation to fail, potentially preventing user registration and password changes.

PASSWORD_VALIDATION_HINT​

  • Type: str
  • Default: "" (empty string)
  • Description: Custom hint message displayed to users when their password fails validation. This message appears in error dialogs during signup, password changes, and admin user creation when the password doesn't meet the requirements defined by PASSWORD_VALIDATION_REGEX_PATTERN. Use this to explain your specific password requirements in user-friendly terms.
  • Example: Password must be at least 12 characters with uppercase, lowercase, number, and special character.
tip

When setting a custom PASSWORD_VALIDATION_REGEX_PATTERN, always set PASSWORD_VALIDATION_HINT to explain the requirements in plain language. Without a hint, users will only see a generic "Invalid password" error with no guidance on what's required.

PASSWORD_HASH_CONCURRENCY​

  • Type: int
  • Default: 4
  • Description: How many password hashes or checks (bcrypt, 100-250 ms of CPU each) each Studio process runs at the same time, in worker threads. More wait their turn, so a burst of sign-ins, or someone hammering the sign-in form with made-up emails, can't take the CPU from the requests being served. Raise it on machines with many cores if sign-ins queue at peak times.

HRIDAAI_SECRET_KEY​

  • Type: str
  • Default: Automatically generated (see below)
  • Description: The secret key used for signing JSON Web Tokens (JWTs) and encrypting sensitive data at rest (including OAuth tokens for MCP). Can be set via the HRIDAAI_SECRET_KEY environment variable or the legacy HRIDAAI_JWT_SECRET_KEY variable (deprecated).
How the secret key is generated

You do not need to manually set this variable for a secure installation — all standard launch methods automatically generate and persist a cryptographically random key on first start:

Launch methodAuto-generates?Persisted to
Docker (start.sh)✅ Yes.hridaai_secret_key file inside the container
Development (hrida-ai dev, direct uvicorn)❌ NoN/A — uses the code-level fallback

The code-level fallback value (t0p-s3cr3t) exists only for development convenience and is never used when Hrida.ai is launched through the standard Docker image. Its startup script checks for the environment variable first, and if it is not set, generate a secure random key, save it to a file, and inject it into the environment — all before the application starts.

Recommended: Set an explicit, persistent value

While the auto-generated key is secure, it is tied to a file inside the container or working directory. If the container is recreated (not just restarted) and the key file is not in a persisted volume, a new key is generated, which causes:

  1. All existing user sessions become invalid (users are logged out).
  2. All OAuth sessions become invalid.
  3. MCP Tools break (Error: Error decrypting tokens) because tokens encrypted with the previous key cannot be decrypted.

To avoid this, explicitly set HRIDAAI_SECRET_KEY to a secure, persistent value that survives container recreates:

bash
# Generate a secure key
openssl rand -hex 32

Then pass it as an environment variable in your Docker Compose or deployment configuration.

warning

Required for Multi-Worker and Multi-Node Deployments AND HIGHLY RECOMMENDED IN SINGLE-WORKER ENVIRONMENTS

When deploying Hrida.ai with UVICORN_WORKERS > 1 or in a multi-node/worker cluster with a load balancer (e.g. helm/kubectl/kubernetes/k8s), you must set this variable to the same value across all replicas. Without it, the following issues will occur:

  • Session management will fail across workers
  • Application state will be inconsistent between instances
  • Websocket connections will not function properly in distributed setups
  • Users may experience intermittent authentication failures

ENABLE_VERSION_UPDATE_CHECK​

  • Type: bool
  • Default: True
  • Description: When enabled, the application makes automatic update checks and notifies you about version updates.
info

If OFFLINE_MODE is enabled, this ENABLE_VERSION_UPDATE_CHECK flag is always set to false automatically.

OFFLINE_MODE​

  • Type: bool
  • Default: False
  • Description: Disables Hrida.ai's network connections for update checks and automatic model downloads.
info

Disabled when enabled:

  • Automatic version update checks (see flag ENABLE_VERSION_UPDATE_CHECK)
  • Downloads of embedding models from Hugging Face Hub
    • If you did not download an embedding model prior to activating OFFLINE_MODE any RAG, web search and document analysis functionality may not work properly
  • Update notifications in the UI (see flag ENABLE_VERSION_UPDATE_CHECK)

Still functional:

  • External LLM API connections (OpenAI, etc.)
  • OAuth authentication providers
  • Web search and RAG with external APIs

Read more about offline mode in the offline mode guide.

HF_HUB_OFFLINE​

  • Type: int
  • Default: 0
  • Description: Tells Hugging Face whether we want to launch in offline mode, so to not connect to hugging face and prevent all automatic model downloads
info

Downloads of models, sentence transformers and other configurable items will NOT WORK when this is set to 1. RAG will also not work on a default installation, if this is set to True.

RESET_CONFIG_ON_START​

  • Type: bool
  • Default: False
  • Description: Resets the config.json file on startup.

SAFE_MODE​

  • Type: bool
  • Default: False
  • Description: Enables safe mode, which disables potentially unsafe features, deactivating all functions.

CORS_ALLOW_ORIGIN​

  • Type: str
  • Default: *
  • Description: Sets the allowed origins for Cross-Origin Resource Sharing (CORS). Smicolon ';' separated list of allowed origins.
warning

This variable is required to be set, otherwise you may experience Websocket issues and weird "{}" responses or "Unexpected token 'd', "data: {"id"... is not valid JSON".

info

If you experience Websocket issues, check the logs of Hrida.ai. If you see lines like this engineio.base_server:_log_error_once:354 - https://yourdomain.com is not an accepted origin. then you need to configure your CORS_ALLOW_ORIGIN more broadly.

Example: CORS_ALLOW_ORIGIN: "https://yourdomain.com;http://yourdomain.com;https://yourhostname;http://youripaddress;http://localhost:3000"

Add all valid IPs, Domains and Hostnames one might access your Hrida.ai to the variable. Once you did, no more websocket issues or warnings in the console should occur.

CORS_ALLOW_CUSTOM_SCHEME​

  • Type str
  • Default: "" (empty string)
  • Description: Sets a list of further allowed schemes for Cross-Origin Resource Sharing (CORS). Allows you to specify additional custom URL schemes, beyond the standard http and https, that are permitted as valid origins for Cross-Origin Resource Sharing (CORS).
info

This is particularly useful for scenarios such as:

  • Integrating with desktop applications that use custom protocols (e.g., app://, custom-app-scheme://).
  • Local development environments or testing setups that might employ non-standard schemes (e.g., file:// if applicable, or electron://).

Provide a semicolon-separated list of scheme names without the ://. For example: app;file;electron;my-custom-scheme.

When configured, these custom schemes will be validated alongside http and https for any origins specified in CORS_ALLOW_ORIGIN.

RAG_EMBEDDING_MODEL_TRUST_REMOTE_CODE​

  • Type: bool
  • Default: False
  • Description: Determines whether to allow custom models defined on the Hub in their own modeling files.

RAG_RERANKING_MODEL_TRUST_REMOTE_CODE​

  • Type: bool
  • Default: False
  • Description: Determines whether to allow custom models defined on the Hub in their own. modeling files for reranking.

RAG_EMBEDDING_MODEL_AUTO_UPDATE​

  • Type: bool
  • Default: True
  • Description: Toggles automatic update of the Sentence-Transformer model.

RAG_RERANKING_MODEL_AUTO_UPDATE​

  • Type: bool
  • Default: True
  • Description: Toggles automatic update of the reranking model.
Hrida.ai is proprietary software of Zlabs Innovation. See the license for terms. © 2026 Zlabs Innovation.