LibreChat

https://librechat.ai/docs
Admin
LibreChat is an open-source, self-hostable AI chat interface supporting various AI providers, custom...
Tokens:166,165
Snippets:2,481
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install dependencies

Source: https://www.librechat.ai/docs/local/npm

Perform a clean install and build of all project dependencies.

```bash
npm run reinstall
```

--------------------------------

### Install dependencies and build

Source: https://www.librechat.ai/docs/development/get_started

Install project dependencies and compile the source code.

```sh
npm run smart-reinstall
```

```sh
npm run build
```

--------------------------------

### Install System Dependencies

Source: https://www.librechat.ai/docs/remote/docker_linux

Installs git, nodejs, and npm packages.

```bash
sudo apt install git nodejs npm
```

--------------------------------

### Registration Object Structure Example

Source: https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/registration

A complete example showing the registration configuration block.

```yaml
# Example Registration Object Structure
registration:
  socialLogins: ["google", "facebook", "github", "discord", "openid"]
  allowedDomains:
    - "gmail.com"
    - "protonmail.com"
```

--------------------------------

### MCP Settings Configuration Example

Source: https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/mcp_settings

A complete example showing how to define allowed domains and SSRF exemptions for internal services.

```yaml
mcpSettings:
  # Strict whitelist mode:
  # allowedDomains:
  #   - "example.com"                    # Specific domain
  #   - "*.example.com"                  # All subdomains using wildcard
  #   - "https://api.example.com:8443"   # With protocol and port
  #   - "http://mcp-server:3000"         # Internal service, explicitly whitelisted

  # Default SSRF mode with private service exemptions:
  allowedAddresses:
    - "host.docker.internal:8080"        # Permit one private host on one port
    - "10.0.0.5:8000"                    # Permit one private IP on one port
```

--------------------------------

### Initialize Environment File

Source: https://www.librechat.ai/docs/remote/docker_linux

Copies the example environment file to .env.

```bash
# Copies the example file as your global env file
cp .env.example .env
```

--------------------------------

### Example clientImageResize Configuration

Source: https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/config

A complete example of the clientImageResize object within the fileConfig structure.

```yaml
fileConfig:
  clientImageResize:
    enabled: true
    maxWidth: 1920
    maxHeight: 1080
    quality: 0.8
    compressFormat: 'jpeg'
```

--------------------------------

### Full Speech Configuration Example

Source: https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/speech

A complete example showing both TTS and STT provider configurations and UI settings.

```yaml
speech:
  tts:
    openai:
      apiKey: "${TTS_API_KEY}"
      model: "tts-1"
      voices: ["alloy", "echo", "fable", "onyx", "nova", "shimmer"]
    elevenlabs:
      apiKey: "${ELEVENLABS_API_KEY}"
      model: "eleven_multilingual_v2"
      voices: ["voice-id-1", "voice-id-2"]
  stt:
    openai:
      apiKey: "${STT_API_KEY}"
      model: "whisper-1"
  speechTab:
    conversationMode: true
    advancedMode: false
    speechToText: true
    textToSpeech: true
```

--------------------------------

### Install and Run Azurite via npm

Source: https://www.librechat.ai/docs/configuration/cdn/azure

Installs the Azurite package globally and starts the service with specified paths.

```bash
npm install -g azurite
azurite --silent --location /path/to/azurite/workspace --debug /path/to/debug/log
```

--------------------------------

### Initialize environment configuration

Source: https://www.librechat.ai/docs/local/npm

Create the .env file from the provided example template.

```bash
cp .env.example .env
```

--------------------------------

### URL Query Parameter Examples

Source: https://www.librechat.ai/docs/features/url_query

Examples of constructing URLs with multiple parameters or model specs.

```bash
https://your-domain.com/c/new?endpoint=google&model=gemini-2.0-flash-exp&temperature=0.7&prompt=Oh hi mark
```

```bash
https://your-domain.com/c/new?spec=meeting-notes-gpt4&prompt=Here%20is%20the%20transcript...
```

--------------------------------

### Configure Balance Settings

Source: https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/balance

Full configuration example for the balance object.

```yaml
balance:
  enabled: false
  startBalance: 20000
  autoRefillEnabled: false
  refillIntervalValue: 30
  refillIntervalUnit: "days"
  refillAmount: 10000
```

--------------------------------

### Start and verify Docker service

Source: https://www.librechat.ai/docs/remote/docker_linux

Ensures the Docker daemon is active and verifies the installation status.

```bash
# should already be running, but just to be safe
sudo systemctl start docker

# confirm docker is running
docker info
```

--------------------------------

### Configure and Start ngrok on Windows

Source: https://www.librechat.ai/docs/remote/ngrok

Commands to add the authentication token and start the tunnel for the local LibreChat server.

```bash
ngrok config add-authtoken <your token>
```

```bash
ngrok http 3080
```

--------------------------------

### Manage MongoDB Container Lifecycle

Source: https://www.librechat.ai/docs/configuration/mongodb/mongodb_auth

Commands to start, stop, and interact with the MongoDB container during the authentication setup process.

```bash
docker compose up -d mongodb
```

```bash
docker exec -it chat-mongodb mongosh -u adminUser -p securePassword --authenticationDatabase admin
```

```bash
exit
```

```bash
docker compose down
```

--------------------------------

### actions / allowedDomains Example

Source: https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/actions

A comprehensive example of an allowedDomains configuration including external and internal addresses.

```yaml
allowedDomains:
  - "swapi.dev"
  - "librechat.ai"
  - "google.com"
  - "https://secure-api.example.com:443"
  - "192.168.1.50"  # Internal service (explicitly allowed)
```

--------------------------------

### Banner Configuration Prompt Example

Source: https://www.librechat.ai/docs/configuration/banner

An example of the interactive CLI prompts used to define banner timing, content, and visibility.

```ansi
--------------------------
Update the banner!
--------------------------
Display From (Format: yyyy-mm-ddTHH:MM:SSZ, Default: now):
> 2025-12-02T09:00:00Z

Display To (Format: yyyy-mm-ddTHH:MM:SSZ, Default: not specified):
> 2025-12-31T23:59:59Z

Enter your message (Enter a single dot "." on a new line to finish):
> 🎉 Welcome to LibreChat! Check out our new features.
> .

Is public (y/N):
> n

Is persistable (cannot be dismissed) (y/N):
> n
```

--------------------------------

### Example Multi-Region Object Paths

Source: https://www.librechat.ai/docs/configuration/cdn/cloudfront

Examples of how object keys are structured when includeRegionInPath is enabled.

```text
/i/r/us-east-2/t/tenantId/images/userId/file.png
/a/r/us-east-2/t/tenantId/avatars/userId/avatar.png
/r/us-east-2/t/tenantId/images/userId/file.pdf
```

--------------------------------

### Create and Initialize Configuration File

Source: https://www.librechat.ai/docs/configuration/librechat_yaml

Commands to create a new configuration file or initialize it from an existing example.

```bash
touch librechat.yaml
```

```bash
cp librechat.example.yaml librechat.yaml
```

--------------------------------

### Install Docker Dependencies

Source: https://www.librechat.ai/docs/remote/docker_linux

Installs the necessary prerequisite packages for Docker.

```bash
sudo apt install apt-transport-https ca-certificates curl software-properties-common gnupg lsb-release
```

--------------------------------

### Web Search Configuration Example

Source: https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/web_search

A YAML configuration example demonstrating how to set up the webSearch block with Firecrawl API keys and various scraping options.

```yaml
webSearch:
  firecrawlApiKey: "${FIRECRAWL_API_KEY}"
  firecrawlOptions:
    formats: ["markdown", "rawHtml"]
    includeTags: ["main", "article", ".content"]
    excludeTags: ["nav", "footer", ".ads"]
    waitFor: 2000
    timeout: 10000
    mobile: false
    blockAds: true
    onlyMainContent: true
    location:
      country: "US"
      languages: ["en"]
```

--------------------------------

### Run Admin Panel Locally for Development

Source: https://www.librechat.ai/docs/features/admin_panel

Clone the repository and start the development server using Bun.

```bash
git clone https://github.com/ClickHouse/librechat-admin-panel.git
cd librechat-admin-panel
cp .env.example .env    # then edit
bun install
bun dev                 # http://localhost:3000
```

--------------------------------

### Initialize Docker Override File

Source: https://www.librechat.ai/docs/configuration/docker_override

Create the override file by copying the provided example template.

```bash
cp docker-compose.override.yml.example docker-compose.override.yml
```

--------------------------------

### Configure and Start ngrok on Mac

Source: https://www.librechat.ai/docs/remote/ngrok

Commands to set the authentication token and start the ngrok tunnel from the extracted directory.

```bash
ngrok authtoken <your token>
```

```bash
./ngrok http 3080
```

--------------------------------

### CloudFront Configuration Example

Source: https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/cloudfront

A complete example of the cloudfront object within the librechat.yaml file structure.

```yaml
fileStrategies:
  avatar: 'cloudfront'
  image: 'cloudfront'
  document: 's3'

cloudfront:
  domain: 'https://cdn.example.com'
  distributionId: 'E1234ABCD'
  invalidateOnDelete: false
  imageSigning: 'cookies'
  cookieDomain: '.example.com'
  cookieExpiry: 1800
  urlExpiry: 3600
  storageRegion: 'us-east-2'
  includeRegionInPath: false
  requireSignedAccess: true
```

--------------------------------

### Traversaal Example Prompts

Source: https://www.librechat.ai/docs/configuration/tools/traversaal

Sample queries for the Traversaal search tool.

```text
Find recent reporting about open source AI coding agents.
Search for sources comparing renewable energy adoption in Europe and North America.
```

--------------------------------

### Install OWASP CRS on Ubuntu

Source: https://www.librechat.ai/docs/remote/nginx

Install the ModSecurity Core Rule Set package via apt.

```bash
sudo apt-get install nginx-modsecurity-crs
```

--------------------------------

### Start LibreChat backend

Source: https://www.librechat.ai/docs/configuration/meilisearch

Launch the LibreChat backend process.

```bash
npm run backend
```

--------------------------------

### Install Helm Chart

Source: https://www.librechat.ai/docs/local/helm_chart

Commands to install the LibreChat Helm chart from the OCI registry or local directory.

```bash
helm install <deployment-name> oci://ghcr.io/danny-avila/librechat-chart/librechat
```

```bash
helm install <deployment-name> ./helm/librechat
```

```bash
helm install librechat oci://ghcr.io/danny-avila/librechat-chart/librechat --values <values-override-filel>
```

--------------------------------

### Install Docker Compose Plugin

Source: https://www.librechat.ai/docs/remote/docker_linux

Installs the official Docker Compose plugin on Linux systems.

```bash
sudo apt install docker-compose-plugin
```

--------------------------------

### Create API environment file

Source: https://www.librechat.ai/docs/development/testing

Initializes the required environment configuration for the API workspace by copying the example file.

```bash
cp .env.example ./api/.env
```

--------------------------------

### Importing Tool Modules

Source: https://www.librechat.ai/docs/development/tools_and_plugins

Initial setup for creating a custom tool by importing the base Tool class.

```javascript
const { Tool } = require('langchain/tools')
// ... whatever else you need
```

--------------------------------

### Start Meilisearch binary

Source: https://www.librechat.ai/docs/configuration/meilisearch

Run the Meilisearch process with a specified master key.

```bash
./meilisearch --master-key=<your_master_key>
```

--------------------------------

### Example OpenWeather Prompts

Source: https://www.librechat.ai/docs/configuration/tools/openweather

Sample natural language queries for interacting with the OpenWeather tool.

```text
What's the current weather in London?
What was the weather like in Paris on 2023-01-01?
Give me a weather summary for Tokyo.
What's the temperature in New York in Fahrenheit?
```

--------------------------------

### Run Azurite with Docker

Source: https://www.librechat.ai/docs/configuration/cdn/azure

Starts the Azurite storage emulator container for local development.

```bash
docker run -p 10000:10000 -p 10001:10001 -p 10002:10002 mcr.microsoft.com/azure-storage/azurite
```

--------------------------------

### GET /c/new

Source: https://www.librechat.ai/docs/features/url_query

Initializes a new chat session using various query parameters to pre-configure the environment.

```APIDOC
## GET /c/new

### Description
Initializes a new chat session. Query parameters allow for pre-filling the prompt or loading specific configurations like model specs, agents, or assistants.

### Method
GET

### Endpoint
/c/new

### Parameters
#### Query Parameters
- **prompt** (string) - Optional - The initial text prompt for the chat. Must be URL-encoded.
- **spec** (string) - Optional - The name of a model spec to load. Overrides other model parameters.
- **agent_id** (string) - Optional - The ID of an agent to load.
- **assistant_id** (string) - Optional - The ID of an assistant to load.
```

--------------------------------

### Start MongoDB with Configuration File

Source: https://www.librechat.ai/docs/configuration/mongodb/mongodb_community

Command to launch the MongoDB daemon using a specific configuration file.

```yaml
./mongod --config /path/to/mongodb/config/mongodb.conf
```

--------------------------------

### Verify Dependency Versions

Source: https://www.librechat.ai/docs/remote/docker_linux

Confirms successful installation of git, node, and npm.

```bash
git --version
node -v
npm -v
```

--------------------------------

### Configure MCP Server Instructions

Source: https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/mcp_servers

Examples of enabling, customizing, or disabling server instructions for agent context injection.

```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
```

--------------------------------

### Enable Marketplace Access

Source: https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/interface.mdx

Example of how to enable access to the Agent Marketplace by setting 'use' to true.

```yaml
interface:
  marketplace:
    use: true # Enable marketplace access
```

--------------------------------

### Combined Bedrock configuration

Source: https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/aws_bedrock

Example showing both custom models and their associated inference profiles configured together.

```yaml
endpoints:
  bedrock:
    models:
      - 'us.anthropic.claude-sonnet-4-20250514-v1:0'
      - 'us.anthropic.claude-haiku-4-20250514-v1:0'
    inferenceProfiles:
      'us.anthropic.claude-sonnet-4-20250514-v1:0': '${BEDROCK_CLAUDE_SONNET_PROFILE}'
      'us.anthropic.claude-haiku-4-20250514-v1:0': '${BEDROCK_CLAUDE_HAIKU_PROFILE}'
```

--------------------------------

### Set Initial Balance

Source: https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/balance

Define the starting token count for new users.

```yaml
balance:
  startBalance: 20000
```

--------------------------------

### Verify Successful Connection

Source: https://www.librechat.ai/docs/configuration/mongodb/mongodb_auth

Example log output indicating a successful connection to the database.

```bash
LibreChat         | 2024-02-04 20:59:43 info: Server listening on all interfaces at port 3080. Use http://localhost:3080 to access it
chat-mongodb      | {"t":{"$date":"2024-02-04T20:59:53.880+00:00"},"s":"I",  "c":"NETWORK",  "id":22943,   "ctx":"listener","msg":"Connection accepted","attr":{"remote":"192.168.160.4:58114","uuid":{"uuid":{"$uuid":"027bdc7b-a3f4-429a-80ee-36cd172058ec"}},"connectionId":17,"connectionCount":10}}
```

--------------------------------

### Configure Chat via URL

Source: https://www.librechat.ai/docs/features/url_query

Examples of initializing new or existing conversations using endpoint and model parameters.

```bash
https://your-domain.com/c/new?endpoint=ollama&model=llama3%3Alatest
https://your-domain.com/c/03debefd-6a50-438a-904d-1a806f82aad4?endpoint=openAI&model=o1-mini
```

--------------------------------

### Start the MongoDB Server

Source: https://www.librechat.ai/docs/configuration/mongodb/mongodb_community

Command to launch the MongoDB daemon with a specified data directory path.

```sh
./mongod --dbpath=/path/to/data/directory
```

--------------------------------

### Add API Key to Environment

Source: https://www.librechat.ai/docs/remote/docker_linux

Example of adding an OpenAI API key to the .env file.

```bash
OPENAI_API_KEY=sk-yourKey
```

--------------------------------

### Agent File Citation Configurations

Source: https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/agents

Examples of balanced, strict, and comprehensive configurations for file citations.

```yaml
endpoints:
  agents:
    maxCitations: 30
    maxCitationsPerFile: 7
    minRelevanceScore: 0.45
```

```yaml
endpoints:
  agents:
    maxCitations: 10
    maxCitationsPerFile: 3
    minRelevanceScore: 0.7
```

```yaml
endpoints:
  agents:
    maxCitations: 50
    maxCitationsPerFile: 10
    minRelevanceScore: 0.0
```

--------------------------------

### Define Custom Endpoints in librechat.yaml

Source: https://www.librechat.ai/docs/quick_start/custom_endpoints

Example configuration for OpenRouter, Ollama, and an Anthropic-compatible gateway. Ensure the version matches your current LibreChat installation.

```yaml
version: 1.3.13
cache: true
endpoints:
  custom:
    - name: 'OpenRouter'
      apiKey: '${OPENROUTER_KEY}'
      baseURL: 'https://openrouter.ai/api/v1'
      models:
        default: ['meta-llama/llama-3-70b-instruct']
        fetch: true
      titleConvo: true
      titleModel: 'meta-llama/llama-3-70b-instruct'
      dropParams: ['stop']
      modelDisplayLabel: 'OpenRouter'
    - name: 'Ollama'
      apiKey: 'ollama'
      baseURL: 'http://host.docker.internal:11434/v1/'
      models:
        default: ['llama3:latest', 'command-r', 'mixtral', 'phi3']
        fetch: true
      titleConvo: true
      titleModel: 'current_model'
    - name: 'Claude-Compatible'
      provider: 'anthropic'
      apiKey: '${ANTHROPIC_API_KEY}'
      baseURL: 'https://api.anthropic.com'
      headers:
        anthropic-version: '2023-06-01'
      models:
        default: ['claude-sonnet-4-5']
        fetch: false
      titleConvo: true
      titleModel: 'claude-sonnet-4-5'
```

--------------------------------

### Install Docker CE

Source: https://www.librechat.ai/docs/remote/docker_linux

Installs the official Docker Community Edition package.

```bash
sudo apt install docker-ce
```

--------------------------------

### Install Certbot for Nginx

Source: https://www.librechat.ai/docs/remote/nginx

Install the Certbot Nginx plugin for Ubuntu or CentOS.

```bash
sudo apt-get install certbot python3-certbot-nginx
```

```bash
sudo yum install certbot python2-certbot-nginx
```

--------------------------------

### Verify Docker Compose Installation

Source: https://www.librechat.ai/docs/remote/docker_linux

Checks the installed version of the Docker Compose plugin.

```bash
docker compose version
```

--------------------------------

### Shared Endpoint Configuration Example

Source: https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/shared_endpoint_settings

Demonstrates how to define individual endpoint settings and use the 'all' key for global configuration overrides.

```yaml
endpoints:
  # Individual endpoint configurations
  openAI:
    streamRate: 25
    titleModel: 'gpt-4o-mini'
    titleMethod: 'completion'
    titleTiming: 'immediate'
    titlePrompt: "Create a concise title for this conversation:\n\n{convo}"
    headers:
      X-Gateway-Metadata: '{"user_email":"{{LIBRECHAT_USER_EMAIL}}"}'

  azureOpenAI:
    streamRate: 35
    titleModel: 'grok-3'
    titleMethod: 'structured'
    titlePrompt: |
      Analyze this conversation and provide:
      1. A concise title in the detected language (5 words or less, no punctuation or quotation)
      2. Always provide a relevant emoji at the start of the title

      {convo}
    titleConvo: true

  anthropic:
    streamRate: 25
    titleModel: 'claude-3-5-haiku-20241022'
    titleMethod: 'completion'
    headers:
      X-Conversation-Id: '{{LIBRECHAT_BODY_CONVERSATIONID}}'

  bedrock:
    streamRate: 25
    titleModel: 'us.amazon.nova-lite-v1:0'
    titleEndpoint: 'anthropic'

  google:
    streamRate: 1
    titleModel: 'gemini-2.0-flash-lite'
    titlePromptTemplate: "Human: {input}\nAssistant: {output}"
    headers:
      X-Gateway-Metadata: '{"user_id":"{{LIBRECHAT_USER_ID}}"}'

  assistants:
    streamRate: 30

  azureAssistants:
    streamRate: 30

  # Global configuration using 'all' - this applies shared settings across endpoints.
  # Most defined values override endpoint defaults; headers are merged and endpoint values win on collisions.
  all:
    headers:
      X-App: 'librechat'
    titleConvo: true
    titleModel: 'gpt-4.1-nano'
    titleTiming: 'immediate'
    titlePrompt: |
      Analyze this conversation and provide:
      1. The detected language of the conversation
      2. A concise title in the detected language (5 words or less, no punctuation or quotation)
      3. Always provide a relevant emoji at the start of the title
      {convo}
```

--------------------------------

### MCP Settings Configuration Example

Source: https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/config

Demonstrates how to configure allowedDomains for strict whitelisting or allowedAddresses for specific private service exemptions.

```yaml
mcpSettings:
  # Strict whitelist mode:
  # allowedDomains:
  #   - "example.com"           # Specific domain
  #   - "*.example.com"         # All subdomains
  #   - "http://mcp-server:3000" # Internal service, explicitly whitelisted

  # Default SSRF mode with private service exemptions:
  allowedAddresses:
    - 'host.docker.internal:8080' # Permit one private host on one port
    - '10.0.0.5:8000' # Permit one private IP on one port
```

--------------------------------

### Start Docker Container

Source: https://www.librechat.ai/docs/remote/docker_linux

Starts the LibreChat Docker container in detached mode or foreground.

```bash
npm run start:deployed
```

```bash
docker compose -f ./deploy-compose.yml up
```

--------------------------------

### Complete Memory Configuration

Source: https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/memory

A comprehensive example demonstrating all available memory configuration options including valid keys, limits, and agent settings.

```yaml
version: 1.3.10
cache: true

memory:
  disabled: false
  validKeys:
    - 'user_preferences'
    - 'conversation_context'
    - 'learned_facts'
    - 'personal_information'
  tokenLimit: 3000
  charLimit: 10000
  maxInputTokens: 12000
  personalize: true
  messageWindowSize: 8
  agent:
    provider: 'openAI'
    model: 'gpt-4'
    instructions: |
      Store memory using only the specified validKeys. For user_preferences: save 
      explicitly stated preferences about communication style, topics of interest, 
      or workflow preferences. For conversation_context: save important facts or 
      ongoing projects mentioned. For learned_facts: save objective information 
      about the user. For personal_information: save only what the user explicitly 
      shares about themselves. Delete outdated or incorrect information promptly.
    model_parameters:
      temperature: 0.2
      max_tokens: 2000
      top_p: 0.8
      frequency_penalty: 0.1
```

--------------------------------

### Configure Token Balance Settings

Source: https://www.librechat.ai/docs/configuration/dotenv

Enable balance checking and define the initial balance for new users.

```bash
CHECK_BALANCE=false
```

```bash
START_BALANCE=20000
```

--------------------------------

### AWS Bedrock Application Inference Profile ARN Example

Source: https://www.librechat.ai/docs/configuration/pre_configured_ai/bedrock_inference_profiles

Example of the unique ARN format generated by AWS for a custom application inference profile.

```text
arn:aws:bedrock:us-east-1:123456789012:application-inference-profile/abc123def456
```

--------------------------------

### Configure MCP Server with Instructions

Source: https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/mcp_servers

Demonstrates enabling, disabling, or providing custom server instructions for MCP servers.

```yaml
# Server that uses its own provided instructions
web-search:
  type: streamable-http
  url: https://example.com/mcp/search
  serverInstructions: true

# Server with instructions explicitly disabled
filesystem:
  command: npx
  args:
    - -y
    - '@modelcontextprotocol/server-filesystem'
    - /home/user/documents/
  serverInstructions: false

# Server with custom instructions
puppeteer:
  type: stdio
  command: npx
  args:
    - -y
    - '@modelcontextprotocol/server-puppeteer'
  serverInstructions: |
    Browser automation security and best practices:
    1. Be cautious with local file access and internal IP addresses
    2. Take screenshots to verify successful page interactions
    3. Wait for page elements to load before interacting with them
    4. Use specific CSS selectors for reliable element targeting
    5. Check console logs for JavaScript errors when troubleshooting
```

--------------------------------

### AWS Bedrock Guardrail Configuration Example

Source: https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/aws_bedrock

Example YAML configuration for applying a specific AWS Bedrock guardrail with tracing and sync processing enabled.

```yaml
endpoints:
  bedrock:
    guardrailConfig:
      guardrailIdentifier: 'abc123xyz'
      guardrailVersion: '1'
      trace: 'enabled'
      streamProcessingMode: 'sync'
```

--------------------------------

### Configure AI Providers in librechat.yaml

Source: https://www.librechat.ai/docs/configuration/librechat_yaml/example

Examples for setting up Groq, Mistral AI, and OpenRouter endpoints. Ensure API keys are managed via environment variables.

```yaml
# Groq Example
    - name: 'groq'
      apiKey: '${GROQ_API_KEY}'
      baseURL: 'https://api.groq.com/openai/v1/'
      models:
        default:
          [
            'llama3-70b-8192',
            'llama3-8b-8192',
            'llama2-70b-4096',
            'mixtral-8x7b-32768',
            'gemma-7b-it',
          ]
        fetch: false
      titleConvo: true
      titleModel: 'mixtral-8x7b-32768'
      modelDisplayLabel: 'groq'
```

```yaml
# Mistral AI Example
    - name: 'Mistral' # Unique name for the endpoint
      # For `apiKey` and `baseURL`, you can use environment variables that you define.
      # recommended environment variables:
      apiKey: '${MISTRAL_API_KEY}'
      baseURL: 'https://api.mistral.ai/v1'

      # Models configuration
      models:
        # List of default models to use. At least one value is required.
        default: ['mistral-tiny', 'mistral-small', 'mistral-medium']
        # Fetch option: Set to true to fetch models from API.
        fetch: true # Defaults to false.

      # Optional configurations

      # Title Conversation setting
      titleConvo: true # Set to true to enable title conversation
      # titleTiming: "immediate" # Generate titles immediately, or use "final" for legacy behavior

      # Title Method: Choose between "completion" or "functions".
      # titleMethod: "completion"  # Defaults to "completion" if omitted.

      # Title Model: Specify the model to use for titles.
      titleModel: 'mistral-tiny' # Defaults to "gpt-3.5-turbo" if omitted.

      # Summarize setting: Set to true to enable summarization.
      # summarize: false

      # Summary Model: Specify the model to use if summarization is enabled.
      # summaryModel: "mistral-tiny"  # Defaults to "gpt-3.5-turbo" if omitted.

      # The label displayed for the AI model in messages.
      modelDisplayLabel: 'Mistral' # Default is "AI" when not set.

      # Add additional parameters to the request. Default params will be overwritten.
      # addParams:
      # safe_prompt: true # This field is specific to Mistral AI: https://docs.mistral.ai/api/

      # Custom endpoint behavior flags, not sent directly as provider params.
      # customParams:
      #   reasoningFormat: reasoning_object # reasoning_effort, reasoning_object, or disabled
      #   reasoningKey: reasoning_content # reasoning or reasoning_content

      # Optional per-model context window and pricing for usage/cost tracking
      # tokenConfig:
      #   mistral-large-latest:
      #     prompt: 2
      #     completion: 6
      #     context: 128000

      # Drop Default params parameters from the request. See default params in guide linked below.
      # NOTE: For Mistral, it is necessary to drop the following parameters or you will encounter a 422 Error:
      dropParams: ['stop', 'user', 'frequency_penalty', 'presence_penalty']
```

```yaml
# OpenRouter Example
    - name: 'OpenRouter'
      # For `apiKey` and `baseURL`, you can use environment variables that you define.
      # recommended environment variables:
      # Known issue: you should not use `OPENROUTER_API_KEY` as it will then override the `openAI` endpoint to use OpenRouter as well.
      apiKey: '${OPENROUTER_KEY}'
      baseURL: 'https://openrouter.ai/api/v1'
      models:
        default: ['meta-llama/llama-3-70b-instruct']
        fetch: true
      titleConvo: true
      titleModel: 'meta-llama/llama-3-70b-instruct'
      # Recommended: Drop the stop parameter from the request as Openrouter models use a variety of stop tokens.
      dropParams: ['stop']
      modelDisplayLabel: 'OpenRouter'
```

--------------------------------

### Configure TrueFoundry Environment Variables

Source: https://www.librechat.ai/docs/configuration/librechat_yaml/ai_endpoints/truefoundry

Add your TrueFoundry API key and gateway URL to the .env file for authentication.

```bash
TRUEFOUNDRY_API_KEY=your-api-key
TRUEFOUNDRY_GATEWAY_URL=your-gateway-url
```

--------------------------------

### Build Project from Root

Source: https://www.librechat.ai/docs/development/conventions

Compiles the entire project from the root directory.

```bash
npm run build
```

--------------------------------

### GET /api/agents/v1/models

Source: https://www.librechat.ai/docs/features/agents_api

Retrieves a list of available agents that can be used as models.

```APIDOC
## GET /api/agents/v1/models

### Description
Returns available agents as models. Useful for discovering which agents are accessible with your API key.

### Method
GET

### Endpoint
/api/agents/v1/models
```

--------------------------------

### Disable Transaction Recording

Source: https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/transactions

Example of disabling transaction recording in the configuration file.

```yaml
transactions:
  enabled: false
```

--------------------------------

### CloudFront Field Definitions

Source: https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/cloudfront

Individual field configuration examples for the cloudfront object.

```yaml
domain: "https://cdn.example.com"
```

```yaml
distributionId: "E1234ABCD"
```

```yaml
invalidateOnDelete: false
```

```yaml
imageSigning: "cookies"
```

```yaml
urlExpiry: 3600
```

```yaml
cookieExpiry: 1800
```

```yaml
cookieDomain: ".example.com"
```

```yaml
storageRegion: "us-east-2"
```

```yaml
includeRegionInPath: false
```

```yaml
requireSignedAccess: true
```

--------------------------------

### Example Banner Commands

Source: https://www.librechat.ai/docs/configuration/banner

Pre-configured commands for common banner scenarios including welcome messages, maintenance, and security alerts.

```bash
npm run update-banner "" "" "👋 Welcome to LibreChat!" "false" "false"
```

```bash
npm run update-banner "2025-12-20T00:00:00Z" "2025-12-21T06:00:00Z" "⚠️ Scheduled maintenance on Dec 20th, 2-6 AM UTC" "true" "true"
```

```bash
npm run update-banner "" "" "🔒 Please update your password by January 1st" "true" "true"
```

--------------------------------

### Update Package List

Source: https://www.librechat.ai/docs/remote/docker_linux

Updates the local package index before installing new software.

```bash
sudo apt update
```

--------------------------------

### Disable File Uploads for an Endpoint

Source: https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/file_config

Example of disabling file uploads for the OpenAI endpoint.

```yaml
openAI:
  disabled: true
```

--------------------------------

### Define MCP Servers in YAML

Source: https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/mcp_servers

Example configuration demonstrating various MCP server types, authentication methods, and custom user variables.

```yaml
mcpServers:
  everything:
    # type: sse # type can optionally be omitted
    url: http://localhost:3001/sse
  googlesheets:
    type: sse
    url: https://mcp.composio.dev/googlesheets/some-endpoint
    requiresOAuth: true
    headers:
      X-User-ID: '{{LIBRECHAT_USER_ID}}'
      X-API-Key: '${SOME_API_KEY}'
    serverInstructions: true # Use server-provided instructions
  puppeteer:
    type: stdio
    command: npx
    args:
      - -y
      - '@modelcontextprotocol/server-puppeteer'
    serverInstructions: 'Do not access any local files or local/internal IP addresses'
  filesystem:
    # type: stdio
    command: npx
    args:
      - -y
      - '@modelcontextprotocol/server-filesystem'
      - /home/user/LibreChat/
    iconPath: /home/user/LibreChat/client/public/assets/logo.svg
    # The “wrench” icon shows up if no icon is provided as it is the default rendering.
  mcp-obsidian:
    command: npx
    args:
      - -y
      - 'mcp-obsidian'
      - /path/to/obsidian/vault
  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/'
    headers:
      X-Auth-Token: '{{MY_SERVICE_API_KEY}}'
    customUserVars:
      MY_SERVICE_API_KEY:
        title: 'My Service API Key'
        description: "Enter your personal API key for the service. You can generate one at <a href='https://myservice.example.com/developer/keys' target='_blank'>Service Developer Portal</a>."
        sensitive: true
      MY_SERVICE_PROJECT:
        title: 'Project ID'
        description: 'Enter the project ID used by this service.'
        sensitive: false
  oauth-example:
    type: streamable-http
    url: https://api.example.com/mcp/
    oauth:
      authorization_url: https://example.com/oauth/authorize
      token_url: https://example.com/oauth/token
      client_id: your_client_id
      client_secret: your_client_secret
      redirect_uri: http://localhost:3080/api/mcp/oauth-example/oauth/callback
      scope: 'read execute'
  obo-example:
    type: streamable-http
    url: https://api.example.com/mcp/
    obo:
      scopes: 'api://mcp-server-id/Mcp.Tools.ReadWrite'
```

--------------------------------

### Default Parameters Structure

Source: https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/default_params

Example of the default parameter structure sent to the OpenAI API.

```yaml
{
  "model": "your-selected-model",
  "user": "LibreChat_User_ID",
  "stream": true,
  "messages": [
    {
      "role": "user",
      "content": "hi how are you",
    },
  ],
}
```

--------------------------------

### Verify Service Account Credentials

Source: https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/anthropic_vertex

Use these commands to activate and list your service account to ensure the key file is correctly configured.

```bash
gcloud auth activate-service-account --key-file=/path/to/key.json
gcloud auth list
```

--------------------------------

### Example PEM Certificate File Content

Source: https://www.librechat.ai/docs/configuration/authentication/SAML

The expected structure of the PEM certificate file.

```text
-----BEGIN CERTIFICATE-----
MIIDazCCAlOgAwIBAgIUKhXaFJGJJPx466rl...
-----END CERTIFICATE-----
```

--------------------------------

### Startup Configuration

Source: https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/mcp_servers

Controls whether the server connects at application startup.

```yaml
startup: false
```

--------------------------------

### Start ngrok tunnel

Source: https://www.librechat.ai/docs/configuration/authentication/OAuth2-OIDC/auth0

Use ngrok to create an HTTPS tunnel for local development.

```bash
ngrok http 3080
# This will give you a URL like: https://abc123.ngrok.io
```

--------------------------------

### Configure npm environment variables

Source: https://www.librechat.ai/docs/configuration/meilisearch

Add search configuration to the .env file for source installations.

```bash
SEARCH=true
MEILI_NO_ANALYTICS=true
MEILI_HOST=http://localhost:7700
MEILI_MASTER_KEY=<your_master_key>
```

--------------------------------

### Create or Update a Banner

Source: https://www.librechat.ai/docs/configuration/banner

Run this command to initiate the interactive prompt for configuring a new or existing banner.

```bash
npm run update-banner
```

--------------------------------

### MongoDB Setup Commands

Source: https://www.librechat.ai/docs/configuration/mongodb/mongodb_auth

A sequence of terminal commands to initialize, secure, and configure MongoDB users within a Docker container.

```bash
docker compose down
```

```bash
docker compose up -d mongodb
```

```bash
docker exec -it chat-mongodb mongosh
```

```bash
use admin
```

```bash
db.createUser({ user: "adminUser", pwd: "securePassword", roles: ["userAdminAnyDatabase", "readWriteAnyDatabase"] })
```

```bash
exit
```

```bash
docker compose down
```

```bash
docker compose up -d mongodb
```

```bash
docker exec -it chat-mongodb mongosh -u adminUser -p securePassword --authenticationDatabase admin
```

```bash
use LibreChat
```

```bash
db.createUser({ user: 'user', pwd: 'userpasswd', roles: [ { role: "readWrite", db: "LibreChat" } ] });
```

```bash
exit
```

```bash
docker compose down
```

```bash
docker compose up
```

--------------------------------

### URL Encoding Example

Source: https://www.librechat.ai/docs/features/url_query

Demonstrates the transformation of a string containing special characters into a URL-encoded format.

```ts
Original: `Write a function: def hello()`
Encoded: `/c/new?prompt=Write%20a%20function%3A%20def%20hello()`
```

--------------------------------

### Test Calculator Tool Prompt

Source: https://www.librechat.ai/docs/configuration/tools/calculator

Example prompt to trigger the calculator tool for an arithmetic operation.

```text
Calculate 12345 * 6789 and show the result.
```

--------------------------------

### Docker Compose Override Configuration

Source: https://www.librechat.ai/docs/configuration/mongodb/mongodb_auth

Example configuration for enabling MongoDB authentication and integrating mongo-express.

```yaml
version: '3.4'

services:
  api:
    volumes:
      - ./librechat.yaml:/app/librechat.yaml
    environment:
      - MONGO_URI=mongodb://user:userpasswd@mongodb:27017/LibreChat
  mongodb:
    command: mongod --auth
  mongo-express:
    image: mongo-express
    container_name: mongo-express
    environment:
      ME_CONFIG_MONGODB_SERVER: mongodb
      ME_CONFIG_BASICAUTH_USERNAME: admin
      ME_CONFIG_BASICAUTH_PASSWORD: password
      ME_CONFIG_MONGODB_URL: 'mongodb://adminUser:securePassword@mongodb:27017'
      ME_CONFIG_MONGODB_ADMINUSERNAME: adminUser
      ME_CONFIG_MONGODB_ADMINPASSWORD: securePassword
    ports:
      - '8081:8081'
    depends_on:
      - mongodb
    restart: always
```
Tokens:
Raw