🧾 docs: Document v0.8.6 Env, Config, And Changelog (#586)

* docs: Document Redis cluster-safe deletes

* docs: document v0.8.6 env and config updates

* docs: add v0.8.6 changelog

Author: danny-avila

content/changelog/config_v1.3.12.mdx

@@ -0,0 +1,16 @@
+---
+date: 2026-05-25
+title: ⚙️ Config v1.3.12
+version: '1.3.12'
+---
+
+- Added `interface.retentionMode`
+  - `"temporary"` keeps retention limited to temporary chats
+  - `"all"` applies configured retention to all supported retained data, including persistent agent resource files
+
+- Added `mcpServers.<server>.proxy`
+  - Allows `sse` and `streamable-http` MCP servers to use a per-server outbound proxy
+  - Supports `http://`, `https://`, `socks://`, and `socks5://` proxy URLs
+
+- Added `modelSpecs.list[].hideBadgeRow`
+  - Allows a model spec to hide the tool badge row in the chat composer

content/changelog/v0.8.6.mdx

@@ -258,6 +258,12 @@ To configure LibreChat for local use or custom domain deployment, set the follow
       'Specifies the server-side domain.',
       'DOMAIN_SERVER=http://localhost:3080',
     ],
+    [
+      'ADMIN_PANEL_URL',
+      'string',
+      'External admin panel base URL used for admin OAuth/SSO redirects when the admin panel is hosted separately. Do not include a trailing slash.',
+      'ADMIN_PANEL_URL=https://admin.example.com/admin',
+    ],
   ]}
 />
 
@@ -303,6 +309,12 @@ LibreChat has built-in central logging, see [Logging System](/docs/configuration
       'Enable verbose console/stdout logs in the same format as file debug logs.',
       'DEBUG_CONSOLE=false',
     ],
+    [
+      'LOG_TO_FILE',
+      'boolean',
+      'Set to false to disable file-backed Winston transports while keeping console logging available.',
+      'LOG_TO_FILE=true',
+    ],
     [
       'CONSOLE_JSON',
       'boolean',
@@ -356,6 +368,65 @@ Note: `DEBUG_CONSOLE` is not recommended, as the outputs can be quite verbose, a
   ]}
 />
 
+### OpenTelemetry Tracing
+
+LibreChat can emit backend OpenTelemetry traces for general API, HTTP, MongoDB, Mongoose, Redis, and outbound request visibility. Use Langfuse for GenAI-specific prompt/model observability.
+
+<OptionTable
+  options={[
+    [
+      'OTEL_TRACING_ENABLED',
+      'boolean',
+      'Enable backend OpenTelemetry tracing. Tracing remains disabled when OTEL_SDK_DISABLED=true.',
+      '# OTEL_TRACING_ENABLED=false',
+    ],
+    [
+      'OTEL_SERVICE_NAME',
+      'string',
+      'Service name reported to OpenTelemetry. Default: librechat.',
+      '# OTEL_SERVICE_NAME=librechat',
+    ],
+    [
+      'OTEL_SERVICE_VERSION',
+      'string',
+      'Service version reported to OpenTelemetry. Defaults to the package version when unset.',
+      '# OTEL_SERVICE_VERSION=',
+    ],
+    [
+      'OTEL_EXPORTER_OTLP_ENDPOINT',
+      'string',
+      'Base OTLP exporter endpoint.',
+      '# OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318',
+    ],
+    [
+      'OTEL_EXPORTER_OTLP_TRACES_ENDPOINT',
+      'string',
+      'Trace-specific OTLP endpoint. Overrides the base endpoint for traces when set.',
+      '# OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=',
+    ],
+    [
+      'OTEL_EXPORTER_OTLP_HEADERS',
+      'string',
+      'Comma-separated OTLP exporter headers, such as authorization metadata.',
+      '# OTEL_EXPORTER_OTLP_HEADERS=',
+    ],
+    ['OTEL_TRACES_EXPORTER', 'string', 'Trace exporter selection.', '# OTEL_TRACES_EXPORTER=otlp'],
+    [
+      'OTEL_TRACES_SAMPLER',
+      'string',
+      'OpenTelemetry trace sampler. Default example: parentbased_always_on.',
+      '# OTEL_TRACES_SAMPLER=parentbased_always_on',
+    ],
+    ['OTEL_LOG_LEVEL', 'string', 'OpenTelemetry SDK log level.', '# OTEL_LOG_LEVEL=INFO'],
+    [
+      'OTEL_SDK_DISABLED',
+      'boolean',
+      'Disable the OpenTelemetry SDK even if tracing is enabled.',
+      '# OTEL_SDK_DISABLED=false',
+    ],
+  ]}
+/>
+
 ### Configuration Path - `librechat.yaml`
 
 Specify an alternative location for the LibreChat configuration file.
@@ -431,7 +502,12 @@ Uncomment `ENDPOINTS` to customize the available endpoints in LibreChat.
       'Comma-separated list of available endpoints.',
       '# ENDPOINTS=openAI,agents,assistants,gptPlugins,azureOpenAI,google,anthropic,bingAI,custom',
     ],
-    ['PROXY', 'string', 'Proxy setting for all endpoints.', 'PROXY='],
+    [
+      'PROXY',
+      'string',
+      'Outbound proxy for server-side requests, including endpoint calls and remote MCP HTTP/SSE transports. Remote MCP transports also honor HTTP_PROXY, HTTPS_PROXY, and NO_PROXY when PROXY is unset.',
+      'PROXY=',
+    ],
     ['TITLE_CONVO', 'boolean', 'Enable titling for all endpoints.', 'TITLE_CONVO=true'],
   ]}
 />
@@ -1766,6 +1842,12 @@ see: **[Authentication System](/docs/configuration/authentication)**
       'Refresh token expiry time.',
       'REFRESH_TOKEN_EXPIRY=(1000 * 60 * 60 * 24) * 7',
     ],
+    [
+      'SESSION_COOKIE_SECURE',
+      'boolean',
+      'Overrides the Secure attribute for session/auth cookies. Leave unset to use the default NODE_ENV/DOMAIN_SERVER heuristic.',
+      '# SESSION_COOKIE_SECURE=false',
+    ],
   ]}
 />
 
@@ -2007,7 +2089,7 @@ For more information:
     [
       'OPENID_USE_PKCE',
       'boolean',
-      'Use PKCE (Proof Key for Code Exchange) for OpenID authentication.',
+      'Use PKCE (Proof Key for Code Exchange) for OpenID authentication. For public clients without a client secret, leave OPENID_CLIENT_SECRET empty and set this to true.',
       '# OPENID_USE_PKCE=true',
     ],
     [
@@ -2706,6 +2788,18 @@ Configure Model Context Protocol settings for enhanced server management and OAu
       'Skip code challenge method validation. When set to true, forces S256 code challenge even if not advertised in .well-known/openid-configuration',
       'MCP_SKIP_CODE_CHALLENGE_CHECK=false',
     ],
+    [
+      'MCP_STREAMABLE_HTTP_MAX_RESPONSE_BYTES',
+      'number',
+      'Maximum bytes allowed in a non-GET streamable HTTP MCP response before rejecting it. Set to 0 to disable. Default: 16777216 (16 MiB).',
+      '# MCP_STREAMABLE_HTTP_MAX_RESPONSE_BYTES=16777216',
+    ],
+    [
+      'MCP_STREAMABLE_HTTP_MAX_LINE_BYTES',
+      'number',
+      'Maximum bytes allowed in one SSE line for non-GET streamable HTTP MCP responses. Set to 0 to disable. Default: 5242880 (5 MiB).',
+      '# MCP_STREAMABLE_HTTP_MAX_LINE_BYTES=5242880',
+    ],
   ]}
 />
 
@@ -2747,6 +2841,12 @@ For detailed configuration and examples, see: **[Redis Configuration Guide](/doc
       'Enable Redis cluster mode when using a single URI',
       '# USE_REDIS_CLUSTER="true"',
     ],
+    [
+      'REDIS_CLUSTER_SAFE_DELETE',
+      'boolean',
+      'Delete Redis cache keys individually to avoid CROSSSLOT errors on single-endpoint managed Redis services that shard keys internally.',
+      '# REDIS_CLUSTER_SAFE_DELETE=true',
+    ],
     [
       'REDIS_USERNAME',
       'string',
@@ -2808,6 +2908,7 @@ Notes:
 
 - When `USE_REDIS=true`, you must provide `REDIS_URI` or the application will throw an error.
 - For Redis Cluster mode, provide multiple URIs: `redis://node1:7001,redis://node2:7002,redis://node3:7003` (cluster mode is auto-detected).
+- For single-endpoint managed Redis services that shard keys internally, keep `USE_REDIS_CLUSTER=false` and set `REDIS_CLUSTER_SAFE_DELETE=true` if cache clears fail with `CROSSSLOT` errors.
 - Use `rediss://` protocol for TLS connections and set `REDIS_CA` if your CA is not publicly trusted.
 - `REDIS_KEY_PREFIX_VAR` and `REDIS_KEY_PREFIX` are mutually exclusive.
 - **AWS Elasticache with TLS**: Elasticache may need to use an alternate dnsLookup for TLS connections. Set `REDIS_USE_ALTERNATIVE_DNS_LOOKUP=true` if using Elasticache with TLS. See [ioredis documentation](https://www.npmjs.com/package/ioredis) for more details.

content/docs/configuration/dotenv.mdx

@@ -10,7 +10,7 @@ icon: FileCode
 This example config includes all documented endpoints (Except Azure, LiteLLM, MLX, and Ollama, which all require additional configurations)
 
 ```yaml filename="librechat.yaml"
-version: 1.3.11
+version: 1.3.12
 
 cache: true
 
@@ -273,7 +273,7 @@ This example configuration file sets up LibreChat with detailed options across s
 # https://www.librechat.ai/docs/configuration/librechat_yaml
 
 # Configuration version (required)
-version: 1.3.11
+version: 1.3.12
 
 # Cache settings: Set to true to enable caching
 cache: true

content/docs/configuration/librechat_yaml/example.mdx

@@ -22,6 +22,7 @@ These are fields under `interface`:
   - `agents`
   - `temporaryChat`
   - `temporaryChatRetention`
+  - `retentionMode`
   - `autoSubmitFromUrl`
   - `customWelcome`
   - `runCode`
@@ -491,6 +492,7 @@ The `temporaryChatRetention` configuration allows you to customize how long temp
 ```yaml filename="interface / temporaryChatRetention"
 interface:
   temporaryChatRetention: 168  # Retain temporary chats for 7 days
+  retentionMode: "temporary"
 ```
 
 **Common Retention Periods:**
@@ -500,6 +502,30 @@ interface:
 - **720 hours**: `temporaryChatRetention: 720` (30 days - default)
 - **8760 hours**: `temporaryChatRetention: 8760` (1 year - maximum)
 
+## retentionMode
+
+Controls which data receives retention deadlines.
+
+**Key:**
+<OptionTable
+  options={[
+    ['retentionMode', 'String', 'Set to "temporary" to apply retention only to temporary chats, or "all" to apply retention to all supported retained data, including persistent agent resource files.', 'retentionMode: "temporary"'],
+  ]}
+/>
+
+**Default:** `temporary`
+
+<Callout type="warning">
+`retentionMode: "all"` applies retention deadlines beyond temporary chats, including persistent agent resource files. Confirm your retention policy before enabling it.
+</Callout>
+
+**Example:**
+```yaml filename="interface / retentionMode"
+interface:
+  temporaryChatRetention: 168
+  retentionMode: "all"
+```
+
 ## autoSubmitFromUrl
 
 Controls whether a prompt supplied via URL query parameters on `/c/new` is auto-submitted to the model.
@@ -622,7 +648,7 @@ Controls the global availability of file citations functionality. When disabled,
 
 > **Deprecated for permission management.** Seeds/globally gates the `FILE_CITATIONS` role permission at startup. Prefer the [Admin Panel](/docs/features/admin_panel) for managing citations permissions per role/group/user.
 
-**Note:** 
+**Note:**
 - This setting acts as a global toggle for the `FILE_CITATIONS` permission system-wide.
 - When set to `false`, no users will see file citations, even if they have been granted the permission through roles.
 - File citations require the `fileSearch` feature to be enabled.

content/docs/configuration/librechat_yaml/object_structure/interface.mdx

@@ -44,6 +44,7 @@ mcpServers:
   streamable-http-server:
     type: streamable-http
     url: https://example.com/api/
+    proxy: "${MCP_PROXY_URL}"
   per-user-credentials-example:
     type: streamable-http
     url: "https://example.com/api/"
@@ -84,6 +85,7 @@ mcpServers:
     ['command', 'String', '(For `stdio` type) The command or executable to run to start the MCP server.', 'command: "npx"'],
     ['args', 'Array of Strings', '(For `stdio` type) Command line arguments to pass to the `command`.', 'args: ["-y", "@modelcontextprotocol/server-puppeteer"]'],
     ['url', 'String', '(For `websocket`, `streamable-http`, or `sse` type) The URL to connect to the MCP server.', 'url: "http://localhost:3001/sse"'],
+    ['proxy', 'String', '(Optional, for `sse` and `streamable-http` types) Outbound proxy URL for this remote MCP server. Supports `http://`, `https://`, `socks://`, and `socks5://` URLs.', 'proxy: "${MCP_PROXY_URL}"'],
     ['headers', 'Object', '(Optional, for `sse` and `streamable-http` types) Custom headers to send with the request. Supports dynamic user field substitution with `{{LIBRECHAT_USER_*}}` placeholders and environment variables with `${ENV_VAR}`.', 'headers:\n  X-User-ID: "{{LIBRECHAT_USER_ID}}"\n  X-API-Key: "${SOME_API_KEY}"'],
     ['apiKey', 'Object', '(Optional, for `sse` and `streamable-http` types) API key authentication configuration for the MCP server.', 'See apiKey section below'],
     ['iconPath', 'String', '(Optional) Defines the tool\'s display icon shown in the tool selection dialog.', 'iconPath: "/path/to/icon.svg"'],
@@ -150,6 +152,21 @@ mcpServers:
   - For `streamable-http` type, the URL must start with `http://` or `https://`.
   - For `websocket` type, the URL must start with `ws://` or `wss://`.
 
+#### `proxy`
+
+- **Type:** String (Optional, for `sse` and `streamable-http` types)
+- **Description:** Outbound proxy URL for this remote MCP server. The value can reference environment variables with `${ENV_VAR}`.
+- **Supported protocols:** `http://`, `https://`, `socks://`, and `socks5://`
+- **Security note:** `proxy` is admin-controlled. It resolves environment variables, but does not resolve user-controlled placeholders such as `{{LIBRECHAT_USER_ID}}` or `customUserVars`.
+- **Example:**
+  ```yaml
+  mcpServers:
+    remote-api:
+      type: streamable-http
+      url: https://api.example.com/mcp
+      proxy: "${MCP_PROXY_URL}"
+  ```
+
 #### `headers`
 
 - **Type:** Object (Optional, for `sse` and `streamable-http` types)
@@ -254,13 +271,13 @@ mcpServers:
   ```yaml
   # Use server-provided instructions
   serverInstructions: true
-  
+
   # Use custom instructions
   serverInstructions: |
     When using this filesystem server:
     1. Always use absolute paths for file operations
     2. Check file permissions before attempting write operations
-  
+
   # Explicitly disable instructions
   serverInstructions: false
   ```
@@ -351,7 +368,7 @@ mcpServers:
 - **Description:** OAuth2 configuration for authenticating with the MCP server. When configured, users will be prompted to authenticate via OAuth flow before the MCP server can be used. If no client id & client secret is provided, Dynamic Client Registration (DCR) will be used.
 - **Required Subkeys:**
   - `authorization_url`: String - The OAuth authorization endpoint URL
-  - `token_url`: String - The OAuth token endpoint URL  
+  - `token_url`: String - The OAuth token endpoint URL
   - `client_id`: String - OAuth client identifier
   - `client_secret`: String - OAuth client secret
   - `redirect_uri`: String - [OAuth redirect URI](/docs/features/mcp#oauth-callback-url) (eg. `http://localhost:3080/api/mcp/${serverName}/oauth/callback`)
@@ -427,7 +444,7 @@ mcpServers:
     type: streamable-http
     url: http://172.24.1.165:8000/mcp
     timeout: 120000
-  
+
   test-mcp:
     type: streamable-http
     url: http://mcp-prod:8001/mcp