Config Structure

Note: Fields not specifically mentioned as required are optional.

version

• required

cache

projects

Key:

Subkeys:

See Projects. Unknown keys inside projects fail validation.

projects:
  maxFiles: 50
  maxInstructionsLength: 16000
  maxDescriptionLength: 1000

permissions

Controls retry behavior for concurrent access-control-list writes.

maxWriteAttempts ranges from 1 through 100.

permissions:
  maxWriteAttempts: 3
  leaseTtlMs: 30000
  leaseWaitMs: 3000

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

fileListLimit

Requests without a limit are not affected. The composer's recent files list (interface.composerRecentFiles) is capped at 100, this setting's default, so the palette never asks for more rows than a default deployment returns.

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.
  • Applies to the built-in tools loaded at startup, which Agents and Assistants use. The Ask User tool (ask_user_question) also honors these lists. MCP tools are configured separately.
  • You can find the names of the tools in api/app/clients/tools/manifest.json
    • Use the pluginKey value

includedTools

• Notes:
  • If includedTools and filteredTools are both specified, only includedTools will be recognized.
  • Applies to the built-in tools loaded at startup, which Agents and Assistants use. The Ask User tool (ask_user_question) also honors these lists. MCP tools are configured separately.
  • You can find the names of the tools in api/app/clients/tools/manifest.json
    • Use the pluginKey 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"

conversationList

Key:

Subkeys:

See Navigation for the conversation list filters. Values outside these ranges fail config validation like any other invalid key. An invalid value set through an Admin Panel override is ignored with a warning, and the defaults apply.

conversationList:
  maxEndpointFilters: 50
  maxEndpointNameLength: 128

ocr

Key:

Subkeys:

see: OCR Config Object Structure

webSearch

Key:

Subkeys:

see: Web Search Object Structure

fileConfig

Key:

Subkeys:

See File Config Object Structure for the full reference, including textFallbackWithoutTools, codeEnvLivenessSafeWindowMs, and legacySearchProbeTimeoutMs.

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:

Precedence: at startup, LibreChat writes each value set under fileUploads, conversationsImport, tts, stt, agentEvents, emailChange, and emailChangeConfirm into the matching environment variable (prefixes FILE_UPLOAD, IMPORT, TTS, STT, AGENT_EVENT, EMAIL_CHANGE, and EMAIL_CHANGE_CONFIRM, with suffixes _IP_MAX, _IP_WINDOW, _USER_MAX, and _USER_WINDOW). A YAML value therefore overrides the environment variable, and a key you leave out keeps the environment value or the built-in default. twoFactorManagement and mcpApps have no environment equivalents.

twoFactorManagement Subkeys:

This budget is always active, even when the block is omitted, and counts successful and failed requests across enable, verify, confirm, disable, and backup-code regeneration. The minimum of 3 permits the enable → verify → confirm setup sequence; 0 does not disable the limiter. All operations and login sessions for the account share the budget. An exhausted budget returns HTTP 429, Retry-After, and response code TWO_FACTOR_RATE_LIMITED before factor verification or mutation.

Configure this under deployment-level rateLimits in librechat.yaml. The limiter reads the YAML-derived base configuration, not role/group/user overrides. With Redis enabled, the account budget is shared across API replicas; otherwise each process has its own memory bucket. Use shared Redis for a deployment-wide limit in a multi-process deployment. The separate temporary-token 2FA login limiter is unchanged. See 2FA Management Attempt Limits.

rateLimits:
  twoFactorManagement:
    requestsPerFiveMinutes: 7

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:

mcpApps Subkeys:

emailChange Subkeys:

emailChangeConfirm Subkeys:

The confirmation endpoint is unauthenticated, so it is bounded by source address as well as by the account the link names. See Email Address Change.

• Example:

rateLimits:
  twoFactorManagement:
    requestsPerFiveMinutes: 7
  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
  mcpApps:
    resourcesPerMinute: 120
    toolCallsPerMinute: 60
  emailChange:
    userMax: 3
    userWindowInMinutes: 2
  emailChangeConfirm:
    ipMax: 20
    ipWindowInMinutes: 2
    userMax: 2
    userWindowInMinutes: 2

registration

Key:

Subkeys:

see also:

• socialLogins,
• alloweddomains,
• Registration Object Structure

emailChange

Key:

Subkeys:

Each field set here takes precedence over its environment fallback. Email delivery must be configured for the option to appear. See Email Address Change.

emailChange:
  enabled: true
  tokenTTLSeconds: 900

passkeys

Key:

Subkeys:

Passkeys themselves are enabled with ALLOW_PASSKEY_LOGIN in .env. See Passkeys.

passkeys:
  perUserMax: 20

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: The openAI, google, anthropic, and bedrock keys are documented with their providers: OpenAI, Google, Anthropic, and AWS Bedrock.

Note: endpoints.agents.pullRequests configures the conversation pull request chip and sidebar mark. See pullRequests.

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 (http is accepted as an alias)
  • 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

telemetry

Controls browser real user monitoring (RUM). This block rejects unknown keys.

telemetry:
  rum:
    enabled: true
    sessionReplay:
      enabled: false

credentials

credentials:
  writeFormat: v3

toolCallPreviews

Bounds the tool call output and arguments sent when a conversation loads. The client receives the start and end of each long string and fetches a part in full only when the reader opens it. Set enabled: false to send every load in full.

toolCallPreviews:
  enabled: true
  outputChars: 512
  argsChars: 512

githubCompare

Controls the GitHub Compare tool, which compares commit ancestry in a public GitHub repository without a workspace. It is available to agents only and is off by default. This block rejects unknown keys.

githubCompare:
  enabled: true
  timeoutMs: 10000

passwordHashing

Password and auth token hashing runs on worker threads, off the event loop.

passwordHashing:
  maxWorkers: 2

timeouts

Time budgets, in milliseconds, for outbound calls made inside a request. Each key is optional and takes a positive integer up to 2147483647. Exceeding a budget fails the call with an error naming the key.

timeouts:
  ragMs: 30000
  ocrMs: 300000

violationLog

violationLog:
  maxEntries: 100

messages

messages:
  maxPageSize: 1000

concurrency

Upper bounds on independent lookups a request runs at once. Each key is optional and takes an integer from 1 to 32. Setting a key to 1 restores serial lookups.

concurrency:
  connectedAgentLoads: 4
  skillNameLookups: 8

clientLimits

Request deadlines for the browser client, in milliseconds, and upload concurrency. Every key is optional; omitting the block keeps the defaults. Raise a deadline when your infrastructure legitimately needs longer. Deadlines accept positive integers up to 3600000, and unknown keys are rejected.

clientLimits:
  refreshMs: 30000
  uploadConcurrency: 3

openapi

openapi:
  enabled: true

skillDeletion

Controls how deleted Skills are finalized and cleaned up in the background. See Skill Deletion for the keys.

mcpAppSandbox

Configures the sandbox host, size limits, and rate limits for MCP Apps rendered in chat. See MCP App Sandbox Object Structure.

balance

Configures token credit balances, including starting balance, automatic refills, refill mode, and how the balance is displayed. See Balance 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

Langfuse Prompt Synchronization

langfuse.promptSync configures prompt catalog synchronization. The operator must first offer it with LANGFUSE_PROMPT_SYNC_AVAILABLE=true, and an authorized administrator must enable the stored Base switch in Settings → Langfuse. A YAML value alone does not replace that active stored setting.

Synchronization is append-only. A page-capped run starts from page 1 again on retry; increase maxPages to reach prompts beyond the same cap. See the Langfuse guide.

Admin Catalog Model Cache

endpoints.catalogModelsTtlMs defaults to 120000 milliseconds and accepts integers 0–3600000. Only deployment librechat.yaml sets it. The admin scope catalog reuses model lists for that period while endpoint configuration is unchanged. 0 resolves models on every catalog read, but a fetched list may still come from the separate two-minute provider model-list cache.