Storage & Infrastructure

Cloud storage, OpenTelemetry, database pooling, encrypted SQLite, Redis, Uvicorn, caching, proxies and Python package installs.

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.

These variables are not specific to Hrida.ai but can still be valuable in certain contexts.

Cloud Storage

STORAGE_PROVIDER

• Type: str
• Options:
  • s3 - uses the S3 client library and related environment variables mentioned in Amazon S3 Storage
  • gcs - uses the GCS client library and related environment variables mentioned in Google Cloud Storage
  • azure - uses the Azure client library and related environment variables mentioned in Microsoft Azure Storage
• Default: empty string (' '), which defaults to local
• Description: Sets the storage provider.

STORAGE_LOCAL_CACHE

• Type: bool
• Default: True
• Description: Controls whether a local copy of a file is retained after it has been uploaded to a cloud storage provider (S3, GCS, Azure). When True (the default), the local cache copy in UPLOAD_DIR is preserved — matching previous behavior. When False, the local copy is removed automatically once processing completes, so files live only in cloud storage. Has no effect when STORAGE_PROVIDER=local.

Amazon S3 Storage

S3_ACCESS_KEY_ID

• Type: str
• Description: Sets the access key ID for S3 storage.

S3_ADDRESSING_STYLE

• Type: str
• Default: None
• Description: Specifies the addressing style to use for S3 storage (e.g., 'path', 'virtual').

S3_BUCKET_NAME

• Type: str
• Description: Sets the bucket name for S3 storage.

S3_ENDPOINT_URL

• Type: str
• Description: Sets the endpoint URL for S3 storage.

info

If the endpoint is an S3-compatible provider like MinIO that uses a TLS certificate signed by a private CA, set the environment variable AWS_CA_BUNDLE to the path of your PEM-encoded CA certificates file. See the Amazon SDK Docs for more information.

S3_KEY_PREFIX

• Type: str
• Description: Sets the key prefix for a S3 object.

S3_REGION_NAME

• Type: str
• Description: Sets the region name for S3 storage.

S3_SECRET_ACCESS_KEY

• Type: str
• Description: Sets the secret access key for S3 storage.

S3_USE_ACCELERATE_ENDPOINT

• Type: str
• Default: False
• Description: Specifies whether to use the accelerated endpoint for S3 storage.

S3_ENABLE_TAGGING

• Type: str
• Default: False
• Description: Enables S3 object tagging after uploads for better organization, searching, and integration with file management policies. Always set to False when using Cloudflare R2, as R2 does not support object tagging.

Google Cloud Storage

GOOGLE_APPLICATION_CREDENTIALS_JSON

• Type: str
• Description: Contents of Google Application Credentials JSON file.
  • Optional - if not provided, credentials will be taken from the environment. User credentials if run locally and Google Metadata server if run on a Google Compute Engine.
  • A file can be generated for a service account following this guide.

GCS_BUCKET_NAME

• Type: str
• Description: Sets the bucket name for Google Cloud Storage. Bucket must already exist.

Microsoft Azure Storage

AZURE_STORAGE_ENDPOINT

• Type: str
• Description: Sets the endpoint URL for Azure Storage.

AZURE_STORAGE_CONTAINER_NAME

• Type: str
• Description: Sets the container name for Azure Storage.

AZURE_STORAGE_KEY

• Type: str
• Description: Set the access key for Azure Storage.
  • Optional - if not provided, credentials will be taken from the environment. User credentials if run locally and Managed Identity if run in Azure services.

OpenTelemetry Configuration

Additional Dependencies May Be Required

The official Hrida.ai Docker image includes the OpenTelemetry libraries. If you build your own image and see ImportError or missing-module errors related to OpenTelemetry, add them to it:

dockerfile

RUN pip install --no-cache-dir opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp

ENABLE_OTEL

• Type: bool
• Default: False
• Description: Enables or disables OpenTelemetry for observability. When enabled, tracing, metrics, and logging data can be collected and exported to an OTLP endpoint.

ENABLE_OTEL_TRACES

• Type: bool
• Default: False
• Description: Enables or disables OpenTelemetry traces collection and export. This variable works in conjunction with ENABLE_OTEL.

ENABLE_OTEL_METRICS

• Type: bool
• Default: False
• Description: Enables or disables OpenTelemetry metrics collection and export. This variable works in conjunction with ENABLE_OTEL.

ENABLE_OTEL_LOGS

• Type: bool
• Default: False
• Description: Enables or disables OpenTelemetry logging export. When enabled, application logs are sent to the configured OTLP endpoint. This variable works in conjunction with ENABLE_OTEL.

OTEL_EXPORTER_OTLP_ENDPOINT

• Type: str
• Default: http://localhost:4317
• Description: Specifies the default OTLP (OpenTelemetry Protocol) endpoint for exporting traces, metrics, and logs. This can be overridden for metrics if OTEL_METRICS_EXPORTER_OTLP_ENDPOINT is set, and for logs if OTEL_LOGS_EXPORTER_OTLP_ENDPOINT is set.

OTEL_METRICS_EXPORTER_OTLP_ENDPOINT

• Type: str
• Default: Value of OTEL_EXPORTER_OTLP_ENDPOINT
• Description: Specifies the dedicated OTLP endpoint for exporting OpenTelemetry metrics. If not set, it defaults to the value of OTEL_EXPORTER_OTLP_ENDPOINT. This is useful when separate endpoints for traces and metrics are used.

OTEL_LOGS_EXPORTER_OTLP_ENDPOINT

• Type: str
• Default: Value of OTEL_EXPORTER_OTLP_ENDPOINT
• Description: Specifies the dedicated OTLP endpoint for exporting OpenTelemetry logs. If not set, it defaults to the value of OTEL_EXPORTER_OTLP_ENDPOINT. This is useful when separate endpoints for logs, traces, and metrics are used.

OTEL_EXPORTER_OTLP_INSECURE

• Type: bool
• Default: False
• Description: If set to True, the OTLP exporter will use an insecure connection (e.g., HTTP for gRPC) for traces. For metrics, its behavior is governed by OTEL_METRICS_EXPORTER_OTLP_INSECURE, and for logs by OTEL_LOGS_EXPORTER_OTLP_INSECURE.

OTEL_METRICS_EXPORTER_OTLP_INSECURE

• Type: bool
• Default: Value of OTEL_EXPORTER_OTLP_INSECURE
• Description: If set to True, the OTLP exporter will use an insecure connection for metrics. If not specified, it uses the value of OTEL_EXPORTER_OTLP_INSECURE.

OTEL_LOGS_EXPORTER_OTLP_INSECURE

• Type: bool
• Default: Value of OTEL_EXPORTER_OTLP_INSECURE
• Description: If set to True, the OTLP exporter will use an insecure connection for logs. If not specified, it uses the value of OTEL_EXPORTER_OTLP_INSECURE.

OTEL_SERVICE_NAME

• Type: str
• Default: hrida-ai
• Description: Sets the service name that will be reported to your OpenTelemetry collector or observability platform. This helps identify your Hrida.ai instance.

OTEL_RESOURCE_ATTRIBUTES

• Type: str
• Default: Empty string (' ')
• Description: Allows you to define additional resource attributes to be attached to all telemetry data, in a comma-separated key1=val1,key2=val2 format.

OTEL_TRACES_SAMPLER

• Type: str
• Options: parentbased_always_on, always_on, always_off, parentbased_always_off, etc.
• Default: parentbased_always_on
• Description: Configures the sampling strategy for OpenTelemetry traces. This determines which traces are collected and exported to reduce data volume.

OTEL_BASIC_AUTH_USERNAME

• Type: str
• Default: Empty string (' ')
• Description: Sets the username for basic authentication with the default OTLP endpoint. This applies to traces, and by default, to metrics and logs unless overridden by their specific authentication variables.

OTEL_BASIC_AUTH_PASSWORD

• Type: str
• Default: Empty string (' ')
• Description: Sets the password for basic authentication with the default OTLP endpoint. This applies to traces, and by default, to metrics and logs unless overridden by their specific authentication variables.

OTEL_METRICS_EXPORT_INTERVAL_MILLIS

• Type: int
• Default: 10000 (10 seconds)
• Description: Controls how often OpenTelemetry metrics are exported, in milliseconds. The default of 10 seconds produces approximately 6 data points per minute. Lower this value for higher resolution, or increase it to reduce cost on platforms that charge per data point (e.g. Grafana Cloud recommends staying below 1 DPM — set to 60000 for one export per minute).

OTEL_METRICS_BASIC_AUTH_USERNAME

• Type: str
• Default: Value of OTEL_BASIC_AUTH_USERNAME
• Description: Sets the username for basic authentication specifically for the OTLP metrics endpoint. If not specified, it uses the value of OTEL_BASIC_AUTH_USERNAME.

OTEL_METRICS_BASIC_AUTH_PASSWORD

• Type: str
• Default: Value of OTEL_BASIC_AUTH_PASSWORD
• Description: Sets the password for basic authentication specifically for the OTLP metrics endpoint. If not specified, it uses the value of OTEL_BASIC_AUTH_PASSWORD.

OTEL_LOGS_BASIC_AUTH_USERNAME

• Type: str
• Default: Value of OTEL_BASIC_AUTH_USERNAME
• Description: Sets the username for basic authentication specifically for the OTLP logs endpoint. If not specified, it uses the value of OTEL_BASIC_AUTH_USERNAME.

OTEL_LOGS_BASIC_AUTH_PASSWORD

• Type: str
• Default: Value of OTEL_BASIC_AUTH_PASSWORD
• Description: Sets the password for basic authentication specifically for the OTLP logs endpoint. If not specified, it uses the value of OTEL_BASIC_AUTH_PASSWORD.

OTEL_OTLP_SPAN_EXPORTER

• Type: str
• Options: grpc, http
• Default: grpc
• Description: Specifies the default protocol for exporting OpenTelemetry traces (gRPC or HTTP). This can be overridden for metrics if OTEL_METRICS_OTLP_SPAN_EXPORTER is set, and for logs if OTEL_LOGS_OTLP_SPAN_EXPORTER is set.

OTEL_METRICS_OTLP_SPAN_EXPORTER

• Type: str
• Options: grpc, http
• Default: Value of OTEL_OTLP_SPAN_EXPORTER
• Description: Specifies the protocol for exporting OpenTelemetry metrics (gRPC or HTTP). If not specified, it uses the value of OTEL_OTLP_SPAN_EXPORTER.

OTEL_LOGS_OTLP_SPAN_EXPORTER

• Type: str
• Options: grpc, http
• Default: Value of OTEL_OTLP_SPAN_EXPORTER
• Description: Specifies the protocol for exporting OpenTelemetry logs (gRPC or HTTP). If not specified, it uses the value of OTEL_OTLP_SPAN_EXPORTER.

Database Pool

DATABASE_URL

• Type: str
• Default: sqlite:///${DATA_DIR}/hridaai.db
• Description: Specifies the complete database connection URL, following SQLAlchemy's URL scheme. This variable takes precedence over individual database connection parameters if explicitly set.

info

The official Docker image includes PostgreSQL support. Supports SQLite, Postgres, and encrypted SQLite via SQLCipher. Changing the URL does not migrate data between databases.

Documentation on the URL scheme is available here.

If your database password contains special characters, please ensure they are properly URL-encoded. For example, a password like p@ssword should be encoded as p%40ssword.

For configuration using individual parameters or encrypted SQLite, see the relevant sections below.

Single-user / single-replica on local disk? The default is fine.

The default sqlite:///${DATA_DIR}/hridaai.db is a perfectly good choice for personal use, evaluation, home-lab setups, and small single-replica deployments — as long as DATA_DIR lives on a locally-attached SSD/NVMe. No migration needed. The rest of this callout is for operators running on network storage or scaling out.

SQLite is only supported on locally-attached SSD/NVMe

Running SQLite on NFS, CIFS/SMB, Azure Files, GlusterFS, CephFS, or any Kubernetes PersistentVolumeClaim backed by network storage is not supported — this is SQLite upstream's own position (SQLite FAQ #5), and under the async backend (0.9.0+) it will produce pool-timeout errors (QueuePool limit of size N overflow M reached), multi-minute stalls, WAL deadlocks, and potential database corruption.

For multi-replica, multi-worker, Kubernetes, Docker Swarm, or any deployment where DATA_DIR is on shared/network storage, set DATABASE_URL to a PostgreSQL URL:

DATABASE_URL=postgresql://user:password@host:5432/hridaai

See Performance → Disk I/O Latency for the full mechanism (fsync + async pool saturation) and Scaling → Step 1 for migration guidance.

Multi-replica / multi-worker deployments REQUIRE PostgreSQL

For multi-replica or high-availability deployments (Kubernetes, Docker Swarm), you must use an external database (PostgreSQL) instead of SQLite. SQLite does not support concurrent writes from multiple instances and will result in database corruption or data inconsistency. A shared SQLite file on NFS does not count as "supported" — it will still corrupt or deadlock. See the scaling guide linked above.

ENABLE_DB_MIGRATIONS

• Type: bool
• Default: True
• Description: Controls whether database migrations are automatically run on startup. In multi-pod or multi-worker deployments, set this to False on all pods except one to designate a "master" pod responsible for migrations, preventing race conditions or schema corruption.

warning

Required for Multi-Replica Setups For multi-replica or high-availability deployments (Kubernetes, Docker Swarm), you MUST use an external database (PostgreSQL) instead of SQLite. SQLite does not support concurrent writes from multiple instances and will result in database corruption or data inconsistency.

DATABASE_TYPE

• Type: str
• Default: None (automatically set to sqlite if DATABASE_URL uses default SQLite path)
• Description: Specifies the database type (e.g., sqlite, postgresql, sqlite+sqlcipher). This is used in conjunction with other individual parameters to construct the DATABASE_URL if a complete DATABASE_URL is not explicitly defined.
• Persistence: No

DATABASE_USER

• Type: str
• Default: None
• Description: Specifies the username for database authentication. This is used to construct the DATABASE_URL when a complete DATABASE_URL is not explicitly defined.
• Persistence: No

DATABASE_PASSWORD

• Type: str
• Default: None
• Description: Specifies the password for database authentication. This is used to construct the DATABASE_URL when a complete DATABASE_URL is not explicitly defined. If your password contains special characters, please ensure they are properly URL-encoded.
• Persistence: No

DATABASE_HOST

• Type: str
• Default: None
• Description: Specifies the hostname or IP address of the database server. This is used to construct the DATABASE_URL when a complete DATABASE_URL is not explicitly defined.
• Persistence: No

DATABASE_PORT

• Type: int
• Default: None
• Description: Specifies the port number of the database server. This is used to construct the DATABASE_URL when a complete DATABASE_URL is not explicitly defined.
• Persistence: No

DATABASE_NAME

• Type: str
• Default: None
• Description: Specifies the name of the database to connect to. This is used to construct the DATABASE_URL when a complete DATABASE_URL is not explicitly defined.
• Persistence: No

info

When DATABASE_URL is not explicitly set, Hrida.ai will attempt to construct it using a combination of DATABASE_TYPE, DATABASE_USER, DATABASE_PASSWORD, DATABASE_HOST, DATABASE_PORT, and DATABASE_NAME. For this automatic construction to occur, all of these individual parameters must be provided. If any are missing, the default DATABASE_URL (SQLite file) or any explicitly set DATABASE_URL will be used instead.

DATABASE_USER_ACTIVE_STATUS_UPDATE_INTERVAL

• Type: float
• Default: 60
• Description: Minimum interval, in seconds, between writes of a user's last_active_at timestamp to the database (this timestamp drives online/"active" presence, evaluated over a ~3-minute window). The write is throttled per user: within the interval, repeat activity does not hit the database.

Throttled by default

Before the default became 60, the write was unthrottled: essentially every authenticated request issued its own UPDATE ... SET last_active_at = ... plus a COMMIT, a continuous flood of tiny write transactions on a busy instance. With the default, each user's timestamp is written at most once a minute, well inside the 3-minute active window.

• Large deployments can raise it to a few hundred seconds, e.g. 300, to write even less; presence stays accurate to within the interval.
• 0 turns the throttle off (a write per request), which is only useful for debugging presence.
• Read once at startup; not a ConfigVar and not changeable from the Admin UI.

DATABASE_ENABLE_SESSION_SHARING

• Type: bool
• Default: False
• Description: Controls database session sharing behavior. When enabled (True), get_db_context reuses existing database sessions, which can improve performance and scalability in high-concurrency environments. When disabled (False), new sessions are always created.

Recommendations by Database Type

• SQLite: Keep this setting disabled (default False). Enabling session sharing on SQLite with limited hardware resources may cause performance issues.
• PostgreSQL: Consider enabling this setting (True) for improved performance, especially in multi-user or high-concurrency deployments.

This setting is very deployment-specific. Users are encouraged to experiment based on their hardware specs and database choice to find the optimal configuration.

warning

Enabling this on low-spec hardware (e.g., Raspberry Pi, containers with limited CPU allocation) may cause significant slowdowns or timeouts. If you experience slow admin page loads or API timeouts after upgrading, ensure this setting is disabled.

Encrypted SQLite with SQLCipher

For enhanced security, Hrida.ai supports at-rest encryption for its primary SQLite database using SQLCipher. This is recommended for deployments handling sensitive data where using a larger database like PostgreSQL is not needed.

Additional Dependencies Required

SQLCipher encryption requires additional dependencies that are not included by default. Before using this feature, you must install:

• The SQLCipher system library (e.g., libsqlcipher-dev on Debian/Ubuntu, sqlcipher on macOS via Homebrew)
• The sqlcipher3-wheels Python package (pip install sqlcipher3-wheels)

For Docker users, this means building a custom image with these dependencies included.

To enable encryption, you must configure two environment variables:

1. Set DATABASE_TYPE="sqlite+sqlcipher".
2. Set DATABASE_PASSWORD="your-secure-password".

When these are set and a full DATABASE_URL is not explicitly defined, Hrida.ai will automatically create and use an encrypted database file at ./data/hridaai.db.

danger

• The DATABASE_PASSWORD environment variable is required when using sqlite+sqlcipher.
• The DATABASE_TYPE variable tells Hrida.ai which connection logic to use. Setting it to sqlite+sqlcipher activates the encryption feature.

Ensure the database password is kept secure, as it is needed to decrypt and access all application data.

Migrating Existing Data to SQLCipher

Hrida.ai does not support automatic migration from an unencrypted SQLite database to an encrypted SQLCipher database. If you enable SQLCipher on an existing installation, the application will fail to read your existing unencrypted data.

To use SQLCipher with existing data, you must either start fresh (with users exporting/re-importing chats), manually migrate the database using external SQLite/SQLCipher tools, use filesystem-level encryption (LUKS/BitLocker) instead, or switch to PostgreSQL.

DATABASE_SCHEMA

• Type: str
• Default: None
• Description: Specifies the database schema to connect to.

DATABASE_POOL_SIZE

• Type: int
• Default: None
• Description: Specifies the pooling strategy and size of the database pool. By default SQLAlchemy will automatically chose the proper pooling strategy for the selected database connection. A value of 0 disables pooling. A value larger 0 will set the pooling strategy to QueuePool and the pool size accordingly.

SQLite: unset does not mean "small". It falls back to 512

The documented default (None) only means "not set by you". On SQLite, current releases (0.9.x, async DB backend) substitute a large internal pool (currently 512 connections) when this is unset, not SQLAlchemy's small default. Each SQLite connection carries its own page cache (DATABASE_SQLITE_PRAGMA_CACHE_SIZE, ~64 MB by default) and mmap window (DATABASE_SQLITE_PRAGMA_MMAP_SIZE, ~256 MB by default), so peak memory scales with the number of simultaneously active connections. On a memory-constrained container this can OOM-kill the process during connection-heavy workflows (for example editing model or knowledge-base permissions and reloading a long model list). On small / low-spec deployments set this explicitly to a small value (e.g. DATABASE_POOL_SIZE=8) and lower the two PRAGMAs below. See Performance → SQLite Memory Footprint on Constrained Containers.

High-Concurrency Deployments

For deployments with many concurrent users, consider increasing both DATABASE_POOL_SIZE and DATABASE_POOL_MAX_OVERFLOW. A good starting point is DATABASE_POOL_SIZE=15 and DATABASE_POOL_MAX_OVERFLOW=20.

Important: The combined total (DATABASE_POOL_SIZE + DATABASE_POOL_MAX_OVERFLOW) should remain well below your database server's max_connections limit. PostgreSQL defaults to 100 max connections, so keeping the combined total under 50-80 per Hrida.ai instance is recommended to leave room for other clients and maintenance connections.

Pool Size Multiplies with Concurrency

Each Hrida.ai process maintains its own independent connection pool. This applies whether you're running multiple Uvicorn workers (UVICORN_WORKERS > 1), multiple Kubernetes pods, Docker Swarm replicas, or any other multi-instance deployment.

The actual maximum number of database connections is:

Total connections = (DATABASE_POOL_SIZE + DATABASE_POOL_MAX_OVERFLOW) × Number of processes/instances

For example, with DATABASE_POOL_SIZE=15, DATABASE_POOL_MAX_OVERFLOW=20, and 4 instances (whether workers, pods, or replicas), you could open up to 140 connections (35 × 4).

When calculating pool settings, always account for this multiplier to avoid exhausting your database's max_connections limit. This is a fundamental limitation—connection pools cannot be shared across separate processes or containers.

SQLite on NFS / network storage — increasing the pool does not help

If you are seeing QueuePool limit of size N overflow M reached, connection timed out errors on SQLite and the database file lives on NFS, CephFS, Azure Files, an SMB mount, or any network-backed Kubernetes PVC, increasing this value will not fix it. The root cause is slow fsync on the network filesystem, which keeps each connection checked out far longer than on local disk; more pool slots just means more concurrent slow fsyncs against the same slow storage. The async backend saturates any size pool you give it.

The only real fixes are:

1. Migrate to PostgreSQL (DATABASE_URL=postgresql+asyncpg://...) — strongly recommended.
2. Move hridaai.db to a locally-attached SSD/NVMe.
3. Temporary workaround: DATABASE_POOL_SIZE=1 + DATABASE_SQLITE_PRAGMA_BUSY_TIMEOUT=30000 — serializes DB access, not a supported long-term config.

See Performance → Disk I/O Latency for the mechanism, and Scaling → Step 1 for migration guidance.

DATABASE_POOL_MAX_OVERFLOW

• Type: int
• Default: 10
• Description: Specifies the database pool max overflow. This allows additional connections beyond DATABASE_POOL_SIZE during traffic spikes. On PostgreSQL these extra connections stay open for DATABASE_POOL_OVERFLOW_IDLE_SECONDS after use, so a busy server reuses them instead of reconnecting.

info

More information about this setting can be found here.

DATABASE_POOL_OVERFLOW_IDLE_SECONDS

• Type: float
• Default: 30
• Description: PostgreSQL only. How long a connection opened beyond DATABASE_POOL_SIZE (one of the DATABASE_POOL_MAX_OVERFLOW extra connections) stays open unused before it is closed. SQLAlchemy's standard pool closes such a connection the moment it is returned while the pool is full; under steady load the number of connections in use swings around the pool size many times a second, so connections were opened and closed constantly: in a load test about 70 a second, each a TCP connect and a SCRAM password exchange, a third of a worker's CPU at 32 concurrent requests. Kept open, they are reused, and after a burst the pool shrinks back to DATABASE_POOL_SIZE. The limits are unchanged: never more than DATABASE_POOL_SIZE + DATABASE_POOL_MAX_OVERFLOW connections per process. 0 closes them at once, as before.

DATABASE_POOL_TIMEOUT

• Type: int
• Default: 30
• Description: Specifies the database pool timeout in seconds to get a connection.

info

More information about this setting can be found here.

DATABASE_POOL_RECYCLE

• Type: int
• Default: 3600
• Description: Specifies the database pool recycle time in seconds.

info

More information about this setting can be found here.

DATABASE_ENABLE_SQLITE_WAL

• Type: bool
• Default: False
• Description: Enables or disables SQLite WAL (Write-Ahead Logging) mode. When enabled, SQLite transactions can be managed more efficiently, allowing multiple readers and one writer concurrently, which can improve database performance, especially under high concurrency. This setting only applies to SQLite databases.

DATABASE_SQLITE_PRAGMA_SYNCHRONOUS

• Type: str
• Default: NORMAL
• Description: Sets the SQLite PRAGMA synchronous value. NORMAL (1) is safe with WAL mode and avoids an fsync per transaction, improving write throughput. Valid values: OFF (0), NORMAL (1), FULL (2), EXTRA (3). Set to an empty string to skip this PRAGMA entirely. This setting only applies to SQLite databases.

DATABASE_SQLITE_PRAGMA_BUSY_TIMEOUT

• Type: str
• Default: 5000
• Description: Sets the SQLite PRAGMA busy_timeout value in milliseconds. Controls how long a connection waits for a write lock before raising SQLITE_BUSY. Higher values reduce lock contention errors under concurrent writes. Set to an empty string to skip this PRAGMA entirely. This setting only applies to SQLite databases.

DATABASE_SQLITE_PRAGMA_CACHE_SIZE

• Type: str
• Default: -65536
• Description: Sets the SQLite PRAGMA cache_size value. Negative values specify the cache size in KiB — the default -65536 allocates approximately 64 MB of page cache. Larger caches reduce disk I/O for read-heavy workloads. Set to an empty string to skip this PRAGMA entirely. This setting only applies to SQLite databases.

This cache is per connection, not global

SQLite's page cache is allocated per connection, so the real worst case is cache_size times the number of simultaneously active pooled connections, not a single 64 MB allocation. With the default SQLite pool fallback (DATABASE_POOL_SIZE unset, see above) that multiplier can be large enough to OOM a memory-constrained container. On small / low-spec deployments lower this (e.g. DATABASE_SQLITE_PRAGMA_CACHE_SIZE=-2000 for ~2 MB per connection) and cap DATABASE_POOL_SIZE. See Performance → SQLite Memory Footprint on Constrained Containers.

DATABASE_SQLITE_PRAGMA_TEMP_STORE

• Type: str
• Default: MEMORY
• Description: Sets the SQLite PRAGMA temp_store value. MEMORY (2) keeps temporary tables and indices in RAM, which improves performance for queries using temporary storage. Valid values: DEFAULT (0), FILE (1), MEMORY (2). Set to an empty string to skip this PRAGMA entirely. This setting only applies to SQLite databases.

DATABASE_SQLITE_PRAGMA_MMAP_SIZE

• Type: str
• Default: 268435456
• Description: Sets the SQLite PRAGMA mmap_size value in bytes. The default 268435456 enables approximately 256 MB of memory-mapped I/O, which can significantly improve read performance by avoiding syscall overhead. Set to 0 to disable mmap, or to an empty string to skip this PRAGMA entirely. This setting only applies to SQLite databases.

Also per connection

Like the page cache above, the mmap window is established per connection. It is mostly virtual / file-backed rather than committed anonymous RAM, but it inflates the process total-vm substantially and the resident portion still counts toward a cgroup memory limit. On memory-constrained containers set DATABASE_SQLITE_PRAGMA_MMAP_SIZE=0 and cap DATABASE_POOL_SIZE. See Performance → SQLite Memory Footprint on Constrained Containers.

DATABASE_SQLITE_PRAGMA_JOURNAL_SIZE_LIMIT

• Type: str
• Default: 67108864
• Description: Sets the SQLite PRAGMA journal_size_limit value in bytes. Caps the WAL file size after checkpoint — without this, the WAL file can grow unbounded during write bursts. The default 67108864 caps it at approximately 64 MB. Set to -1 for no limit (SQLite default), or to an empty string to skip this PRAGMA entirely. This setting only applies to SQLite databases.

Redis

REDIS_URL

• Type: str
• Description: Specifies the URL of the Redis instance or cluster host for storing application state.
• Examples:
  • redis://localhost:6379/0
  • rediss://:password@localhost:6379/0 (with password and TLS)
  • rediss://redis-cluster.redis.svc.cluster.local:6379/0?ssl_cert_reqs=required&ssl_certfile=/tls/redis/tls.crt&ssl_keyfile=/tls/redis/tls.key&ssl_ca_certs=/tls/redis/ca.crt (with mTLS)

warning

Required for Multi-Worker and Multi-Node Deployments

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 the REDIS_URL value. 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

Redis serves as the central state store that allows multiple Hrida.ai instances to coordinate and share critical application data.

info

Single Instance Deployments

If you're running Hrida.ai as a single instance with UVICORN_WORKERS=1 (the default), Redis is not required for basic functionality. However, without Redis, signing out and password changes do not invalidate existing JWT tokens — they remain valid until they expire (default: 4 weeks). For production deployments, either configure Redis or shorten JWT_EXPIRES_IN. See Token Revocation for details.

danger

Critical Redis Server Configuration — Prevent Connection Exhaustion

Hrida.ai uses Redis for token validation, WebSocket management, and session storage. Each user action can create Redis connections. If your Redis server is misconfigured, connections will accumulate over time until the limit is reached, causing 500 Internal Server Errors and preventing all users from logging in.

You must configure these settings in your redis.conf (not Hrida.ai environment variables):

Setting	Bad Default	Recommended	Why
maxclients	1000 (some distros)	10000 or higher	Low limits cause "max number of clients reached" errors
timeout	0 (never close)	1800 (30 minutes)	Without timeout, idle connections accumulate forever

Example redis.conf settings:

maxclients 10000
timeout 1800

For high-concurrency websocket deployments, also review Redis Pub/Sub output buffer limits. Hrida.ai uses Socket.IO over Redis Pub/Sub when WEBSOCKET_MANAGER=redis is enabled, and streaming responses can produce large websocket events. If Redis disconnects Pub/Sub clients under large streaming payloads, you may see Cannot publish to redis... giving up, Redis timeout errors, or stalled live updates. Check:

bash

redis-cli INFO stats | grep client_output_buffer_limit_disconnections
redis-cli SLOWLOG GET 50
redis-cli CONFIG GET client-output-buffer-limit

If client_output_buffer_limit_disconnections increases and the slow log shows large PUBLISH socketio ... entries, raise the Pub/Sub buffer limit in redis.conf. Example:

client-output-buffer-limit normal 0 0 0 replica 268435456 67108864 60 pubsub 1073741824 268435456 180

This leaves normal clients unchanged and allows Pub/Sub clients to buffer up to 1 GB hard / 256 MB soft for 180 seconds. Tune these values to your available Redis memory and expected websocket payload size.

Symptoms of this misconfiguration:

• Works fine for days/weeks, then suddenly all logins fail with 500 errors
• redis.exceptions.ConnectionError: max number of clients reached in logs
• Problem appears to "fix itself" temporarily, then returns

Why this happens: With timeout 0, every Redis connection stays open indefinitely. Over days or weeks, connections from token checks, WebSocket events, and session validations accumulate. Once maxclients is reached, no new connections can be made, and authentication fails completely.

To check your current connection count:

bash

redis-cli INFO clients | grep connected_clients

To verify your settings:

bash

redis-cli CONFIG GET maxclients
redis-cli CONFIG GET timeout

REDIS_SENTINEL_HOSTS

• Type: str
• Description: Comma-separated list of Redis Sentinels for app state. If specified, the "hostname" in REDIS_URL will be interpreted as the Sentinel service name.

REDIS_SENTINEL_PORT

• Type: int
• Default: 26379
• Description: Sentinel port for app state Redis.

REDIS_CLUSTER

• Type: bool
• Default: False
• Description: Connect to a Redis Cluster instead of a single instance or using Redis Sentinels. If True, REDIS_URL must also be defined. This mode is compatible with AWS Elasticache Serverless and other Redis Cluster implementations.

info

This option has no effect if REDIS_SENTINEL_HOSTS is defined.

OpenTelemetry Support

Redis Cluster mode is fully compatible with OpenTelemetry instrumentation. When ENABLE_OTEL is enabled, Redis operations are properly traced regardless of whether you're using a single Redis instance or Redis Cluster mode.

REDIS_KEY_PREFIX

• Type: str
• Default: hrida-ai
• Description: Customizes the Redis key prefix used for storing configuration values. This allows multiple Hrida.ai instances to share the same Redis instance without key conflicts. When operating in Redis cluster mode, the prefix is formatted as {prefix}: (e.g., {hrida-ai}:config:*) to enable multi-key operations on configuration keys within the same hash slot.

REDIS_SOCKET_CONNECT_TIMEOUT

• Type: float (seconds) or empty string for None
• Default: None (no timeout, uses redis-py library default)
• Description: Sets the socket connection timeout in seconds for all Redis client connections, including Sentinel, Cluster, and plain URL modes. This timeout applies to the initial TCP connection establishment. When set, it prevents indefinite blocking when attempting to connect to unreachable Redis nodes.

danger

Critical for Redis Sentinel Deployments

Without a socket connection timeout, Redis Sentinel failover can cause the application to hang indefinitely when a master node goes offline. The application may become completely unresponsive and even fail to restart.

For Sentinel deployments, it is strongly recommended to set this value (e.g., REDIS_SOCKET_CONNECT_TIMEOUT=5).

warning

Interaction with WEBSOCKET_REDIS_OPTIONS

If you explicitly set WEBSOCKET_REDIS_OPTIONS, this variable will not apply to the AsyncRedisManager used for websocket communication. In that case, you must include socket_connect_timeout directly within WEBSOCKET_REDIS_OPTIONS:

bash

WEBSOCKET_REDIS_OPTIONS='{"socket_connect_timeout": 5}'

If WEBSOCKET_REDIS_OPTIONS is not set, REDIS_SOCKET_CONNECT_TIMEOUT will be applied to websocket connections automatically.

REDIS_SOCKET_KEEPALIVE

• Type: bool
• Default: False
• Description: Enables TCP SO_KEEPALIVE on all Redis client sockets (plain, cluster, and sentinel connections, both sync and async). When enabled, the operating system kernel sends TCP keepalive probes on idle connections, detecting half-closed sockets (e.g., after a silent firewall/load balancer reset or a NIC flap) before the next Redis command lands on them.

When to enable

Enable this setting in environments where:

• A firewall or load balancer sits between the application and Redis and may silently drop idle connections
• Network instability can cause connections to become half-open without notification
• You want an additional layer of dead-connection detection alongside REDIS_HEALTH_CHECK_INTERVAL

REDIS_SOCKET_KEEPALIVE operates at the TCP level (kernel-driven probes), while REDIS_HEALTH_CHECK_INTERVAL operates at the application level (redis-py PING commands). They are complementary and can be used together for maximum reliability.

REDIS_SENTINEL_MAX_RETRY_COUNT

• Type: int
• Default: 2
• Description: Sets the maximum number of retries for Redis operations when using Sentinel fail-over. This is a critical high-availability setting that allows the application time for master election and promotion. If your Sentinel down-after-milliseconds is high, you should tune this value accordingly to ensure the service survives the failover window without dropping connections.

REDIS_RECONNECT_DELAY

• Type: float (milliseconds)
• Default: None
• Description: Optional reconnect delay in milliseconds for Redis Sentinel retry logic, applied consistently across both synchronous and asynchronous Redis operations. This improves stability during Sentinel failover by preventing tight retry loops. When unset or invalid, retry behavior remains unchanged.

REDIS_HEALTH_CHECK_INTERVAL

• Type: int (seconds)
• Default: None (disabled)
• Description: How often (in seconds) redis-py should PING an idle pooled connection before reusing it. When set to a positive integer, redis-py will PING any pooled connection that has been idle longer than this interval before handing it back to a caller. This detects stale/dead connections before a real command lands on them, preventing ConnectionError: Connection reset by peer errors. Set to 0 or leave empty to disable.

Recommended for production

Set REDIS_HEALTH_CHECK_INTERVAL to a value shorter than both:

• Your Redis server's timeout setting (e.g., timeout 1800)
• Any firewall or load balancer idle timeout on the path to Redis

A typical value is 60 (seconds). This keeps actively-used pooled connections warm (the PING resets the server's idle timer) while still allowing the Redis server to reap truly orphaned connections via its timeout setting.

How it works

When enabled, redis-py performs a lightweight PING on checkout for any connection that has been idle longer than the configured interval. This serves two purposes:

1. Detects dead connections — stale sockets are identified and replaced before your application code runs a command on them
2. Keeps active connections alive — the PING resets the Redis server's per-connection idle timer, preventing the server from reaping connections that are still in the pool

Without this setting, if your Redis server has a timeout configured (recommended to prevent connection exhaustion), the first request that grabs a reaped socket from the pool will fail with a ConnectionError.

WEBSOCKET_REDIS_LOCK_TIMEOUT

• Type: int
• Default: 60
• Description: Sets the timeout in seconds for Redis locks used by the websocket manager.

ENABLE_WEBSOCKET_SUPPORT

• Type: bool
• Default: True
• Description: Enables websocket support in Hrida.ai.

warning

Required for Multi-Worker and Multi-Node Deployments

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

WEBSOCKET_MANAGER

• Type: str
• Default: "" (empty string)
• Description: Specifies the websocket manager to use. Allowed values include: redis

warning

Required for Multi-Worker and Multi-Node Deployments

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

WEBSOCKET_REDIS_URL

• Type: str
• Default: ${REDIS_URL}
• Description: Specifies the URL of the Redis instance or cluster host for websocket communication. It is distinct from REDIS_URL and in practice, it is recommended to set both.

warning

Required for Multi-Worker and Multi-Node Deployments

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

WEBSOCKET_SENTINEL_HOSTS

• Type: str
• Description: Comma-separated list of Redis Sentinels for websocket. If specified, the "hostname" in WEBSOCKET_REDIS_URL will be interpreted as the Sentinel service name.

WEBSOCKET_SENTINEL_PORT

• Type: int
• Default: 26379
• Description: Sentinel port for websocket Redis.

WEBSOCKET_REDIS_CLUSTER

• Type: bool
• Default: ${REDIS_CLUSTER}
• Description: Specifies that websocket should communicate with a Redis Cluster instead of a single instance or using Redis Sentinels. If True, WEBSOCKET_REDIS_URL and/or REDIS_URL must also be defined.

info

This option has no effect if WEBSOCKET_SENTINEL_HOSTS is defined.

WEBSOCKET_REDIS_OPTIONS

• Type: str
• Default: {} (empty, which allows REDIS_SOCKET_CONNECT_TIMEOUT to apply if set)
• Description: A string representation of a dictionary containing additional Redis connection options for the websocket Redis client (AsyncRedisManager). This allows you to specify advanced connection parameters such as SSL settings, timeouts, or other Redis client configurations that are not covered by the standard WEBSOCKET_REDIS_URL. The string should be formatted as valid JSON. For example: {"retry_on_timeout": true, "socket_connect_timeout": 5, "socket_timeout": 5, "max_connections": 8}. All JSON encodable options listed here can be used.

warning

AWS SSM and Docker compose cannot ingest raw JSON, as such you need to escape any double quotes like the following: {\"retry_on_timeout\": true, \"socket_connect_timeout\": 5, \"socket_timeout\": 5, \"max_connections\": 8}

info

Precedence with REDIS_SOCKET_CONNECT_TIMEOUT

When this variable is left empty (default), REDIS_SOCKET_CONNECT_TIMEOUT is automatically applied to websocket connections if set. However, if you explicitly set WEBSOCKET_REDIS_OPTIONS to any value, REDIS_SOCKET_CONNECT_TIMEOUT will not be injected—you must include socket_connect_timeout manually within this JSON if needed.

WEBSOCKET_SERVER_LOGGING

• Type: bool
• Default: false
• Description: Controls logging for SocketIO server related to websocket operations.

warning

This can be very verbose, it is only recommended to use this flag when debugging Redis related issues.

WEBSOCKET_SERVER_ENGINEIO_LOGGING

• Type: bool
• Default: Falls back to WEBSOCKET_SERVER_LOGGING if not set, otherwise false
• Description: Controls logging for Engine.IO server related to websocket operations. If not explicitly set, this inherits the value from WEBSOCKET_SERVER_LOGGING.

warning

This can be very verbose, it is only recommended to use this flag when debugging Redis related issues.

WEBSOCKET_SERVER_PING_TIMEOUT

• Type: int
• Default: 20
• Description: The number of seconds the Socket.IO/Engine.IO server waits for a client pong before considering the websocket connection dead. Increase this for slow networks, browser tabs that may pause briefly, or deployments that send large websocket events.

WEBSOCKET_SERVER_PING_INTERVAL

• Type: int
• Default: 25
• Description: The interval in seconds at which the Socket.IO/Engine.IO server sends heartbeat pings to connected websocket clients.

WEBSOCKET_EVENT_CALLER_TIMEOUT

• Type: int
• Default: 300
• Description: Sets the timeout in seconds for the sio.call() used in event_call events. This controls how long the server waits for a user to respond to interactive prompts, forms, or dropdowns generated by tools and actions using event_call (e.g., execute() type events). Increase this value if users need more time to fill out forms or make decisions presented by event calls.

MODELS_REGISTRY_CACHE_SECONDS

• Type: float (seconds)
• Default: 1
• Description: With WEBSOCKET_MANAGER=redis, the list of available models is shared through Redis, and every chat message looked it up about ten times, each a blocking round trip. Each Studio process now keeps a copy and checks it against Redis at most this often. A model it doesn't have is looked up in Redis at once, so a model added on another replica is never reported missing; a changed model's settings reach other replicas within this time. 0 reads Redis on every lookup, as before.

ENABLE_STAR_SESSIONS_MIDDLEWARE

• Type: bool
• Default: False
• Description: Enables Redis-based session storage for OAuth authentication flows using the StarSessions middleware. When enabled, OAuth session state is stored in Redis instead of browser cookies, which can help resolve CSRF errors in multi-replica deployments where session data needs to be shared across pods.
• Persistence: This is an environment variable.

Known Limitations

This feature has known compatibility issues:

• Redis Sentinel and Redis Cluster configurations are not yet supported and will cause authentication failures if this setting is enabled
• Only basic Redis setups (single instance or standard Redis URL) are currently compatible
• This feature was introduced to address CSRF "mismatching_state" errors in multi-pod deployments, but it is disabled by default due to ongoing compatibility work

Only enable this setting if:

• You are experiencing persistent CSRF errors during OAuth login in a multi-replica deployment
• You are using a basic Redis setup (not Sentinel or Cluster)
• You have confirmed that HRIDAAI_SECRET_KEY is set to the same value across all replicas
• You understand this feature may change or be removed in future releases

For most deployments, the default browser cookie-based session management is sufficient and more stable.

Uvicorn Settings

HRIDAAI_SERVICE

• Type: str
• Default: Empty string (Studio)
• Description: gateway makes start.sh run only the API Builder gateway, as a service of its own next to Studio, sharing its database, Redis and HRIDAAI_SECRET_KEY. Run it with ENABLE_DB_MIGRATIONS=false: Studio migrates.

ENABLE_ROUTE_INDEX

• Type: bool
• Default: True
• Description: Finds each request's route among the few whose path prefix fits, instead of trying Studio's hundreds of routes in turn (in a load test, that took about a sixth of the CPU). The route chosen is the same either way; False turns it off.

GC_FREEZE_AFTER_STARTUP

• Type: bool
• Default: True
• Description: When startup is done, Studio (and the gateway service) collects garbage once and freezes the objects still alive (gc.freeze()), so later collections skip the millions of long-lived objects that make up a Studio process. Without it, each full collection paused the server for about half a second, several times a minute under load. False turns it off.

FRONTEND_ASSET_CACHE_MB

• Type: float (megabytes)
• Default: 64
• Description: Memory each Studio worker may use to keep the web app's files, compressed once (brotli, else gzip): the hashed files under /_app/immutable and index.html, which is re-read when its file changes. Without it, each request for one of these files cost two realpath() walks and a stat in a worker thread, the read in more thread hops, and a fresh compression of the whole file: in a load test about 14 ms of a worker's CPU per 100 KB file, and a page load with a cold browser cache fetches over a hundred of them (after every deploy, for every user). From memory, a file takes under a millisecond. Files over 8 MB, range requests and clients that accept no compression are served from disk as before. 0 turns it off.

LAZY_ML_IMPORTS

• Type: bool
• Default: True
• Description: Keeps the machine-learning stack (torch, transformers, sentence-transformers, nltk, scipy, scikit-learn, pandas) out of a Studio worker until something uses it. A LangChain package Studio imports at startup loaded all of them, about 480 MB of memory per worker, even when embeddings and reranking come from an external API (RAG_EMBEDDING_ENGINE=openai, ollama or azure_openai). With a local embedding or reranking model they are still loaded, when the model is set up. False loads them at startup, as before.

UVICORN_TIMEOUT_GRACEFUL_SHUTDOWN

• Type: int (seconds)
• Default: None (wait for every request in progress)
• Description: On SIGTERM, how long requests in progress may finish before the process stops, so shutdown work (such as writing the gateway's buffered call log) completes before the orchestrator's kill deadline. Keep it below Kubernetes' terminationGracePeriodSeconds or Swarm's stop_grace_period.

UVICORN_WORKERS

• Type: int
• Default: 1
• Description: Controls the number of worker processes that Uvicorn spawns to handle requests. Each worker runs its own instance of the application in a separate process.

info

When deploying in orchestrated environments like Kubernetes or using Helm charts, it's recommended to keep UVICORN_WORKERS set to 1. Container orchestration platforms already provide their own scaling mechanisms through pod replication, and using multiple workers inside containers can lead to resource allocation issues and complicate horizontal scaling strategies.

If you use UVICORN_WORKERS, you also need to ensure that related environment variables for scalable multi-worker setups are set accordingly.

ChromaDB Not Compatible with Multiple Workers

The default vector database (ChromaDB) uses a local SQLite-backed PersistentClient. SQLite connections are not fork-safe — when uvicorn forks multiple workers, each process inherits the same SQLite connection, and concurrent writes will crash workers instantly (Child process died).

If you set UVICORN_WORKERS > 1, you must either switch to a client-server vector database (PGVector, Milvus, Qdrant) via VECTOR_DB, or run ChromaDB as a separate server and set CHROMA_HTTP_HOST.

Database Migrations with Multiple Workers / Multi-Pod Deployments

When UVICORN_WORKERS > 1 or when running multiple replicas, starting the application can trigger concurrent database migrations from multiple processes, potentially causing database schema corruption or inconsistent states.

Recommendation: To handle migrations safely in multi-process/multi-pod environments, you can:

1. Designate a Master (Recommended): Set ENABLE_DB_MIGRATIONS=False on all but one instance/worker. The instance with ENABLE_DB_MIGRATIONS=True (default) will handle the migration, while others will wait or skip it.
2. Scale Down: Temporarily scale down to a single instance/worker to let migrations finish before scaling back up.

For Kubernetes, Helm, and Orchestrated Setups: It is recommended to use the ENABLE_DB_MIGRATIONS variable to designate a specific pod for migrations, or use an init container/job to handle migrations before scaling up the main application pods. This ensures schema updates are applied exactly once.

Cache Settings

CACHE_CONTROL

• Type: str
• Default: Not set (no Cache-Control header added)
• Description: Sets the Cache-Control header for all HTTP responses. Supports standard directives like public, private, no-cache, no-store, must-revalidate, max-age=seconds, etc. If an invalid value is provided, defaults to "no-store, max-age=0" (no caching).
• Examples:
  • "private, max-age=86400" - Cache privately for 24 hours
  • "public, max-age=3600, must-revalidate" - Cache publicly for 1 hour, then revalidate
  • "no-cache, no-store, must-revalidate" - Never cache

Proxy Settings

Hrida.ai supports using proxies for HTTP and HTTPS retrievals. To specify proxy settings, Hrida.ai uses the following environment variables:

http_proxy

• Type: str
• Description: Sets the URL for the HTTP proxy.

https_proxy

• Type: str
• Description: Sets the URL for the HTTPS proxy.

no_proxy

• Type: str
• Description: Lists domain extensions (or IP addresses) for which the proxy should not be used, separated by commas. For example, setting no_proxy to '.mit.edu' ensures that the proxy is bypassed when accessing documents from MIT.

Install Required Python Packages

Hrida.ai provides environment variables to customize the pip installation process. Below are the environment variables used by Hrida.ai for adjusting package installation behavior:

ENABLE_PIP_INSTALL_FRONTMATTER_REQUIREMENTS

• Type: bool
• Default: True
• Description: Controls whether Hrida.ai automatically runs pip install for Python packages declared in function and tool requirements frontmatter. When enabled, dependencies are installed at runtime — both on startup (for all active functions and admin tools) and when saving a function or tool with new requirements.

Security Hardening for Production

Strongly recommended: set ENABLE_PIP_INSTALL_FRONTMATTER_REQUIREMENTS=False in production. Runtime pip installs allow any admin-uploaded function or tool to install arbitrary Python packages into the running process. Disabling this:

• Prevents arbitrary package installation from user-uploaded code
• Eliminates race conditions that crash workers when UVICORN_WORKERS > 1 or multiple replicas attempt concurrent pip installs
• Ensures reproducible deployments — all dependencies are baked into the container image

Pre-install required packages in your Dockerfile instead:

dockerfile

FROM ghcr.io/hrida-ai/hrida-ai-studio:main

RUN pip install --no-cache-dir python-docx requests beautifulsoup4

When disabled, functions and tools that import missing packages will fail with a ModuleNotFoundError at load time, clearly indicating which packages need to be pre-installed.

PIP_OPTIONS

• Type: str
• Description: Specifies additional command-line options that pip should use when installing packages. For example, you can include flags such as --upgrade, --user, or --no-cache-dir to control the installation process.

PIP_PACKAGE_INDEX_OPTIONS

• Type: str
• Description: Defines custom package index behavior for pip. This can include specifying additional or alternate index URLs (e.g., --extra-index-url), authentication credentials, or other parameters to manage how packages are retrieved from different locations.