librechat.ai/content/docs/configuration/dotenv.mdx

---
title: Environment Variables
icon: Variable
description: Comprehensive guide for configuring your application's environment with the `.env` file. This document is your one-stop resource for understanding and customizing the environment variables that will shape your application's behavior in different contexts.
---

Welcome to the comprehensive guide for configuring your application's environment with the `.env` file. This document is your one-stop resource for understanding and customizing the environment variables that will shape your application's behavior in different contexts.

While the default settings provide a solid foundation for a standard `docker` installation, delving into this guide will unveil the full potential of LibreChat. This guide empowers you to tailor LibreChat to your precise needs. Discover how to adjust language model availability, integrate social logins, manage the automatic moderation system, and much more. It's all about giving you the control to fine-tune LibreChat for an optimal user experience.

> **Reminder: Please restart LibreChat for the configuration changes to take effect**

Alternatively, you can create a new file named `docker-compose.override.yml` in the same directory as your main `docker-compose.yml` file for LibreChat, where you can set your .env variables as needed under `environment`, or modify the default configuration provided by the main `docker-compose.yml`, without the need to directly edit or duplicate the whole file.

For more info see:

- Our quick guide:
    - **[Docker Override](/docs/configuration/docker_override)**

- The official docker documentation:
    - **[docker docs - understanding-multiple-compose-files](https://docs.docker.com/compose/multiple-compose-files/extends/#understanding-multiple-compose-files)**
    - **[docker docs - merge-compose-files](https://docs.docker.com/compose/multiple-compose-files/merge/#merge-compose-files)**
    - **[docker docs - specifying-multiple-compose-files](https://docs.docker.com/compose/reference/#specifying-multiple-compose-files)**

- You can also view an example of an override file for LibreChat in your LibreChat folder and on GitHub:
    - **[docker-compose.override.example](https://github.com/danny-avila/LibreChat/blob/main/docker-compose.override.yml.example)**

---

## Server Configuration

### Port

- The server listens on a specific port.
- The `PORT` environment variable sets the port where the server listens. By default, it is set to `3080`.


<OptionTable
  options={[
    ['HOST', 'string', 'Specifies the host.', 'HOST=localhost'],
    ['PORT', 'number', 'Specifies the port.', 'PORT=3080'],
  ]}
/>

### Trust proxy
Use the address that is at most n number of hops away from the Express application.
req.socket.remoteAddress is the first hop, and the rest are looked for in the X-Forwarded-For header from right to left.
A value of 0 means that the first untrusted address would be req.socket.remoteAddress, i.e. there is no reverse proxy.
The `TRUST_PROXY` environment variable default is set to `1`.

Refer to [Express.js - trust proxy](https://expressjs.com/en/guide/behind-proxies.html) for more information about this.

<OptionTable
  options={[
    ['TRUST_PROXY', 'number', 'Specifies the number of hops.', 'TRUST_PROXY=1'],
  ]}
/>

### Credentials Configuration

To securely store credentials, you need a fixed key and IV. You can set them here for prod and dev environments.

<OptionTable
  options={[
    ['CREDS_KEY', 'string', '32-byte key (64 characters in hex) for securely storing credentials. Required for app startup.', 'CREDS_KEY=f34be427ebb29de8d88c107a71546019685ed8b241d8f2ed00c3df97ad2566f0'],
    ['CREDS_IV', 'string', '16-byte IV (32 characters in hex) for securely storing credentials. Required for app startup.', 'CREDS_IV=e2341419ec3dd3d19b13a1a87fafcbfb'],
  ]}
/>

<Callout type="warning" title="Warning">
**Warning:** If you don't set `CREDS_KEY` and `CREDS_IV`, the app will crash on startup.
- You can use this [Key Generator](/toolkit/creds_generator) to generate them quickly.
</Callout>

### Static File Handling

<OptionTable
  options={[
    ['STATIC_CACHE_MAX_AGE', 'string', 'Cache-Control max-age in seconds','STATIC_CACHE_MAX_AGE=172800'],
    ['STATIC_CACHE_S_MAX_AGE', 'string', 'Cache-Control s-maxage in seconds for shared caches (CDNs and proxies)','STATIC_CACHE_S_MAX_AGE="86400"'],
    ['DISABLE_COMPRESSION', 'boolean', 'Disables compression for static files.','DISABLE_COMPRESSION=false'],
    ['ENABLE_IMAGE_OUTPUT_GZIP_SCAN', 'boolean', 'Enables serving gzipped versions of uploaded images if present in the same folder.','ENABLE_IMAGE_OUTPUT_GZIP_SCAN=true'],
  ]}
/>

**Behaviour:**

Sets the [Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) headers for static files. These configurations only trigger when the `NODE_ENV` is set to `production`.

* Uncomment `STATIC_CACHE_MAX_AGE` to change the local `max-age` for static files. By default this is set to 2 days (172800 seconds).
* Uncomment `STATIC_CACHE_S_MAX_AGE` to set the `s-maxage` for shared caches (CDNs and proxies). By default this is set to 1 day (86400 seconds).
* Uncomment `DISABLE_COMPRESSION` to disable compression for static files. By default, compression is enabled.
* Uncomment `ENABLE_IMAGE_OUTPUT_GZIP_SCAN` to enable scanning and serving of gzipped version of images if they have been pre-compressed in the same folder, with the same name and a .gz extension. By default, gzip scan for uploaded images is disabled.

<Callout type="warning" title="Warning">
- This only affects static files served by the API server and is not applicable to _Firebase_, _NGINX_, or any other configurations.
</Callout>

### Index HTML Cache Control

<OptionTable
  options={[
    ['INDEX_CACHE_CONTROL', 'string', 'Cache-Control header for index.html','INDEX_CACHE_CONTROL=no-cache, no-store, must-revalidate'],
    ['INDEX_PRAGMA', 'string', 'Pragma header for index.html','INDEX_PRAGMA=no-cache'],
    ['INDEX_EXPIRES', 'string', 'Expires header for index.html','INDEX_EXPIRES=0'],
  ]}
/>

**Behaviour:**

Controls caching headers specifically for the index.html response. By default, these settings prevent caching to ensure users always get the latest version of the application.

<Callout type="note" title="Note">
Unlike static assets which are cached for performance, the index.html file's cache headers are configured separately to ensure users always get the latest application shell.
</Callout>

### MongoDB Database

<OptionTable
  options={[
    ['MONGO_URI', 'string', 'Specifies the MongoDB URI.','MONGO_URI=mongodb://127.0.0.1:27017/LibreChat'],
  ]}
/>

Change this to your MongoDB URI if different. You should add `LibreChat` or your own `APP_TITLE` as the database name in the URI.

If you are using an online database, the URI format is `mongodb+srv://<username>:<password>@<host>/<database>?<options>`. Your `MONGO_URI` should look like this:
* `mongodb+srv://username:password@host.mongodb.net/LibreChat?retryWrites=true` (`retryWrites` is the only option you need when using the online database.)

#### MongoDB Connection Pool Configuration

<OptionTable
  options={[
    ['MONGO_MAX_POOL_SIZE', 'number', 'The maximum number of connections in the connection pool.', '# MONGO_MAX_POOL_SIZE='],
    ['MONGO_MIN_POOL_SIZE', 'number', 'The minimum number of connections in the connection pool.', '# MONGO_MIN_POOL_SIZE='],
    ['MONGO_MAX_CONNECTING', 'number', 'The maximum number of connections that may be in the process of being established concurrently by the connection pool.', '# MONGO_MAX_CONNECTING='],
    ['MONGO_MAX_IDLE_TIME_MS', 'number', 'The maximum number of milliseconds that a connection can remain idle in the pool before being removed and closed.', '# MONGO_MAX_IDLE_TIME_MS='],
    ['MONGO_WAIT_QUEUE_TIMEOUT_MS', 'number', 'The maximum time in milliseconds that a thread can wait for a connection to become available.', '# MONGO_WAIT_QUEUE_TIMEOUT_MS='],
  ]}
/>

#### MongoDB Schema Configuration

<OptionTable
  options={[
    ['MONGO_AUTO_INDEX', 'boolean', 'Set to false to disable automatic index creation for all models associated with this connection. When omitted, uses Mongoose default behavior.', '# MONGO_AUTO_INDEX='],
    ['MONGO_AUTO_CREATE', 'boolean', 'Set to false to disable Mongoose automatically calling createCollection() on every model created on this connection. When omitted, uses Mongoose default behavior.', '# MONGO_AUTO_CREATE='],
  ]}
/>

Alternatively you can use `documentDb` that emulates `mongoDb` but it:

* does not support `retryWrites` - use `retryWrites=false`
* requires TLS connection, hence use parameters `tls=true` to enable TLS and `tlsCAFile=/path-to-ca/bundle.pem` to point to the AWS provided CA bundle file

The URI for `documentDb` will look like:
* `mongodb+srv://username:password@domain/dbname?retryWrites=false&tls=true&tlsCAFile=/path-to-ca/bundle.pem`

See also:

* [MongoDB Atlas](/docs/configuration/mongodb/mongodb_atlas) for instructions on how to create an online MongoDB Atlas database (useful for use without Docker)
* [MongoDB Community Server](/docs/configuration/mongodb/mongodb_community) for instructions on how to create a local MongoDB database (without Docker)
* [MongoDB Authentication](/docs/configuration/mongodb/mongodb_auth) To enable explicit authentication for MongoDB in Docker.
* [Manage your database with Mongo Express](/blog/2023-11-30_mongoexpress) for securely accessing your Docker MongoDB database

### Application Domains

To configure LibreChat for local use or custom domain deployment, set the following environment variables:

<OptionTable
  options={[
    ['DOMAIN_CLIENT', 'string', 'Specifies the client-side domain.', 'DOMAIN_CLIENT=http://localhost:3080'],
    ['DOMAIN_SERVER', 'string', 'Specifies the server-side domain.', 'DOMAIN_SERVER=http://localhost:3080'],
  ]}
/>

When deploying LibreChat to a custom domain, replace `http://localhost:3080` with your deployed URL
- e.g. `https://librechat.example.com`.

### Prevent Public Search Engines Indexing

By default, your website will not be indexed by public search engines (e.g. Google, Bing, …). This means that people will not be able to find your website through these search engines. If you want to make your website more visible and searchable, you can change the following setting to `false`

<OptionTable
  options={[
    ['NO_INDEX', 'boolean', 'Prevents public search engines from indexing your website.', 'NO_INDEX=true'],
  ]}
/>

❗**Note:** This method is not guaranteed to work for all search engines, and some search engines may still index your website or web page for other purposes, such as caching or archiving. Therefore, you should not rely solely on this method to protect sensitive or confidential information on your website or web page.

### Logging

LibreChat has built-in central logging, see [Logging System](/docs/configuration/logging) for more info.

#### Log Files

* Debug logging is enabled by default and crucial for development.
* To report issues, reproduce the error and submit logs from `./api/logs/debug-%DATE%.log` at: **[LibreChat GitHub Issues](https://github.com/danny-avila/LibreChat/issues)**
* Error logs are stored in the same location.

#### Environment Variables

<OptionTable
  options={[
    ['DEBUG_LOGGING', 'boolean', 'Keep debug logs active.','DEBUG_LOGGING=true'],
    ['DEBUG_CONSOLE', 'boolean', 'Enable verbose console/stdout logs in the same format as file debug logs.', 'DEBUG_CONSOLE=false'],
    ['CONSOLE_JSON', 'boolean', 'Enable verbose JSON console/stdout logs suitable for cloud deployments like GCP/AWS.', 'CONSOLE_JSON=false'],
    ['CONSOLE_JSON_STRING_LENGTH', 'number', 'Configure the truncation size for console/stdout logs, defaults to 255', 'CONSOLE_JSON_STRING_LENGTH=1000'],
    ['LIBRECHAT_LOG_DIR', 'string', 'Custom directory for log files. Defaults to /app/logs (Docker) or api/logs (local dev).', '# LIBRECHAT_LOG_DIR=/custom/log/path'],
  ]}
/>

Note:
* `DEBUG_LOGGING` can be used with either `DEBUG_CONSOLE` or `CONSOLE_JSON` but not both.
* `DEBUG_CONSOLE` and `CONSOLE_JSON` are mutually exclusive.
* `CONSOLE_JSON`: When handling console logs in cloud deployments (such as GCP or AWS), enabling this will dump the logs with a UTC timestamp and format them as JSON.
  * See: [feat: Add CONSOLE_JSON](https://github.com/danny-avila/LibreChat/pull/2146)

Note: `DEBUG_CONSOLE` is not recommended, as the outputs can be quite verbose, and so it's disabled by default.

### Permission
> UID and GID are numbers assigned by Linux to each user and group on the system. If you have permission problems, set here the UID and GID of the user running the Docker Compose command. The applications in the container will run with these UID/GID.

<OptionTable
  options={[
    ['UID', 'number', 'The user ID.', '# UID=1000'],
    ['GID', 'number', 'The group ID.', '# GID=1000'],
  ]}
/>

### Configuration Path - `librechat.yaml`
Specify an alternative location for the LibreChat configuration file.
You may specify an **absolute path**, a **relative path**, or a **URL**. The filename in the path is flexible and does not have to be `librechat.yaml`; any valid configuration file will work.

> **Note**: If you prefer LibreChat to search for the configuration file in the root directory (which is the default behavior), simply leave this option commented out.

<OptionTable
  options={[
    ['CONFIG_PATH', 'string', 'An alternative location for the LibreChat configuration file.', '# CONFIG_PATH=https://raw.githubusercontent.com/danny-avila/LibreChat/main/librechat.example.yaml'],
  ]}
/>

### Configuration Validation

By default, LibreChat will exit with an error (exit code 1) if the `librechat.yaml` configuration file contains validation errors. This fail-fast behavior helps catch configuration issues early in deployment pipelines and prevents running with unintended default settings.

<OptionTable
  options={[
    ['CONFIG_BYPASS_VALIDATION', 'boolean', 'When set to `true`, the server will log a warning and continue starting with default configuration even if `librechat.yaml` has validation errors. This preserves the legacy behavior.', '# CONFIG_BYPASS_VALIDATION=true'],
  ]}
/>

<Callout type="warning" title="Warning">
Using `CONFIG_BYPASS_VALIDATION=true` is not recommended for production environments. It is intended as a temporary workaround while debugging configuration issues. Always fix validation errors in your configuration file.
</Callout>

### Uncaught Exception Handling

By default, LibreChat will exit the process when an uncaught exception occurs, which is the standard Node.js behavior. You can override this to keep the app running after uncaught exceptions.

<OptionTable
  options={[
    ['CONTINUE_ON_UNCAUGHT_EXCEPTION', 'boolean', 'When set to `true`, the app will continue running after encountering uncaught exceptions instead of exiting the process.', '# CONTINUE_ON_UNCAUGHT_EXCEPTION=false'],
  ]}
/>

<Callout type="warning" title="Warning">
Not recommended for production unless necessary. Uncaught exceptions may leave the application in an unpredictable state.
</Callout>

## Endpoints
In this section, you can configure the endpoints and models selection, their API keys, and the proxy and reverse proxy settings for the endpoints that support it.

### General Config
Uncomment `ENDPOINTS` to customize the available endpoints in LibreChat.

<OptionTable
  options={[
    ['ENDPOINTS', 'string', 'Comma-separated list of available endpoints.', '# ENDPOINTS=openAI,agents,assistants,gptPlugins,azureOpenAI,google,anthropic,bingAI,custom'],
    ['PROXY', 'string', 'Proxy setting for all endpoints.', 'PROXY='],
    ['TITLE_CONVO', 'boolean', 'Enable titling for all endpoints.', 'TITLE_CONVO=true'],
  ]}
/>

### Known Endpoints - `librechat.yaml`
- see also: [Custom Endpoints & Configuration](/docs/configuration/librechat_yaml)

<OptionTable
  options={[
    ['ANYSCALE_API_KEY', 'string', 'API key for Anyscale.', '# ANYSCALE_API_KEY='],
    ['APIPIE_API_KEY', 'string', 'API key for Apipie.', '# APIPIE_API_KEY='],
    ['COHERE_API_KEY', 'string', 'API key for Cohere.', '# COHERE_API_KEY='],
    ['FIREWORKS_API_KEY', 'string', 'API key for Fireworks.', '# FIREWORKS_API_KEY='],
    ['GROQ_API_KEY', 'string', 'API key for Groq.', '# GROQ_API_KEY='],
    ['MISTRAL_API_KEY', 'string', 'API key for Mistral.', '# MISTRAL_API_KEY='],
    ['OPENROUTER_KEY', 'string', 'API key for OpenRouter.', '# OPENROUTER_KEY='],
    ['PERPLEXITY_API_KEY', 'string', 'API key for Perplexity.', '# PERPLEXITY_API_KEY='],
    ['SHUTTLEAI_API_KEY', 'string', 'API key for ShuttleAI.', '# SHUTTLEAI_API_KEY='],
    ['TOGETHERAI_API_KEY', 'string', 'API key for TogetherAI.', '# TOGETHERAI_API_KEY='],
    ['DEEPSEEK_API_KEY', 'string', 'API key for Deepseek API', '# DEEPSEEK_API_KEY='],
  ]}
/>

### Web Search

The web search feature enables internet search capabilities within LibreChat.

**Important**: The exact environment variable names shown below are default references and can be customized through the `librechat.yaml` configuration file to use any variable names you prefer.

For detailed configuration and customization options, see: [Web Search Configuration](/docs/configuration/librechat_yaml/object_structure/web_search)

<OptionTable
  options={[
    ['SERPER_API_KEY', 'string', 'API key for Serper search provider. Get your key from https://serper.dev/api-key', '# SERPER_API_KEY='],
    ['FIRECRAWL_API_KEY', 'string', 'API key for Firecrawl scraper service. Get your key from https://docs.firecrawl.dev/introduction#api-key', '# FIRECRAWL_API_KEY='],
    ['FIRECRAWL_API_URL', 'string', 'Custom Firecrawl API URL (optional). Only needed for custom Firecrawl instances.', '# FIRECRAWL_API_URL='],
    ['FIRECRAWL_VERSION', 'string', 'Firecrawl API version (v0 or v1).', '# FIRECRAWL_VERSION=v1'],
    ['JINA_API_KEY', 'string', 'API key for Jina reranker service. Get your key from https://jina.ai/api-dashboard/', '# JINA_API_KEY='],
    ['JINA_API_URL', 'string', 'Custom Jina API URL (optional). Only needed for custom Jina instances.', '# JINA_API_URL='],
    ['COHERE_API_KEY', 'string', 'API key for Cohere reranker service. Get your key from https://dashboard.cohere.com/welcome/login', '# COHERE_API_KEY='],
  ]}
/>

**Note**: These variable names can be customized in your `librechat.yaml` configuration file. For example, you could use `CUSTOM_SERPER_KEY` instead of `SERPER_API_KEY` by configuring it in the web search settings. See the [Web Search Configuration](/docs/configuration/librechat_yaml/object_structure/web_search) documentation for details on customizing variable names.

### Anthropic
see: [Anthropic Endpoint](/docs/configuration/pre_configured_ai/anthropic)
- You can request an access key from https://console.anthropic.com/
- Leave `ANTHROPIC_API_KEY=` blank to disable this endpoint
- Set `ANTHROPIC_API_KEY=` to "user_provided" to allow users to provide their own API key from the WebUI
- If you have access to a reverse proxy for `Anthropic`, you can set it with `ANTHROPIC_REVERSE_PROXY=`
    - leave blank or comment it out to use default base url

<OptionTable
  options={[
    ['ANTHROPIC_API_KEY', 'string', 'Anthropic API key or "user_provided" to allow users to provide their own API key.', 'Defaults to an empty string.'],
    ['ANTHROPIC_MODELS', 'string', 'Comma-separated list of Anthropic models to use.', '# ANTHROPIC_MODELS=claude-3-opus-20240229,claude-3-sonnet-20240229,claude-3-haiku-20240307,claude-2.1,claude-2,claude-1.2,claude-1,claude-1-100k,claude-instant-1,claude-instant-1-100k'],
    ['ANTHROPIC_REVERSE_PROXY', 'string', 'Reverse proxy for Anthropic.', '# ANTHROPIC_REVERSE_PROXY='],
    ['ANTHROPIC_TITLE_MODEL', 'string', 'DEPRECATED: Model to use for titling with Anthropic.', '# ANTHROPIC_TITLE_MODEL=claude-3-haiku-20240307'],
  ]}
/>

- `ANTHROPIC_TITLE_MODEL` is now deprecated and will be removed in future versions. Use the [`titleModel` Endpoint Setting](/docs/configuration/librechat_yaml/object_structure/shared_endpoint_settings#titlemodel) instead in the `librechat.yaml` config instead.

> **Note:** Must be compatible with the Anthropic Endpoint. Also, Claude 2 and Claude 3 models perform best at this task, with `claude-3-haiku` models being the cheapest.

#### Anthropic via Vertex AI

You can also use Anthropic Claude models through Google Cloud Vertex AI. For detailed YAML configuration options, see: [Anthropic Vertex AI Configuration](/docs/configuration/librechat_yaml/object_structure/anthropic_vertex)

<OptionTable
  options={[
    ['ANTHROPIC_USE_VERTEX', 'boolean', 'Set to true to use Anthropic models through Google Vertex AI instead of direct API.', 'ANTHROPIC_USE_VERTEX=true'],
    ['ANTHROPIC_VERTEX_REGION', 'string', 'The Google Cloud region for Vertex AI. Default: us-east5.', 'ANTHROPIC_VERTEX_REGION=us-east5'],
  ]}
/>

> **Note:** When using Vertex AI, you must also configure `GOOGLE_SERVICE_KEY_FILE` (see [Google Configuration](#google)) with a service account that has the `Vertex AI User` role.

### AWS Bedrock

See: [AWS Bedrock Setup](/docs/configuration/pre_configured_ai/bedrock)

<OptionTable
  options={[
    ['BEDROCK_AWS_DEFAULT_REGION', 'string', 'A default AWS region must be provided for Bedrock.', 'BEDROCK_AWS_DEFAULT_REGION=us-east-1'],
    ['BEDROCK_AWS_ACCESS_KEY_ID', 'string', 'AWS access key ID for Bedrock. Optional if using default AWS credentials chain.', '# BEDROCK_AWS_ACCESS_KEY_ID=your_access_key_id'],
    ['BEDROCK_AWS_SECRET_ACCESS_KEY', 'string', 'AWS secret access key for Bedrock. Optional if using default AWS credentials chain.', '# BEDROCK_AWS_SECRET_ACCESS_KEY=your_secret_access_key'],
    ['BEDROCK_AWS_SESSION_TOKEN', 'string', 'AWS session token for temporary credentials. Optional.', '# BEDROCK_AWS_SESSION_TOKEN=your_session_token'],
    ['BEDROCK_AWS_MODELS', 'string', 'Comma-separated list of Bedrock model IDs. If omitted, all known supported models are included.', '# BEDROCK_AWS_MODELS=anthropic.claude-3-5-sonnet-20240620-v1:0,meta.llama3-1-8b-instruct-v1:0'],
  ]}
/>

> **Note:** You can omit the access keys to use the default AWS credentials chain (environment variables, SSO credentials, shared credentials files, or EC2/ECS Instance Metadata Service). See [AWS Bedrock Setup](/docs/configuration/pre_configured_ai/bedrock) for more details.

### BingAI
Bing, also used for Sydney, jailbreak, and Bing Image Creator

<OptionTable
  options={[
    ['BINGAI_TOKEN', 'string', 'Bing access token. Leave blank to disable. Can be set to "user_provided" to allow users to provide their own token from the WebUI.', 'BINGAI_TOKEN=user_provided'],
    ['BINGAI_HOST', 'string', 'Bing host URL. Leave commented out to use default server.', '# BINGAI_HOST=https://cn.bing.com'],
  ]}
/>

Note: It is recommended to leave it as "user_provided" and provide the token from the WebUI.

### Google

Follow these instructions to setup the [Google Endpoint](/docs/configuration/pre_configured_ai/google)

<OptionTable
  options={[
    ['GOOGLE_KEY', 'string', 'Google API key. Set to "user_provided" to allow users to provide their own API key from the WebUI.', 'GOOGLE_KEY=user_provided'],
    ['GOOGLE_SERVICE_KEY_FILE', 'string', 'Path to Google service account JSON key file, URL to fetch it from, or stringified JSON. Used for Vertex AI authentication (e.g., OCR features).', 'GOOGLE_SERVICE_KEY_FILE=/path/to/auth.json'],
    ['GOOGLE_REVERSE_PROXY', 'string', 'Google reverse proxy URL.', 'GOOGLE_REVERSE_PROXY='],
    ['GOOGLE_AUTH_HEADER', 'boolean', 'Use Authorization header instead of X-goog-api-key. Some reverse proxies require this.', '# GOOGLE_AUTH_HEADER=true'],
    ['GOOGLE_MODELS', 'string', 'Available Gemini API Google models, separated by commas.', 'GOOGLE_MODELS=gemini-1.0-pro,gemini-1.0-pro-001,gemini-1.0-pro-latest,gemini-1.0-pro-vision-latest,gemini-1.5-pro-latest,gemini-pro,gemini-pro-vision'],
    ['GOOGLE_MODELS', 'string', 'Available Vertex AI Google models, separated by commas.', 'GOOGLE_MODELS=gemini-1.5-pro-preview-0409,gemini-1.0-pro-vision-001,gemini-pro,gemini-pro-vision,chat-bison,chat-bison-32k,codechat-bison,codechat-bison-32k,text-bison,text-bison-32k,text-unicorn,code-gecko,code-bison,code-bison-32k'],
    ['GOOGLE_TITLE_MODEL', 'string', 'DEPRECATED: The model used for titling with Google.', 'GOOGLE_TITLE_MODEL=gemini-pro'],
    ['GOOGLE_LOC', 'string', 'Specifies the Google Cloud location for processing API requests', 'GOOGLE_LOC=us-central1'],
    ['GOOGLE_CLOUD_LOCATION', 'string', 'Alternative region for Gemini Image Generation (e.g., global).', '# GOOGLE_CLOUD_LOCATION=global'],
    ['GOOGLE_EXCLUDE_SAFETY_SETTINGS', 'string', 'Completely omit the safety settings that are included by default, which will use provider defaults', 'GOOGLE_EXCLUDE_SAFETY_SETTINGS=true'],
    ['GOOGLE_SAFETY_SEXUALLY_EXPLICIT', 'string', 'Safety setting for sexually explicit content. Options are BLOCK_ALL, BLOCK_ONLY_HIGH, WARN_ONLY, and OFF.', 'GOOGLE_SAFETY_SEXUALLY_EXPLICIT=BLOCK_ONLY_HIGH'],
    ['GOOGLE_SAFETY_HATE_SPEECH', 'string', 'Safety setting for hate speech content. Options are BLOCK_ALL, BLOCK_ONLY_HIGH, WARN_ONLY, and OFF.', 'GOOGLE_SAFETY_HATE_SPEECH=BLOCK_ONLY_HIGH'],
    ['GOOGLE_SAFETY_HARASSMENT', 'string', 'Safety setting for harassment content. Options are BLOCK_ALL, BLOCK_ONLY_HIGH, WARN_ONLY, and OFF.', 'GOOGLE_SAFETY_HARASSMENT=BLOCK_ONLY_HIGH'],
    ['GOOGLE_SAFETY_DANGEROUS_CONTENT', 'string', 'Safety setting for dangerous content. Options are BLOCK_ALL, BLOCK_ONLY_HIGH, WARN_ONLY, and OFF.', 'GOOGLE_SAFETY_DANGEROUS_CONTENT=BLOCK_ONLY_HIGH'],
    ['GOOGLE_SAFETY_CIVIC_INTEGRITY', 'string', 'Safety setting for civic integrity content. Options are BLOCK_ALL, BLOCK_ONLY_HIGH, WARN_ONLY, and OFF.', '# GOOGLE_SAFETY_CIVIC_INTEGRITY=BLOCK_ONLY_HIGH'],
  ]}
/>

Customize the available models, separated by commas, **without spaces**. The first will be default. Leave it blank or commented out to use internal settings.

- `GOOGLE_TITLE_MODEL` is now deprecated and will be removed in future versions. Use the [`titleModel` Endpoint Setting](/docs/configuration/librechat_yaml/object_structure/shared_endpoint_settings#titlemodel) instead in the `librechat.yaml` config instead.

**Note:** For the Vertex AI `GOOGLE_SAFETY` variables, you do not have access to the `BLOCK_NONE` setting by default. To use this restricted `HarmBlockThreshold` setting, you will need to either:
- (a) Get access through an allowlist via your Google account team
- (b) Switch your account type to monthly invoiced billing following this instruction:
    https://cloud.google.com/billing/docs/how-to/invoiced-billing

#### Gemini Image Generation

Gemini Image Generation is a tool for Agents that supports both the Gemini API and Vertex AI. See: [Gemini Image Generation](/docs/configuration/tools/gemini_image_gen)

<OptionTable
  options={[
    ['GEMINI_API_KEY', 'string', 'Dedicated Gemini API key for image generation. Falls back to GOOGLE_KEY if not set.', '# GEMINI_API_KEY=your_gemini_api_key'],
    ['GEMINI_VERTEX_ENABLED', 'boolean', 'Enable Vertex AI for Gemini image generation. Uses service account authentication.', '# GEMINI_VERTEX_ENABLED=true'],
    ['GEMINI_IMAGE_MODEL', 'string', 'Gemini model for image generation. Default: gemini-2.5-flash-image.', '# GEMINI_IMAGE_MODEL=gemini-2.5-flash-image'],
  ]}
/>

> **Note:** When using Vertex AI (`GEMINI_VERTEX_ENABLED=true`), you must also configure `GOOGLE_SERVICE_KEY_FILE` with a service account that has the `Vertex AI User` role. No API key is required.

### OpenAI

See: [OpenAI Setup](/docs/configuration/pre_configured_ai/openai)

<OptionTable
  options={[
    ['OPENAI_API_KEY', 'string', 'Your OpenAI API key. Leave blank to disable this endpoint or set to "user_provided" to allow users to provide their own API key from the WebUI.', 'OPENAI_API_KEY=user_provided'],
    ['OPENAI_MODELS', 'string', 'Customize the available models, separated by commas, without spaces. The first will be default. Leave commented out to use internal settings.', '# OPENAI_MODELS=gpt-3.5-turbo-0125,gpt-3.5-turbo-0301,gpt-3.5-turbo,gpt-4,gpt-4-0613,gpt-4-vision-preview,gpt-3.5-turbo-0613,gpt-3.5-turbo-16k-0613,gpt-4-0125-preview,gpt-4-turbo-preview,gpt-4-1106-preview,gpt-3.5-turbo-1106,gpt-3.5-turbo-instruct,gpt-3.5-turbo-instruct-0914,gpt-3.5-turbo-16k'],
    ['DEBUG_OPENAI', 'boolean', 'Enable debug mode for the OpenAI endpoint.', 'DEBUG_OPENAI=false'],
    ['OPENAI_SUMMARIZE', 'boolean', 'Enable message summarization. False by default', '# OPENAI_SUMMARIZE=true'],
    ['OPENAI_SUMMARY_MODEL', 'string', 'The model used for OpenAI summarization.', '# OPENAI_SUMMARY_MODEL=gpt-3.5-turbo'],
    ['OPENAI_FORCE_PROMPT', 'boolean', 'Force the API to be called with a prompt payload instead of a messages payload.', '# OPENAI_FORCE_PROMPT=false'],
    ['OPENAI_ORGANIZATION', 'string', 'Specify which organization to use for each API request to OpenAI. Optional', '# OPENAI_ORGANIZATION='],
    ['OPENAI_REVERSE_PROXY', 'string', 'DEPRECATED: Reverse proxy settings for OpenAI.', '# OPENAI_REVERSE_PROXY='],
    ['OPENAI_TITLE_MODEL', 'string', 'DEPRECATED: The model used for OpenAI titling.', '# OPENAI_TITLE_MODEL=gpt-3.5-turbo'],
  ]}
/>

- `OPENAI_TITLE_MODEL` is now deprecated and will be removed in future versions. Use the [`titleModel` Endpoint Setting](/docs/configuration/librechat_yaml/object_structure/shared_endpoint_settings#titlemodel) instead in the `librechat.yaml` config instead.
- `OPENAI_REVERSE_PROXY` is now deprecated and will be removed in future versions. Use a [custom endpoint](/docs/quick_start/custom_endpoints) instead.

### Assistants

See: [Assistants Setup](/docs/configuration/pre_configured_ai/assistants)

<OptionTable
  options={[
    ['ASSISTANTS_API_KEY', 'string', 'Your OpenAI API key for Assistants API. Leave blank to disable this endpoint or set to "user_provided" to allow users to provide their own API key from the WebUI.', 'ASSISTANTS_API_KEY=user_provided'],
    ['ASSISTANTS_MODELS', 'string', 'Customize the available models, separated by commas, without spaces. The first will be default. Leave blank to use internal settings.', '# ASSISTANTS_MODELS=gpt-3.5-turbo-0125,gpt-3.5-turbo-16k-0613,gpt-3.5-turbo-16k,gpt-3.5-turbo,gpt-4,gpt-4-0314,gpt-4-32k-0314,gpt-4-0613,gpt-3.5-turbo-0613,gpt-3.5-turbo-1106,gpt-4-0125-preview,gpt-4-turbo-preview,gpt-4-1106-preview'],
    ['ASSISTANTS_BASE_URL', 'string', 'Alternate base URL for Assistants API.', '# ASSISTANTS_BASE_URL='],
  ]}
/>

Note: You can customize the available models, separated by commas, without spaces. The first will be default. Leave it blank or commented out to use internal settings.

### Tavily

Get your API key here: **[https://tavily.com/#api](https://tavily.com/#api)**

**Environment Variables:**

<OptionTable
  options={[    ['TAVILY_API_KEY', 'string', 'Tavily API key.','TAVILY_API_KEY='],
  ]}
/>

### Traversaal

**Description:** LLM-enhanced search tool.

Get API key here: **https://api.traversaal.ai/dashboard**

**Environment Variables:**

<OptionTable
  options={[
    ['TRAVERSAAL_API_KEY', 'string', 'Traversaal API key.','TRAVERSAAL_API_KEY='],
  ]}
/>

### WolframAlpha

See detailed instructions here: **[Wolfram Alpha](/docs/configuration/tools/wolfram)**

**Environment Variables:**

<OptionTable
  options={[
    ['WOLFRAM_APP_ID', 'string', 'Wolfram Alpha App ID.','WOLFRAM_APP_ID='],
  ]}
/>

### Zapier

**Description:** - You need a Zapier account. Get your API key from here: **[Zapier](https://nla.zapier.com/credentials/)**
- Create allowed actions - Follow step 3 in this getting start guide from Zapier

**Note:** Zapier is known to be finicky with certain actions. Writing email drafts is probably the best use of it.

**Environment Variables:**

<OptionTable
  options={[
    ['ZAPIER_NLA_API_KEY', 'string', 'Zapier NLA API key.','ZAPIER_NLA_API_KEY='],
  ]}
/>

### OpenWeather

See detailed instructions here: **[OpenWeather](/docs/configuration/tools/openweather)**

<OptionTable
  options={[
    ['OPENWEATHER_API_KEY', 'string', 'OpenWeather API key for the One Call API 3.0.','OPENWEATHER_API_KEY='],
  ]}
/>

## Code Interpreter

The Code Interpreter API provides a secure environment for executing code and managing files. See: [Code Interpreter API](/docs/features/code_interpreter)

<OptionTable
  options={[
    ['LIBRECHAT_CODE_API_KEY', 'string', 'API key for the Code Interpreter service. When set globally, provides access to all users.', 'LIBRECHAT_CODE_API_KEY=your-api-key'],
    ['LIBRECHAT_CODE_BASEURL', 'string', 'Custom base URL for the Code Interpreter API (Enterprise plans only).', '# LIBRECHAT_CODE_BASEURL=https://your-custom-domain.com'],
  ]}
/>

## Artifacts

Artifacts leverage the CodeSandbox library for secure rendering of HTML/JS code. By default, the public CDN hosted by CodeSandbox is used.

Fortunately, for those with internal network requirements, you can [self-host the bundler](https://sandpack.codesandbox.io/docs/guides/hosting-the-bundler) that compiles the frontend code and specify a custom bundler URL for Sandpack.

For more info, including pre-made container images for self-hosting with metric requests removed, see: https://github.com/LibreChat-AI/codesandbox-client

<OptionTable
  options={[
    ['SANDPACK_BUNDLER_URL', 'string', 'Specifies a custom bundler URL for Sandpack, used by Artifacts','SANDPACK_BUNDLER_URL=your-bundler-url'],
  ]}
/>

## Search (Meilisearch)

Enables search in messages and conversations:

<OptionTable
  options={[
    ['SEARCH', 'boolean', 'Enables search in messages and conversations.','SEARCH=true'],
  ]}
/>

> Note: If you're not using docker, it requires the installation of the free self-hosted Meilisearch or a paid remote plan

To disable anonymized telemetry analytics for MeiliSearch for absolute privacy, set to true:

<OptionTable
  options={[
    ['MEILI_NO_ANALYTICS', 'boolean', 'Disables anonymized telemetry analytics for MeiliSearch.','MEILI_NO_ANALYTICS=true'],
  ]}
/>

For the API server to connect to the search server. Replace '0.0.0.0' with 'meilisearch' if serving MeiliSearch with docker-compose.

<OptionTable
  options={[
    ['MEILI_HOST', 'string', 'The API server connection to the search server.','MEILI_HOST=http://0.0.0.0:7700'],
  ]}
/>

This master key must be at least 16 bytes, composed of valid UTF-8 characters. MeiliSearch will throw an error and refuse to launch if no master key is provided or if it is under 16 bytes. MeiliSearch will suggest a secure autogenerated master key. This is a ready-made secure key for docker-compose, you can replace it with your own.

<OptionTable
  options={[
    ['MEILI_MASTER_KEY', 'string', 'The master key for MeiliSearch.','MEILI_MASTER_KEY=DrhYf7zENyR6AlUCKmnz0eYASOQdl6zxH7s7MKFSfFCt'],
  ]}
/>

To prevent LibreChat from attempting a database indexing sync with Meilisearch, you can set the following environment variable to `true`. This is useful in a node cluster, or multi-node setup, where only one instance should be responsible for indexing.

<OptionTable
  options={[
    ['MEILI_NO_SYNC', 'string', 'Toggle for disabling Mellisearch index sync','MEILI_NO_SYNC=true'],
  ]}
/>

## RAG API

Configure Retrieval-Augmented Generation for document indexing and context-aware responses. See: **[RAG API Configuration](/docs/configuration/rag_api)**

<OptionTable
  options={[
    ['RAG_API_URL', 'string', 'URL of the RAG API service.', 'RAG_API_URL=http://host.docker.internal:8000'],
    ['RAG_OPENAI_API_KEY', 'string', 'OpenAI API key for RAG embeddings. Overrides OPENAI_API_KEY for RAG.', '# RAG_OPENAI_API_KEY=sk-your-openai-api-key'],
    ['RAG_OPENAI_BASEURL', 'string', 'Custom OpenAI base URL for RAG embeddings.', '# RAG_OPENAI_BASEURL='],
    ['RAG_USE_FULL_CONTEXT', 'boolean', 'Fetch entire file context instead of top 4 results. Default: false.', '# RAG_USE_FULL_CONTEXT=true'],
    ['EMBEDDINGS_PROVIDER', 'string', 'Embeddings provider: openai, azure, huggingface, huggingfacetei, or ollama. Default: openai.', '# EMBEDDINGS_PROVIDER=openai'],
    ['EMBEDDINGS_MODEL', 'string', 'Embeddings model to use. Default depends on provider.', '# EMBEDDINGS_MODEL=text-embedding-3-small'],
  ]}
/>

> **Note:** When using the default Docker setup, the `.env` file is shared between LibreChat and the RAG API. For complete configuration options, see the [RAG API documentation](/docs/configuration/rag_api).

## Speech to Text & Text to Speech

Configure Speech-to-Text (STT) and Text-to-Speech (TTS) services. See: **[Speech Settings](/docs/configuration/stt_tts)**

<OptionTable
  options={[
    ['STT_API_KEY', 'string', 'API key for Speech-to-Text service (e.g., OpenAI Whisper).', '# STT_API_KEY='],
    ['TTS_API_KEY', 'string', 'API key for Text-to-Speech service (e.g., OpenAI TTS).', '# TTS_API_KEY='],
  ]}
/>

> **Note:** STT and TTS are primarily configured through the `speech:` section in `librechat.yaml`. These environment variables are referenced in that configuration. See [Speech Settings](/docs/configuration/stt_tts) for full YAML configuration options.

## Shared Links

Configure shared conversation links functionality.

<OptionTable
  options={[
    ['ALLOW_SHARED_LINKS', 'boolean', 'Enable or disable shared conversation links. Default: true.', 'ALLOW_SHARED_LINKS=true'],
    ['ALLOW_SHARED_LINKS_PUBLIC', 'boolean', 'Allow shared links to be publicly accessible. Default: true.', 'ALLOW_SHARED_LINKS_PUBLIC=true'],
  ]}
/>

## User System
This section contains the configuration for:

  - [Automated Moderation](#moderation)
  - [Balance/Token Usage](#balance)
  - [Registration and Social Logins](#registration-and-login)
  - [Email Password Reset](#email-password-reset)

### Moderation
The Automated Moderation System uses a scoring mechanism to track user violations. As users commit actions like excessive logins, registrations, or messaging, they accumulate violation scores. Upon reaching a set threshold, the user and their IP are temporarily banned. This system ensures platform security by monitoring and penalizing rapid or suspicious activities.

see: **[Automated Moderation](/docs/configuration/mod_system)**

#### Basic Moderation Settings
<OptionTable
  options={[
    ['OPENAI_MODERATION', 'boolean', 'Whether or not to enable OpenAI moderation on the **OpenAI** and **Plugins** endpoints.','OPENAI_MODERATION=false'],
    ['OPENAI_MODERATION_API_KEY', 'string', 'Your OpenAI API key.','OPENAI_MODERATION_API_KEY='],
    ['OPENAI_MODERATION_REVERSE_PROXY', 'string', 'Note: Commented out by default, this is not working with all reverse proxys.','# OPENAI_MODERATION_REVERSE_PROXY='],
  ]}
/>

#### Banning Settings
<OptionTable
  options={[
    ['BAN_VIOLATIONS', 'boolean', 'Whether or not to enable banning users for violations (they will still be logged).','BAN_VIOLATIONS=true'],
    ['BAN_DURATION', 'integer', 'How long the user and associated IP are banned for (in milliseconds).','BAN_DURATION=1000 * 60 * 60 * 2'],
    ['BAN_INTERVAL', 'integer', 'The user will be banned every time their score reaches/crosses over the interval threshold.','BAN_INTERVAL=20'],
  ]}
/>

#### Login and registration rate limiting

Prevents brute force attacks and spam registrations by limiting login attempts and new account registrations.

<OptionTable
  options={[
    ['LOGIN_MAX', 'integer', 'The max amount of logins allowed per IP per LOGIN_WINDOW.','LOGIN_MAX=7'],
    ['LOGIN_WINDOW', 'integer', 'In minutes, determines the window of time for LOGIN_MAX logins.','LOGIN_WINDOW=5'],
    ['REGISTER_MAX', 'integer', 'The max amount of registrations allowed per IP per REGISTER_WINDOW.','REGISTER_MAX=5'],
    ['REGISTER_WINDOW', 'integer', 'In minutes, determines the window of time for REGISTER_MAX registrations.','REGISTER_WINDOW=60'],
  ]}
/>

#### Score for each violation
<OptionTable
  options={[
    ['LOGIN_VIOLATION_SCORE', 'integer', 'Score for login violations.','LOGIN_VIOLATION_SCORE=1'],
    ['REGISTRATION_VIOLATION_SCORE', 'integer', 'Score for registration violations.','REGISTRATION_VIOLATION_SCORE=1'],
    ['CONCURRENT_VIOLATION_SCORE', 'integer', 'Score for concurrent violations.','CONCURRENT_VIOLATION_SCORE=1'],
    ['MESSAGE_VIOLATION_SCORE', 'integer', 'Score for message violations.','MESSAGE_VIOLATION_SCORE=1'],
    ['NON_BROWSER_VIOLATION_SCORE', 'integer', 'Score for non-browser violations.','NON_BROWSER_VIOLATION_SCORE=20'],
    ['ILLEGAL_MODEL_REQ_SCORE', 'integer', 'Score for illegal model requests.','ILLEGAL_MODEL_REQ_SCORE=5'],
    ['IMPORT_VIOLATION_SCORE', 'integer', 'Score for import conversation violations.','IMPORT_VIOLATION_SCORE=1'],
    ['FORK_VIOLATION_SCORE', 'integer', 'Score for conversation fork violations.','FORK_VIOLATION_SCORE=1'],
    ['TTS_VIOLATION_SCORE', 'integer', 'Score for text-to-speech violations.','TTS_VIOLATION_SCORE=0'],
    ['STT_VIOLATION_SCORE', 'integer', 'Score for speech-to-text violations.','STT_VIOLATION_SCORE=0'],
    ['FILE_UPLOAD_VIOLATION_SCORE', 'integer', 'Score for file upload violations.','FILE_UPLOAD_VIOLATION_SCORE=0'],
    ['RESET_PASSWORD_VIOLATION_SCORE', 'integer', 'Score for password reset violations.','RESET_PASSWORD_VIOLATION_SCORE=0'],
    ['VERIFY_EMAIL_VIOLATION_SCORE', 'integer', 'Score for email verification violations.','VERIFY_EMAIL_VIOLATION_SCORE=0'],
    ['TOOL_CALL_VIOLATION_SCORE', 'integer', 'Score for tool call violations.','TOOL_CALL_VIOLATION_SCORE=0'],
    ['CONVO_ACCESS_VIOLATION_SCORE', 'integer', 'Score for conversation access violations.','CONVO_ACCESS_VIOLATION_SCORE=0'],
  ]}
/>

> Note: Non-browser access and Illegal model requests are almost always nefarious as it means a 3rd party is attempting to access the server through an automated script.


#### Message rate limiting (per user & IP)

<OptionTable
  options={[
    ['LIMIT_CONCURRENT_MESSAGES', 'boolean', 'Whether to limit the amount of messages a user can send per request.','LIMIT_CONCURRENT_MESSAGES=true'],
    ['CONCURRENT_MESSAGE_MAX', 'integer', 'The max amount of messages a user can send per request.','CONCURRENT_MESSAGE_MAX=2'],
  ]}
/>

#### Limiters

> Note: You can utilize both limiters, but default is to limit by IP only.

##### IP Limiter:

<OptionTable
  options={[
    ['LIMIT_MESSAGE_IP', 'boolean', 'Whether to limit the amount of messages an IP can send per `MESSAGE_IP_WINDOW`.','LIMIT_MESSAGE_IP=true'],
    ['MESSAGE_IP_MAX', 'integer', 'The max amount of messages an IP can send per `MESSAGE_IP_WINDOW`.','MESSAGE_IP_MAX=40'],
    ['MESSAGE_IP_WINDOW', 'integer', 'In minutes, determines the window of time for `MESSAGE_IP_MAX` messages.','MESSAGE_IP_WINDOW=1'],
  ]}
/>

##### User Limiter:

<OptionTable
  options={[
    ['LIMIT_MESSAGE_USER', 'boolean', 'Whether to limit the amount of messages an user can send per `MESSAGE_USER_WINDOW`.','LIMIT_MESSAGE_USER=false'],
    ['MESSAGE_USER_MAX', 'integer', 'The max amount of messages an user can send per `MESSAGE_USER_WINDOW`.','MESSAGE_USER_MAX=40'],
    ['MESSAGE_USER_WINDOW', 'integer', 'In minutes, determines the window of time for `MESSAGE_USER_MAX` messages.','MESSAGE_USER_WINDOW=1'],
  ]}
/>

#### Import conversation rate limiting

Limits how often users can import conversations to prevent abuse.

> Note: You can utilize both limiters, but default is to limit by IP only.

##### IP Limiter:

<OptionTable
  options={[
    ['LIMIT_IMPORT_IP', 'boolean', 'Whether to limit the amount of conversation imports an IP can perform per `IMPORT_IP_WINDOW`.','LIMIT_IMPORT_IP=true'],
    ['IMPORT_IP_MAX', 'integer', 'The max amount of conversation imports an IP can perform per `IMPORT_IP_WINDOW`.','IMPORT_IP_MAX=100'],
    ['IMPORT_IP_WINDOW', 'integer', 'In minutes, determines the window of time for `IMPORT_IP_MAX` imports.','IMPORT_IP_WINDOW=1'],
  ]}
/>

##### User Limiter:

<OptionTable
  options={[
    ['LIMIT_IMPORT_USER', 'boolean', 'Whether to limit the amount of conversation imports a user can perform per `IMPORT_USER_WINDOW`.','LIMIT_IMPORT_USER=false'],
    ['IMPORT_USER_MAX', 'integer', 'The max amount of conversation imports a user can perform per `IMPORT_USER_WINDOW`.','IMPORT_USER_MAX=50'],
    ['IMPORT_USER_WINDOW', 'integer', 'In minutes, determines the window of time for `IMPORT_USER_MAX` imports.','IMPORT_USER_WINDOW=1'],
  ]}
/>

#### Conversation forking rate limiting

Limits how often users can fork conversations to prevent abuse.

> Note: You can utilize both limiters, but default is to limit by IP only.

##### IP Limiter:

<OptionTable
  options={[
    ['LIMIT_FORK_IP', 'boolean', 'Whether to limit the amount of conversation forks an IP can create per `FORK_IP_WINDOW`.','LIMIT_FORK_IP=true'],
    ['FORK_IP_MAX', 'integer', 'The max amount of conversation forks an IP can create per `FORK_IP_WINDOW`.','FORK_IP_MAX=30'],
    ['FORK_IP_WINDOW', 'integer', 'In minutes, determines the window of time for `FORK_IP_MAX` forks.','FORK_IP_WINDOW=1'],
  ]}
/>

##### User Limiter:

<OptionTable
  options={[
    ['LIMIT_FORK_USER', 'boolean', 'Whether to limit the amount of conversation forks a user can create per `FORK_USER_WINDOW`.','LIMIT_FORK_USER=false'],
    ['FORK_USER_MAX', 'integer', 'The max amount of conversation forks a user can create per `FORK_USER_WINDOW`.','FORK_USER_MAX=7'],
    ['FORK_USER_WINDOW', 'integer', 'In minutes, determines the window of time for `FORK_USER_MAX` forks.','FORK_USER_WINDOW=1'],
  ]}
/>

#### File upload rate limiting

Limits how often users can upload files to prevent abuse.

> Note: These can also be configured via `librechat.yaml` in the `rateLimits.fileUploads` section.

##### IP Limiter:

<OptionTable
  options={[
    ['FILE_UPLOAD_IP_MAX', 'integer', 'Max file uploads per IP per `FILE_UPLOAD_IP_WINDOW`. Default: 100.','# FILE_UPLOAD_IP_MAX=100'],
    ['FILE_UPLOAD_IP_WINDOW', 'integer', 'In minutes, determines the window of time for `FILE_UPLOAD_IP_MAX`. Default: 15.','# FILE_UPLOAD_IP_WINDOW=15'],
  ]}
/>

##### User Limiter:

<OptionTable
  options={[
    ['FILE_UPLOAD_USER_MAX', 'integer', 'Max file uploads per user per `FILE_UPLOAD_USER_WINDOW`. Default: 50.','# FILE_UPLOAD_USER_MAX=50'],
    ['FILE_UPLOAD_USER_WINDOW', 'integer', 'In minutes, determines the window of time for `FILE_UPLOAD_USER_MAX`. Default: 15.','# FILE_UPLOAD_USER_WINDOW=15'],
  ]}
/>

#### TTS (Text-to-Speech) rate limiting

Limits how often users can use Text-to-Speech to prevent abuse.

> Note: These can also be configured via `librechat.yaml` in the `rateLimits.tts` section.

##### IP Limiter:

<OptionTable
  options={[
    ['TTS_IP_MAX', 'integer', 'Max TTS requests per IP per `TTS_IP_WINDOW`. Default: 100.','# TTS_IP_MAX=100'],
    ['TTS_IP_WINDOW', 'integer', 'In minutes, determines the window of time for `TTS_IP_MAX`. Default: 1.','# TTS_IP_WINDOW=1'],
  ]}
/>

##### User Limiter:

<OptionTable
  options={[
    ['TTS_USER_MAX', 'integer', 'Max TTS requests per user per `TTS_USER_WINDOW`. Default: 50.','# TTS_USER_MAX=50'],
    ['TTS_USER_WINDOW', 'integer', 'In minutes, determines the window of time for `TTS_USER_MAX`. Default: 1.','# TTS_USER_WINDOW=1'],
  ]}
/>

#### STT (Speech-to-Text) rate limiting

Limits how often users can use Speech-to-Text to prevent abuse.

> Note: These can also be configured via `librechat.yaml` in the `rateLimits.stt` section.

##### IP Limiter:

<OptionTable
  options={[
    ['STT_IP_MAX', 'integer', 'Max STT requests per IP per `STT_IP_WINDOW`. Default: 100.','# STT_IP_MAX=100'],
    ['STT_IP_WINDOW', 'integer', 'In minutes, determines the window of time for `STT_IP_MAX`. Default: 1.','# STT_IP_WINDOW=1'],
  ]}
/>

##### User Limiter:

<OptionTable
  options={[
    ['STT_USER_MAX', 'integer', 'Max STT requests per user per `STT_USER_WINDOW`. Default: 50.','# STT_USER_MAX=50'],
    ['STT_USER_WINDOW', 'integer', 'In minutes, determines the window of time for `STT_USER_MAX`. Default: 1.','# STT_USER_WINDOW=1'],
  ]}
/>

### Balance

The following feature allows for the management of user balances within the system's endpoints. You have the option to add balances manually, or you may choose to implement a system that accumulates balances automatically for users. If a specific initial balance is defined in the configuration, tokens will be credited to the user's balance automatically when they register.

see: **[Token Usage](/docs/configuration/token_usage)**

<OptionTable
  options={[
    ['CHECK_BALANCE', 'boolean', 'Enable token credit balances for the OpenAI/Plugins endpoints.','CHECK_BALANCE=false'],
    ['START_BALANCE', 'integer', 'If the value is set, tokens will be credited to the user\'s balance after registration.', 'START_BALANCE=20000']
  ]}
/>

#### Managing Balances

- Run `npm run add-balance` to manually add balances.
    - You can also specify the email and token credit amount to add, e.g.: `npm run add-balance example@example.com 1000`
- Run `npm run set-balance` to manually set balances, similar to `add-balance`.
- Run `npm run list-balances` to list the balance of every user.

> **Note:** 1000 credits = $0.001 (1 mill USD)


### Registration and Login
see: **[Authentication System](/docs/configuration/authentication)**

<div style={{display: "flex", justifyContent: "center", alignItems: "center", flexDirection: "column"}}>
  <div className="image-light-theme">
    <img src="https://github.com/danny-avila/LibreChat/assets/32828263/4c51dc25-31d3-4c51-8c2a-0cdfb5a25033" style={{ width: "75%", height: "75%" }} alt="Image for Light Theme" />
  </div>

  <div className="image-dark-theme">
    <img src="https://github.com/danny-avila/LibreChat/assets/32828263/3bc5371d-e51d-4e91-ac68-56db6e85bb2c" style={{ width: "75%", height: "75%" }} alt="Image for Dark Theme" />
  </div>
</div>

<Callout type="info" title="Configuration File Clarification">
All authentication settings in this section should be configured in your `.env` file, not in the `librechat.yaml` file or `docker-compose.override.yml`. The `docker-compose.override.yml` file is only used to mount volumes and set environment variables for Docker, while the `librechat.yaml` file is used for custom endpoints and other application settings.
</Callout>

- General Settings:

<OptionTable
  options={[
    ['ALLOW_EMAIL_LOGIN', 'boolean', 'Enable or disable ONLY email login.','ALLOW_EMAIL_LOGIN=true'],
    ['ALLOW_REGISTRATION', 'boolean', 'Enable or disable Email registration of new users.','ALLOW_REGISTRATION=true'],
    ['ALLOW_SOCIAL_LOGIN', 'boolean', 'Allow users to connect to LibreChat with various social networks.','ALLOW_SOCIAL_LOGIN=false'],
    ['ALLOW_SOCIAL_REGISTRATION', 'boolean', 'Enable or disable registration of new users using various social networks.','ALLOW_SOCIAL_REGISTRATION=false'],
    ['ALLOW_PASSWORD_RESET', 'boolean', 'Enable or disable the ability for users to reset their password by themselves','ALLOW_PASSWORD_RESET=false'],
    ['ALLOW_ACCOUNT_DELETION', 'boolean', 'Enable or disable the ability for users to delete their account by themselves. Enabled by default if omitted/commented out','ALLOW_ACCOUNT_DELETION=true'],
    ['ALLOW_UNVERIFIED_EMAIL_LOGIN', 'boolean', 'Set to true to allow users to log in without verifying their email address. If set to false, users will be required to verify their email before logging in.', 'ALLOW_UNVERIFIED_EMAIL_LOGIN=true'],
    ['MIN_PASSWORD_LENGTH', 'number', 'Minimum password length for user authentication. When using LDAP authentication, you may want to set this to 1 to bypass local password validation, as LDAP servers handle their own password policies.', 'MIN_PASSWORD_LENGTH=8'],
  ]}
/>

> **Quick Tip:** Even with registration disabled, add users directly to the database using `npm run create-user`.
> **Quick Tip:** With registration disabled, you can delete a user with `npm run delete-user email@domain.com`.

- Session and Refresh Token Settings:

<OptionTable
  options={[
    ['SESSION_EXPIRY', 'integer (milliseconds)', 'Session expiry time.','SESSION_EXPIRY=1000 * 60 * 15'],
    ['REFRESH_TOKEN_EXPIRY', 'integer (milliseconds)', 'Refresh token expiry time.','REFRESH_TOKEN_EXPIRY=(1000 * 60 * 60 * 24) * 7'],
  ]}
/>

- For more information: **[Refresh Token](https://github.com/danny-avila/LibreChat/pull/927)**

- JWT Settings:

You should use new secure values. The examples given are 32-byte keys (64 characters in hex).
Use this replit to generate some quickly: **[JWT Keys](/toolkit/creds_generator)**

<OptionTable
  options={[
    ['JWT_SECRET', 'string (hex)', 'JWT secret key.','JWT_SECRET=16f8c0ef4a5d391b26034086c628469d3f9f497f08163ab9b40137092f2909ef'],
    ['JWT_REFRESH_SECRET', 'string (hex)', 'JWT refresh secret key.','JWT_REFRESH_SECRET=eaa5191f2914e30b9387fd84e254e4ba6fc51b4654968a9b0803b456a54b8418'],
  ]}
/>

### Social Logins
For more details: [OAuth2-OIDC](/docs/configuration/authentication/OAuth2-OIDC)

#### Apple Authentication

For more information: **[Apple Authentication](/docs/configuration/authentication/OAuth2-OIDC/apple)**

<OptionTable
  options={[
    ['APPLE_CLIENT_ID', 'string', 'Your Apple Services ID (e.g., com.yourdomain.librechat.services).', 'APPLE_CLIENT_ID=com.yourdomain.librechat.services'],
    ['APPLE_TEAM_ID', 'string', 'Your Apple Developer Team ID.', 'APPLE_TEAM_ID=YOUR_TEAM_ID'],
    ['APPLE_KEY_ID', 'string', 'Your Apple Key ID from the downloaded key.', 'APPLE_KEY_ID=YOUR_KEY_ID'],
    ['APPLE_PRIVATE_KEY_PATH', 'string', 'Absolute path to your downloaded .p8 file.', 'APPLE_PRIVATE_KEY_PATH=/path/to/AuthKey.p8'],
    ['APPLE_CALLBACK_URL', 'string', 'The callback URL for Apple authentication.', 'APPLE_CALLBACK_URL=/oauth/apple/callback'],
  ]}
/>


#### Discord Authentication

For more information: **[Discord](/docs/configuration/authentication/OAuth2-OIDC/discord)**

<OptionTable
  options={[
    ['DISCORD_CLIENT_ID', 'string', 'Your Discord client ID.','DISCORD_CLIENT_ID='],
    ['DISCORD_CLIENT_SECRET', 'string', 'Your Discord client secret.','DISCORD_CLIENT_SECRET='],
    ['DISCORD_CALLBACK_URL', 'string', 'The callback URL for Discord authentication.','DISCORD_CALLBACK_URL=/oauth/discord/callback'],
  ]}
/>

#### Facebook Authentication

For more information: **[Facebook Authentication](/docs/configuration/authentication/OAuth2-OIDC/facebook)**

<OptionTable
  options={[
    ['FACEBOOK_CLIENT_ID', 'string', 'Your Facebook client ID.','FACEBOOK_CLIENT_ID='],
    ['FACEBOOK_CLIENT_SECRET', 'string', 'Your Facebook client secret.','FACEBOOK_CLIENT_SECRET='],
    ['FACEBOOK_CALLBACK_URL', 'string', 'The callback URL for Facebook authentication.','FACEBOOK_CALLBACK_URL=/oauth/facebook/callback'],
  ]}
/>

#### GitHub Authentication

For more information: **[GitHub Authentication](/docs/configuration/authentication/OAuth2-OIDC/github)**

<OptionTable
  options={[
    ['GITHUB_CLIENT_ID', 'string', 'Your GitHub client ID.','GITHUB_CLIENT_ID='],
    ['GITHUB_CLIENT_SECRET', 'string', 'Your GitHub client secret.','GITHUB_CLIENT_SECRET='],
    ['GITHUB_CALLBACK_URL', 'string', 'The callback URL for GitHub authentication.','GITHUB_CALLBACK_URL=/oauth/github/callback'],
    ['GITHUB_ENTERPRISE_BASE_URL', 'string', 'Optional: The base URL for your GitHub Enterprise instance.', 'GITHUB_ENTERPRISE_BASE_URL='],
    ['GITHUB_ENTERPRISE_USER_AGENT', 'string', 'Optional: The user agent for GitHub Enterprise requests.', 'GITHUB_ENTERPRISE_USER_AGENT='],
  ]}
/>

#### Google Authentication

For more information: **[Google Authentication](/docs/configuration/authentication/OAuth2-OIDC/google)**

<OptionTable
  options={[
    ['GOOGLE_CLIENT_ID', 'string', 'Your Google client ID.','GOOGLE_CLIENT_ID='],
    ['GOOGLE_CLIENT_SECRET', 'string', 'Your Google client secret.','GOOGLE_CLIENT_SECRET='],
    ['GOOGLE_CALLBACK_URL', 'string', 'The callback URL for Google authentication.','GOOGLE_CALLBACK_URL=/oauth/google/callback'],
  ]}
/>

#### OpenID Connect

For more information:
  - [Auth0](/docs/configuration/authentication/OAuth2-OIDC/auth0)
  - [AWS Cognito](/docs/configuration/authentication/OAuth2-OIDC/aws)
  - [Azure Entra/AD](/docs/configuration/authentication/OAuth2-OIDC/azure)
  - [Keycloak](/docs/configuration/authentication/OAuth2-OIDC/keycloak)

<OptionTable
  options={[
    ['OPENID_CLIENT_ID', 'string', 'Your OpenID client ID.','OPENID_CLIENT_ID='],
    ['OPENID_CLIENT_SECRET', 'string', 'Your OpenID client secret.','OPENID_CLIENT_SECRET='],
    ['OPENID_ISSUER', 'string', 'The OpenID issuer URL.','OPENID_ISSUER='],
    ['OPENID_SESSION_SECRET', 'string', 'The secret for OpenID session storage.','OPENID_SESSION_SECRET='],
    ['OPENID_SCOPE', 'string', 'The OpenID scope.', 'OPENID_SCOPE="openid profile email"'],
    ['OPENID_CALLBACK_URL', 'string', 'The callback URL for OpenID authentication.','OPENID_CALLBACK_URL=/oauth/openid/callback'],
    ['OPENID_AUDIENCE', 'string', 'The audience parameter for authorization requests. Required for Auth0 when using OPENID_REUSE_TOKENS=true to receive JWT access tokens instead of opaque tokens.','OPENID_AUDIENCE=https://api.librechat.com'],
    ['OPENID_REQUIRED_ROLE', 'string', 'The required role(s) for validation. Supports a single role or multiple comma-separated roles. When multiple roles are specified, the user needs ANY of the specified roles (OR logic).','OPENID_REQUIRED_ROLE=admin or OPENID_REQUIRED_ROLE=role1,role2,admin'],
    ['OPENID_REQUIRED_ROLE_TOKEN_KIND', 'string', 'The token kind for required role validation.','OPENID_REQUIRED_ROLE_TOKEN_KIND='],
    ['OPENID_REQUIRED_ROLE_PARAMETER_PATH', 'string', 'The parameter path for required role validation.','OPENID_REQUIRED_ROLE_PARAMETER_PATH='],
    ['OPENID_ADMIN_ROLE', 'string', 'The role the user should have in order to be an admin in LibreChat.','OPENID_ADMIN_ROLE='],
    ['OPENID_ADMIN_ROLE_TOKEN_KIND', 'string', 'The source of the information for admin role verification. Possible values are: access, id or userinfo.','OPENID_ADMIN_ROLE_TOKEN_KIND='],
    ['OPENID_ADMIN_ROLE_PARAMETER_PATH', 'string', 'The parameter path for required role validation.','OPENID_ADMIN_ROLE_PARAMETER_PATH='],
    ['OPENID_BUTTON_LABEL', 'string', 'The label for the OpenID login button.','OPENID_BUTTON_LABEL='],
    ['OPENID_IMAGE_URL', 'string', 'The URL of the OpenID login button image.','OPENID_IMAGE_URL='],
    ['OPENID_USE_END_SESSION_ENDPOINT', 'string', 'Whether to use the Issuer End Session Endpoint as a Logout Redirect','OPENID_USE_END_SESSION_ENDPOINT=TRUE'],
    ['OPENID_AUTO_REDIRECT', 'boolean', 'Whether to automatically redirect to the OpenID provider.','OPENID_AUTO_REDIRECT=true'],
    ['OPENID_USE_PKCE', 'boolean', 'Use PKCE (Proof Key for Code Exchange) for OpenID authentication.','# OPENID_USE_PKCE=true'],
    ['OPENID_POST_LOGOUT_REDIRECT_URI', 'string', 'Redirect URI after OpenID logout. Defaults to ${DOMAIN_CLIENT}/login.','# OPENID_POST_LOGOUT_REDIRECT_URI='],
    ['OPENID_CLOCK_TOLERANCE', 'number', 'Clock tolerance in seconds for token validation. Default: 300.','# OPENID_CLOCK_TOLERANCE=300'],
    ['OPENID_GENERATE_NONCE', 'boolean', 'Force the OpenID client to generate a nonce parameter. Required by some identity providers like AWS Cognito (especially with federation) and Authentik.','OPENID_GENERATE_NONCE=true'],
    ['DEBUG_OPENID_REQUESTS', 'boolean', 'Enable detailed logging of OpenID request headers. When disabled (default), only request URLs are logged at debug level. When enabled, request headers are also logged (with sensitive data masked) for deeper debugging of authentication issues.','DEBUG_OPENID_REQUESTS=false'],
  ]}
/>
                                                                                                                               
##### OpenID Connect Token Reuse

LibreChat supports reusing access and refresh tokens issued by your OpenID Connect provider (like Azure Entra ID or Auth0) to manage user authentication state. When this feature is active, the refresh token passed to the user as a cookie is issued by your OpenID provider instead of LibreChat.

<OptionTable
  options={[
    ['OPENID_REUSE_TOKENS', 'boolean', 'Enable reuse of OpenID provider tokens for session management.', 'OPENID_REUSE_TOKENS=false'],
    ['OPENID_SCOPE', 'string', 'Space-separated list of OpenID scopes. Must include offline_access for token reuse.', 'OPENID_SCOPE=api://librechat/.default openid profile email offline_access'],
    ['OPENID_AUDIENCE', 'string', 'The audience parameter for authorization requests. Required for Auth0 when OPENID_REUSE_TOKENS=true. See the note in the main OpenID section above.', 'OPENID_AUDIENCE=https://api.librechat.com'],
    ['OPENID_JWKS_URL_CACHE_ENABLED', 'boolean', 'Enable caching of signing key verification results.', 'OPENID_JWKS_URL_CACHE_ENABLED=true'],
    ['OPENID_JWKS_URL_CACHE_TIME', 'number', 'Cache duration in milliseconds (default: 600000 ms / 10 minutes).', 'OPENID_JWKS_URL_CACHE_TIME=600000'],
    ['OPENID_ON_BEHALF_FLOW_FOR_USERINFO_REQUIRED', 'boolean', 'Enable on-behalf-of flow for user info.', 'OPENID_ON_BEHALF_FLOW_FOR_USERINFO_REQUIRED=true'],
    ['OPENID_ON_BEHALF_FLOW_USERINFO_SCOPE', 'string', 'Scope for user info in on-behalf-of flow.', 'OPENID_ON_BEHALF_FLOW_USERINFO_SCOPE=user.read'],
    ['OPENID_USE_END_SESSION_ENDPOINT', 'boolean', 'Enable use of the end session endpoint for logout.', 'OPENID_USE_END_SESSION_ENDPOINT=true'],
  ]}
/>

<Callout type="note" title="Note">
For detailed configuration steps and prerequisites, see [Re-use OpenID Tokens for Login Session](/docs/configuration/authentication/OAuth2-OIDC/token-reuse).
</Callout>

##### Microsoft Graph API / Entra ID Integration

When using Azure Entra ID (formerly Azure AD) as your OpenID provider, you can enable additional Microsoft Graph API features for enhanced people and group search capabilities within the permissions and sharing system.

<OptionTable
  options={[
    ['USE_ENTRA_ID_FOR_PEOPLE_SEARCH', 'boolean', 'Enable Entra ID people search integration in permissions/sharing system. When enabled, the people picker will search both local database and Entra ID.', 'USE_ENTRA_ID_FOR_PEOPLE_SEARCH=false'],
    ['ENTRA_ID_INCLUDE_OWNERS_AS_MEMBERS', 'boolean', 'When enabled, Entra ID group owners will be considered as members of the group.', 'ENTRA_ID_INCLUDE_OWNERS_AS_MEMBERS=false'],
    ['OPENID_GRAPH_SCOPES', 'string', 'Microsoft Graph API scopes needed for people/group search. Default scopes provide access to user profiles and group memberships.', 'OPENID_GRAPH_SCOPES=User.Read,People.Read,GroupMember.Read.All,User.ReadBasic.All'],
  ]}
/>

<Callout type="warning" title="Important Prerequisites">
- You must have Azure Entra ID configured as your OpenID provider
- **OpenID token reuse MUST be enabled** (`OPENID_REUSE_TOKENS=true`) - this feature will not work without it
- Your Azure app registration must have the appropriate Microsoft Graph API permissions
- For group search functionality, admin consent may be required for certain Graph API scopes
</Callout>

##### SharePoint Integration

LibreChat supports direct integration with SharePoint Online and OneDrive for Business, allowing users to select and attach files from their SharePoint libraries directly within conversations. This enterprise feature leverages the existing Azure Entra ID authentication.

<OptionTable
  options={[
    ['ENABLE_SHAREPOINT_FILEPICKER', 'boolean', 'Enable SharePoint file picker in chat and agent panels. When enabled, adds "From SharePoint" option in file attachment menu.', 'ENABLE_SHAREPOINT_FILEPICKER=true'],
    ['SHAREPOINT_BASE_URL', 'string', 'SharePoint tenant base URL. Required when SharePoint integration is enabled.', 'SHAREPOINT_BASE_URL=https://yourtenant.sharepoint.com'],
    ['SHAREPOINT_PICKER_SHAREPOINT_SCOPE', 'string', 'SharePoint-specific OAuth scope for the file picker. Used for authentication when opening the SharePoint file picker interface.', 'SHAREPOINT_PICKER_SHAREPOINT_SCOPE=https://yourtenant.sharepoint.com/AllSites.Read'],
    ['SHAREPOINT_PICKER_GRAPH_SCOPE', 'string', 'Microsoft Graph API scope for file downloads. Used for downloading files from SharePoint after selection.', 'SHAREPOINT_PICKER_GRAPH_SCOPE=Files.Read.All'],
  ]}
/>

<Callout type="error" title="Critical Requirements">
**All of the following must be configured for SharePoint integration to work:**
- Azure Entra ID authentication must be fully configured
- **`OPENID_REUSE_TOKENS=true`** is mandatory (uses on-behalf-of token flow)
- Your Azure app registration must have SharePoint and Graph API permissions
- All four SharePoint environment variables must be set
- HTTPS is required in production environments
</Callout>

<Callout type="info" title="Feature Capabilities">
When enabled, users can:
- Access files from SharePoint document libraries and OneDrive for Business
- Select multiple files at once (default max: 10 files)
- See real-time download progress
- Files are downloaded and attached to the conversation like regular uploads
</Callout>

For detailed SharePoint configuration instructions, see: [SharePoint Integration Guide](/docs/configuration/sharepoint)

#### SAML

For more information:
  - [Auth0](/docs/configuration/authentication/SAML/auth0)

<Callout type="warning" title="Mutual Exclusion of OpenID and SAML">
If OpenID is enabled, SAML authentication will be automatically disabled.

Only one authentication method can be active at a time.
</Callout>

<OptionTable
  options={[
    ['SAML_ENTRY_POINT', 'string', 'The SAML identity provider (IdP) entry point URL.', 'SAML_ENTRY_POINT='],
    ['SAML_ISSUER', 'string', 'The SAML service provider (SP) entity ID.', 'SAML_ISSUER='],
    ['SAML_CERT', 'string', 'The SAML signing certificate, provided as a file path or a one-line PEM string.', 'SAML_CERT='],
    ['SAML_CALLBACK_URL', 'string', 'The callback URL for SAML authentication.','SAML_CALLBACK_URL=/oauth/saml/callback'],
    ['SAML_SESSION_SECRET', 'string', 'The secret for SAML session storage.','SAML_SESSION_SECRET='],
    ['SAML_EMAIL_CLAIM', 'string', '<Optional>: The attribute in the SAML assertion containing the user email. (default: email)','SAML_EMAIL_CLAIM='],
    ['SAML_USERNAME_CLAIM', 'string', '<Optional>: The attribute in the SAML assertion containing the username. (default: username)','SAML_USERNAME_CLAIM='],
    ['SAML_GIVEN_NAME_CLAIM', 'string', '<Optional>: The attribute in the SAML assertion containing the given name. (default: given_name)','SAML_GIVEN_NAME_CLAIM='],
    ['SAML_FAMILY_NAME_CLAIM', 'string', '<Optional>: The attribute in the SAML assertion containing the family name. (default: family_name)','SAML_FAMILY_NAME_CLAIM='],
    ['SAML_PICTURE_CLAIM', 'string', '<Optional>: The attribute in the SAML assertion containing the profile picture URL. (default: picture)','SAML_PICTURE_CLAIM='],
    ['SAML_NAME_CLAIM', 'string', '<Optional>: The attribute in the SAML assertion containing the full name.','SAML_NAME_CLAIM='],
    ['SAML_BUTTON_LABEL', 'string', '<Optional>: The label for the SAML login button.','SAML_BUTTON_LABEL='],
    ['SAML_IMAGE_URL', 'string', '<Optional>: The URL of the SAML login button image.','SAML_IMAGE_URL='],
    ['SAML_USE_AUTHN_RESPONSE_SIGNED', 'boolean', '<Optional>: If "true", signs the entire SAML Response. Otherwise, only the Assertion is signed (default).', 'SAML_USE_AUTHN_RESPONSE_SIGNED=']
  ]}
/>

#### LDAP/AD Authentication

For more information: **[LDAP/AD Authentication](/docs/configuration/authentication/ldap)**

<OptionTable
    options={[
        ['LDAP_URL', 'string', 'LDAP server URL.', 'LDAP_URL=ldap://localhost:389'],
        ['LDAP_BIND_DN', 'string', 'Bind DN', 'LDAP_BIND_DN=cn=root'],
        ['LDAP_BIND_CREDENTIALS', 'string', 'Password for bindDN', 'LDAP_BIND_CREDENTIALS=password'],
        [
            'LDAP_USER_SEARCH_BASE',
            'string',
            'LDAP user search base',
            'LDAP_USER_SEARCH_BASE=o=users,o=example.com',
        ],
        ['LDAP_SEARCH_FILTER', 'string', 'LDAP search filter', 'LDAP_SEARCH_FILTER=mail={{username}}'],
        [
            'LDAP_CA_CERT_PATH',
            'string',
            'CA certificate path.',
            'LDAP_CA_CERT_PATH=/path/to/root_ca_cert.crt',
        ],
        [
            'LDAP_TLS_REJECT_UNAUTHORIZED',
            'string',
            'LDAP TLS verification',
            'LDAP_TLS_REJECT_UNAUTHORIZED=true',
        ],
        [
            'LDAP_STARTTLS',
            'string',
            'Enable LDAP StartTLS for upgrading the connection to TLS. Set to true to enable this feature.',
            'LDAP_STARTTLS=true',
        ],
        [
            'LDAP_LOGIN_USES_USERNAME',
            'boolean',
            'Use username instead of email for LDAP login.',
            '# LDAP_LOGIN_USES_USERNAME=true',
        ],
        [
            'LDAP_ID',
            'string',
            'LDAP attribute for unique user ID. Default: uid or sAMAccountName, mail.',
            '# LDAP_ID=uid',
        ],
        [
            'LDAP_USERNAME',
            'string',
            'LDAP attribute for username. Default: givenName or mail.',
            '# LDAP_USERNAME=givenName',
        ],
        [
            'LDAP_EMAIL',
            'string',
            'LDAP attribute for email. Default: mail.',
            '# LDAP_EMAIL=userPrincipalName',
        ],
        [
            'LDAP_FULL_NAME',
            'string',
            'LDAP attribute(s) for full name. Can be comma-separated. Default: givenName + surname.',
            '# LDAP_FULL_NAME=givenName,surname',
        ],
    ]}
/>

### Password Reset

Email is used for account verification and password reset. LibreChat supports both Mailgun API and traditional SMTP services. See: **[Email setup](/docs/configuration/authentication/email)**

**Important Note**: You must configure either Mailgun (recommended for servers that block SMTP) or SMTP for email to work.

> **Warning**: Failing to set valid values for either Mailgun or SMTP will result in LibreChat using the unsecured password reset!

#### Mailgun Configuration (Recommended)

Mailgun is particularly useful for deployments on servers that block SMTP ports. When both `MAILGUN_API_KEY` and `MAILGUN_DOMAIN` are set, LibreChat will use Mailgun instead of SMTP.

<OptionTable
  options={[
    ['MAILGUN_API_KEY', 'string', 'Your Mailgun API key (required for Mailgun).','MAILGUN_API_KEY='],
    ['MAILGUN_DOMAIN', 'string', 'Your Mailgun domain (required for Mailgun).','MAILGUN_DOMAIN=mg.yourdomain.com'],
    ['MAILGUN_HOST', 'string', 'Custom Mailgun API host (optional). Use https://api.eu.mailgun.net for EU region.','MAILGUN_HOST=https://api.mailgun.net'],
    ['EMAIL_FROM', 'string', 'From email address. Required.','EMAIL_FROM=noreply@librechat.ai'],
    ['EMAIL_FROM_NAME', 'string', 'From name (defaults to APP_TITLE if not set).','EMAIL_FROM_NAME='],
  ]}
/>

#### SMTP Configuration

If Mailgun is not configured, LibreChat will fall back to SMTP settings.

> **Warning**: If using `EMAIL_SERVICE`, **do NOT** set the extended connection parameters:
> HOST, PORT, ENCRYPTION, ENCRYPTION_HOSTNAME, ALLOW_SELFSIGNED.

See: **[nodemailer well-known-services](https://community.nodemailer.com/2-0-0-beta/setup-smtp/well-known-services/)**

<OptionTable
  options={[
    ['EMAIL_SERVICE', 'string', 'Email service (e.g., Gmail, Outlook).','EMAIL_SERVICE='],
    ['EMAIL_HOST', 'string', 'Mail server host.','EMAIL_HOST='],
    ['EMAIL_PORT', 'number', 'Mail server port.','EMAIL_PORT=25'],
    ['EMAIL_ENCRYPTION', 'string', 'Encryption method (starttls, tls, etc.).','EMAIL_ENCRYPTION='],
    ['EMAIL_ENCRYPTION_HOSTNAME', 'string', 'Hostname for encryption.','EMAIL_ENCRYPTION_HOSTNAME='],
    ['EMAIL_ALLOW_SELFSIGNED', 'boolean', 'Allow self-signed certificates.','EMAIL_ALLOW_SELFSIGNED='],
    ['EMAIL_USERNAME', 'string', 'Username for authentication.','EMAIL_USERNAME='],
    ['EMAIL_PASSWORD', 'string', 'Password for authentication.','EMAIL_PASSWORD='],
    ['EMAIL_FROM_NAME', 'string', 'From name.','EMAIL_FROM_NAME='],
    ['EMAIL_FROM', 'string', 'From email address. Required.','EMAIL_FROM=noreply@librechat.ai'],
  ]}
/>

### Firebase CDN

See: **[Firebase CDN Configuration](/docs/configuration/cdn/firebase)**

<Callout type="warning" title="Important">
- If you are using Firebase as your file storage strategy, make sure to set the `file_strategy` option to `firebase` in your `librechat.yaml` configuration file. - For more information on configuring the `librechat.yaml` file, please refer to the YAML Configuration Guide: [Custom Endpoints & Configuration](/docs/configuration/librechat_yaml)
</Callout>

<OptionTable
  options={[
    ['FIREBASE_API_KEY', 'string', 'The API key for your Firebase project.', 'FIREBASE_API_KEY='],
    ['FIREBASE_AUTH_DOMAIN', 'string', 'The Firebase Auth domain for your project.', 'FIREBASE_AUTH_DOMAIN='],
    ['FIREBASE_PROJECT_ID', 'string', 'The ID of your Firebase project.', 'FIREBASE_PROJECT_ID='],
    ['FIREBASE_STORAGE_BUCKET', 'string', 'The Firebase Storage bucket for your project.', 'FIREBASE_STORAGE_BUCKET='],
    ['FIREBASE_MESSAGING_SENDER_ID', 'string', 'The Firebase Cloud Messaging sender ID.', 'FIREBASE_MESSAGING_SENDER_ID='],
    ['FIREBASE_APP_ID', 'string', 'The Firebase App ID for your project.', 'FIREBASE_APP_ID='],
  ]}
/>

### Amazon S3 CDN

See: **[Amazon S3 CDN Configuration](/docs/configuration/cdn/s3)**

<Callout type="warning" title="Important">
If you are using S3 as your file storage strategy, make sure to set the `file_strategy` option to `s3` in your `librechat.yaml` configuration file.
</Callout>

<OptionTable
  options={[
    ['AWS_ACCESS_KEY_ID', 'string', 'Your IAM user access key ID. Optional if using IRSA.', 'AWS_ACCESS_KEY_ID=your_access_key_id'],
    ['AWS_SECRET_ACCESS_KEY', 'string', 'Your IAM user secret access key. Optional if using IRSA.', 'AWS_SECRET_ACCESS_KEY=your_secret_access_key'],
    ['AWS_REGION', 'string', 'The AWS region where your S3 bucket is located.', 'AWS_REGION=us-east-1'],
    ['AWS_BUCKET_NAME', 'string', 'The name of the S3 bucket for file storage.', 'AWS_BUCKET_NAME=your_bucket_name'],
    ['AWS_ENDPOINT_URL', 'string', 'Custom AWS endpoint URL (optional). For S3-compatible services.', '# AWS_ENDPOINT_URL='],
  ]}
/>

> **Note:** For Kubernetes deployments (e.g., on EKS), you can use IRSA (IAM Roles for Service Accounts) instead of providing explicit credentials. In that case, only `AWS_REGION` and `AWS_BUCKET_NAME` are required.

### Azure Blob Storage CDN

See: **[Azure Blob Storage CDN Configuration](/docs/configuration/cdn/azure)**

<Callout type="warning" title="Important">
If you are using Azure Blob Storage as your file storage strategy, make sure to set the `file_strategy` option to `azure_blob` in your `librechat.yaml` configuration file.
</Callout>

<OptionTable
  options={[
    ['AZURE_STORAGE_CONNECTION_STRING', 'string', 'Azure Blob Storage connection string. Use this OR AZURE_STORAGE_ACCOUNT_NAME for Managed Identity.', 'AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...'],
    ['AZURE_STORAGE_ACCOUNT_NAME', 'string', 'Azure Storage account name. Use for Managed Identity authentication (do not set connection string).', '# AZURE_STORAGE_ACCOUNT_NAME=yourAccountName'],
    ['AZURE_STORAGE_PUBLIC_ACCESS', 'boolean', 'Enable public access for blobs. Default: false.', 'AZURE_STORAGE_PUBLIC_ACCESS=false'],
    ['AZURE_CONTAINER_NAME', 'string', 'Container name for file storage. Default: files.', 'AZURE_CONTAINER_NAME=files'],
  ]}
/>

> **Note:** Use either `AZURE_STORAGE_CONNECTION_STRING` (Option A) or `AZURE_STORAGE_ACCOUNT_NAME` with Managed Identity (Option B), not both.

### UI

#### Help and FAQ Button

<OptionTable
  options={[
    ['HELP_AND_FAQ_URL', 'string', 'Help and FAQ URL. If empty or commented, the button is enabled. To disable the Help and FAQ button, set to "/".','HELP_AND_FAQ_URL=https://librechat.ai'],
  ]}
/>

**Behaviour:**

Sets the [Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) headers for static files. These configurations only trigger when the `NODE_ENV` is set to `production`.

Properly setting cache headers is crucial for optimizing the performance and efficiency of your web application. By controlling how long browsers and CDNs store copies of your static files, you can significantly reduce server load, decrease page load times, and improve the overall user experience.

* Uncomment `STATIC_CACHE_MAX_AGE` to change the `max-age` for static files. By default this is set to 4 weeks.
* Uncomment `STATIC_CACHE_S_MAX_AGE` to change the `s-maxage` for static files. By default this is set to 1 week.
  - This is for the _shared cache_, which is used by CDNs and proxies.

#### App Title and Footer

<OptionTable
  options={[
    ['APP_TITLE', 'string', 'App title.','APP_TITLE=LibreChat'],
    ['CUSTOM_FOOTER', 'string', 'Custom footer.','# CUSTOM_FOOTER="My custom footer"'],
    ['TEMP_CHAT_RETENTION_HOURS', 'number', '**Deprecated:** Use `interface.temporaryChatRetention` in librechat.yaml instead. Hours to retain temporary chats. Default: 720 (30 days).','# TEMP_CHAT_RETENTION_HOURS=168'],
  ]}
/>

**Behaviour:**

 * Uncomment `CUSTOM_FOOTER` to add a custom footer.
 * Uncomment and leave `CUSTOM_FOOTER` empty to remove the footer.
 * You can now add one or more links in the CUSTOM_FOOTER value using the following format: `[Anchor text](URL)`. Each link should be delineated with a pipe (`|`).

 > **Markdown example:** `CUSTOM_FOOTER=[Link 1](http://example1.com) | [Link 2](http://example2.com)`

#### Birthday Hat

<OptionTable
  options={[
    ['SHOW_BIRTHDAY_ICON', 'boolean', 'Show the birthday hat icon.','# SHOW_BIRTHDAY_ICON=true'],
  ]}
/>

**Behaviour:**

* The birthday hat icon will show automatically on February 11th (LibreChat's birthday).
* Set `SHOW_BIRTHDAY_ICON` to `false` to disable the birthday hat.
* Set `SHOW_BIRTHDAY_ICON` to `true` to enable the birthday hat all the time.


### Analytics

#### Google Tag Manager

LibreChat supports Google Tag Manager for analytics. You will need a Google Tag Manager ID to enable it in LibreChat. Follow [this guide](https://support.google.com/tagmanager/answer/9442095?sjid=10155093630524971297-EU) to generate a Google Tag Manager ID and configure Google Analytics. Then set the `ANALYTICS_GTM_ID` environment variable to your Google Tag Manager ID.

**Note:** If `ANALYTICS_GTM_ID` is not set, Google Tag Manager will not be enabled. If it is set incorrectly, you will see failing requests to `gtm.js`

<OptionTable
  options={[
    ['ANALYTICS_GTM_ID', 'string', 'Google Tag Manager ID.','ANALYTICS_GTM_ID='],
  ]}
/>

#### Conversation Import

Configure limits for conversation file imports to prevent memory issues.

<OptionTable
  options={[
    ['CONVERSATION_IMPORT_MAX_FILE_SIZE_BYTES', 'number', 'Maximum file size in bytes for conversation imports. Default: 0 (no limit enforced). Example: 262144000 (250 MiB).','# CONVERSATION_IMPORT_MAX_FILE_SIZE_BYTES=262144000'],
  ]}
/>

### MCP (Model Context Protocol)

Configure Model Context Protocol settings for enhanced server management and OAuth support.

#### MCP Server Configuration

<OptionTable
  options={[
    ['MCP_OAUTH_ON_AUTH_ERROR', 'boolean', 'Treat 401/403 responses as OAuth requirement when no oauth metadata found.', 'MCP_OAUTH_ON_AUTH_ERROR=true'],
    ['MCP_OAUTH_DETECTION_TIMEOUT', 'number', 'Timeout for OAuth detection requests in milliseconds.', 'MCP_OAUTH_DETECTION_TIMEOUT=5000'],
    ['MCP_CONNECTION_CHECK_TTL', 'number', 'Cache connection status checks for this many milliseconds to avoid expensive verification.', 'MCP_CONNECTION_CHECK_TTL=30000'],
    ['MCP_SKIP_CODE_CHALLENGE_CHECK', 'boolean', 'Skip code challenge method validation. When set to true, forces S256 code challenge even if not advertised in .well-known/openid-configuration', 'MCP_SKIP_CODE_CHALLENGE_CHECK=false'],
  ]}
/>

### Other

#### Redis

Redis provides significant performance improvements and enables horizontal scaling capabilities for LibreChat.

**Note:** Redis support is experimental, and you may encounter some problems when using it.

**Important:** If using Redis, you should flush the cache after changing any LibreChat settings.

For detailed configuration and examples, see: **[Redis Configuration Guide](/docs/configuration/redis)**

<OptionTable
  options={[
    ['USE_REDIS', 'boolean', 'Enable Redis for caching and session storage. When true, REDIS_URI must be provided.', 'USE_REDIS=true'],
    ['USE_REDIS_STREAMS', 'boolean', 'Enable Redis for resumable LLM streams. Defaults to USE_REDIS value if not set. Set to false to use in-memory storage for streams.', '# USE_REDIS_STREAMS=true'],
    ['REDIS_URI', 'string', 'Redis connection URI. For single instance: redis://host:port. For cluster: comma-separated URIs.', 'REDIS_URI=redis://127.0.0.1:6379'],
    ['USE_REDIS_CLUSTER', 'boolean', 'Enable Redis cluster mode when using a single URI', '# USE_REDIS_CLUSTER="true"'],
    ['REDIS_USERNAME', 'string', 'Redis username for authentication. Overrides username in URI if both provided.', '# REDIS_USERNAME=your_redis_username'],
    ['REDIS_PASSWORD', 'string', 'Redis password for authentication. Overrides password in URI if both provided.', '# REDIS_PASSWORD=your_redis_password'],
    ['REDIS_CA', 'string', 'Path to CA certificate for TLS verification when using rediss:// protocol.', '# REDIS_CA=/path/to/ca-cert.pem'],
    ['REDIS_KEY_PREFIX', 'string', 'Static prefix for all Redis keys to prevent cross-deployment contamination.', '# REDIS_KEY_PREFIX=librechat-prod-v2'],
    ['REDIS_KEY_PREFIX_VAR', 'string', 'Environment variable name containing dynamic prefix (e.g., K_REVISION for Cloud Run). Cannot be used with REDIS_KEY_PREFIX.', '# REDIS_KEY_PREFIX_VAR=K_REVISION'],
    ['REDIS_MAX_LISTENERS', 'number', 'Maximum event listeners per Redis client. Prevents memory leaks. Default: 40.', '# REDIS_MAX_LISTENERS=40'],
    ['REDIS_PING_INTERVAL', 'number', 'Ping interval in seconds to maintain connections. Default: 0 (disabled). Only set if experiencing timeouts.', '# REDIS_PING_INTERVAL=300'],
    ['FORCED_IN_MEMORY_CACHE_NAMESPACES', 'string', 'Comma-separated cache keys to force in-memory storage even when Redis is enabled.', '# FORCED_IN_MEMORY_CACHE_NAMESPACES=ROLES,MESSAGES'],
    ['REDIS_USE_ALTERNATIVE_DNS_LOOKUP', 'boolean', 'Enable alternate dnsLookup for TLS connections with AWS Elasticache. Required for Elasticache clusters with TLS.', '# REDIS_USE_ALTERNATIVE_DNS_LOOKUP=true'],
  ]}
/>

Notes:
- When `USE_REDIS=true`, you must provide `REDIS_URI` or the application will throw an error.
- For Redis Cluster mode, provide multiple URIs: `redis://node1:7001,redis://node2:7002,redis://node3:7003` (cluster mode is auto-detected).
- Use `rediss://` protocol for TLS connections and set `REDIS_CA` if your CA is not publicly trusted.
- `REDIS_KEY_PREFIX_VAR` and `REDIS_KEY_PREFIX` are mutually exclusive.
- **AWS Elasticache with TLS**: Elasticache may need to use an alternate dnsLookup for TLS connections. Set `REDIS_USE_ALTERNATIVE_DNS_LOOKUP=true` if using Elasticache with TLS. See [ioredis documentation](https://www.npmjs.com/package/ioredis) for more details.

#### Leader Election

Configure distributed leader election for multi-instance deployments with Redis. Leader election ensures only one instance performs certain operations like scheduled tasks.

<OptionTable
  options={[
    ['LEADER_LEASE_DURATION', 'number', 'Duration in seconds that the leader lease is valid before it expires. Default: 25.', 'LEADER_LEASE_DURATION=25'],
    ['LEADER_RENEW_INTERVAL', 'number', 'Interval in seconds at which the leader renews its lease. Default: 10.', 'LEADER_RENEW_INTERVAL=10'],
    ['LEADER_RENEW_ATTEMPTS', 'number', 'Maximum number of retry attempts when renewing the lease fails. Default: 3.', 'LEADER_RENEW_ATTEMPTS=3'],
    ['LEADER_RENEW_RETRY_DELAY', 'number', 'Delay in seconds between retry attempts when renewing the lease. Default: 0.5.', 'LEADER_RENEW_RETRY_DELAY=0.5'],
  ]}
/>

Notes:
- Leader election requires Redis to be enabled (`USE_REDIS=true`).
- These settings are only relevant for multi-instance deployments.
- The leader lease must be renewed before expiration to maintain leadership.
- If lease renewal fails after max attempts, the instance will relinquish leadership.