Skip to content

interface.mdx

Latest commit

 

History

History
744 lines (581 loc) · 26.3 KB

interface.mdx

File metadata and controls

744 lines (581 loc) · 26.3 KB
title Interface Object Structure
icon LayoutDashboard

Overview

The interface object allows for customization of various user interface elements within the application, including visibility and behavior settings for components such as menus, panels, and links. This section provides a detailed breakdown of the interface object structure.

These are fields under interface:

  • mcpServers
  • privacyPolicy
  • termsOfService
  • modelSelect
  • parameters
  • presets
  • prompts
  • bookmarks
  • memories
  • multiConvo
  • agents
  • temporaryChat
  • temporaryChatRetention
  • retentionMode
  • autoSubmitFromUrl
  • customWelcome
  • runCode
  • webSearch
  • fileSearch
  • fileCitations
  • peoplePicker
  • marketplace

Notes:

  • The interface configurations are applied globally within the application.
  • Default values are provided for most settings but can be overridden based on specific requirements or conditions.
  • Conditional logic in the application can further modify these settings based on other configurations like model specifications.
Several fields below (`mcpServers`, `prompts`, `bookmarks`, `memories`, `multiConvo`, `agents`, `remoteAgents`, `temporaryChat`, `runCode`, `webSearch`, `fileSearch`, `fileCitations`, `peoplePicker`, `marketplace`) don't just toggle UI, they seed role permissions in the database at startup, and only for the built-in `USER` role.

For ongoing management, use the LibreChat Admin Panel, which edits the permission matrix directly on each role (including custom roles). These YAML fields remain supported for bootstrapping a fresh instance or fully file-driven deployments, but should no longer be used as the primary way to manage feature permissions.

See Access Control for the full permission model.

Example

interface:
  mcpServers:
    placeholder: "MCP Servers"
    use: true
    create: true
    share: false
    public: false
    trustCheckbox:
      label: "I trust this server"
      subLabel: "Only enable servers you trust"
  privacyPolicy:
    externalUrl: "https://example.com/privacy"
    openNewTab: true
  termsOfService:
    externalUrl: "https://example.com/terms"
    openNewTab: true
    modalAcceptance: true
    modalTitle: "Terms of Service"
    modalContent: |
      # Terms of Service
      ## Introduction
      Welcome to LibreChat!
  modelSelect: false
  parameters: true
  presets: false
  prompts:
    use: true
    create: true
    share: true
    public: false
  bookmarks: true
  multiConvo: true
  agents:
    use: true
    create: true
    share: true
    public: false
  customWelcome: "Hey {{user.name}}! Welcome to LibreChat"
  runCode: true
  webSearch: true
  fileSearch: true
  fileCitations: true

mcpServers

Deprecated for permission management. The use, create, share, and public sub-keys seed role permissions at startup. Prefer the Admin Panel for managing MCP server permissions per role/group/user. The placeholder and trustCheckbox sub-keys are unaffected.

Key: <OptionTable options={[ ['mcpServers', 'Object', 'Contains settings related to the MCP (Model Context Protocol) server selection interface and access control.', 'Allows for customization of the placeholder text, user permissions, and trust checkbox labels.'], ]} />

Sub-keys: <OptionTable options={[ ['placeholder', 'String', 'The placeholder text displayed in the MCP server selection dropdown when no server is selected.', 'MCP Servers'], ['use', 'Boolean', 'Controls whether users have permission to use existing MCP servers.', 'true'], ['create', 'Boolean', 'Controls whether users have permission to create new MCP servers.', 'true'], ['share', 'Boolean', 'Controls whether users have permission to share MCP servers with other users.', 'false'], ['public', 'Boolean', 'Controls whether users can share MCP servers publicly (visible to all users).', 'false'], ['trustCheckbox', 'Object', 'Customizable labels for the trust checkbox in the MCP server dialog. Supports simple strings or language-keyed objects for internationalization.', 'See below'], ]} />

trustCheckbox Sub-keys: <OptionTable options={[ ['label', 'String or Object', 'The main label for the trust checkbox. Can be a simple string or a language-keyed object (e.g., { en: "I trust this server", es: "Confío en este servidor" }).', ''], ['subLabel', 'String or Object', 'The sub-label (help text) for the trust checkbox. Can be a simple string or a language-keyed object for internationalization.', ''], ]} />

Example:

interface:
  mcpServers:
    placeholder: "Select MCP Server"
    use: true
    create: true
    share: false
    trustCheckbox:
      label:
        en: "I trust this server"
        es: "Confío en este servidor"
      subLabel:
        en: "Only enable servers you trust"
        es: "Solo habilite servidores en los que confíe"

privacyPolicy

Key: <OptionTable options={[ ['privacyPolicy', 'Object', 'Contains settings related to the privacy policy link provided in the user interface.', 'Allows for the specification of a custom URL and the option to open it in a new tab.'], ]} />

Sub-keys: <OptionTable options={[ ['externalUrl', 'String (URL)', 'The URL pointing to the privacy policy document.', ''], ['openNewTab', 'Boolean', 'Specifies whether the link should open in a new tab.', ''], ]} />

termsOfService

Key: <OptionTable options={[ ['termsOfService', 'Object', 'Contains settings related to the terms of service link provided in the user interface.', 'Allows for the specification of a custom URL and the option to open it in a new tab, as well as a modal acceptance dialog for the terms of service.'], ]} />

Sub-keys: <OptionTable options={[ ['externalUrl', 'String (URL)', 'The URL pointing to the terms of service document.', 'https://librechat.ai/tos'], ['openNewTab', 'Boolean', 'Specifies whether the link should open in a new tab.', 'true'], ['modalAcceptance', 'Boolean', 'Specifies whether to show a modal terms and conditions dialog for users to accept in order to be able to use LibreChat.', 'true'], ['modalTitle', 'String', 'Specifies a custom title for the modal terms and conditions dialog (optional).', 'Terms of Service'], ['modalContent', 'String', 'Specifies the content of the modal terms and conditions dialog in MarkDown format.', 'See librechat.yaml.example for how to correctly format the multi-line parameter.'], ]} />

modelSelect

Key: <OptionTable options={[ ['modelSelect', 'Boolean', 'Determines whether the model selection feature is available in the UI.', 'Enabling this feature allows users to select different models directly from the interface.'], ]} />

Default: true

Notes:

  • This is required to be true if using modelSpecs.addedEndpoints.
  • If modelSpecs.addedEndpoints is used and interface.modelSelect is not explicitly set, it defaults to true.

Example:

interface:
  modelSelect: true

parameters

Key: <OptionTable options={[ ['parameters', 'Boolean', 'Toggles the visibility of parameter configuration options within the interface.', 'This setting is crucial for users who need to adjust parameters for specific functionalities within the application.'], ]} />

Default: true

Example:

interface:
  parameters: false

presets

Key: <OptionTable options={[ ['presets', 'Boolean', 'Enables or disables the use of presets in the application's UI.', 'Presets can simplify user interactions by providing pre-configured settings or operations, enhancing user experience and efficiency.'], ]} />

Default: true

Example:

interface:
  presets: true

prompts

Deprecated for permission management. Seeds the PROMPTS role permissions at startup for the default USER role only. Prefer the Admin Panel for managing prompt permissions per role/group/user.

Key: <OptionTable options={[ ['prompts', 'Boolean or Object', 'Controls prompt-related features for all users. Can be a boolean for simple enable/disable, or an object for granular control over use, creation, sharing, and public visibility.', 'When set to false, users will not have access to create, edit, or use custom prompts.'], ]} />

Default: true

Important: Boolean vs Object Configuration

  • Boolean (prompts: true): Only updates the use permission. Existing create, share, and public permission values are preserved from the database. Use this as a simple feature toggle without affecting other settings configured through the admin panel.

  • Object: Updates only the sub-permissions that are explicitly specified. Any permissions not included in the config are preserved from the database.

When using the object structure:

Sub-keys: <OptionTable options={[ ['use', 'Boolean', 'Controls whether users can use prompts.', 'true'], ['create', 'Boolean', 'Controls whether users can create new prompts.', 'true'], ['share', 'Boolean', 'Controls whether users can share prompts with specific users/groups.', 'false'], ['public', 'Boolean', 'Controls whether users can share prompts publicly (visible to all users).', 'false'], ]} />

Example (boolean - simple feature toggle):

interface:
  prompts: true  # Only updates USE; create/share/public remain unchanged

Example (object - granular control):

interface:
  prompts:
    use: true
    create: false  # Disable creation while allowing use
    # share and public not specified - preserves existing values

Example (object - full control):

interface:
  prompts:
    use: true
    create: true
    share: true
    public: false

bookmarks

Deprecated for permission management. Seeds the BOOKMARKS role permission at startup for the default USER role only. Prefer the Admin Panel.

Key: <OptionTable options={[ ['bookmarks', 'Boolean', 'Enables or disables all bookmarks-related features for all users.', 'When disabled, users will not be able to create, manage, or access bookmarks within the application.'], ]} />

Default: true

Example:

interface:
  bookmarks: true

memories

Deprecated for permission management. Seeds the MEMORIES role permissions at startup for the default USER role only. Prefer the Admin Panel. Note this toggle is separate from the memory behavior configuration.

Key: <OptionTable options={[ ['memories', 'Boolean', 'Enables or disables the memories feature for all users in the interface.', 'When disabled, users will not have access to the memories panel or memory-related features.'], ]} />

Default: true

Note: This controls the UI visibility of the memories feature. For detailed memory behavior configuration (token limits, personalization, agent settings), see the Memory Configuration.

Example:

interface:
  memories: true

multiConvo

Deprecated for permission management. Seeds the MULTI_CONVO role permission at startup for the default USER role only. Prefer the Admin Panel.

Key: <OptionTable options={[ ['multiConvo', 'Boolean', 'Enables or disables all "multiConvo", AKA multiple response streaming, related features for all users.', 'When disabled, users will not be able to stream responses from 2 AI models at the same time.'], ]} />

Default: true

Example:

interface:
  multiConvo: true

agents

More info on Agents

Deprecated for permission management. Seeds the AGENTS role permissions at startup for the default USER role only. Prefer the Admin Panel for managing agent permissions per role/group/user.

Key: <OptionTable options={[ ['agents', 'Boolean or Object', 'Controls agent-related features for all users. Can be a boolean for simple enable/disable, or an object for granular control over use, creation, sharing, and public visibility.', 'When set to false, users will not have access to agents.'], ]} />

Default: true

Important: Boolean vs Object Configuration

  • Boolean (agents: true): Only updates the use permission. Existing create, share, and public permission values are preserved from the database. Use this as a simple feature toggle without affecting other settings configured through the admin panel.

  • Object: Updates only the sub-permissions that are explicitly specified. Any permissions not included in the config are preserved from the database.

When using the object structure:

Sub-keys: <OptionTable options={[ ['use', 'Boolean', 'Controls whether users can use agents.', 'true'], ['create', 'Boolean', 'Controls whether users can create new agents.', 'true'], ['share', 'Boolean', 'Controls whether users can share agents with specific users/groups.', 'false'], ['public', 'Boolean', 'Controls whether users can share agents publicly (visible to all users).', 'false'], ]} />

Example (boolean - simple feature toggle):

interface:
  agents: true  # Only updates USE; create/share/public remain unchanged

Example (object - granular control):

interface:
  agents:
    use: true
    create: false  # Disable creation while allowing use
    # share and public not specified - preserves existing values

Example (object - full control):

interface:
  agents:
    use: true
    create: true
    share: true
    public: false

remoteAgents

Controls access to the Agents API (OpenAI-compatible and Open Responses API endpoints), which allows external applications to interact with LibreChat agents programmatically via API keys.

Deprecated for permission management. Seeds the REMOTE_AGENTS role permissions at startup for the default USER role only. Prefer the Admin Panel.

Key: <OptionTable options={[ ['remoteAgents', 'Object', 'Configuration for remote agent API access control. All fields default to false.', ''], ]} />

Sub-keys: <OptionTable options={[ ['use', 'Boolean', 'Controls whether users can access the remote agents API.', 'false'], ['create', 'Boolean', 'Controls whether users can create API keys for remote agents.', 'false'], ['share', 'Boolean', 'Controls whether users can share remote agents.', 'false'], ['public', 'Boolean', 'Controls whether users can share remote agents publicly.', 'false'], ]} />

Default: All fields default to false (disabled).

Example:

interface:
  remoteAgents:
    use: true
    create: true
    share: false
    public: false

Note: Admin users have all remote agent permissions enabled by default regardless of this configuration.

temporaryChat

Controls whether the temporary chat feature is available to users. Temporary chats are not saved to conversation history and are automatically deleted after a configurable retention period.

Deprecated for permission management. Seeds the TEMPORARY_CHAT role permission at startup for the default USER role only. Prefer the Admin Panel. temporaryChatRetention below is not a permission and remains the recommended way to configure retention.

Key: <OptionTable options={[ ['temporaryChat', 'Boolean', 'Enables or disables the temporary chat feature.', 'When set to false, users will not see the option to start temporary chats.'], ]} />

Default: true

Note: The retention period for temporary chats can be configured using temporaryChatRetention.

Example:

interface:
  temporaryChat: true

temporaryChatRetention

The temporaryChatRetention configuration allows you to customize how long temporary chats are retained before being automatically deleted.

Key: <OptionTable options={[ ['temporaryChatRetention', 'Number', 'Sets the retention period for temporary chats in hours.', 'temporaryChatRetention: 168'], ]} />

Validation Rules:

  • Minimum: 1 hour (prevents immediate deletion)
  • Maximum: 8760 hours (1 year maximum retention)
  • Default: 720 hours (30 days)

Configuration Methods:

  1. LibreChat.yaml (recommended): interface.temporaryChatRetention: 168
  2. Environment Variable (deprecated): TEMP_CHAT_RETENTION_HOURS=168

Note: The environment variable TEMP_CHAT_RETENTION_HOURS is deprecated. Please use the interface.temporaryChatRetention config option in librechat.yaml instead. The config file value takes precedence over the environment variable.

Example:

interface:
  temporaryChatRetention: 168  # Retain temporary chats for 7 days
  retentionMode: "temporary"

Common Retention Periods:

  • 1 hour: temporaryChatRetention: 1 (minimal retention)
  • 24 hours: temporaryChatRetention: 24 (1 day)
  • 168 hours: temporaryChatRetention: 168 (1 week)
  • 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 conversation data.', 'retentionMode: "temporary"'], ]} />

Default: temporary

`retentionMode: "all"` applies retention deadlines beyond temporary chats. Confirm your retention policy before enabling it.

Example:

interface:
  temporaryChatRetention: 168
  retentionMode: "all"

autoSubmitFromUrl

Controls whether a prompt supplied via URL query parameters on /c/new is auto-submitted to the model.

When /c/new?prompt=…&submit=true is opened by an authenticated user, LibreChat normally pre-fills the composer with the URL-supplied prompt and submits it immediately. This is a convenience feature for crafted deeplinks and shared chat URLs.

For deployments where users may receive crafted links from external sources — and where memory- or tool-enabled models could leak sensitive context if a prompt-injection payload reaches the model — operators can disable auto-submission. With the flag set to false, the prompt is still pre-filled in the composer but the user must press Send explicitly.

Key: <OptionTable options={[ ['autoSubmitFromUrl', 'Boolean', 'Controls whether /c/new?prompt=…&submit=true auto-submits to the model.', 'When false, the prompt is pre-filled in the composer but not submitted.'], ]} />

Default: true (existing behavior is preserved unless explicitly disabled).

Notes:

  • This setting does not affect URL-driven model spec selection or other URL-driven settings — only the auto-submission step.
  • The query parameter accepts both prompt and q as the prompt source, with prompt taking precedence. submit=true is the trigger.
  • Recommended for instances handling sensitive memory or tool data, where a 1-click prompt-injection vector should require explicit user confirmation.

Example:

interface:
  autoSubmitFromUrl: false

customWelcome

Key: <OptionTable options={[ ['customWelcome', 'String', 'Allows administrators to define a custom welcome message for the chat interface, with the option to personalize it using the {{user.name}} parameter.'], ]} />

Default: None (if not specified, a default greeting is used)

Example:

interface:
    customWelcome: "Hey {{user.name}}! Welcome to LibreChat"

Note: You can use {{user.name}} within the customWelcome message to dynamically insert the user's name for a personalized greeting experience.

runCode

Enables/disables the "Run Code" button for Markdown Code Blocks. More info on the LibreChat Code Interpreter API

Note: This setting does not disable the Agents Code Interpreter Capability. To disable the Agents Capability, see the Agents Endpoint configuration instead.

Deprecated for permission management. Seeds the RUN_CODE role permission at startup for the default USER role only. Prefer the Admin Panel.

Key: <OptionTable options={[ ['runCode', 'Boolean', 'Enables or disables the "Run Code" button for Markdown Code Blocks.'], ]} />

Default: true

Example:

interface:
  runCode: true

webSearch

Enables/disables the web search button in the chat interface. More info on Web Search Configuration

Note: This setting does not disable the Agents Web Search Capability. To disable the Agents Capability, see the Agents Endpoint configuration instead.

Deprecated for permission management. Seeds the WEB_SEARCH role permission at startup for the default USER role only. Prefer the Admin Panel.

Key: <OptionTable options={[ ['webSearch', 'Boolean', 'Enables or disables the web search button in the chat interface.'], ]} />

Default: true

Example:

interface:
  webSearch: true

fileSearch

Enables/disables the file search (for RAG API usage via tool) button in the chat interface

Note: This setting does not disable the Agents File Search Capability. To disable the Agents Capability, see the Agents Endpoint configuration instead.

Deprecated for permission management. Seeds the FILE_SEARCH role permission at startup for the default USER role only. Prefer the Admin Panel.

Key: <OptionTable options={[ ['fileSearch', 'Boolean', 'Enables or disables the file search button in the chat interface.'], ]} />

Default: true

Example:

interface:
  fileSearch: true

fileCitations

Controls the global availability of file citations functionality. When disabled, it effectively removes the FILE_CITATIONS permission for all users, preventing any file citations from being displayed when using file search, regardless of individual user permissions.

Deprecated for permission management. Seeds/globally gates the FILE_CITATIONS role permission at startup. Prefer the Admin Panel for managing citations permissions per role/group/user.

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.
  • When using agents with file search capability, citation behavior (quantity and quality) can be configured through the Agents endpoint configuration.

Key: <OptionTable options={[ ['fileCitations', 'Boolean', 'Globally enables or disables the FILE_CITATIONS permission for all users, controlling whether file search results can include source citations.'], ]} />

Default: true

Example:

interface:
  fileCitations: true

peoplePicker

Controls which principal types (users, groups, roles) are available for selection in the people picker interface, typically used when sharing agents or managing access controls.

Deprecated for permission management. Seeds the PEOPLE_PICKER role permissions at startup for the default USER role only. Prefer the Admin Panel.

Key: <OptionTable options={[ ['peoplePicker', 'Object', 'Configuration for which principal types are available in the people picker interface.'], ]} />

Sub-keys:

<OptionTable options={[ ['users', 'Boolean', 'Enables user search in the people picker. Default: true'], ['groups', 'Boolean', 'Enables group search in the people picker. Default: true'], ['roles', 'Boolean', 'Enables role search in the people picker. Default: true'], ]} />

Default:

peoplePicker:
  users: true
  groups: true
  roles: true

Example:

interface:
  peoplePicker:
    users: true
    groups: true
    roles: false  # Disable role selection in people picker

marketplace

Enables/disables access to the Agent Marketplace.

Deprecated for permission management. Seeds the MARKETPLACE role permission at startup for the default USER role only. Prefer the Admin Panel.

Key: <OptionTable options={[ ['marketplace', 'Object', 'Configuration for Agent Marketplace access control.'], ]} />

Sub-keys:

<OptionTable options={[ ['use', 'Boolean', 'Enables or disables marketplace access. Default: false'], ]} />

Default:

marketplace:
  use: false

Example:

interface:
  marketplace:
    use: true  # Enable marketplace access