Config Structure

Note: Fields not specifically mentioned as required are optional.

version

• required

cache

langfuse

Subkeys:

Manage connection fields through Settings → Langfuse or an authorized administrator configuration client. The Settings flow verifies the connection and derives projectId; authorized administrator writes encrypt secretKey, generate secretKeyPreview, and redact the secret from reads. Plaintext secretKey values placed directly in librechat.yaml are not accepted by the runtime connection path. The legacy displaySecretKey and fanout.enabled fields are no longer part of the schema.

headers is different: it is deployment infrastructure and can only be set in librechat.yaml. Admin configuration writes reject both the whole map and individual header paths so gateway credentials are not stored or returned through Mongo-backed configuration. Values support ${ENV_VAR} interpolation; use environment references instead of literals. LibreChat drops unresolved variables, protected infrastructure-secret references, blank values, and invalid HTTP header names with a warning.

Custom headers are sent on trace and media export, feedback-score requests, project lookup, and admin credential verification only when the deployment resolves exactly one Langfuse origin. If central, tenant, or collector configuration produces multiple origins, LibreChat sends no custom headers and logs a warning because the map cannot safely identify a recipient. They cannot use per-user {{...}} placeholders, and the fanout collector forwards only Authorization upstream.

langfuse:
  headers:
    CF-Access-Client-Id: '${CF_ACCESS_CLIENT_ID}'
    CF-Access-Client-Secret: '${CF_ACCESS_CLIENT_SECRET}'

langfuse is a base-configuration-only section. Role, group, and user configuration overrides cannot replace or tombstone it.

See Langfuse Configuration for availability rules, authenticated proxy setup, environment-managed credentials, and optional fanout deployment.

skillSync

see: Skill Sync Object Structure

filters

filters is a base-configuration-only policy. Role, group, user, and database overrides cannot add, replace, or tombstone it. In a multi-replica deployment, coordinate the config rollout or restart so every replica loads the same policy.

See: Content Filter Object Structure

messageFilter

See: Legacy messageFilter

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

Local images are protected when this field is omitted. Private conversation images require an active session and owner access. Stored user avatars require an authenticated viewer in the same tenant. Agent avatars follow the Agent's view ACL, including public visibility, while Assistant avatars require the same tenant plus the effective endpoint sharing or Assistant-management policy. Authorization and configuration lookup failures fail closed.

Set secureImageLinks: false only as a compatibility opt-out for deployments that intentionally expose local image URLs without authentication. Role and user configuration overrides are resolved from the image owner's effective configuration.

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 controls client-side downscaling 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 resizing is enabled, supported images that exceed maxWidth or maxHeight are downscaled in the browser before upload. LibreChat preserves the aspect ratio, never upscales smaller images, and keeps the original file when the encoded result would not be smaller.

If enabled is omitted, users can turn Resize images before upload on or off under Settings > Chat. The preference is stored in that browser and defaults to off. Setting enabled: true or enabled: false in librechat.yaml overrides every user's preference and disables the toggle.

Example:

fileConfig:
  clientImageResize:
    # Omit enabled so each user can choose under Settings > Chat.
    maxWidth: 1900
    maxHeight: 1900
    quality: 0.92

To enforce one behavior for the deployment, add either enabled: true or enabled: false to the same block.

Notes:

• The resize pipeline supports JPEG, PNG, and WebP in browsers with the required Canvas APIs.
• Animated PNG and WebP files are sent unchanged so resizing does not discard animation.
• The output keeps the source format. There is no compressFormat setting.
• Browser encoders may ignore quality for lossless formats such as PNG.
• A resize failure falls back to the original file; normal server upload limits still apply.

see: File Config Object Structure

rateLimits

Key:

Subkeys:

fileUploads Subkeys:

conversationsImport Subkeys:

agentEvents Subkeys:

This admission bucket is separate from normal message execution limits. The durable worker consumes the normal message-user bucket when it executes a delivery, avoiding a double charge at admission time. Legacy AGENT_EVENT_USER_MAX and AGENT_EVENT_USER_WINDOW values remain fallbacks when the YAML fields are omitted; explicit YAML values take precedence.

tts Subkeys:

stt Subkeys:

• Example:

rateLimits:
  agentEvents:
    userMax: 40
    userWindowInMinutes: 1
  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:

Both speech.tts and speech.stt accept an allowedAddresses array of trusted private host:port exemptions. Speech requests enforce the default private-address block at connect time. See the detailed Speech reference for entry rules, proxy behavior, and examples.

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