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

MongoDB Database

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

For example:

• 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=true is the only option you need when using the online database)

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, see: Bing Access token and Bing Jailbreak

Follow these instructions to get your Bing access token (it’s best to use the full cookie string for that purpose): Bing Access Token

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.

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:

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.

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

Here is the rewritten content in MDX format with improvements:

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 enables user balances for the OpenAI/Plugins endpoints, which you can add manually or you will need to build out a balance accruing system for users.

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 example@example.com 1000
• 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@domain.com.

• 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

Email Password Reset

Email is used for password reset. See: Email Password Reset

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:

• If HELP_AND_FAQ_URL is empty or commented, the button is enabled.
• If HELP_AND_FAQ_URL is set to a URL (e.g., https://example.com), the button is enabled and links to that URL.
• If HELP_AND_FAQ_URL is set to /, the button is disabled.

App Title and Footer

Behaviour:

• Uncomment CUSTOM_FOOTER to add a custom footer.
• Uncomment and leave CUSTOM_FOOTER empty to remove the footer.

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.

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.