Config Structure

Note: Fields not specifically mentioned as required are optional.

version

• required

cache

skillSync

see: Skill Sync Object Structure

messageFilter

see: Message Filter Object Structure

fileStrategy

• Options: "local" | "firebase" | "s3" | "azure_blob" | "cloudfront"

• Notes:
  • "cloudfront" stores files in S3 and returns CloudFront URLs for stable media delivery, signed cookies, and signed downloads.
  • "firebase" serves files through Firebase Storage and Firebase Hosting edge locations.
  • S3 serves files via presigned URLs (temporary signed tokens) that expire. Once expired, any image or avatar referencing that URL will appear broken in the UI. This makes S3 unsuitable as a primary strategy for visual assets. See the related discussion for details.
  • For best performance of images and avatars, use "cloudfront" or "firebase", or configure fileStrategies to route avatar and image to a CDN-backed strategy.
  • Please refer to the File Storage & CDN documentation for setup details

fileStrategies

Allows granular control over file storage strategies for different file types.

• Available Strategies: "local" | "firebase" | "s3" | "azure_blob" | "cloudfront"

Sub-keys:

• Notes:
  • This setting takes precedence over the single fileStrategy option
  • If a specific file type is not configured, it falls back to default, then to fileStrategy, and finally to "local"
  • Images and avatars need persistent, stable URLs to render correctly across the UI. S3 presigned URLs expire (AWS cap: 7 days for IAM users, hours for STS/role-based credentials), causing broken images in the model selector and chat UI. See the related discussion for full context. Use "cloudfront" or "firebase" for avatar and image to avoid this.
  • S3 and Azure Blob Storage are well-suited for document storage, where short-lived presigned download URLs are appropriate.
  • Please refer to the File Storage & CDN documentation for setup details for each storage provider

Examples:

# Use a single strategy for all file types
fileStrategies:
  default: 's3'

# Route images and avatars to CDN, keep documents in object storage
fileStrategies:
  avatar: 'cloudfront' # CDN delivery for avatars
  image: 'cloudfront' # CDN delivery for generated/uploaded images
  document: 's3' # Object storage for documents

# Only configure specific types, others use default
fileStrategies:
  default: 'local'
  avatar: 'firebase' # Only avatars use Firebase CDN, everything else is local

cloudfront

Key:

Subkeys:

see: CloudFront Object Structure and CloudFront with S3

filteredTools

• Notes:
  • If includedTools and filteredTools are both specified, only includedTools will be recognized.
  • Affects both gptPlugins and assistants endpoints
  • You can find the names of the tools to filter in api/app/clients/tools/manifest.json
    • Use the pluginKey value
  • Also, any listed under the ".well-known" directory api/app/clients/tools/.well-known
    • Use the name_for_model value

includedTools

• Notes:
  • If includedTools and filteredTools are both specified, only includedTools will be recognized.
  • Affects both gptPlugins and assistants endpoints
  • You can find the names of the tools to filter in api/app/clients/tools/manifest.json
    • Use the pluginKey value
  • Also, any listed under the ".well-known" directory api/app/clients/tools/.well-known
    • Use the name_for_model value

secureImageLinks

imageOutputType

• Note: Case-sensitive. Google endpoint only supports "jpeg" and "png" output types.
• Options: "png" | "webp" | "jpeg"

ocr

Key:

Subkeys:

see: OCR Config Object Structure

webSearch

Key:

Subkeys:

see: Web Search Object Structure

fileConfig

Key:

Subkeys:

clientImageResize

Key:

Subkeys:

Description:

The clientImageResize configuration enables automatic client-side image resizing before upload. This feature helps:

• Prevent upload failures due to large image files exceeding server limits
• Reduce bandwidth usage by compressing images before transmission
• Improve upload performance with smaller file sizes
• Maintain image quality while optimizing file size

When enabled, images that exceed the specified maxWidth or maxHeight dimensions are automatically resized on the client side before being uploaded to the server. The resizing maintains the original aspect ratio while ensuring the image fits within the specified bounds.

Example:

fileConfig:
  clientImageResize:
    enabled: true
    maxWidth: 1920
    maxHeight: 1080
    quality: 0.8
    compressFormat: 'jpeg'

Notes:

• Only applies to image files (JPEG, PNG, WebP, etc.)
• Resizing occurs automatically when images exceed the specified dimensions
• Original aspect ratio is preserved during resizing
• The feature works with all supported image upload endpoints
• Quality setting only applies to JPEG and WebP formats
• Setting quality too low (< 0.5) may result in noticeable image degradation

see: File Config Object Structure

rateLimits

Key:

Subkeys:

fileUploads Subkeys:

conversationsImport Subkeys:

tts Subkeys:

stt Subkeys:

• Example:

rateLimits:
  fileUploads:
    ipMax: 100
    ipWindowInMinutes: 60
    userMax: 50
    userWindowInMinutes: 60
  conversationsImport:
    ipMax: 100
    ipWindowInMinutes: 60
    userMax: 50
    userWindowInMinutes: 60
  stt:
    ipMax: 100
    ipWindowInMinutes: 1
    userMax: 50
    userWindowInMinutes: 1
  tts:
    ipMax: 100
    ipWindowInMinutes: 1
    userMax: 50
    userWindowInMinutes: 1

registration

Key:

Subkeys:

see also:

• socialLogins,
• alloweddomains,
• Registration Object Structure

memory

Key:

Subkeys:

see: Memory Object Structure

summarization

Key:

Subkeys:

see: Summarization Object Structure

actions

Key:

Subkeys:

see also:

• allowedDomains,
• allowedAddresses,
• Actions Object Structure

interface

Key:

Subkeys:

see: Interface Object Structure

modelSpecs

Key:

Subkeys:

see: Model Specs Object Structure

endpoints

Key:

Subkeys:

Note: Endpoints support Shared Endpoint Settings such as streamRate, headers, titleModel, titleMethod, titlePrompt, titlePromptTemplate, titleEndpoint, and maxToolResultChars. These can be configured individually per endpoint or globally using the all key. headers are merged with endpoint-level values winning on key collisions. The all key does not accept baseURL.

Note: endpoints.allowedAddresses applies to user-provided baseURL values (when an admin configures a custom endpoint with apiKey: 'user_provided' and baseURL: 'user_provided'). Each user-supplied baseURL is validated against the SSRF block at request time; entries listed here are exempted. See mcpSettings.allowedAddresses for the field semantics — same rules apply (private IP space only, port required, no URLs/paths/CIDR/bare hosts/public IP literals).

mcpSettings

Key:

Subkeys:

• Notes:
  • This is a security feature to protect against abuse / misuse of internal addresses via MCP servers
  • By default, LibreChat restricts MCP servers from connecting to internal, local, or private network addresses
  • MCP servers using local IP addresses or domains can either be added to the strict allowedDomains whitelist (which then becomes the only reachable set), or — to keep public destinations reachable — exempted as exact host:port services via allowedAddresses
  • As with all yaml configuration changes, a LibreChat restart is required to take effect
  • Supports domains, wildcard subdomains (*.example.com), docker domains, and IP addresses

Example:

mcpSettings:
  # Strict whitelist mode:
  # allowedDomains:
  #   - "example.com"           # Specific domain
  #   - "*.example.com"         # All subdomains
  #   - "http://mcp-server:3000" # Internal service, explicitly whitelisted
 
  # Default SSRF mode with private service exemptions:
  allowedAddresses:
    - 'host.docker.internal:8080' # Permit one private host on one port
    - '10.0.0.5:8000' # Permit one private IP on one port

see: MCP Settings Object Structure

mcpServers

Key:

Subkeys:

• Notes:
  • Initialization happens at startup, and the app must be restarted for changes to take effect.
  • The <serverName> is a unique identifier for each MCP server configuration.
  • Each MCP server can be configured using one of four connection types:
    • stdio
    • websocket
    • sse
    • streamable-http
  • The type field specifies the connection type to the MCP server.
  • If type is omitted, it defaults based on the presence and format of url or command:
    • If url is specified and starts with http or https, type defaults to sse.
    • If url is specified and starts with ws or wss, type defaults to websocket.
    • If command is specified, type defaults to stdio.
  • Additional configuration options include:
    • timeout: Timeout in milliseconds for MCP server requests. Determines how long to wait for a response for tool requests.
    • initTimeout: Timeout in milliseconds for MCP server initialization. Determines how long to wait for the server to initialize.
    • serverInstructions: Controls whether server instructions are included in agent context. Can be true (use server-provided), false (disabled), or a custom string (overrides server-provided).
    • customUserVars: (Optional) Defines custom variables (e.g., API keys, URLs) that individual users can set for an MCP server. These per-user values, provided through the UI, can then be referenced in the server's headers or env configurations using {{VARIABLE_NAME}} syntax. This allows for per-user authentication or customization for MCP tools.
  • see: MCP Servers Object Structure

Example:

mcpServers:
  everything:
    # type: sse # type can optionally be omitted
    url: http://localhost:3001/sse
    timeout: 30000
    initTimeout: 10000
    serverInstructions: true # Use server-provided instructions
  puppeteer:
    type: stdio
    command: npx
    args:
      - -y
      - '@modelcontextprotocol/server-puppeteer'
    timeout: 30000
    initTimeout: 10000
    serverInstructions: 'Do not access any local files or local/internal IP addresses'
  filesystem:
    # type: stdio
    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
  streamable-http-example:
    type: streamable-http
    url: https://example.com/mcp
    headers:
      Authorization: 'Bearer ${API_TOKEN}'
    timeout: 30000
  per-user-crendentials-example:
    type: sse
    url: 'https//some.mcp/sse'
    headers:
      X-Custom-Auth-Token: '{{USER_API_KEY}}' # Placeholder for the user-provided API key, defined in `customUserVars` below.
    customUserVars:
      USER_API_KEY:
        title: 'Service API Key'
        description: "Your personal API key for this service. You can get it <a href='https://example.com/api-keys' target='_blank'>here</a>."
    serverInstructions: true

see: MCP Servers Object Structure

speech

Key:

Subkeys:

see: Speech Object Structure

turnstile

Key:

Subkeys:

see: Turnstile Object Structure

transactions

Key:

Subkeys:

see: Transactions Object Structure

Additional links

• Summarization Object Structure
• AWS Bedrock Object Structure
• Custom Endpoint Object Structure
• Azure OpenAI Endpoint Object Structure
• Assistants Endpoint Object Structure
• Agents
• OCR Config Object Structure
• Speech Object Structure
• Turnstile Object Structure
• Transactions Object Structure
• Balance Object Structure
• Web Search Object Structure
• Memory Object Structure