librechat.yaml Configuration

The librechat.yaml file provides advanced configuration options for LibreChat, including endpoint configuration, interface customization, and feature toggles.

Configuration File Location

CONFIG_PATH

string

default:"./librechat.yaml"

Path to the LibreChat YAML configuration file. Can be absolute, relative, or a URL.

.env

CONFIG_PATH="/alternative/path/to/librechat.yaml"

Version

version

string

required

Configuration file version. Current version: 1.3.4

version: 1.3.4

Cache Settings

cache

boolean

default:"true"

Enable caching for improved performance

cache: true

File Storage Strategy

Configure where files are stored. Supports both legacy single-strategy and new granular configurations.

Legacy Format (Single Strategy)

fileStrategy

string

default:"local"

Single storage strategy for all file types.Options: "local", "s3", "firebase", "azure_blob"

fileStrategy: "s3"

Granular Format (Recommended)

fileStrategy

object

Different storage strategies for different file types:

avatar: User and agent avatar images
image: Uploaded images in chats
document: Document uploads (PDFs, text files, etc.)

fileStrategy:
  avatar: "s3"        # Fast global access
  image: "firebase"   # Automatic optimization
  document: "local"   # Privacy/compliance

Mix and match storage strategies based on your needs:

Use S3 for avatars for fast global access
Use Firebase for images with automatic optimization
Use local storage for documents for privacy/compliance

Interface Configuration

interface

object

Customize the LibreChat user interface

Welcome Message

interface.customWelcome

string

Custom welcome message displayed to users

interface:
  customWelcome: 'Welcome to LibreChat! Enjoy your experience.'

Feature Toggles

interface.fileSearch

boolean

default:"true"

Enable/disable file search in chat area

This does not disable the Agents File Search Capability

interface:
  fileSearch: true

Show/hide endpoints selection menu

interface.modelSelect

boolean

default:"true"

Enable/disable model selection dropdown

interface.parameters

boolean

default:"true"

Show/hide model parameters configuration

interface.sidePanel

boolean

default:"true"

Enable/disable side panel

interface.presets

boolean

default:"true"

Enable/disable presets feature

interface.bookmarks

boolean

default:"true"

Enable/disable bookmarks feature

interface.multiConvo

boolean

default:"true"

Enable/disable multi-conversation feature

interface.fileCitations

boolean

default:"true"

Enable/disable file citations in responses

Privacy Policy & Terms

interface.privacyPolicy

object

interface:
  privacyPolicy:
    externalUrl: 'https://librechat.ai/privacy-policy'
    openNewTab: true

interface.termsOfService

object

interface:
  termsOfService:
    externalUrl: 'https://librechat.ai/tos'
    openNewTab: true
    modalAcceptance: true
    modalTitle: 'Terms of Service for LibreChat'
    modalContent: |
      # Terms and Conditions for LibreChat
      *Effective Date: February 18, 2024*
      
      Your terms content here in Markdown format...

Prompts Configuration

interface.prompts

object

Configure prompt sharing and creation

interface:
  prompts:
    use: true      # Allow using prompts
    create: true   # Allow creating prompts
    share: false   # Allow sharing with specific users
    public: false  # Allow public sharing

Agents Configuration

interface.agents

object

Configure agent permissions

interface:
  agents:
    use: true      # Allow using agents
    create: true   # Allow creating agents
    share: false   # Allow sharing agents
    public: false  # Allow public agent sharing

People Picker

interface.peoplePicker

object

Configure people picker for sharing

interface:
  peoplePicker:
    users: true   # Search for users
    groups: true  # Search for groups
    roles: true   # Search by roles

Marketplace

interface.marketplace

object

Enable/disable marketplace features

interface:
  marketplace:
    use: false

MCP Servers Configuration

interface.mcpServers

object

Configure MCP (Model Context Protocol) server permissions and UI elements

interface:
  mcpServers:
    # User permissions
    use: true      # Allow using MCP servers
    create: true   # Allow creating MCP servers
    share: false   # Allow sharing with specific users
    public: false  # Allow public sharing
    
    # Creation dialog configuration
    trustCheckbox:
      label:
        en: 'I understand and I want to continue'
        de: 'Ich verstehe und möchte fortfahren'
      subLabel:
        en: |
          LibreChat hasn't reviewed this MCP server. Attackers may attempt to steal your data.
          <a href="https://example.com" target="_blank"><strong>Learn more.</strong></a>

Temporary Chat Retention

interface.temporaryChatRetention

number

default:"720"

Retention period for temporary chats in hours

Minimum: 1 hour
Maximum: 8760 hours (1 year)
Default: 720 hours (30 days)

interface:
  temporaryChatRetention: 168  # 7 days

Cloudflare Turnstile

turnstile

object

Configure Cloudflare Turnstile CAPTCHA

turnstile:
  siteKey: "your-site-key-here"
  options:
    language: "auto"  # or ISO 639-1 code (e.g., "en")
    size: "normal"    # "normal", "compact", "flexible", "invisible"

Registration

registration

object

Configure registration settings

Enable social login providersOptions: github, google, discord, openid, facebook, apple, saml

registration:
  socialLogins: ['github', 'google', 'discord', 'openid']

registration.allowedDomains

array

Restrict registration to specific email domains

registration:
  allowedDomains:
    - "company.com"
    - "partner.com"

Balance System

balance

object

Configure token balance system

balance:
  enabled: false
  startBalance: 20000              # Initial tokens
  autoRefillEnabled: false         # Auto-refill tokens
  refillIntervalValue: 30          # Refill every 30...
  refillIntervalUnit: 'days'       # ...days
  refillAmount: 10000              # Tokens to add

Transactions

transactions

object

Control transaction record saving

transactions:
  enabled: true  # Save transaction records

If balance is enabled, transactions are always enabled regardless of this setting

Speech Configuration

Text-to-Speech

speech.tts

object

Configure text-to-speech services

speech:
  tts:
    openai:
      url: 'https://api.openai.com/v1'
      apiKey: '${TTS_API_KEY}'
      model: 'tts-1'
      voices: ['alloy', 'echo', 'fable']

Speech-to-Text

speech.stt

object

Configure speech-to-text services

speech:
  stt:
    openai:
      url: 'https://api.openai.com/v1'
      apiKey: '${STT_API_KEY}'
      model: 'whisper-1'

Rate Limits

rateLimits

object

Configure rate limiting for various operations

rateLimits:
  fileUploads:
    ipMax: 100                    # Max uploads per IP
    ipWindowInMinutes: 60         # Time window for IP limit
    userMax: 50                   # Max uploads per user
    userWindowInMinutes: 60       # Time window for user limit
  conversationsImport:
    ipMax: 100
    ipWindowInMinutes: 60
    userMax: 50
    userWindowInMinutes: 60

Agent Actions Domain Restrictions

actions

object

Configure allowed domains for Agent Actions (OpenAPI specs)

If not configured, SSRF targets are blocked (localhost, private IPs, .internal/.local TLDs). To allow internal targets, explicitly add them to allowedDomains.

actions:
  allowedDomains:
    - 'swapi.dev'
    - 'librechat.ai'
    - '*.example.com'                      # Wildcard subdomain
    - 'https://api.example.com:8443'       # Protocol/port restriction
    - 'http://10.225.26.25:7894'           # Internal IP (if needed)

MCP Server Domain Restrictions

mcpSettings

object

Configure allowed domains for MCP remote transports (SSE, WebSocket, HTTP)

If not configured, SSRF targets are blocked. To allow Docker host access or internal targets, explicitly add them.

mcpSettings:
  allowedDomains:
    - 'host.docker.internal'    # Docker host access (required for Docker)
    - 'localhost'               # Local development
    - '*.example.com'           # Wildcard subdomain
    - 'https://secure.api.com'  # Protocol-restricted
    - 'http://internal:8080'    # Protocol and port restricted

MCP Servers

mcpServers

object

Define MCP (Model Context Protocol) server connections

mcpServers:
  everything:
    type: sse  # Optional, can be omitted
    url: http://localhost:3001/sse
    timeout: 60000  # 1 minute (default)
  
  puppeteer:
    type: stdio
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-puppeteer"
    timeout: 300000  # 5 minutes
  
  filesystem:
    type: stdio  # Optional
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-filesystem"
      - /home/user/LibreChat/
    iconPath: /home/user/LibreChat/client/public/assets/logo.svg
  
  mcp-obsidian:
    command: npx
    args:
      - -y
      - "mcp-obsidian"
      - /path/to/obsidian/vault

File Upload Configuration

fileConfig

object

Configure file upload limits and restrictions

fileConfig:
  endpoints:
    assistants:
      fileLimit: 5                    # Max number of files
      fileSizeLimit: 10               # Max size per file (MB)
      totalSizeLimit: 50              # Max total size (MB)
      supportedMimeTypes:
        - "image/.*"
        - "application/pdf"
    openAI:
      disabled: true                  # Disable file uploads
    default:
      totalSizeLimit: 20
    YourCustomEndpointName:
      fileLimit: 2
      fileSizeLimit: 5
  
  serverFileSizeLimit: 100            # Global limit (MB)
  avatarSizeLimit: 2                  # Avatar limit (MB)
  
  imageGeneration:
    percentage: 100                   # Percentage-based sizing
    # OR
    px: 1024                          # Pixel-based sizing
  
  clientImageResize:
    enabled: false                    # Client-side image resizing
    maxWidth: 1900                    # Max width (px)
    maxHeight: 1900                   # Max height (px)
    quality: 0.92                     # JPEG quality (0.0-1.0)

Web Search Configuration

webSearch

object

Configure web search functionality

webSearch:
  # Rerankers
  jinaApiKey: '${JINA_API_KEY}'
  jinaApiUrl: '${JINA_API_URL}'  # Optional, defaults to Jina API
  cohereApiKey: '${COHERE_API_KEY}'
  
  # Search providers
  serperApiKey: '${SERPER_API_KEY}'
  searxngInstanceUrl: '${SEARXNG_INSTANCE_URL}'
  searxngApiKey: '${SEARXNG_API_KEY}'
  
  # Content scrapers
  firecrawlApiKey: '${FIRECRAWL_API_KEY}'
  firecrawlApiUrl: '${FIRECRAWL_API_URL}'

Memory Configuration

memory

object

Configure user memory functionality

memory:
  disabled: false                     # Enable/disable memory
  validKeys:                          # Restrict memory keys
    - "preferences"
    - "work_info"
    - "personal_info"
    - "skills"
    - "interests"
    - "context"
  tokenLimit: 10000                   # Max tokens for memory storage
  personalize: true                   # Show Personalization tab
  
  # Option 1: Use existing agent by ID
  agent:
    id: "your-memory-agent-id"
  
  # Option 2: Define agent inline
  # agent:
  #   provider: "openai"
  #   model: "gpt-4o-mini"
  #   instructions: "You are a memory management assistant."
  #   model_parameters:
  #     temperature: 0.1

Model Specs

modelSpecs

object

Define custom model specifications with grouping

modelSpecs:
  list:
    # Nested under an endpoint
    - name: "gpt-4o"
      label: "GPT-4 Optimized"
      description: "Most capable GPT-4 model with multimodal support"
      group: "openAI"              # Groups with openAI endpoint
      preset:
        endpoint: "openAI"
        model: "gpt-4o"
    
    # Custom group with icon URL
    - name: "coding-assistant"
      label: "Coding Assistant"
      description: "Specialized for coding tasks"
      group: "my-assistants"       # Custom group
      groupIcon: "https://example.com/icons/assistants.png"
      preset:
        endpoint: "openAI"
        model: "gpt-4o"
        instructions: "You are an expert coding assistant..."
        temperature: 0.3
    
    # Custom group with built-in icon
    - name: "fast-models"
      label: "Fast Response Model"
      group: "Fast Models"
      groupIcon: "groq"            # Uses built-in Groq icon
      preset:
        endpoint: "groq"
        model: "llama3-8b-8192"
    
    # Standalone (no group)
    - name: "general-assistant"
      label: "General Assistant"
      description: "General purpose assistant"
      preset:
        endpoint: "openAI"
        model: "gpt-4o-mini"

Model Spec Grouping:

If group matches an endpoint name, the spec appears nested under that endpoint
If group is a custom name, it creates a separate collapsible section
If group is omitted, the spec appears as a standalone item
Use groupIcon to set icons for custom groups (URL or built-in endpoint key)

Next Steps

AI Endpoints

Configure AI endpoints and custom models

Environment Variables

Complete environment variable reference

File Storage

Set up file storage strategies

Authentication

Configure authentication methods

Get Started

Core Features

Configuration

Deployment

User Guide

Administration

​librechat.yaml Configuration

​Configuration File Location

​Version

​Cache Settings

​File Storage Strategy

​Legacy Format (Single Strategy)

​Granular Format (Recommended)

​Interface Configuration

​Welcome Message

​Feature Toggles

​Privacy Policy & Terms

​Prompts Configuration

​Agents Configuration

​People Picker

​Marketplace

​MCP Servers Configuration

​Temporary Chat Retention

​Cloudflare Turnstile

​Registration

​Balance System

​Transactions

​Speech Configuration

​Text-to-Speech

​Speech-to-Text

​Rate Limits

​Agent Actions Domain Restrictions

​MCP Server Domain Restrictions

​MCP Servers

​File Upload Configuration

​Web Search Configuration

​Memory Configuration

​Model Specs

​Next Steps

AI Endpoints

Environment Variables

File Storage

Authentication

Build docs developers (and LLMs) love

librechat.yaml Configuration

Configuration File Location

Version

Cache Settings

File Storage Strategy

Legacy Format (Single Strategy)

Granular Format (Recommended)

Interface Configuration

Welcome Message

Feature Toggles

Privacy Policy & Terms

Prompts Configuration

Agents Configuration

People Picker

Marketplace

MCP Servers Configuration

Temporary Chat Retention

Cloudflare Turnstile

Registration

Balance System

Transactions

Speech Configuration

Text-to-Speech

Speech-to-Text

Rate Limits

Agent Actions Domain Restrictions

MCP Server Domain Restrictions

MCP Servers

File Upload Configuration

Web Search Configuration

Memory Configuration

Model Specs

Next Steps