Interface Object Structure

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:

• theme
• mcpServers
• privacyPolicy
• termsOfService
• modelSelect
• agentSelectorLimit
• parameters
• contextUsage
• contextCost
• currency
• presets
• prompts
• bookmarks
• memories
• multiConvo
• agents
• remoteAgents
• skills
• sharedLinks
• schedules
• temporaryChat
• temporaryChatRetention
• generalChatRetention
• retentionMode
• retainAgentFiles
• autoSubmitFromUrl
• customWelcome
• codeHighlightThrottleMs
• artifactUndocking
• runCode
• webSearch
• fileSearch
• fileCitations
• feedback
• replyNotifications
• defaultPinnedTools
• composerRecentFiles
• steerArmConfirmationTimeoutMs
• queuedTurnReconciliationTimeoutMs
• queuedSendLockTimeoutMs
• 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.

Example

interface:
  theme: librechat
  mcpServers:
    placeholder: 'MCP Servers'
    use: true
    create: true
    share: false
    public: false
    configureObo: 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
  agentSelectorLimit: 10
  parameters: true
  contextUsage: true
  contextCost: true
  currency:
    code: EUR
    rate: 0.92
  presets: false
  prompts:
    use: true
    create: true
    share: true
    public: false
  bookmarks: true
  multiConvo: true
  agents:
    use: true
    create: true
    share: true
    public: false
  skills:
    use: true
    create: true
    share: false
    public: false
    defaultActiveOnShare: false
  sharedLinks:
    create: true
    share: true
    public: false
    snapshotFiles: true
  schedules:
    use: true
    create: true
    maxPerUser: 10
    minIntervalMinutes: 60
    autoDisableAfterFailures: 5
    fireConcurrency: 5
  customWelcome: 'Hey {{user.name}}! Welcome to LibreChat'
  codeHighlightThrottleMs: 300
  artifactUndocking: true
  runCode: true
  webSearch: true
  fileSearch: true
  fileCitations: true
  feedback: true
  defaultPinnedTools:
    - artifacts
    - execute_code

theme

Sets the deployment theme applied to every user, in both light and dark mode. Either the name of a bundled theme (librechat or clickhouse) or an inline theme definition with its own colors, radii, fonts, shadows and motion.

It outranks the REACT_APP_THEME_* build-time colors and users' stored themes, yields to the high-contrast modes, and is never saved to the user's browser. Removing it restores each user's own stored theme, or the REACT_APP_THEME_* colors when the client was built with them.

Key:

Default: None (the default LibreChat theme, or the user's own theme)

Example:

interface:
  theme: clickhouse

See Theme for the inline definition format, every appearance key with its default, the ClickHouse reference theme and how shared links pick their theme.

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:

Sub-keys:

trustCheckbox Sub-keys:

Example:

interface:
  mcpServers:
    placeholder: 'Select MCP Server'
    toolsRefreshInterval: 300000
    statusRefreshInterval: 30000
    use: true
    create: true
    share: false
    configureObo: 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:

Sub-keys:

Where the policy links appear

On the sign-in and registration screens, published policies appear as a consent sentence: "By continuing, you agree to the Terms of Service and acknowledge the Privacy Policy." If only one policy is published, the sentence names only that one. On the registration screen it sits under the submit button; on the sign-in screen it sits below the sign-in options.

In chat, the policy links appear under the message box on the welcome screen of a new chat, and are hidden once a conversation starts.

A policy whose externalUrl is empty or blank is treated as not published and is never shown. When termsOfService.modalAcceptance is true, the auth screens show plain policy links instead of the consent sentence, because users accept the terms explicitly in the dialog after signing in.

termsOfService

Key:

Sub-keys:

When modal acceptance is enabled, LibreChat records both the acceptance state and the time it was accepted. After upgrading an existing deployment, run npm run migrate:terms-timestamp to backfill accepted users that do not have a timestamp. The migration asks for confirmation, processes all tenants, uses each user's account creation time as the fallback, and exits non-zero if any batch fails. Running npm run reset-terms clears both the acceptance state and its timestamp so users must accept again.

modelSelect

Key:

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:

Default: true

Example:

interface:
  parameters: false

contextUsage

Key:

Default: true

Example:

interface:
  contextUsage: true

contextCost

Key:

Default: false

Notes:

• Set contextCost: true to opt in to visible cost values. Token usage can remain visible through contextUsage while cost values stay hidden.
• currency only affects displayed costs when cost display is enabled.

Example:

interface:
  contextCost: true

currency

Key:

Sub-keys:

Example:

interface:
  currency:
    code: EUR
    rate: 0.92

presets

Key:

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:

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:

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:

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:

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:

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:

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:

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

agentSelectorLimit

Limits the unsearched Agents panel selector to 10 Agents by default. Set an integer from 1 through 100 to change how many are listed before the user starts typing. Searching still reaches all accessible Agents; the limit is not an access-control setting.

interface:
  agentSelectorLimit: 10

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:

Sub-keys:

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.

skills

Deprecated for permission management. Seeds the SKILLS role permissions at startup for the default USER role only. Prefer the Admin Panel for managing Skills permissions per role/group/user. defaultActiveOnShare is not a permission bit and remains a YAML behavior setting.

Key:

Default: true for use and create, false for share, public, and defaultActiveOnShare.

Sub-keys:

Example:

interface:
  skills:
    use: true
    create: true
    share: false
    public: false
    defaultActiveOnShare: false

For Skills behavior and invocation modes, see Skills.

sharedLinks

Deprecated for permission management. Seeds the SHARED_LINKS role permissions at startup for the default USER role only. Prefer the Admin Panel for managing shared-link permissions per role/group/user.

Key:

Default: create: true, share: true, public: true

Important: Boolean vs Object Configuration

• Boolean (sharedLinks: true): Enables all SHARED_LINKS permissions for the default USER role.
• Boolean (sharedLinks: false): Disables all SHARED_LINKS permissions for the default USER role.
• Object: Updates only the sub-permissions that are explicitly specified. Any permissions not included in the config are preserved from the database.

Sub-keys:

Example:

interface:
  sharedLinks:
    create: true
    share: true
    public: false
    snapshotFiles: true

For user-facing shared-link behavior, see Shareable Links.

schedules

Enables the experimental Scheduled Chats panel and configures its permissions and runtime limits.

Deprecated for permission management. The use and create sub-keys seed the SCHEDULES permissions at startup for the default USER role only. Prefer the Admin Panel for ongoing permission management. The runtime limit fields remain YAML settings.

Key:

Boolean behavior:

• schedules: true opts in with the default runtime limits without changing stored role permissions.
• schedules: false is a deployment-wide stop. It cannot be re-enabled by a role, group, or user configuration override.
• Object form opts in unless use: false is set.

Sub-keys:

interface:
  schedules:
    use: true
    create: true
    maxPerUser: 10
    minIntervalMinutes: 60
    autoDisableAfterFailures: 5
    admissionConcurrency: 20
    fireConcurrency: 5
    mcpPreflightConcurrency: 3
    mcpPreflightTimeoutMs: 300000
    requireProject: false
    # projectId: '000000000000000000000000'

The base YAML is authoritative for the global enable state. Configuration overrides can narrow access and tune inherited limits, but cannot re-enable a base false or { use: false }. SCHEDULES_DISABLED=true is an additional emergency stop for both automatic and manual runs.

requireProject is enforced both when a schedule is written and immediately before each run. A schedule that no longer satisfies the requirement is auto-disabled rather than starting an unscoped conversation. projectId outranks a schedule's stored selection and is resolved as the schedule owner; because projects are user-owned, it is primarily useful in per-role or per-user configuration overrides rather than as one deployment-wide value.

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:

Default: true

Note: The retention period for temporary chats can be configured using temporaryChatRetention. Under retentionMode: "ephemeral" the toggle is shown, locked on, to every user regardless of this setting or the TEMPORARY_CHAT permission.

Example:

interface:
  temporaryChat: true

temporaryChatRetention

The temporaryChatRetention configuration allows you to customize how long temporary chats are retained before being automatically deleted. Under retentionMode: "ephemeral", every chat is temporary, so this value is the lifetime of every chat.

Key:

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)

generalChatRetention

Controls how long regular chats are retained when retentionMode is set to "all". It is ignored by the other modes; under "ephemeral" every chat is temporary and uses temporaryChatRetention.

The value must be between 1 and 8760 hours. This setting lets regular and temporary chats use different lifetimes. Changing either retention value affects deadlines assigned to new or updated records; LibreChat does not rewrite existing stored deadlines automatically.

interface:
  temporaryChatRetention: 168 # 7 days for temporary chats
  generalChatRetention: 2160 # 90 days for regular chats
  retentionMode: 'all'

retentionMode

Controls which data receives retention deadlines, and whether every chat is forced to be temporary.

Key:

Default: temporary

Modes:

• temporary (default): only chats a user marks temporary expire. Normal chats never expire.
• all: every chat and message gets an expiredAt but stays visible and searchable until it expires.
• ephemeral: every chat is forced temporary, hidden from history and search, and the toggle is locked on. Enforcement is server-authoritative.

See the Temporary Chat & Data Retention feature page for the full behavior matrix and migration guidance.

Example:

interface:
  temporaryChatRetention: 168
  generalChatRetention: 2160
  retentionMode: 'all'

To force every chat to be temporary and never persisted long-term:

interface:
  temporaryChatRetention: 24
  retentionMode: 'ephemeral'

retainAgentFiles

Controls whether persistent agent resource files are exempt from all-data retention.

Key:

Default: false

Notes:

• This setting only changes behavior when retentionMode is set to "all" or "ephemeral".
• Set this to true when agents should keep their persistent resource files even while conversations, messages, and non-agent files receive retention deadlines.

Example:

interface:
  temporaryChatRetention: 168
  retentionMode: 'all'
  retainAgentFiles: true

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:

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:

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.

codeHighlightThrottleMs

Controls the minimum interval between syntax-highlighting passes while a code block is changing during a streamed response. Throttling reduces repeated highlighting work without delaying the streamed text itself. The same value applies when rendering shared conversations.

Default: 300 milliseconds

Set the value to 0 to highlight every streamed update. Valid values range from 0 through 60000 milliseconds.

interface:
  codeHighlightThrottleMs: 300

artifactUndocking

Controls whether users can move the Artifacts pane into its own browser window.

Key:

Default: true

Setting it to false hides the button for new undocks. A pane that is already in its own window keeps its Dock back to panel button, so users can always bring it back.

Example:

interface:
  artifactUndocking: false

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:

Default: true

Example:

interface:
  runCode: true

webSearch

Enables/disables the Web Search tool in the composer palette. 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:

Default: true

Example:

interface:
  webSearch: true

fileSearch

Enables/disables the File Search tool (RAG API usage via tool) in the composer palette.

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:

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:

Default: true

Example:

interface:
  fileCitations: true

feedback

Controls whether the thumbs up / thumbs down buttons are shown under responses. When set to false, the buttons are removed from the message action row and the server rejects feedback writes, so a deployment that hides the controls also stores no ratings.

Notes:

• The other message actions (read aloud, copy, edit, fork, and regenerate) are unaffected, and the action row reflows without leaving a gap.
• With feedback disabled, PUT /api/messages/:conversationId/:messageId/feedback responds with 403 and {"error": "Feedback is disabled"} before anything is written to the database or exported.
• Ratings collected while the feature was enabled stay on existing messages. The flag stops new writes, it does not delete stored feedback.
• Ratings are only consumed outside LibreChat when Langfuse tracing is configured, where each one is sent as a user-feedback score. See Message Feedback Scores.
• This is a plain interface flag rather than a role permission, so there is nothing to grant per role in the Admin Panel.

Key:

Default: true

Example:

interface:
  feedback: false

replyNotifications

Controls which unread-reply alerts users are allowed to turn on. When a reply finishes while a user is looking at another chat, LibreChat marks that chat as unread. Users then choose their own alerts in Settings > General > Notifications; these options only decide which of those alerts are offered.

The unread dots in the chat list and the Mark as unread action are always available and are not affected by this setting.

Key:

Sub-keys:

Setting tabBadge, desktop or sound to false hides that option from users' settings. What each user turns on is stored per device. See Settings for the user side.

Example:

interface:
  replyNotifications:
    tabBadge: true
    desktop: true
    sound: false
    pollIntervalMs: 60000

defaultPinnedTools

Seeds the initial prompt-bar pinned tools for users who have not customized their pinned tool state. Once a user pins or unpins a tool, LibreChat preserves that user's choice.

Key:

Supported values:

• Built-in tool keys: artifacts, execute_code, web_search, file_search, skills

The mcp keyword and MCP server names are still accepted for compatibility, but the redesigned composer does not pin MCP servers to the bar. Users turn servers on from the palette's MCP Servers section instead.

Example:

interface:
  defaultPinnedTools:
    - artifacts
    - execute_code

composerRecentFiles

How many recently used files the composer palette requests for its Your files section before the user searches.

Key:

Default: 5

The palette displays at most five of them, so values above 5 have no visible effect; use a lower value to shorten the list, or 0 to hide it. Searching the palette, or Show all, still reaches every file. The value is also capped by the top-level fileListLimit.

interface:
  composerRecentFiles: 10

Queue and steer timeouts

Three timeouts tune how the client handles messages sent while a response is still streaming (queued messages and steers, see Agents). The defaults suit most deployments; raise them when a slow proxy or a lagging database replica makes queued messages show as unconfirmed.

All three must be positive integers.

interface:
  queuedTurnReconciliationTimeoutMs: 120000

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:

Sub-keys:

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:

Sub-keys:

Default:

marketplace:
  use: false

Example:

interface:
  marketplace:
    use: true # Enable marketplace access