# Config Structure (https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/config)

**Note:** Fields not specifically mentioned as required are optional.

## version

- **required**

<OptionTable
  options={[
    ['version', 'String', 'Specifies the version of the configuration file.', 'version: 1.3.15'],
  ]}
/>

## cache

<OptionTable
  options={[
    [
      'cache',
      'Boolean',
      'Toggles caching on or off. Set to `true` to enable caching (default).',
      'cache: true',
    ],
  ]}
/>

## langfuse

<OptionTable
  options={[
    [
      'langfuse',
      'Object',
      'Configures the encrypted Langfuse connection and deployment-owned request headers.',
      '',
    ],
  ]}
/>

**Subkeys:**

<OptionTable
  options={[
    ['enabled', 'Boolean', 'Enables or disables Langfuse tracing for this config scope.', ''],
    ['publicKey', 'String', 'Langfuse project public key.', ''],
    ['secretKey', 'String', 'Encrypted Langfuse project secret key.', ''],
    ['projectId', 'String', 'Verified Langfuse project identity.', ''],
    ['secretKeyPreview', 'String', 'Server-generated masked preview of the stored secret key.', ''],
    [
      'destination',
      'String',
      'Selects one deployment-approved Langfuse destination key.',
      '',
    ],
    [
      'headers',
      'Object/Map of Strings',
      'Deployment-owned headers sent to one configured Langfuse origin for proxy or gateway authentication. Supports `${ENV_VAR}` references.',
      '',
    ],
  ]}
/>

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.

```yaml filename="langfuse / headers"
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](/docs/configuration/langfuse) for availability rules, authenticated proxy setup, environment-managed credentials, and optional fanout deployment.

## skillSync

<OptionTable
  options={[
    [
      'skillSync',
      'Object',
      'Configures external Skill mirroring. In v1.3.13, GitHub Skill Sync is supported.',
      '',
    ],
  ]}
/>

see: [Skill Sync Object Structure](/docs/configuration/librechat_yaml/object_structure/skill_sync)

## filters

<OptionTable
  options={[
    [
      'filters',
      'Object',
      'Configures source-aware content protection for messages, prompts, Agent instructions, conversation starters and titles, feedback, Skills, memories, files, tool arguments, model parameters, and Action metadata.',
      '',
    ],
  ]}
/>

`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](/docs/configuration/librechat_yaml/object_structure/message_filter#source-aware-filters)

## messageFilter

<OptionTable
  options={[
    [
      'messageFilter',
      'Object',
      'Configures the legacy message-only PII policy. Existing deployments can keep this block while migrating to `filters.messages`; when both are configured, both policies apply.',
      '',
    ],
  ]}
/>

See: [Legacy messageFilter](/docs/configuration/librechat_yaml/object_structure/message_filter#legacy-messagefilter)

## fileStrategy

- **Options**: "local" | "firebase" | "s3" | "azure_blob" | "cloudfront"

<OptionTable
  options={[
    [
      'fileStrategy',
      'String',
      'Determines where to save user uploaded/generated files. Defaults to `"local"` if omitted.',
      'fileStrategy: "firebase"',
    ],
  ]}
/>

- **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](https://github.com/danny-avila/LibreChat/discussions/10280#discussioncomment-14803903) 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](/docs/configuration/cdn) for setup details

## fileStrategies

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

- **Available Strategies**: "local" | "firebase" | "s3" | "azure_blob" | "cloudfront"

<OptionTable
  options={[
    [
      'fileStrategies',
      'Object',
      'Configures different storage strategies for different file types. More flexible than the single fileStrategy option.',
      '',
    ],
  ]}
/>

**Sub-keys:**

<OptionTable
  options={[
    [
      'default',
      'String',
      'Fallback storage strategy when specific type is not defined. Defaults to "local".',
      '',
    ],
    [
      'avatar',
      'String',
      'Storage strategy for user and agent avatar images. Recommended to use a CDN-backed strategy (`"cloudfront"` or `"firebase"`) for best performance.',
      '',
    ],
    [
      'image',
      'String',
      'Storage strategy for images uploaded in chats. Recommended to use a CDN-backed strategy (`"cloudfront"` or `"firebase"`) for best performance.',
      '',
    ],
    ['document', 'String', 'Storage strategy for document uploads (PDFs, text files, etc.).', ''],
    ['skills', 'String', 'Storage strategy for files bundled with Skills.', ''],
  ]}
/>

- **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](https://github.com/danny-avila/LibreChat/discussions/10280#discussioncomment-14803903) 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](/docs/configuration/cdn) for setup details for each storage provider

**Examples:**

```yaml filename="fileStrategies - All in one place"
# Use a single strategy for all file types
fileStrategies:
  default: 's3'
```

```yaml filename="fileStrategies - Mixed strategies"
# 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
```

```yaml filename="fileStrategies - Partial configuration"
# Only configure specific types, others use default
fileStrategies:
  default: 'local'
  avatar: 'firebase' # Only avatars use Firebase CDN, everything else is local
```

## cloudfront

**Key:**

<OptionTable
  options={[['cloudfront', 'Object', 'Configures CloudFront delivery for files stored in S3.', '']]}
/>

**Subkeys:**

<OptionTable
  options={[
    [
      'domain',
      'String',
      'CloudFront distribution domain or CNAME. Required when any file strategy uses `"cloudfront"`.',
      'domain: "https://cdn.example.com"',
    ],
    [
      'distributionId',
      'String',
      'CloudFront distribution ID. Required when `invalidateOnDelete` is true.',
      'distributionId: "E1234ABCD"',
    ],
    [
      'invalidateOnDelete',
      'Boolean',
      'Creates a CloudFront invalidation for deleted files. Default: false.',
      'invalidateOnDelete: false',
    ],
    [
      'imageSigning',
      'String',
      'Controls inline image/avatar access. Options: `"none"` or `"cookies"`. `"url"` is reserved and not implemented for images.',
      'imageSigning: "cookies"',
    ],
    [
      'cookieDomain',
      'String',
      'Shared parent cookie domain required for signed cookies. Must start with a dot.',
      'cookieDomain: ".example.com"',
    ],
    [
      'cookieExpiry',
      'Number',
      'Signed cookie lifetime in seconds. Default: 1800, maximum: 604800.',
      'cookieExpiry: 1800',
    ],
    [
      'urlExpiry',
      'Number',
      'Signed CloudFront download URL lifetime in seconds. Default: 3600.',
      'urlExpiry: 3600',
    ],
    [
      'storageRegion',
      'String',
      'Optional region label used in generated object keys when region paths are enabled.',
      'storageRegion: "us-east-2"',
    ],
    [
      'includeRegionInPath',
      'Boolean',
      'Includes the storage region in newly generated object keys. Default: false.',
      'includeRegionInPath: false',
    ],
    [
      'requireSignedAccess',
      'Boolean',
      'Refuses startup when signed-cookie CloudFront access cannot initialize. Default: false.',
      'requireSignedAccess: true',
    ],
  ]}
/>

see: [CloudFront Object Structure](/docs/configuration/librechat_yaml/object_structure/cloudfront) and [CloudFront with S3](/docs/configuration/cdn/cloudfront)

## filteredTools

<OptionTable
  options={[
    [
      'filteredTools',
      'Array of Strings',
      'Filters out specific tools from both Plugins and OpenAI Assistants endpoints.',
      'filteredTools: ["scholarai", "calculator"]',
    ],
  ]}
/>

- **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`](https://github.com/danny-avila/LibreChat/blob/main/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

<OptionTable
  options={[
    [
      'includedTools',
      'Array of Strings',
      'Includes specific tools from both Plugins and OpenAI Assistants endpoints.',
      'includedTools: ["calculator"]',
    ],
  ]}
/>

- **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`](https://github.com/danny-avila/LibreChat/blob/main/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

<OptionTable
  options={[
    [
      'secureImageLinks',
      'Boolean',
      'Requires authorization for image links hosted locally by the app. Default: true.',
      'secureImageLinks: true',
    ],
  ]}
/>

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"

<OptionTable
  options={[
    [
      'imageOutputType',
      'String',
      'The image output type for image responses. Defaults to "png" if omitted.',
      'imageOutputType: "webp"',
    ],
  ]}
/>

## ocr

**Key:**

<OptionTable
  options={[
    [
      'ocr',
      'Object',
      'Configures Optical Character Recognition (OCR) settings for extracting text from images.',
      '',
    ],
  ]}
/>

**Subkeys:**

<OptionTable
  options={[
    ['apiKey', 'String', 'The API key for the OCR service.', ''],
    ['baseURL', 'String', 'The base URL for the OCR service API.', ''],
    [
      'strategy',
      'String',
      'The OCR strategy to use. Options are "mistral_ocr", "azure_mistral_ocr", "vertexai_mistral_ocr", "document_parser", or "custom_ocr".',
      '',
    ],
    ['mistralModel', 'String', 'The Mistral model to use for OCR processing.', ''],
    [
      'allowedAddresses',
      'Array of Strings',
      'Trusted private host:port exemptions for OCR connect-time SSRF checks. Public destinations remain available.',
      '',
    ],
  ]}
/>

see: [OCR Config Object Structure](/docs/configuration/librechat_yaml/object_structure/ocr)

## webSearch

**Key:**

<OptionTable
  options={[
    [
      'webSearch',
      'Object',
      'Configures web search functionality, including search providers, content scrapers, and result rerankers.',
      '',
    ],
  ]}
/>

**Subkeys:**

<OptionTable
  options={[
    [
      'serperApiKey',
      'String',
      'Environment variable name for the Serper API key. If not set in .env, users will be prompted to provide it via UI.',
      '',
    ],
    [
      'searxngInstanceUrl',
      'String',
      'Environment variable name for the SearXNG instance URL. If not set in .env, users will be prompted to provide it via UI.',
      '',
    ],
    [
      'searxngApiKey',
      'String',
      'Environment variable name for the SearXNG API key. If not set in .env, users will be prompted to provide it via UI.',
      '',
    ],
    [
      'tavilyApiKey',
      'String',
      'Environment variable name for the Tavily API key. Used for both search and scraper. If not set in .env, users will be prompted to provide it via UI.',
      '',
    ],
    [
      'tavilySearchUrl',
      'String',
      'Environment variable name for a custom Tavily Search API URL. Optional; defaults to Tavily hosted search when unset.',
      '',
    ],
    [
      'tavilyExtractUrl',
      'String',
      'Environment variable name for a custom Tavily Extract API URL. Optional; defaults to Tavily hosted extract when unset.',
      '',
    ],
    [
      'firecrawlApiKey',
      'String',
      'Environment variable name for the Firecrawl API key. If not set in .env, users will be prompted to provide it via UI.',
      '',
    ],
    [
      'firecrawlApiUrl',
      'String',
      'Environment variable name for the Firecrawl API URL. If not set in .env, users will be prompted to provide it via UI.',
      '',
    ],
    [
      'jinaApiKey',
      'String',
      'Environment variable name for the Jina API key. If not set in .env, users will be prompted to provide it via UI.',
      '',
    ],
    [
      'cohereApiKey',
      'String',
      'Environment variable name for the Cohere API key. If not set in .env, users will be prompted to provide it via UI.',
      '',
    ],
    [
      'searchProvider',
      'String',
      'Specifies which search provider to use. Options: "serper", "searxng", "tavily".',
      '',
    ],
    [
      'scraperProvider',
      'String',
      'Specifies which scraper service to use. Options: "firecrawl", "serper", "tavily".',
      '',
    ],
    ['firecrawlVersion', 'String', 'Specifies Firecrawl API version (v0 or v1).', ''],
    [
      'rerankerType',
      'String',
      'Specifies which reranker service to use. Set to "none" to skip reranking. Options: "jina", "cohere", "none".',
      '',
    ],
    [
      'scraperTimeout',
      'Integer',
      'Timeout in milliseconds for scraper requests. Must be a non-negative integer.',
      '',
    ],
    [
      'safeSearch',
      'Number',
      'Safe search filtering level. 0 = OFF, 1 = MODERATE (default), 2 = STRICT.',
      '',
    ],
    [
      'allowedAddresses',
      'Array of Strings',
      'Trusted private host:port exemptions for web search, scrape, and rerank connect-time SSRF checks. Public destinations remain available.',
      '',
    ],
  ]}
/>

see: [Web Search Object Structure](/docs/configuration/librechat_yaml/object_structure/web_search)

## fileConfig

**Key:**

<OptionTable
  options={[
    [
      'fileConfig',
      'Object',
      'Configures file handling settings for the application, including size limits and MIME type restrictions.',
      '',
    ],
  ]}
/>

**Subkeys:**

<OptionTable
  options={[
    [
      'endpoints',
      'Record/Object',
      'Specifies file handling configurations for individual endpoints, allowing customization per endpoint basis.',
      '',
    ],
    [
      'serverFileSizeLimit',
      'Number',
      'The maximum file size (in MB) that the server will accept. Applies globally across all endpoints unless overridden by endpoint-specific settings.',
      '',
    ],
    ['avatarSizeLimit', 'Number', 'Maximum size (in MB) for user avatar images.', ''],
    [
      'clientImageResize',
      'Object',
      'Configures client-side image resizing to optimize file uploads and prevent upload errors due to large image sizes.',
      '',
    ],
    ['ocr', 'Object', 'Settings for Optical Character Recognition (OCR) file processing.', ''],
    ['text', 'Object', 'Settings for direct text file parsing.', ''],
    ['stt', 'Object', 'Settings for Speech-to-Text (STT) audio file processing.', ''],
    [
      'fileTokenLimit',
      'Number',
      'Maximum number of tokens from text files to include in prompts before truncation.',
      'fileTokenLimit: 100000',
    ],
  ]}
/>

## clientImageResize

**Key:**

<OptionTable
  options={[
    [
      'clientImageResize',
      'Object',
      'Configures client-side image resizing to optimize file uploads and prevent upload errors due to large image sizes.',
      '',
    ],
  ]}
/>

**Subkeys:**

<OptionTable
  options={[
    [
      'enabled',
      'Boolean',
      'When explicitly set, forces client-side resizing on or off for every user and locks the Settings toggle. Omit it to let each user choose in Settings > Chat; the user preference defaults to off.',
      'enabled: true',
    ],
    [
      'maxWidth',
      'Number',
      'Maximum width in pixels for resized images. Must be at least 1. Default: 1900.',
      'maxWidth: 1900',
    ],
    [
      'maxHeight',
      'Number',
      'Maximum height in pixels for resized images. Must be at least 1. Default: 1900.',
      'maxHeight: 1900',
    ],
    [
      'quality',
      'Number',
      'Browser encoder quality from 0 to 1. Higher values usually preserve more detail and produce larger files. Default: 0.92.',
      'quality: 0.92',
    ],
  ]}
/>

**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:**

```yaml filename="clientImageResize"
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](/docs/configuration/librechat_yaml/object_structure/file_config)

## rateLimits

**Key:**

<OptionTable
  options={[
    [
      'rateLimits',
      'Object',
      'Defines rate limiting policies to prevent abuse by limiting the number of requests.',
      '',
    ],
  ]}
/>

**Subkeys:**

<OptionTable
  options={[
    [
      'fileUploads',
      'Object',
      'Configures rate limits specifically for file upload operations.',
      '',
    ],
    [
      'conversationsImport',
      'Object',
      'Configures rate limits specifically for conversation import operations.',
      '',
    ],
    [
      'agentEvents',
      'Object',
      'Configures the API-key-principal admission limit for authenticated Agent event requests.',
      '',
    ],
    ['stt', 'Object', 'Configures rate limits specifically for speech-to-text (stt) requests', ''],
    ['tts', 'Object', 'Configures rate limits specifically for text-to-speech (tts) requests', ''],
  ]}
/>

**fileUploads Subkeys:**

<OptionTable
  options={[
    ['ipMax', 'Number', 'Maximum number of uploads allowed per IP address per window.', ''],
    ['ipWindowInMinutes', 'Number', 'Time window in minutes for the IP-based upload limit.', ''],
    ['userMax', 'Number', 'Maximum number of uploads allowed per user per window.', ''],
    [
      'userWindowInMinutes',
      'Number',
      'Time window in minutes for the user-based upload limit.',
      '',
    ],
  ]}
/>

**conversationsImport Subkeys:**

<OptionTable
  options={[
    ['ipMax', 'Number', 'Maximum number of imports allowed per IP address per window.', ''],
    ['ipWindowInMinutes', 'Number', 'Time window in minutes for the IP-based imports limit.', ''],
    ['userMax', 'Number', 'Maximum number of imports per user per window.', ''],
    [
      'userWindowInMinutes',
      'Number',
      'Time window in minutes for the user-based imports limit.',
      '',
    ],
  ]}
/>

**agentEvents Subkeys:**

<OptionTable
  options={[
    [
      'userMax',
      'Number',
      'Maximum authenticated Agent event admissions per Remote Agents API key principal in one window.',
      '40',
    ],
    [
      'userWindowInMinutes',
      'Number',
      'Length of the authenticated Agent event admission window in minutes.',
      '1',
    ],
  ]}
/>

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:**

<OptionTable
  options={[
    ['ipMax', 'Number', 'Maximum number of requests allowed per IP address per window.', ''],
    ['ipWindowInMinutes', 'Number', 'Time window in minutes for the IP-based requests limit.', ''],
    ['userMax', 'Number', 'Maximum number of requests per user per window.', ''],
    [
      'userWindowInMinutes',
      'Number',
      'Time window in minutes for the user-based requests limit.',
      '',
    ],
  ]}
/>

**stt Subkeys:**

<OptionTable
  options={[
    ['ipMax', 'Number', 'Maximum number of requests allowed per IP address per window.', ''],
    ['ipWindowInMinutes', 'Number', 'Time window in minutes for the IP-based requests limit.', ''],
    ['userMax', 'Number', 'Maximum number of requests per user per window.', ''],
    [
      'userWindowInMinutes',
      'Number',
      'Time window in minutes for the user-based requests limit.',
      '',
    ],
  ]}
/>

    - **Example**:
    ```yaml filename="rateLimits"
    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:**

<OptionTable
  options={[
    ['registration', 'Object', 'Configures registration-related settings for the application.', ''],
  ]}
/>

**Subkeys:**

<OptionTable
  options={[
    ['socialLogins', '', 'Social login configurations.', ''],
    ['allowedDomains', '', 'Specifies allowed domains for registration.', ''],
  ]}
/>

see also:

- [socialLogins](/docs/configuration/librechat_yaml/object_structure/registration#sociallogins),
- [alloweddomains](/docs/configuration/librechat_yaml/object_structure/registration#alloweddomains),
- [Registration Object Structure](/docs/configuration/librechat_yaml/object_structure/registration)

## memory

**Key:**

<OptionTable
  options={[
    [
      'memory',
      'Object',
      'Configures conversation memory and personalization features for the application.',
      '',
    ],
  ]}
/>

**Subkeys:**

<OptionTable
  options={[
    ['disabled', 'Boolean', 'Disables memory functionality when set to true.', ''],
    ['validKeys', 'Array of Strings', 'Specifies which keys are valid for memory storage.', ''],
    [
      'tokenLimit',
      'Number',
      'Sets the maximum number of tokens for memory storage and processing.',
      '',
    ],
    [
      'charLimit',
      'Number',
      'Sets the maximum number of characters for memory storage. Default: 10000.',
      '',
    ],
    [
      'maxInputTokens',
      'Number',
      'Caps the recent-chat tokens sent to the automatic memory agent before extraction. Default: 12000.',
      '',
    ],
    ['personalize', 'Boolean', 'Enables or disables personalization features.', ''],
    [
      'messageWindowSize',
      'Number',
      'Specifies the number of recent messages to include in memory context.',
      '',
    ],
    [
      'agent',
      'Object | Union',
      'Configures the optional automatic memory agent. Set `agent.enabled: true` to run it.',
      '',
    ],
  ]}
/>

see: [Memory Object Structure](/docs/configuration/librechat_yaml/object_structure/memory)

## summarization

**Key:**

<OptionTable
  options={[
    [
      'summarization',
      'Object',
      'Configures conversation summarization and context pruning. Replaces the per-endpoint `summarize` and `summaryModel` fields.',
      '',
    ],
  ]}
/>

**Subkeys:**

<OptionTable
  options={[
    [
      'provider',
      'String',
      "LLM provider for summarization calls. Defaults to the agent's own provider.",
      '',
    ],
    ['model', 'String', "Model for summarization calls. Defaults to the agent's own model.", ''],
    ['parameters', 'Object', 'Additional LLM parameters for summarization requests.', ''],
    ['prompt', 'String', 'Custom prompt for initial summarization.', ''],
    ['updatePrompt', 'String', 'Custom prompt for re-compaction when a prior summary exists.', ''],
    [
      'trigger',
      'Object',
      'Defines when summarization is triggered (by token ratio, remaining tokens, or message count).',
      '',
    ],
    [
      'maxSummaryTokens',
      'Number',
      'Maximum output tokens for the summarization model response.',
      '',
    ],
    [
      'reserveRatio',
      'Number',
      'Fraction of token budget reserved as headroom (0–1). Default: 0.05.',
      '',
    ],
    [
      'contextPruning',
      'Object',
      'Configures position-based tool result degradation for older messages.',
      '',
    ],
    [
      'retainRecent',
      'Object',
      'Preserves recent complete turns and/or tokens outside the generated summary.',
      '',
    ],
  ]}
/>

see: [Summarization Object Structure](/docs/configuration/librechat_yaml/object_structure/summarization)

## actions

**Key:**

<OptionTable
  options={[
    ['actions', 'Object', 'Configures actions-related settings, used by Agents and Assistants', ''],
  ]}
/>

**Subkeys:**

<OptionTable
  options={[
    [
      'allowedDomains',
      'Array of Strings',
      'Strict whitelist of domains for actions. When set, only listed domains are reachable.',
      '',
    ],
    [
      'allowedAddresses',
      'Array of Strings',
      'SSRF exemption list (private IP space only). Permits specific private host:port services without restricting public destinations when `allowedDomains` is not configured.',
      '',
    ],
  ]}
/>

see also:

- [allowedDomains](/docs/configuration/librechat_yaml/object_structure/actions#alloweddomains),
- [allowedAddresses](/docs/configuration/librechat_yaml/object_structure/actions#allowedaddresses),
- [Actions Object Structure](/docs/configuration/librechat_yaml/object_structure/actions)

## interface

**Key:**

<OptionTable
  options={[
    [
      'interface',
      'Object',
      'Configures user interface elements within the application, allowing for customization of visibility and behavior of various components.',
      '',
    ],
  ]}
/>

**Subkeys:**

<OptionTable
  options={[
    [
      'privacyPolicy',
      'Object',
      'Contains settings related to the privacy policy link provided.',
      '',
    ],
    [
      'termsOfService',
      'Object',
      'Contains settings related to the terms of service link provided.',
      '',
    ],
    ['modelSelect', 'Boolean', 'Determines whether the model selection feature is available.', ''],
    [
      'parameters',
      'Boolean',
      'Toggles the visibility of parameter configuration options AKA conversation settings.',
      '',
    ],
    ['presets', 'Boolean', 'Enables or disables the presets menu', ''],
    [
      'prompts',
      'Boolean or Object',
      'Enables or disables all prompt-related features for all users',
      '',
    ],
    [
      'bookmarks',
      'Boolean',
      'Enables or disables all bookmarks-related features for all users',
      '',
    ],
    ['memories', 'Boolean', 'Enables or disables the memories feature for all users', ''],
    [
      'multiConvo',
      'Boolean',
      'Enables or disables all "multi convo", AKA multiple response streaming, related features for all users',
      '',
    ],
    ['agents', 'Boolean or Object', 'Enables or disables all agents features for all users', ''],
    ['temporaryChat', 'Boolean', 'Enables or disables the temporary chat feature', ''],
    [
      'temporaryChatRetention',
      'Number',
      'Configures the retention period for temporary chats in hours. Min: 1, Max: 8760. Default: 720 (30 days).',
      '',
    ],
    [
      'autoSubmitFromUrl',
      'Boolean',
      'Controls whether `/c/new?prompt=…&submit=true` auto-submits to the model. When `false`, the prompt is pre-filled but not submitted.',
      '',
    ],
    [
      'mcpServers',
      'Object',
      'Contains settings related to MCP server selection and access control.',
      '',
    ],
    ['customWelcome', 'String', 'Custom welcome message displayed in the chat interface.', ''],
    [
      'runCode',
      'Boolean',
      'Enables or disables the "Run Code" button for Markdown Code Blocks',
      '',
    ],
    ['webSearch', 'Boolean', 'Enables or disables the web search button in the chat interface', ''],
    [
      'fileSearch',
      'Boolean',
      'Enables or disables the file search button in the chat interface',
      '',
    ],
    ['fileCitations', 'Boolean', 'Globally enables or disables file citations for all users', ''],
    [
      'feedback',
      'Boolean',
      'Shows or hides the thumbs up/thumbs down feedback buttons on responses',
      '',
    ],
    [
      'peoplePicker',
      'Object',
      'Configures which principal types are available controls in the people picker interface',
      '',
    ],
    ['marketplace', 'Object', 'Enables or disables access to the Agent Marketplace', ''],
  ]}
/>
see: [Interface Object Structure](/docs/configuration/librechat_yaml/object_structure/interface)

## modelSpecs

**Key:**

<OptionTable
  options={[
    [
      'modelSpecs',
      'Object',
      'Configures model specifications, allowing for detailed setup and customization of AI models and their behaviors within the application.',
      '',
    ],
  ]}
/>

**Subkeys:**

<OptionTable
  options={[
    [
      'enforce',
      'Boolean',
      'Determines whether the model specifications should strictly override other configuration settings.',
      '',
    ],
    [
      'prioritize',
      'Boolean',
      'Specifies if model specifications should take priority over the default configuration when both are applicable.',
      '',
    ],
    [
      'list',
      'Array of Objects',
      'Contains a list of individual model specifications detailing various configurations and behaviors.',
      '',
    ],
  ]}
/>

see: [Model Specs Object Structure](/docs/configuration/librechat_yaml/object_structure/model_specs)

## endpoints

**Key:**

<OptionTable
  options={[['endpoints', 'Object', 'Defines custom API endpoints for the application.', '']]}
/>

**Subkeys:**

<OptionTable
  options={[
    [
      'custom',
      'Array of Objects',
      'Each object in the array represents a unique endpoint configuration.',
      '',
    ],
    ['azureOpenAI', 'Object', 'Azure OpenAI endpoint-specific configuration', ''],
    ['assistants', 'Object', 'Assistants endpoint-specific configuration.', ''],
    ['azureAssistants', 'Object', 'Azure Assistants endpoint-specific configuration.', ''],
    ['agents', 'Object', 'Agents endpoint-specific configuration.', ''],
    [
      'all',
      'Object',
      'Global endpoint settings that apply to all endpoints. See Shared Endpoint Settings.',
      '',
    ],
    [
      'allowedAddresses',
      'Array of Strings',
      'SSRF exemption list (private IP space only). Permits user-provided baseURLs to point at specific private host:port services (e.g. self-hosted Ollama) without disabling SSRF protection for everything else.',
      '',
    ],
  ]}
/>

> **Note:** Endpoints support [Shared Endpoint Settings](/docs/configuration/librechat_yaml/object_structure/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`](/docs/configuration/librechat_yaml/object_structure/mcp_settings#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:**

<OptionTable
  options={[
    [
      'mcpSettings',
      'Object',
      'Defines global settings for Model Context Protocol (MCP) servers',
      '',
    ],
  ]}
/>

**Subkeys:**

<OptionTable
  options={[
    [
      'allowedDomains',
      'Array of Strings',
      'Strict whitelist of domains for MCP server connections. When set, only listed entries are reachable.',
      '',
    ],
    [
      'allowedAddresses',
      'Array of Strings',
      'SSRF exemption list (private IP space only). Permits specific private host:port services without flipping `allowedDomains` into strict-whitelist mode.',
      '',
    ],
  ]}
/>

- **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:**

```yaml filename="mcpSettings"
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](/docs/configuration/librechat_yaml/object_structure/mcp_settings)

## mcpServers

**Key:**

<OptionTable
  options={[
    [
      'mcpServers',
      'Object',
      'Defines the configuration for Model Context Protocol (MCP) servers, allowing dynamic integration of MCP servers within the application.',
      '',
    ],
  ]}
/>

**Subkeys:**

<OptionTable
  options={[
    [
      '<serverName>',
      'Object',
      'Each key under `mcpServers` represents an individual MCP server configuration, identified by a unique name.',
      '',
    ],
  ]}
/>

- **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](/docs/configuration/librechat_yaml/object_structure/mcp_servers)

**Example:**

```yaml filename="mcpServers"
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](/docs/configuration/librechat_yaml/object_structure/mcp_servers)

## speech

**Key:**

<OptionTable
  options={[
    [
      'speech',
      'Object',
      'Configures Text-to-Speech (TTS) and Speech-to-Text (STT) providers for the application.',
      '',
    ],
  ]}
/>

**Subkeys:**

<OptionTable
  options={[
    [
      'tts',
      'Object',
      'Text-to-Speech provider configurations (OpenAI, Azure OpenAI, ElevenLabs, LocalAI).',
      '',
    ],
    ['stt', 'Object', 'Speech-to-Text provider configurations (OpenAI, Azure OpenAI).', ''],
    ['speechTab', 'Object', 'Default UI settings for speech features.', ''],
  ]}
/>

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](/docs/configuration/librechat_yaml/object_structure/speech#ssrf-protection) for entry rules, proxy behavior, and examples.

see: [Speech Object Structure](/docs/configuration/librechat_yaml/object_structure/speech)

## turnstile

**Key:**

<OptionTable
  options={[
    [
      'turnstile',
      'Object',
      'Configures Cloudflare Turnstile for bot protection on registration and login forms.',
      '',
    ],
  ]}
/>

**Subkeys:**

<OptionTable
  options={[
    ['siteKey', 'String', 'Your Cloudflare Turnstile site key (required).', ''],
    ['options', 'Object', 'Additional Turnstile widget options (optional).', ''],
  ]}
/>

see: [Turnstile Object Structure](/docs/configuration/librechat_yaml/object_structure/turnstile)

## transactions

**Key:**

<OptionTable
  options={[
    ['transactions', 'Object', 'Controls transaction logging and visibility features.', ''],
  ]}
/>

**Subkeys:**

<OptionTable
  options={[['enabled', 'Boolean', 'Enables or disables transaction logging. Default: true.', '']]}
/>

see: [Transactions Object Structure](/docs/configuration/librechat_yaml/object_structure/transactions)

## Additional links

- [Summarization Object Structure](/docs/configuration/librechat_yaml/object_structure/summarization)
- [AWS Bedrock Object Structure](/docs/configuration/librechat_yaml/object_structure/aws_bedrock)
- [Custom Endpoint Object Structure](/docs/configuration/librechat_yaml/object_structure/custom_endpoint)
- [Azure OpenAI Endpoint Object Structure](/docs/configuration/librechat_yaml/object_structure/azure_openai)
- [Assistants Endpoint Object Structure](/docs/configuration/librechat_yaml/object_structure/assistants_endpoint)
- [Agents](/docs/configuration/librechat_yaml/object_structure/agents)
- [OCR Config Object Structure](/docs/configuration/librechat_yaml/object_structure/ocr)
- [Speech Object Structure](/docs/configuration/librechat_yaml/object_structure/speech)
- [Turnstile Object Structure](/docs/configuration/librechat_yaml/object_structure/turnstile)
- [Transactions Object Structure](/docs/configuration/librechat_yaml/object_structure/transactions)
- [Balance Object Structure](/docs/configuration/librechat_yaml/object_structure/balance)
- [Web Search Object Structure](/docs/configuration/librechat_yaml/object_structure/web_search)
- [Memory Object Structure](/docs/configuration/librechat_yaml/object_structure/memory)