diff --git a/content/changelog/config_v1.3.12.mdx b/content/changelog/config_v1.3.12.mdx new file mode 100644 index 000000000..1c4f9de8a --- /dev/null +++ b/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 conversation data + +- Added `mcpServers..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 diff --git a/content/changelog/v0.8.6.mdx b/content/changelog/v0.8.6.mdx new file mode 100644 index 000000000..24ea96965 --- /dev/null +++ b/content/changelog/v0.8.6.mdx @@ -0,0 +1,190 @@ +--- +date: 2026-05-30 +title: ๐Ÿš€ LibreChat v0.8.6 +description: The v0.8.6 release of LibreChat +version: '0.8.6' +--- + +## What's Changed + +## ๐Ÿž๏ธ Highlights + +- **Agent Skills & Subagents** + - Agent Skills package reusable instructions, references, scripts, assets, and permissions into portable capabilities that agents can invoke automatically or on request. + - Subagents let agents delegate specialized work to other agents while preserving upload, user, and MCP context with recursion and graph limits. +- **Code Execution & Artifacts** + - Text, source-code, DOCX, CSV, XLSX, and PPTX artifacts can render inline or in the side panel with richer previews. + - Artifact editing, Gemini PDF media blocks, model-spec icons, and persistent agent resource files received reliability fixes. +- **Observability & Operations** + - Added Prometheus metrics, backend OpenTelemetry tracing, SSE lifecycle tracing, HyperDX browser RUM, structured logging context, explicit readiness endpoints, file-log controls, and graceful HTTP shutdown. +- **MCP, Auth, and Admin Hardening** + - Improved MCP remote proxy support, OAuth audience handling, JWT expiry fallback, optional OpenID/MCP client-secret flows, multi-audience OpenID validation, trusted registration overrides, admin-panel SSO redirects, and streamable HTTP limits. +- **Provider and Model Updates** + - Added Claude Opus 4.8 support, Gemini 3.5 Flash support, Gemini tool combinations, Gemma 4 thinking-level support, model-aware Google/Gemini max output tokens, Bedrock AWS profile/API key support, and Bedrock guardrail handling. +- **Reliability and UI Polish** + - Hardened retention semantics, Redis/in-memory generation cleanup, MCP title rendering, sidebar/chat race handling, hover actions, shared links, generated file chips, and balance script config loading. + +For detailed changes in the release candidate, see: + +- [v0.8.6-rc1](/changelog/v0.8.6-rc1) + +--- + +## Changes Since v0.8.6-rc1 + +### โœจ Features + +- ๐Ÿšง feat: Support Guardrail Config Option `streamProcessingMode` by [@dlew](https://github.com/dlew) in [#12815](https://github.com/danny-avila/LibreChat/pull/12815) +- ๐Ÿ“ˆ feat: Add Prometheus Metrics Endpoint + AWS Credential Providers by [@danny-avila](https://github.com/danny-avila) in [#13111](https://github.com/danny-avila/LibreChat/pull/13111) +- ๐Ÿงพ feat: Add Structured Logging Context by [@danny-avila](https://github.com/danny-avila) in [#13110](https://github.com/danny-avila/LibreChat/pull/13110) +- ๐Ÿ›ก๏ธ feat: Bedrock Guardrail Config Environment Variable Resolution by [@entropic489](https://github.com/entropic489) in [#11717](https://github.com/danny-avila/LibreChat/pull/11717) +- ๐Ÿ“ก feat: Add Backend OpenTelemetry Tracing by [@danny-avila](https://github.com/danny-avila) in [#12909](https://github.com/danny-avila/LibreChat/pull/12909) +- ๐Ÿท๏ธ feat: Hide Model Spec Badge Rows by [@danny-avila](https://github.com/danny-avila) in [#13124](https://github.com/danny-avila/LibreChat/pull/13124) +- ๐Ÿ‘Ÿ feat: Enable Eager Execution of Tool Calls by [@danny-avila](https://github.com/danny-avila) in [#13192](https://github.com/danny-avila/LibreChat/pull/13192) +- ๐Ÿช feat: Add Session Cookie Secure Override by [@danny-avila](https://github.com/danny-avila) in [#13189](https://github.com/danny-avila/LibreChat/pull/13189) +- ๐Ÿช‚ feat: Graceful HTTP shutdown on SIGTERM/SIGINT by [@pjhampton](https://github.com/pjhampton) in [#13211](https://github.com/danny-avila/LibreChat/pull/13211) +- ๐Ÿฉบ feat: Add Explicit Readiness Endpoints by [@danny-avila](https://github.com/danny-avila) in [#13212](https://github.com/danny-avila/LibreChat/pull/13212) +- ๐Ÿ—‚๏ธ feat: Allow Disabling File Log Transports by [@danny-avila](https://github.com/danny-avila) in [#13215](https://github.com/danny-avila/LibreChat/pull/13215) +- โšก feat: Add Gemini 3.5 Flash Support by [@danny-avila](https://github.com/danny-avila) in [#13231](https://github.com/danny-avila/LibreChat/pull/13231) +- ๐Ÿ›ฃ๏ธ feat: Add MCP Remote Proxy Support by [@danny-avila](https://github.com/danny-avila) in [#13076](https://github.com/danny-avila/LibreChat/pull/13076) +- โš–๏ธ feat: Add Operational Prometheus Metrics by [@danny-avila](https://github.com/danny-avila) in [#13265](https://github.com/danny-avila/LibreChat/pull/13265) +- ๐Ÿ–ฒ๏ธ feat: Trace SSE Stream Lifecycle with OTel by [@upman](https://github.com/upman) in [#13266](https://github.com/danny-avila/LibreChat/pull/13266) +- ๐Ÿ“œ feat: Add Explicit new Skill Route from Agent Builder by [@sand116](https://github.com/sand116) in [#13119](https://github.com/danny-avila/LibreChat/pull/13119) +- ๐Ÿ†” feat: Built-in Build Metadata for Support Triage by [@danny-avila](https://github.com/danny-avila) in [#12756](https://github.com/danny-avila/LibreChat/pull/12756) +- ๐Ÿ›‚ feat: Add AWS Profile Support for Bedrock Credentials by [@iElsha](https://github.com/iElsha) in [#10504](https://github.com/danny-avila/LibreChat/pull/10504) +- ๐Ÿช™ feat: Add AWS Bedrock API key support by [@dustinhealy](https://github.com/dustinhealy) in [#8690](https://github.com/danny-avila/LibreChat/pull/8690) +- ๐Ÿ›ฐ๏ธ feat: Support Gemini Tool Combinations by [@danny-avila](https://github.com/danny-avila) in [#13273](https://github.com/danny-avila/LibreChat/pull/13273) +- ๐Ÿง  feat: Add Claude Opus 4.8 Support by [@danny-avila](https://github.com/danny-avila) in [#13380](https://github.com/danny-avila/LibreChat/pull/13380) +- โ™Š feat: Model-Aware Max Output Tokens for Google/Gemini by [@danny-avila](https://github.com/danny-avila) in [#13390](https://github.com/danny-avila/LibreChat/pull/13390) +- ๐Ÿ“ก feat: Add Configurable HyperDX Browser Real User Monitoring by [@upman](https://github.com/upman) in [#13287](https://github.com/danny-avila/LibreChat/pull/13287) +- ๐Ÿชช feat: Accept Multiple OpenID JWT Audiences by [@danny-avila](https://github.com/danny-avila) in [#13404](https://github.com/danny-avila/LibreChat/pull/13404) +- ๐Ÿชช feat: MCP OAuth - Support `audience` parameter for Auth0/Cognito-style providers by [@Freudator86](https://github.com/Freudator86) in [#13402](https://github.com/danny-avila/LibreChat/pull/13402) +- ๐Ÿ’  feat: Extend `thinkingLevel` Support to Gemma 4 Models by [@King-of-Infinite-Space](https://github.com/King-of-Infinite-Space) in [#13088](https://github.com/danny-avila/LibreChat/pull/13088) + +### ๐Ÿ› Fixes + +- ๐Ÿงฐ fix: Scope MCP Registry Initialization To Config Fingerprints by [@danny-avila](https://github.com/danny-avila) in [#13115](https://github.com/danny-avila/LibreChat/pull/13115) +- ๐Ÿงน fix: Reset Redis Reorder State After Last Unsubscribe by [@sand116](https://github.com/sand116) in [#13117](https://github.com/danny-avila/LibreChat/pull/13117) +- ๐Ÿท๏ธ fix: Harden Helm Chart Tag Parsing by [@danny-avila](https://github.com/danny-avila) in [#13123](https://github.com/danny-avila/LibreChat/pull/13123) +- ๐Ÿ›ก๏ธ fix: Sanitize Agent List Skill Scope by [@danny-avila](https://github.com/danny-avila) in [#13122](https://github.com/danny-avila/LibreChat/pull/13122) +- ๐Ÿ—๏ธ fix: Protect Model Spec Instructions by [@danny-avila](https://github.com/danny-avila) in [#13125](https://github.com/danny-avila/LibreChat/pull/13125) +- ๐Ÿชต fix: Restore Winston Format Factory Shape In Test Mocks by [@JorgeCosta87](https://github.com/JorgeCosta87) in [#13139](https://github.com/danny-avila/LibreChat/pull/13139) +- ๐Ÿ›ก๏ธ fix: Escape People Picker Search Regex by [@danny-avila](https://github.com/danny-avila) in [#13169](https://github.com/danny-avila/LibreChat/pull/13169) +- ๐Ÿค fix: Honor OPENID_REUSE_TOKENS in Admin OAuth Exchange by [@jangByeongHui](https://github.com/jangByeongHui) in [#13154](https://github.com/danny-avila/LibreChat/pull/13154) +- ๐Ÿชช fix: Resolve Group-Scoped Config Overrides by [@danny-avila](https://github.com/danny-avila) in [#13176](https://github.com/danny-avila/LibreChat/pull/13176) +- ๐Ÿงฝ fix: Strip Admin OAuth Redirect Params by [@danny-avila](https://github.com/danny-avila) in [#13181](https://github.com/danny-avila/LibreChat/pull/13181) +- ๐Ÿ” fix: Prefer LibreChat Web Search over Anthropic's when Both Selected by [@danny-avila](https://github.com/danny-avila) in [#13166](https://github.com/danny-avila/LibreChat/pull/13166) +- ๐Ÿ—‚๏ธ fix: Scope Handoff Agent Context Docs by [@danny-avila](https://github.com/danny-avila) in [#13167](https://github.com/danny-avila/LibreChat/pull/13167) +- ๐Ÿชช fix: Scope Message Conversation Access by [@danny-avila](https://github.com/danny-avila) in [#13183](https://github.com/danny-avila/LibreChat/pull/13183) +- ๐Ÿงญ fix: Reduce MCP Registry ACL Lookups by [@danny-avila](https://github.com/danny-avila) in [#13195](https://github.com/danny-avila/LibreChat/pull/13195) +- โ›ด๏ธ fix: Stop Double-Wrapping configYamlContent in Helm ConfigMap by [@vdittgen](https://github.com/vdittgen) in [#13198](https://github.com/danny-avila/LibreChat/pull/13198) +- ๐Ÿ“ก fix: Handle Pre-Session 406 for Optional SSE MCP Stream by [@pnancarrow](https://github.com/pnancarrow) in [#13202](https://github.com/danny-avila/LibreChat/pull/13202) +- ๐Ÿงฏ fix: Harden Data Retention Semantics by [@danny-avila](https://github.com/danny-avila) in [#13049](https://github.com/danny-avila/LibreChat/pull/13049) +- ๐Ÿชช fix: Add Admin Panel SSO URL Config by [@danny-avila](https://github.com/danny-avila) in [#13220](https://github.com/danny-avila/LibreChat/pull/13220) +- ๐Ÿฆฃ fix: Response Size Limits for Streamable HTTP MCP Responses by [@danny-avila](https://github.com/danny-avila) in [#13219](https://github.com/danny-avila/LibreChat/pull/13219) +- ๐Ÿƒ fix: Improve OpenID Lookup Planning by [@danny-avila](https://github.com/danny-avila) in [#13229](https://github.com/danny-avila/LibreChat/pull/13229) +- ๐Ÿงฉ fix: Support DocumentDB Prompt Group Lookup by [@danny-avila](https://github.com/danny-avila) in [#13232](https://github.com/danny-avila/LibreChat/pull/13232) +- ๐Ÿ“ก fix: Respect Custom Endpoint Stream Usage Opt-In by [@danny-avila](https://github.com/danny-avila) in [#13237](https://github.com/danny-avila/LibreChat/pull/13237) +- ๐Ÿž fix: don't show 'deleting file' toast on attached files by [@dlew](https://github.com/dlew) in [#13239](https://github.com/danny-avila/LibreChat/pull/13239) +- ๐Ÿงต fix: Preserve Streaming Messages During Stale Refetch by [@danny-avila](https://github.com/danny-avila) in [#13247](https://github.com/danny-avila/LibreChat/pull/13247) +- ๐Ÿ›ก๏ธ fix: Harden MCP OAuth Request Handling by [@danny-avila](https://github.com/danny-avila) in [#13264](https://github.com/danny-avila/LibreChat/pull/13264) +- ๐Ÿชช fix: Consolidate MCP OAuth Policy by [@danny-avila](https://github.com/danny-avila) in [#13254](https://github.com/danny-avila/LibreChat/pull/13254) +- ๐Ÿชช fix: Prevent MCP Server Name Collisions by [@danny-avila](https://github.com/danny-avila) in [#13256](https://github.com/danny-avila/LibreChat/pull/13256) +- โŒ› fix: Use JWT exp claim for MCP when OAuth token omits expires_in by [@devanchohan](https://github.com/devanchohan) in [#13248](https://github.com/danny-avila/LibreChat/pull/13248) +- ๐Ÿชช fix: Support OpenID PKCE Without Client Secret by [@eleite93](https://github.com/eleite93) in [#12364](https://github.com/danny-avila/LibreChat/pull/12364) +- ๐Ÿชช fix: Allow Optional client_secret for MCP OAuth by [@aupuzikov](https://github.com/aupuzikov) in [#12460](https://github.com/danny-avila/LibreChat/pull/12460) +- ๐Ÿ›‚ fix: Detect OAuth Errors From HTTP 400 Responses by [@janluedemann-esome](https://github.com/janluedemann-esome) in [#11961](https://github.com/danny-avila/LibreChat/pull/11961) +- ๐Ÿชฌ fix: Skip MCP Tools When Required Custom User Vars Are Unset by [@verifizieren](https://github.com/verifizieren) in [#13152](https://github.com/danny-avila/LibreChat/pull/13152) +- ๐Ÿชจ fix: Normalize Empty MCP Tool Descriptions to `undefined` for Bedrock Compat. by [@serhiizghama](https://github.com/serhiizghama) in [#13217](https://github.com/danny-avila/LibreChat/pull/13217) +- ๐Ÿ“ก fix: Tighten Streaming Message Cache Preservation by [@danny-avila](https://github.com/danny-avila) in [#13271](https://github.com/danny-avila/LibreChat/pull/13271) +- ๐Ÿงท fix: Harden MCP Proxy SSRF Checks by [@danny-avila](https://github.com/danny-avila) in [#13274](https://github.com/danny-avila/LibreChat/pull/13274) +- ๐Ÿงฑ fix: Validate Bedrock User Credentials by [@danny-avila](https://github.com/danny-avila) in [#13277](https://github.com/danny-avila/LibreChat/pull/13277) +- ๐Ÿงท fix: Pin MCP OAuth Client Secrets by [@danny-avila](https://github.com/danny-avila) in [#13276](https://github.com/danny-avila/LibreChat/pull/13276) +- ๐Ÿฃ fix: Reject System Tenant In Auth Context by [@danny-avila](https://github.com/danny-avila) in [#13278](https://github.com/danny-avila/LibreChat/pull/13278) +- ๐Ÿงพ fix: Validate Bedrock User Credentials by [@danny-avila](https://github.com/danny-avila) in [#13279](https://github.com/danny-avila/LibreChat/pull/13279) +- ๐ŸชŸ fix: Apply Admin-Panel Config Overrides To YAML-Defined MCP Servers by [@dustinhealy](https://github.com/dustinhealy) in [#13173](https://github.com/danny-avila/LibreChat/pull/13173) +- ๐Ÿชก fix: Prevent Hover Actions Flash While Streaming by [@danny-avila](https://github.com/danny-avila) in [#13285](https://github.com/danny-avila/LibreChat/pull/13285) +- ๐Ÿงฉ fix: Add REDIS_CLUSTER_SAFE_DELETE Flag for ElastiCache Serverless CROSSSLOT Errors by [@serhiizghama](https://github.com/serhiizghama) in [#13275](https://github.com/danny-avila/LibreChat/pull/13275) +- ๐Ÿงต fix: Prevent Message Loading Race During Streaming by [@danny-avila](https://github.com/danny-avila) in [#13295](https://github.com/danny-avila/LibreChat/pull/13295) +- โญ๏ธ fix: Avoid False Resume Submission Stale Detection by [@danny-avila](https://github.com/danny-avila) in [#13297](https://github.com/danny-avila/LibreChat/pull/13297) +- ๐Ÿงฏ fix: Suppress Google Service Key Noise by [@danny-avila](https://github.com/danny-avila) in [#13322](https://github.com/danny-avila/LibreChat/pull/13322) +- โœ‚๏ธ fix: Truncate Long MCP Server Titles In Builder Panel by [@dustinhealy](https://github.com/dustinhealy) in [#13321](https://github.com/danny-avila/LibreChat/pull/13321) +- ๐Ÿ“Ž fix: Preserve Gemini PDF Media Blocks by [@danny-avila](https://github.com/danny-avila) in [#13357](https://github.com/danny-avila/LibreChat/pull/13357) +- ๐Ÿ›ก๏ธ fix: Harden Model Spec Icon Rendering by [@danny-avila](https://github.com/danny-avila) in [#13356](https://github.com/danny-avila/LibreChat/pull/13356) +- ๐Ÿชก fix: Artifact Edit Saves by [@danny-avila](https://github.com/danny-avila) in [#13358](https://github.com/danny-avila/LibreChat/pull/13358) +- ๐Ÿ›ก๏ธ fix: Cap Default Limit on Agent List Queries by [@danny-avila](https://github.com/danny-avila) in [#13382](https://github.com/danny-avila/LibreChat/pull/13382) +- ๐Ÿชจ fix: Preserve Bedrock Guardrail Config by [@danny-avila](https://github.com/danny-avila) in [#13381](https://github.com/danny-avila/LibreChat/pull/13381) +- โš“ fix: Skip Retention for Persistent Agent Resource Files by [@maxesse](https://github.com/maxesse) in [#13394](https://github.com/danny-avila/LibreChat/pull/13394) +- ๐ŸงŸ fix: Reap Hung In-Memory Generations for Redis Failsafe Parity by [@danny-avila](https://github.com/danny-avila) in [#13396](https://github.com/danny-avila/LibreChat/pull/13396) +- ๐Ÿชƒ fix: Retry MCP OAuth Token Refresh Without Scope on Server Rejection by [@danny-avila](https://github.com/danny-avila) in [#13412](https://github.com/danny-avila/LibreChat/pull/13412) +- ๐Ÿ–ผ๏ธ fix: Preserve Model Spec Icon URLs by [@danny-avila](https://github.com/danny-avila) in [#13370](https://github.com/danny-avila/LibreChat/pull/13370) +- ๐Ÿ”‘ fix: support 'userinfo' in OPENID_REQUIRED_ROLE_TOKEN_KIND by [@pboers1988](https://github.com/pboers1988) in [#13182](https://github.com/danny-avila/LibreChat/pull/13182) +- ๐Ÿชช fix: Preserve Trusted Registration Provider Overrides by [@danny-avila](https://github.com/danny-avila) in [#13307](https://github.com/danny-avila/LibreChat/pull/13307) +- ๐Ÿ’ฐ fix: Load app config in `set-balance` script to respect balance settings by [@ucodia](https://github.com/ucodia) in [#12669](https://github.com/danny-avila/LibreChat/pull/12669) +- ๐Ÿ“ฌ fix: Honor Admin-Panel `allowedDomains` Override at Registration by [@nangelovv](https://github.com/nangelovv) in [#13204](https://github.com/danny-avila/LibreChat/pull/13204) + +### ๐Ÿ”ง Refactoring + +- ๐Ÿ“ธ refactor: Refresh Shared Links With Latest Snapshot by [@danny-avila](https://github.com/danny-avila) in [#13095](https://github.com/danny-avila/LibreChat/pull/13095) +- ๐Ÿ—‚๏ธ refactor: Collapse Generated File Chips by [@danny-avila](https://github.com/danny-avila) in [#13116](https://github.com/danny-avila/LibreChat/pull/13116) +- ๐Ÿ›Ÿ refactor: Gracefully Skip Unavailable Web Search Rerankers by [@danny-avila](https://github.com/danny-avila) in [#13191](https://github.com/danny-avila/LibreChat/pull/13191) +- ๐Ÿ—‚๏ธ refactor: Clarify Code Sandbox File Guidance by [@danny-avila](https://github.com/danny-avila) in [#13236](https://github.com/danny-avila/LibreChat/pull/13236) +- ๐Ÿงฌ refactor: Derive Latest Message From Cache by [@danny-avila](https://github.com/danny-avila) in [#13294](https://github.com/danny-avila/LibreChat/pull/13294) +- โฑ๏ธ refactor: Optimistically Show New Chats In Sidebar by [@danny-avila](https://github.com/danny-avila) in [#13298](https://github.com/danny-avila/LibreChat/pull/13298) +- ๐Ÿง  refactor: Replay DeepSeek `reasoning_content` via OpenRouter by [@danny-avila](https://github.com/danny-avila) in [#13368](https://github.com/danny-avila/LibreChat/pull/13368) +- ๐Ÿ“ค refactor: Align Mention Options With Model Selector by [@danny-avila](https://github.com/danny-avila) in [#13397](https://github.com/danny-avila/LibreChat/pull/13397) + +### ๐Ÿงช Tests + +- ๐Ÿ›Ÿ test: Restore Playwright Smoke E2E by [@danny-avila](https://github.com/danny-avila) in [#13020](https://github.com/danny-avila/LibreChat/pull/13020) + +### ๐Ÿ“ฆ Dependencies, Chores & CI + +- ๐Ÿงน chore: Type Agent MCP lean projection in ServerConfigsDB by [@gaurav0107](https://github.com/gaurav0107) in [#13171](https://github.com/danny-avila/LibreChat/pull/13171) +- ๐Ÿ›ก๏ธ chore: Harden CI Supply Chain Workflows by [@danny-avila](https://github.com/danny-avila) in [#13090](https://github.com/danny-avila/LibreChat/pull/13090) +- ๐Ÿ•ต๐Ÿป ci: Improve Flaky Subagents Test by [@dustinhealy](https://github.com/dustinhealy) in [#13185](https://github.com/danny-avila/LibreChat/pull/13185) +- ๐Ÿ“ฆ chore: npm audit fix, bump otel & `@librechat/agents` by [@danny-avila](https://github.com/danny-avila) in [#13186](https://github.com/danny-avila/LibreChat/pull/13186) +- ๐Ÿ“ฆ chore: Bump `@librechat/agents` to v3.1.88 by [@danny-avila](https://github.com/danny-avila) in [#13187](https://github.com/danny-avila/LibreChat/pull/13187) +- ๐Ÿงช ci: Stabilize Virtualized Agent Grid Tests by [@danny-avila](https://github.com/danny-avila) in [#13214](https://github.com/danny-avila/LibreChat/pull/13214) +- ๐Ÿงต chore: Raise MCP SSE Line Default by [@danny-avila](https://github.com/danny-avila) in [#13224](https://github.com/danny-avila/LibreChat/pull/13224) +- ๐Ÿ“ฆ chore: bump `@librechat/agents` to v3.1.90 and npm audit fix by [@danny-avila](https://github.com/danny-avila) in [#13242](https://github.com/danny-avila/LibreChat/pull/13242) +- ๐Ÿšฆ ci: Enforce ESLint on Package Changes by [@danny-avila](https://github.com/danny-avila) in [#13280](https://github.com/danny-avila/LibreChat/pull/13280) +- ๐ŸŽจ chore: prettier --write all workspaces by [@danny-avila](https://github.com/danny-avila) in [#13281](https://github.com/danny-avila/LibreChat/pull/13281) +- ๐ŸŽจ ci: Check Prettier Formatting Drift on Package Changes by [@danny-avila](https://github.com/danny-avila) in [#13282](https://github.com/danny-avila/LibreChat/pull/13282) +- ๐Ÿชค chore: Prevent CI Path Argument Injection by [@danny-avila](https://github.com/danny-avila) in [#13284](https://github.com/danny-avila/LibreChat/pull/13284) +- ๐ŸŒ chore: Guard Locize Reviewer Request by [@danny-avila](https://github.com/danny-avila) in [#13286](https://github.com/danny-avila/LibreChat/pull/13286) +- ๐Ÿ“ฆ chore: bump `@librechat/agents`, `qs`, `langfuse` by [@danny-avila](https://github.com/danny-avila) in [#13299](https://github.com/danny-avila/LibreChat/pull/13299) +- ๐Ÿข ci: Raise test-packages-api timeout to 20 min by [@danny-avila](https://github.com/danny-avila) in [#13326](https://github.com/danny-avila/LibreChat/pull/13326) +- ๐Ÿงฎ chore: Update Gemma Context Token Defaults by [@danny-avila](https://github.com/danny-avila) in [#13410](https://github.com/danny-avila/LibreChat/pull/13410) +- โœ‚๏ธ chore: Strip Session JWT Forwarding from Browser RUM by [@danny-avila](https://github.com/danny-avila) in [#13414](https://github.com/danny-avila/LibreChat/pull/13414) +- ๐Ÿ“ฆ chore: Bump `@hyperdx/browser` to v0.24.0 by [@danny-avila](https://github.com/danny-avila) in [#13416](https://github.com/danny-avila/LibreChat/pull/13416) + +### ๐ŸŒ Internationalization + +- ๐ŸŒ i18n: Update translation.json with latest translations by [@github-actions[bot]](https://github.com/apps/github-actions) in [#13107](https://github.com/danny-avila/LibreChat/pull/13107) +- ๐ŸŒ i18n: Update translation.json with latest translations by [@github-actions[bot]](https://github.com/apps/github-actions) in [#13128](https://github.com/danny-avila/LibreChat/pull/13128) +- ๐ŸŒ i18n: Update translation.json with latest translations by [@danny-avila](https://github.com/danny-avila) in [#13230](https://github.com/danny-avila/LibreChat/pull/13230) +- ๐ŸŒ i18n: Update translation.json with latest translations by [@danny-avila](https://github.com/danny-avila) in [#13283](https://github.com/danny-avila/LibreChat/pull/13283) +- ๐ŸŒ i18n: Update translation.json with latest translations by [@danny-avila](https://github.com/danny-avila) in [#13291](https://github.com/danny-avila/LibreChat/pull/13291) +- ๐ŸŒ i18n: Update translation.json with latest translations by [@danny-avila](https://github.com/danny-avila) in [#13325](https://github.com/danny-avila/LibreChat/pull/13325) + +## New Contributors + +- [@entropic489](https://github.com/entropic489) made their first contribution in [#11717](https://github.com/danny-avila/LibreChat/pull/11717) +- [@sand116](https://github.com/sand116) made their first contribution in [#13117](https://github.com/danny-avila/LibreChat/pull/13117) +- [@JorgeCosta87](https://github.com/JorgeCosta87) made their first contribution in [#13139](https://github.com/danny-avila/LibreChat/pull/13139) +- [@jangByeongHui](https://github.com/jangByeongHui) made their first contribution in [#13154](https://github.com/danny-avila/LibreChat/pull/13154) +- [@pjhampton](https://github.com/pjhampton) made their first contribution in [#13211](https://github.com/danny-avila/LibreChat/pull/13211) +- [@devanchohan](https://github.com/devanchohan) made their first contribution in [#13248](https://github.com/danny-avila/LibreChat/pull/13248) +- [@eleite93](https://github.com/eleite93) made their first contribution in [#12364](https://github.com/danny-avila/LibreChat/pull/12364) +- [@aupuzikov](https://github.com/aupuzikov) made their first contribution in [#12460](https://github.com/danny-avila/LibreChat/pull/12460) +- [@janluedemann-esome](https://github.com/janluedemann-esome) made their first contribution in [#11961](https://github.com/danny-avila/LibreChat/pull/11961) +- [@verifizieren](https://github.com/verifizieren) made their first contribution in [#13152](https://github.com/danny-avila/LibreChat/pull/13152) +- [@serhiizghama](https://github.com/serhiizghama) made their first contribution in [#13217](https://github.com/danny-avila/LibreChat/pull/13217) +- [@iElsha](https://github.com/iElsha) made their first contribution in [#10504](https://github.com/danny-avila/LibreChat/pull/10504) +- [@Freudator86](https://github.com/Freudator86) made their first contribution in [#13402](https://github.com/danny-avila/LibreChat/pull/13402) +- [@pboers1988](https://github.com/pboers1988) made their first contribution in [#13182](https://github.com/danny-avila/LibreChat/pull/13182) +- [@King-of-Infinite-Space](https://github.com/King-of-Infinite-Space) made their first contribution in [#13088](https://github.com/danny-avila/LibreChat/pull/13088) +- [@nangelovv](https://github.com/nangelovv) made their first contribution in [#13204](https://github.com/danny-avila/LibreChat/pull/13204) + +**Full Changelog**: https://github.com/danny-avila/LibreChat/compare/v0.8.6-rc1...v0.8.6 diff --git a/content/docs/configuration/dotenv.mdx b/content/docs/configuration/dotenv.mdx index 8e0d3fef9..c9bcdc0b4 100644 --- a/content/docs/configuration/dotenv.mdx +++ b/content/docs/configuration/dotenv.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. + + + ### 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'], ]} /> @@ -1754,6 +1830,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', + ], ]} /> @@ -1995,7 +2077,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', ], [ @@ -2694,6 +2776,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', + ], ]} /> @@ -2735,6 +2829,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', @@ -2796,6 +2896,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. diff --git a/content/docs/configuration/librechat_yaml/example.mdx b/content/docs/configuration/librechat_yaml/example.mdx index 815a5354b..bc16202b8 100644 --- a/content/docs/configuration/librechat_yaml/example.mdx +++ b/content/docs/configuration/librechat_yaml/example.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 diff --git a/content/docs/configuration/librechat_yaml/object_structure/interface.mdx b/content/docs/configuration/librechat_yaml/object_structure/interface.mdx index f3f851650..db517c3fa 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/interface.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/interface.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:** + + +**Default:** `temporary` + + +`retentionMode: "all"` applies retention deadlines beyond temporary chats. Confirm your retention policy before enabling it. + + +**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. diff --git a/content/docs/configuration/librechat_yaml/object_structure/mcp_servers.mdx b/content/docs/configuration/librechat_yaml/object_structure/mcp_servers.mdx index 3158ec151..f713bcd1f 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/mcp_servers.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/mcp_servers.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 ``` @@ -350,7 +367,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`) @@ -426,7 +443,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 diff --git a/content/docs/configuration/librechat_yaml/object_structure/model_specs.mdx b/content/docs/configuration/librechat_yaml/object_structure/model_specs.mdx index 517a6f566..756424d39 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/model_specs.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/model_specs.mdx @@ -1,5 +1,5 @@ --- -title: "Model Specs Object Structure" +title: 'Model Specs Object Structure' icon: Braces --- @@ -9,19 +9,19 @@ The `modelSpecs` object helps you provide a simpler UI experience for AI models There are 3 main fields under `modelSpecs`: - - `enforce` (optional; default: false) - - `prioritize` (optional; default: true) - - `list` (required) - - `addedEndpoints` (optional) +- `enforce` (optional; default: false) +- `prioritize` (optional; default: true) +- `list` (required) +- `addedEndpoints` (optional) **Notes:** -- If `enforce` is set to true, model specifications can potentially conflict with other interface settings such as `modelSelect`, `presets`, and `parameters`. +- If `enforce` is set to true, model specifications can potentially conflict with other interface settings such as `modelSelect`, `presets`, and `parameters`. - The `list` array contains detailed configurations for each model, including presets that dictate specific behaviors, appearances, and capabilities. - If [interface](interface.mdx) fields are not specified in the configuration, having a list of model specs will disable the following interface elements: - - `modelSelect` - - `parameters` - - `presets` + - `modelSelect` + - `parameters` + - `presets` - If you would like to enable these interface elements along with model specs, you can set them to `true` in the `interface` object. ## Example @@ -31,18 +31,19 @@ modelSpecs: enforce: true prioritize: true list: - - name: "meeting-notes-gpt4" - label: "Meeting Notes Assistant (GPT4)" + - name: 'meeting-notes-gpt4' + label: 'Meeting Notes Assistant (GPT4)' default: true - description: "Generate meeting notes by simply pasting in the transcript from a Teams recording." - iconURL: "https://example.com/icon.png" + description: 'Generate meeting notes by simply pasting in the transcript from a Teams recording.' + iconURL: 'https://example.com/icon.png' + hideBadgeRow: true preset: - endpoint: "azureOpenAI" - model: "gpt-4-turbo-1106-preview" + endpoint: 'azureOpenAI' + model: 'gpt-4-turbo-1106-preview' maxContextTokens: 128000 # Maximum context tokens max_tokens: 4096 # Maximum output tokens temperature: 0.2 - modelLabel: "Meeting Summarizer" + modelLabel: 'Meeting Summarizer' greeting: | This assistant creates meeting notes based on transcripts of Teams recordings. To start, simply paste the transcript into the chat box. @@ -70,13 +71,19 @@ modelSpecs: **Default:** `false` **Example:** + ```yaml filename="modelSpecs / enforce" modelSpecs: enforce: true @@ -88,13 +95,19 @@ modelSpecs: **Default:** `true` **Example:** + ```yaml filename="modelSpecs / prioritize" modelSpecs: prioritize: false @@ -106,16 +119,23 @@ modelSpecs: **Default:** `[]` (empty list) **Note:** Must be one of the following: + - `openAI, azureOpenAI, google, anthropic, assistants, azureAssistants, bedrock` **Example:** + ```yaml filename="modelSpecs / addedEndpoints" modelSpecs: # ... other modelSpecs fields @@ -132,7 +152,12 @@ modelSpecs: @@ -159,7 +184,12 @@ Unique identifier for the model. @@ -172,7 +202,12 @@ A user-friendly name or label for the model, shown in the header dropdown. @@ -185,7 +220,12 @@ Specifies if this model spec is the default selection, to be auto-selected on ev @@ -198,7 +238,12 @@ URL or a predefined endpoint name for the model's icon. @@ -211,8 +256,18 @@ A brief description of the model and its intended use or role, shown in the head @@ -225,6 +280,40 @@ Optional group name for organizing model specs in the UI selector. The `group` f This feature is particularly useful when you want to add descriptions to models without losing the organizational structure of the selector menu. +--- + +### hideBadgeRow + + + +**Default:** `false` + +Use this when a curated model spec should not show the row of tool/capability badges beneath the composer. + +**Example:** + +```yaml filename="modelSpecs / hideBadgeRow" +modelSpecs: + list: + - name: 'general-assistant' + label: 'General Assistant' + hideBadgeRow: true + preset: + endpoint: 'openAI' + model: 'gpt-4o-mini' +``` + +--- + **Example:** ```yaml filename="modelSpecs with group field examples" @@ -232,52 +321,52 @@ modelSpecs: list: # Example 1: Nested under an endpoint # When group matches an endpoint name, the spec appears under that endpoint - - name: "gpt-4o-optimized" - label: "GPT-4 Optimized" - description: "Most capable GPT-4 model with multimodal support" - group: "openAI" # Appears nested under the OpenAI endpoint + - name: 'gpt-4o-optimized' + label: 'GPT-4 Optimized' + description: 'Most capable GPT-4 model with multimodal support' + group: 'openAI' # Appears nested under the OpenAI endpoint preset: - endpoint: "openAI" - model: "gpt-4o" + endpoint: 'openAI' + model: 'gpt-4o' # Example 2: Custom group section with icon # When group is a custom name, it creates a separate collapsible section - - name: "coding-assistant" - label: "Coding Assistant" - description: "Specialized for coding tasks" - group: "My Assistants" - groupIcon: "https://example.com/icons/assistants.png" # Custom icon for the group + - name: 'coding-assistant' + label: 'Coding Assistant' + description: 'Specialized for coding tasks' + group: 'My Assistants' + groupIcon: 'https://example.com/icons/assistants.png' # Custom icon for the group preset: - endpoint: "openAI" - model: "gpt-4o" + endpoint: 'openAI' + model: 'gpt-4o' # Multiple specs with the same group name are grouped together - - name: "writing-assistant" - label: "Writing Assistant" - description: "Specialized for creative writing" - group: "My Assistants" # Grouped with coding-assistant, uses its icon + - name: 'writing-assistant' + label: 'Writing Assistant' + description: 'Specialized for creative writing' + group: 'My Assistants' # Grouped with coding-assistant, uses its icon preset: - endpoint: "anthropic" - model: "claude-sonnet-4" + endpoint: 'anthropic' + model: 'claude-sonnet-4' # Example 3: Custom group using built-in icon - - name: "fast-model" - label: "Fast Model" - group: "Fast Models" - groupIcon: "groq" # Uses built-in Groq icon + - name: 'fast-model' + label: 'Fast Model' + group: 'Fast Models' + groupIcon: 'groq' # Uses built-in Groq icon preset: - endpoint: "groq" - model: "llama3-8b-8192" + endpoint: 'groq' + model: 'llama3-8b-8192' # Example 4: Standalone (no group) # When group is omitted, the spec appears at the top level - - name: "general-assistant" - label: "General Assistant" - description: "General purpose assistant" + - name: 'general-assistant' + label: 'General Assistant' + description: 'General purpose assistant' # No group field - appears as standalone item at top level preset: - endpoint: "openAI" - model: "gpt-4o-mini" + endpoint: 'openAI' + model: 'gpt-4o-mini' ``` --- @@ -286,7 +375,12 @@ modelSpecs: @@ -299,7 +393,12 @@ Controls whether the model's icon appears in the header dropdown menu. Defaults @@ -312,7 +411,12 @@ Controls whether the model's icon appears in the header dropdown button, left of @@ -325,7 +429,12 @@ Authentication type required for the model spec. Determines whether authenticati @@ -333,15 +442,16 @@ Authentication type required for the model spec. Determines whether authenticati Enables web search capability for this model spec. When set to `true`, the model can perform web searches to retrieve current information. **Example:** + ```yaml filename="modelSpecs / webSearch" modelSpecs: list: - - name: "research-assistant" - label: "Research Assistant" + - name: 'research-assistant' + label: 'Research Assistant' webSearch: true preset: - endpoint: "openAI" - model: "gpt-4o" + endpoint: 'openAI' + model: 'gpt-4o' ``` --- @@ -350,7 +460,12 @@ modelSpecs: @@ -358,15 +473,16 @@ modelSpecs: Enables file search capability for this model spec. When set to `true`, the model can search through and reference uploaded files. **Example:** + ```yaml filename="modelSpecs / fileSearch" modelSpecs: list: - - name: "document-analyst" - label: "Document Analyst" + - name: 'document-analyst' + label: 'Document Analyst' fileSearch: true preset: - endpoint: "openAI" - model: "gpt-4o" + endpoint: 'openAI' + model: 'gpt-4o' ``` --- @@ -375,7 +491,12 @@ modelSpecs: @@ -383,15 +504,16 @@ modelSpecs: Enables code execution capability for this model spec. When set to `true`, the model can execute code in a sandboxed environment. **Example:** + ```yaml filename="modelSpecs / executeCode" modelSpecs: list: - - name: "code-assistant" - label: "Code Assistant" + - name: 'code-assistant' + label: 'Code Assistant' executeCode: true preset: - endpoint: "openAI" - model: "gpt-4o" + endpoint: 'openAI' + model: 'gpt-4o' ``` --- @@ -400,7 +522,12 @@ modelSpecs: @@ -408,18 +535,19 @@ modelSpecs: List of Model Context Protocol (MCP) server names to enable for this model spec. MCP servers extend the model's capabilities with custom tools and resources. **Example:** + ```yaml filename="modelSpecs / mcpServers" modelSpecs: list: - - name: "enhanced-assistant" - label: "Enhanced Assistant" + - name: 'enhanced-assistant' + label: 'Enhanced Assistant' mcpServers: - - "filesystem" - - "sequential-thinking" - - "fetch" + - 'filesystem' + - 'sequential-thinking' + - 'fetch' preset: - endpoint: "openAI" - model: "gpt-4o" + endpoint: 'openAI' + model: 'gpt-4o' ``` --- @@ -428,7 +556,12 @@ modelSpecs: @@ -436,15 +569,16 @@ modelSpecs: Enables the Artifacts capability for this model spec, allowing the model to generate and display interactive artifacts such as React components, HTML, and Mermaid diagrams. When set to `true`, the default artifact mode is used. You can also specify a mode string directly. **Example:** + ```yaml filename="modelSpecs / artifacts" modelSpecs: list: - - name: "artifact-assistant" - label: "Artifact Assistant" + - name: 'artifact-assistant' + label: 'Artifact Assistant' artifacts: true preset: - endpoint: "openAI" - model: "gpt-4o" + endpoint: 'openAI' + model: 'gpt-4o' ``` --- @@ -453,7 +587,12 @@ modelSpecs: @@ -473,6 +612,7 @@ The `preset` field for a `modelSpecs.list` item is made up of a comprehensive co **Required** **Accepted Values:** + - `openAI` - `azureOpenAI` - `google` @@ -486,14 +626,20 @@ The `preset` field for a `modelSpecs.list` item is made up of a comprehensive co **Example:** + ```yaml filename="modelSpecs / list / {spec_item} / preset / endpoint" preset: - endpoint: "openAI" + endpoint: 'openAI' ``` --- @@ -502,16 +648,22 @@ preset: **Default:** `None` **Example:** + ```yaml filename="modelSpecs / list / {spec_item} / preset / modelLabel" preset: - modelLabel: "Customer Support Bot" + modelLabel: 'Customer Support Bot' ``` --- @@ -520,16 +672,22 @@ preset: **Default:** `None` **Example:** + ```yaml filename="modelSpecs / list / {spec_item} / preset / greeting" preset: - greeting: "This assistant creates meeting notes based on transcripts of Teams recordings. To start, simply paste the transcript into the chat box." + greeting: 'This assistant creates meeting notes based on transcripts of Teams recordings. To start, simply paste the transcript into the chat box.' ``` --- @@ -538,19 +696,26 @@ preset: **Default:** `None` **Example 1:** + ```yaml filename="modelSpecs / list / {spec_item} / preset / promptPrefix" preset: - promptPrefix: "As a financial advisor, ..." + promptPrefix: 'As a financial advisor, ...' ``` **Example 2:** + ```yaml filename="modelSpecs / list / {spec_item} / preset / promptPrefix" preset: promptPrefix: | @@ -575,13 +740,19 @@ preset: **Default:** `true` **Example:** + ```yaml filename="modelSpecs / list / {spec_item} / preset / resendFiles" preset: resendFiles: true @@ -592,22 +763,29 @@ preset: #### imageDetail **Accepted Values:** + - low - auto - high **Default:** `"auto"` **Example:** + ```yaml filename="modelSpecs / list / {spec_item} / preset / imageDetail" preset: - imageDetail: "high" + imageDetail: 'high' ``` --- @@ -616,11 +794,17 @@ preset: **Example:** + ```yaml filename="modelSpecs / list / {spec_item} / preset / maxContextTokens" preset: maxContextTokens: 4096 @@ -638,22 +822,20 @@ You should exclude any model options and defer to the agent's configuration as d As of v0.8.0, LibreChat uses an ACL (Access Control List) based permissions system for agents. When model specs are configured to use agents, any agents that the user doesn't have access to will be automatically filtered out, even if they are configured in the model spec. This ensures users only see and can use agents they have proper permissions for. For more information about the ACL permissions system, see the [Agents documentation](/docs/features/agents#migration-required-v080-rc3). + --- #### agent_id - + **Example:** + ```yaml filename="modelSpecs / list / {spec_item} / preset / agent_id" preset: - agent_id: "agent_someUniqueId" + agent_id: 'agent_someUniqueId' ``` --- @@ -668,16 +850,13 @@ Similar to [Agents](#agent-options), you should exclude any model options and de #### assistant_id - + **Example:** + ```yaml filename="modelSpecs / list / {spec_item} / preset / assistant_id" preset: - assistant_id: "asst_someUniqueId" + assistant_id: 'asst_someUniqueId' ``` --- @@ -696,15 +875,14 @@ More information: - https://platform.openai.com/docs/api-reference/runs/createRun#runs-createrun-additional_instructions **Example:** + ```yaml filename="modelSpecs / list / {spec_item} / preset / instructions" preset: - instructions: "Please handle customer queries regarding order status." + instructions: 'Please handle customer queries regarding order status.' ``` --- @@ -715,11 +893,17 @@ Adds the current date and time to `additional_instructions` for each run. Does n **Example:** + ```yaml filename="modelSpecs / list / {spec_item} / preset / append_current_datetime" preset: append_current_datetime: true @@ -733,7 +917,7 @@ preset: > **OpenAI / AzureOpenAI / Custom** typically support `temperature`, `presence_penalty`, `frequency_penalty`, `stop`, `top_p`, `max_tokens`. > **Google / Anthropic** typically support `topP`, `topK`, `maxOutputTokens`. > **Anthropic / Bedrock (Anthropic and Nova models)** support `promptCache`. -> **Bedrock** supports `region`, `maxTokens`, and a few others. +> **Bedrock** supports `region`, `maxTokens`, and a few others. #### model @@ -741,31 +925,43 @@ preset: **Default:** `None` **Example:** + ```yaml preset: - model: "gpt-4-turbo" + model: 'gpt-4-turbo' ``` --- #### temperature -> **Supported by:** `openAI`, `azureOpenAI`, `google` (as `temperature`), `anthropic` (as `temperature`), and custom (OpenAI-like) +> **Supported by:** `openAI`, `azureOpenAI`, `google` (as `temperature`), `anthropic` (as `temperature`), and custom (OpenAI-like) **Example:** + ```yaml preset: temperature: 0.7 @@ -776,15 +972,21 @@ preset: #### presence_penalty > **Supported by:** `openAI`, `azureOpenAI`, custom (OpenAI-like) -> *Not typically used by Google/Anthropic/Bedrock* +> _Not typically used by Google/Anthropic/Bedrock_ **Example:** + ```yaml preset: presence_penalty: 0.3 @@ -795,15 +997,21 @@ preset: #### frequency_penalty > **Supported by:** `openAI`, `azureOpenAI`, custom (OpenAI-like) -> *Not typically used by Google/Anthropic/Bedrock* +> _Not typically used by Google/Anthropic/Bedrock_ **Example:** + ```yaml preset: frequency_penalty: 0.5 @@ -814,20 +1022,26 @@ preset: #### stop > **Supported by:** `openAI`, `azureOpenAI`, custom (OpenAI-like) -> *Not typically used by Google/Anthropic/Bedrock* +> _Not typically used by Google/Anthropic/Bedrock_ **Example:** + ```yaml preset: stop: - - "END" - - "STOP" + - 'END' + - 'STOP' ``` --- @@ -839,11 +1053,17 @@ preset: **Example:** + ```yaml preset: top_p: 0.9 @@ -857,12 +1077,11 @@ preset: > (similar purpose to `top_p`, but named differently in those APIs) **Example:** + ```yaml preset: topP: 0.8 @@ -876,12 +1095,11 @@ preset: > (k-sampling limit on the next token distribution) **Example:** + ```yaml preset: topK: 40 @@ -892,15 +1110,14 @@ preset: #### max_tokens > **Supported by:** `openAI`, `azureOpenAI`, custom (OpenAI-like) -> *For Google/Anthropic, use `maxOutputTokens` or `maxTokens` (depending on the endpoint).* +> _For Google/Anthropic, use `maxOutputTokens` or `maxTokens` (depending on the endpoint)._ **Example:** + ```yaml preset: max_tokens: 4096 @@ -911,15 +1128,21 @@ preset: #### maxOutputTokens > **Supported by:** `google`, `anthropic` -> *Equivalent to `max_tokens` for these providers.* +> _Equivalent to `max_tokens` for these providers._ **Example:** + ```yaml preset: maxOutputTokens: 2048 @@ -941,6 +1164,7 @@ preset: **Default:** `true` **Example:** + ```yaml preset: promptCache: true @@ -953,6 +1177,7 @@ preset: #### reasoning_effort **Accepted Values:** + - `""` (empty string โ€” unset, uses API default) - `"none"` - `"minimal"` @@ -965,16 +1190,22 @@ preset: **Default:** `""` (unset) **Example:** + ```yaml preset: - reasoning_effort: "low" + reasoning_effort: 'low' ``` --- @@ -982,6 +1213,7 @@ preset: #### reasoning_summary **Accepted Values:** + - `""` (empty string โ€” disables reasoning summaries) - `"auto"` - `"concise"` @@ -998,9 +1230,10 @@ preset: **Default:** `""` (disabled) **Example:** + ```yaml preset: - reasoning_summary: "detailed" + reasoning_summary: 'detailed' ``` --- @@ -1018,6 +1251,7 @@ preset: **Default:** `false` **Example:** + ```yaml preset: useResponsesApi: true @@ -1028,6 +1262,7 @@ preset: #### verbosity **Accepted Values:** + - `""` (empty string โ€” unset, uses API default) - `"low"` - `"medium"` @@ -1036,17 +1271,16 @@ preset: > **Supported by:** `openAI`, `azureOpenAI`, custom (OpenAI-like) **Default:** `""` (unset) **Example:** + ```yaml preset: - verbosity: "low" + verbosity: 'low' ``` --- @@ -1066,6 +1300,7 @@ preset: **Note:** For Google endpoints, this parameter appears as `Grounding with Google Search` in the actual panel but controls `web_search` in the implementation. **Example:** + ```yaml preset: web_search: true @@ -1078,14 +1313,13 @@ preset: > **Supported by:** `openAI`, `azureOpenAI`, custom (OpenAI-like) **Default:** `false` **Example:** + ```yaml preset: disableStreaming: true @@ -1099,16 +1333,22 @@ preset: **Default:** `"Auto (-1)"` (Google), `2000` (Anthropic, Bedrock (Anthropic models)) **Example:** + ```yaml preset: - thinkingBudget: "2000" + thinkingBudget: '2000' ``` --- @@ -1119,11 +1359,17 @@ preset: **Accepted Values:** + - `""` (unset/auto) - `"minimal"` - `"low"` @@ -1133,9 +1379,10 @@ preset: **Default:** `""` (unset โ€” model decides) **Example:** + ```yaml preset: - thinkingLevel: "medium" + thinkingLevel: 'medium' ``` --- @@ -1146,7 +1393,12 @@ preset: @@ -1155,9 +1407,10 @@ preset: **Default:** `""` (unset โ€” model decides) **Example:** + ```yaml preset: - effort: "high" + effort: 'high' ``` --- @@ -1168,7 +1421,12 @@ preset: @@ -1181,9 +1439,10 @@ preset: **Default:** `"auto"` **Example:** + ```yaml preset: - thinkingDisplay: "summarized" + thinkingDisplay: 'summarized' ``` --- @@ -1194,13 +1453,19 @@ preset: **Default:** `true` **Example:** + ```yaml preset: thinking: true @@ -1213,16 +1478,13 @@ preset: > **Supported by:** `bedrock` > (Used to specify an AWS region for Amazon Bedrock) - + **Example:** + ```yaml preset: - region: "us-east-1" + region: 'us-east-1' ``` --- @@ -1233,12 +1495,11 @@ preset: > (Used in place of `max_tokens`) **Example:** + ```yaml preset: maxTokens: 1024 diff --git a/content/docs/configuration/logging.mdx b/content/docs/configuration/logging.mdx index ae48dcf34..569c01517 100644 --- a/content/docs/configuration/logging.mdx +++ b/content/docs/configuration/logging.mdx @@ -98,3 +98,75 @@ By default, the JSON string length is truncated to 255 characters. You can confi ], ]} /> + +- File-backed log transports are enabled by default. Set `LOG_TO_FILE=false` if your deployment should only emit logs to stdout/stderr. + + + +### OpenTelemetry Tracing + +LibreChat can emit backend OpenTelemetry traces for server, database, Redis, and outbound HTTP visibility. This is separate from Langfuse, which remains the recommended option for GenAI-specific prompt and model observability. + + diff --git a/content/docs/configuration/redis.mdx b/content/docs/configuration/redis.mdx index 76b09d28b..44b0b084b 100644 --- a/content/docs/configuration/redis.mdx +++ b/content/docs/configuration/redis.mdx @@ -61,6 +61,21 @@ REDIS_URI=redis://127.0.0.1:7001 USE_REDIS_CLUSTER=true ``` +### Single-Endpoint Managed Redis Services + +Some managed Redis services, including AWS ElastiCache Serverless and Redis Enterprise Cloud on AWS, expose a single connection endpoint while sharding keys internally. In that setup, keep LibreChat in single-node connection mode, but enable cluster-safe deletes if cache clears fail with `CROSSSLOT Keys in request don't hash to the same slot`. + +```bash +USE_REDIS=true +REDIS_URI=rediss://your-managed-redis-endpoint:6379 +USE_REDIS_CLUSTER=false +REDIS_CLUSTER_SAFE_DELETE=true +``` + +`REDIS_CLUSTER_SAFE_DELETE=true` makes LibreChat delete matching cache keys one at a time instead of sending multi-key `DEL` commands. This avoids `CROSSSLOT` errors without changing how LibreChat connects to Redis. + +Use `USE_REDIS_CLUSTER=true` only when LibreChat should create a Redis Cluster client. For single-endpoint managed services, `REDIS_CLUSTER_SAFE_DELETE=true` is the safer option. + ### Redis with TLS/SSL For secure Redis connections: @@ -104,9 +119,10 @@ REDIS_URI=rediss://your-redis-host:6380 # Provide CA certificate for verification REDIS_CA=/path/to/your/ca-certificate.pem ``` + ### TLS with Elasticache -Elasticache may need to use an alternate dnsLookup for TLS connections. see "Special Note: Aws Elasticache Clusters with TLS" on this webpage: https://www.npmjs.com/package/ioredis +Elasticache may need to use an alternate dnsLookup for TLS connections. see "Special Note: Aws Elasticache Clusters with TLS" on this webpage: https://www.npmjs.com/package/ioredis ```bash # Enable redis alternate dnsLookup @@ -153,11 +169,13 @@ REDIS_KEY_PREFIX=dev-john-local **Important**: You cannot set both `REDIS_KEY_PREFIX_VAR` and `REDIS_KEY_PREFIX` simultaneously. **Examples of contamination without prefixing**: + - Production cache overwritten by staging deployment - Feature branch tests corrupting main branch cache - Old deployment versions serving stale cached data **Key prefixing format**: + - IoRedis client: `{prefix}::{key}` - Keyv client: Handled by the store layer @@ -183,6 +201,7 @@ REDIS_PING_INTERVAL=300 ``` **Important**: + - Setting `REDIS_PING_INTERVAL=0` or omitting it disables pinging entirely - Only set a positive value (in seconds) if you experience connection timeout issues - The interval is specified in seconds and applies to both IoRedis and Keyv Redis clients @@ -199,33 +218,34 @@ FORCED_IN_MEMORY_CACHE_NAMESPACES=ROLES,MESSAGES Valid cache keys (from the `CacheKeys` enum in `librechat-data-provider`): -| Key | Description | -|---|---| -| `CONFIG_STORE` | Configuration store | -| `ROLES` | User roles | -| `PLUGINS` | Plugins data | -| `GEN_TITLE` | Generated titles | -| `TOOLS` | Tools data | -| `MODELS_CONFIG` | Models configuration | -| `MODEL_QUERIES` | Model queries | -| `STARTUP_CONFIG` | Startup configuration | -| `ENDPOINT_CONFIG` | Endpoint configuration | -| `TOKEN_CONFIG` | Token configuration | -| `APP_CONFIG` | Application configuration | -| `ABORT_KEYS` | Abort keys | -| `BANS` | Ban data | -| `ENCODED_DOMAINS` | Encoded domains | -| `AUDIO_RUNS` | Audio processing runs | -| `MESSAGES` | Messages | -| `FLOWS` | Flows data | -| `PENDING_REQ` | Pending requests | -| `S3_EXPIRY_INTERVAL` | S3 expiry intervals | -| `OPENID_EXCHANGED_TOKENS` | OpenID exchanged tokens | -| `OPENID_SESSION` | OpenID sessions | -| `SAML_SESSION` | SAML sessions | +| Key | Description | +| ------------------------- | ------------------------- | +| `CONFIG_STORE` | Configuration store | +| `ROLES` | User roles | +| `PLUGINS` | Plugins data | +| `GEN_TITLE` | Generated titles | +| `TOOLS` | Tools data | +| `MODELS_CONFIG` | Models configuration | +| `MODEL_QUERIES` | Model queries | +| `STARTUP_CONFIG` | Startup configuration | +| `ENDPOINT_CONFIG` | Endpoint configuration | +| `TOKEN_CONFIG` | Token configuration | +| `APP_CONFIG` | Application configuration | +| `ABORT_KEYS` | Abort keys | +| `BANS` | Ban data | +| `ENCODED_DOMAINS` | Encoded domains | +| `AUDIO_RUNS` | Audio processing runs | +| `MESSAGES` | Messages | +| `FLOWS` | Flows data | +| `PENDING_REQ` | Pending requests | +| `S3_EXPIRY_INTERVAL` | S3 expiry intervals | +| `OPENID_EXCHANGED_TOKENS` | OpenID exchanged tokens | +| `OPENID_SESSION` | OpenID sessions | +| `SAML_SESSION` | SAML sessions | -Using an invalid key (e.g., the deprecated `STATIC_CONFIG`) will cause a startup error. Only use keys from the table above. + Using an invalid key (e.g., the deprecated `STATIC_CONFIG`) will cause a startup error. Only use + keys from the table above. ## Performance Tuning @@ -233,6 +253,7 @@ Using an invalid key (e.g., the deprecated `STATIC_CONFIG`) will cause a startup ### Connection Keep-Alive The application implements configurable connection keep-alive: + - Ping intervals are controlled by `REDIS_PING_INTERVAL` environment variable - Default behavior: No pinging (recommended for most deployments) - When enabled, pings both IoRedis and Keyv Redis clients at the specified interval @@ -241,6 +262,7 @@ The application implements configurable connection keep-alive: ### Cache Strategy The application uses a dual-client approach: + - **IoRedis client**: Primary Redis operations with automatic prefixing - **Keyv Redis client**: Store-layer operations with prefix handling in `cacheFactory.js` @@ -319,4 +341,4 @@ USE_REDIS_CLUSTER=true REDIS_URI=redis://node1:7001,redis://node2:7002,redis://node3:7003 ``` -See [Resumable Streams](/docs/features/resumable_streams) for more details on this feature. \ No newline at end of file +See [Resumable Streams](/docs/features/resumable_streams) for more details on this feature. diff --git a/content/docs/features/admin_panel.mdx b/content/docs/features/admin_panel.mdx index c5d4832e8..d49baf713 100644 --- a/content/docs/features/admin_panel.mdx +++ b/content/docs/features/admin_panel.mdx @@ -9,7 +9,10 @@ description: A standalone web UI for managing LibreChat users, groups, roles, co The **LibreChat Admin Panel** is a standalone browser-based management interface for LibreChat. It connects to the same database as LibreChat itself and provides a GUI for the administrative tasks that power [granular access control](/docs/features/access_control): user and group administration, role management, configuration overrides scoped to roles or groups, and system-level capability grants. -The admin panel is available for testing now and is the upcoming management surface that builds on the admin APIs introduced in [LibreChat v0.8.5](/changelog/v0.8.5). Source, issues, and releases live at [github.com/ClickHouse/librechat-admin-panel](https://github.com/ClickHouse/librechat-admin-panel). + The admin panel is available for testing now and is the upcoming management surface that builds on + the admin APIs introduced in [LibreChat v0.8.5](/changelog/v0.8.5). Source, issues, and releases + live at + [github.com/ClickHouse/librechat-admin-panel](https://github.com/ClickHouse/librechat-admin-panel). ## What It Does @@ -42,15 +45,15 @@ The admin panel runs as a separate service; it does not share a process with Lib The admin API surface exposed by LibreChat is: -| Mount | Purpose | -| --- | --- | -| `POST /api/admin/login`   `/oauth/*` | Admin-specific authentication endpoints (local + SSO) | -| `GET /api/admin/verify` | Validates the admin session | -| `/api/admin/users` | User listing and search | -| `/api/admin/groups` | Group CRUD + member management | -| `/api/admin/roles` | Custom role CRUD + permission editing + member management | -| `/api/admin/grants` | System capability grants (assign/revoke/list) | -| `/api/admin/config` | Base + per-principal configuration overrides | +| Mount | Purpose | +| ----------------------------------------- | --------------------------------------------------------- | +| `POST /api/admin/login`   `/oauth/*` | Admin-specific authentication endpoints (local + SSO) | +| `GET /api/admin/verify` | Validates the admin session | +| `/api/admin/users` | User listing and search | +| `/api/admin/groups` | Group CRUD + member management | +| `/api/admin/roles` | Custom role CRUD + permission editing + member management | +| `/api/admin/grants` | System capability grants (assign/revoke/list) | +| `/api/admin/config` | Base + per-principal configuration overrides | ## Getting Started @@ -88,7 +91,10 @@ docker run -p 3000:3000 \ ``` -Inside a container, `localhost` refers to the container itself, not your host. When LibreChat runs on the same host, point `VITE_API_BASE_URL` at `http://host.docker.internal:3080` (Linux: add `--add-host=host.docker.internal:host-gateway`). In production, use the public/internal DNS name of your LibreChat API. + Inside a container, `localhost` refers to the container itself, not your host. When LibreChat runs + on the same host, point `VITE_API_BASE_URL` at `http://host.docker.internal:3080` (Linux: add + `--add-host=host.docker.internal:host-gateway`). In production, use the public/internal DNS name + of your LibreChat API. ### Run Locally for Development @@ -103,28 +109,45 @@ bun dev # http://localhost:3000 ## Environment Variables -| Variable | Required | Default | Description | -| --- | --- | --- | --- | -| `SESSION_SECRET` | **Yes** in production | Hardcoded dev fallback when running `bun dev`; **no default** in the Docker image | Session encryption key. Must be at least 32 characters. | -| `VITE_API_BASE_URL` | **Yes** in Docker | `http://localhost:3080` (local dev only) | Browser-facing URL of the LibreChat API server, used for OAuth redirects. | -| `API_SERVER_URL` | No | Falls back to `VITE_API_BASE_URL` | Server-side URL for LibreChat API calls. Useful when the admin-panel server reaches LibreChat on a different URL than the browser (e.g. internal Kubernetes service vs. public hostname). | -| `PORT` | No | `3000` | Port the admin panel listens on. | -| `ADMIN_SSO_ONLY` | No | `false` | Hide the email/password form, forcing SSO-only login. | -| `ADMIN_SESSION_IDLE_TIMEOUT_MS` | No | `1800000` (30 min) | Session idle timeout in milliseconds. | -| `SESSION_COOKIE_SECURE` | No | `true` in production | Whether the session cookie requires HTTPS. | -| `ADMIN_PANEL_METRICS_SECRET` | No | _unset_ | Bearer token required to scrape the `/metrics` Prometheus endpoint. The endpoint returns `401` when unset or mismatched. | +| Variable | Required | Default | Description | +| ------------------------------- | --------------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `SESSION_SECRET` | **Yes** in production | Hardcoded dev fallback when running `bun dev`; **no default** in the Docker image | Session encryption key. Must be at least 32 characters. | +| `VITE_API_BASE_URL` | **Yes** in Docker | `http://localhost:3080` (local dev only) | Browser-facing URL of the LibreChat API server, used for OAuth redirects. | +| `API_SERVER_URL` | No | Falls back to `VITE_API_BASE_URL` | Server-side URL for LibreChat API calls. Useful when the admin-panel server reaches LibreChat on a different URL than the browser (e.g. internal Kubernetes service vs. public hostname). | +| `PORT` | No | `3000` | Port the admin panel listens on. | +| `ADMIN_SSO_ONLY` | No | `false` | Hide the email/password form, forcing SSO-only login. | +| `ADMIN_SESSION_IDLE_TIMEOUT_MS` | No | `1800000` (30 min) | Session idle timeout in milliseconds. | +| `SESSION_COOKIE_SECURE` | No | `true` in production | Whether the session cookie requires HTTPS. | +| `ADMIN_PANEL_METRICS_SECRET` | No | _unset_ | Bearer token required to scrape the `/metrics` Prometheus endpoint. The endpoint returns `401` when unset or mismatched. | + +### LibreChat Redirect URL + +When the admin panel is hosted on a separate URL from LibreChat, set `ADMIN_PANEL_URL` in the LibreChat API environment. Use the external admin panel base URL, including any path prefix, and omit the trailing slash: + +```bash filename=".env" +ADMIN_PANEL_URL=https://admin.example.com/admin +``` + +For Helm deployments, set `librechat.adminPanelUrl` in your values file. The chart renders it as `ADMIN_PANEL_URL` for LibreChat's admin OAuth flow: + +```yaml filename="values.yaml" +librechat: + adminPanelUrl: https://admin.example.com/admin +``` + +For OpenID SSO, register `${DOMAIN_SERVER}/api/admin/oauth/openid/callback` with your identity provider. ### Cache Controls These mirror LibreChat's cache env vars. `ADMIN_PANEL_*` variants take precedence, falling back to the shared LibreChat equivalents when unset. -| Variable | Purpose | -| --- | --- | -| `STATIC_CACHE_MAX_AGE` / `ADMIN_PANEL_STATIC_CACHE_MAX_AGE` | Browser `max-age` in seconds for hashed assets in `/assets/` (default 172800 = 2 days). | -| `STATIC_CACHE_S_MAX_AGE` / `ADMIN_PANEL_STATIC_CACHE_S_MAX_AGE` | CDN `s-maxage` in seconds (default 86400 = 1 day). | -| `INDEX_CACHE_CONTROL` / `ADMIN_PANEL_INDEX_CACHE_CONTROL` | `Cache-Control` header for the HTML index response. | -| `INDEX_PRAGMA` / `ADMIN_PANEL_INDEX_PRAGMA` | `Pragma` header for the HTML index response. | -| `INDEX_EXPIRES` / `ADMIN_PANEL_INDEX_EXPIRES` | `Expires` header for the HTML index response. | +| Variable | Purpose | +| --------------------------------------------------------------- | --------------------------------------------------------------------------------------- | +| `STATIC_CACHE_MAX_AGE` / `ADMIN_PANEL_STATIC_CACHE_MAX_AGE` | Browser `max-age` in seconds for hashed assets in `/assets/` (default 172800 = 2 days). | +| `STATIC_CACHE_S_MAX_AGE` / `ADMIN_PANEL_STATIC_CACHE_S_MAX_AGE` | CDN `s-maxage` in seconds (default 86400 = 1 day). | +| `INDEX_CACHE_CONTROL` / `ADMIN_PANEL_INDEX_CACHE_CONTROL` | `Cache-Control` header for the HTML index response. | +| `INDEX_PRAGMA` / `ADMIN_PANEL_INDEX_PRAGMA` | `Pragma` header for the HTML index response. | +| `INDEX_EXPIRES` / `ADMIN_PANEL_INDEX_EXPIRES` | `Expires` header for the HTML index response. | ## Authentication