.env File Configuration

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

• The official docker documentation:

  • docker docs - understanding-multiple-compose-files
  • docker docs - merge-compose-files
  • docker docs - 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

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.

Static File Handling

Behaviour:

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

Index HTML Cache Control

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.

MongoDB Database

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:[email protected]/LibreChat?retryWrites=true (retryWrites is the only option you need when using the online database.)

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 for instructions on how to create an online MongoDB Atlas database (useful for use without Docker)
• MongoDB Community Server for instructions on how to create a local MongoDB database (without Docker)
• MongoDB Authentication To enable explicit authentication for MongoDB in Docker.
• Manage your database with Mongo Express for securely accessing your Docker MongoDB database

Application Domains

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

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

❗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 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
• Error logs are stored in the same location.

Environment Variables

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

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.

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.

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.

Known Endpoints - librechat.yaml

• see also: Custom Endpoints & Configuration

Anthropic

see: Anthropic Endpoint

• 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

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.

BingAI

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

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

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

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

OpenAI

See: OpenAI Setup

Assistants

See: Assistants Setup

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.

Plugins

Here are some useful resources about plugins:

• Introduction
• Make Your Own

General Configuration

Environment Variables

Credentials Configuration

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

Azure AI Search

This plugin supports searching Azure AI Search for answers to your questions. See: Azure AI Search

DALL-E:

API Keys:

API Keys (Version Specific):

System Prompts:

Reverse Proxy Settings:

Base URLs:

Azure OpenAI Integration (Optional):

Remember to replace placeholder text with actual prompts or instructions and provide your actual API keys if you choose to include them directly in the file (though managing sensitive keys outside of the codebase is a best practice). Always review and respect OpenAI’s usage policies when embedding API keys in software.

Note: if you have PROXY set, it will be used for DALL-E calls also, which is universal for the app.

DALL-E (Azure)

Here’s the updated layout for the DALL-E configuration options:

API Keys:

API Keys (Version Specific):

System Prompts:

Reverse Proxy Settings:

Base URLs:

Azure OpenAI Integration (Optional):

Remember to replace placeholder text with actual prompts or instructions and provide your actual API keys if you choose to include them directly in the file (though managing sensitive keys outside of the codebase is a best practice). Always review and respect OpenAI’s usage policies when embedding API keys in software.

Note: if you have PROXY set, it will be used for DALL-E calls also, which is universal for the app.

Google Search

See detailed instructions here: Google Search

Environment Variables:

SerpAPI

Description: SerpApi is a real-time API to access Google search results (not as performant)

Environment Variables:

Stable Diffusion (Automatic1111)

See detailed instructions here: Stable Diffusion

Description: Use http://127.0.0.1:7860 with local install and http://host.docker.internal:7860 for docker

Environment Variables:

Tavily

Get your API key here: https://tavily.com/#api

Environment Variables:

Traversaal

Description: LLM-enhanced search tool.

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

Environment Variables:

WolframAlpha

See detailed instructions here: Wolfram Alpha

Environment Variables:

Zapier

Description: - You need a Zapier account. Get your API key from here: Zapier

• 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:

Search (Meilisearch)

Enables search in messages and conversations:

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:

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

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.

User System

This section contains the configuration for:

• Automated Moderation
• Balance/Token Usage
• Registration and Social Logins
• 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

Basic Moderation Settings

Banning Settings

Score for each violation

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)

Limiters

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

IP Limiter:

User Limiter:

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

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 [email protected] 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

• General Settings:

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

• Session and Refresh Token Settings:

• For more information: Refresh Token

• 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

Social Logins

For more details: OAuth2-OIDC

Discord Authentication

For more information: Discord

Facebook Authentication

For more information: Facebook Authentication

GitHub Authentication

For more information: GitHub Authentication

Google Authentication

For more information: Google Authentication

OpenID Connect

For more information:

• AWS Cognito
• Azure Entra/AD
• Keycloak

LDAP/AD Authentication

For more information: LDAP/AD Authentication

Password Reset

Email is used for account verification and password reset. See: Email setup

Important Note: All of the service or host, username, and password, and the From address must be set for email to work.

Warning: If using EMAIL_SERVICE, do NOT set the extended connection parameters: HOST, PORT, ENCRYPTION, ENCRYPTION_HOSTNAME, ALLOW_SELFSIGNED. Failing to set valid values here will result in LibreChat using the unsecured password reset!

See: nodemailer well-known-services

Firebase CDN

See: Firebase CDN Configuration

UI

Help and FAQ Button

Behaviour:

Sets the 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

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

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

Other

Redis

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.