mirror of
https://github.com/LibreChat-AI/librechat.ai.git
synced 2026-03-27 02:38:32 +07:00
docs: rewrite high-traffic pages as actionable step-by-step guides (#530)
* docs(config): rewrite overview with FileTree and restart guide - Replace vague marketing copy with actionable config guide - Add FileTree showing 4 config files (.env, librechat.yaml, docker-compose.yml, docker-compose.override.yml) - Add file descriptions explaining what each config file controls - Add restart Callout with Docker/Local tabs - Add next-step Cards linking to librechat.yaml setup, Docker setup, .env reference * docs(config): restructure librechat.yaml with guide-first setup steps - Replace feature list with 4-step setup procedure using Steps component - Add Docker/Local Tabs for deployment-specific commands - Add OpenRouter worked example with OPENROUTER_KEY warning - Add Reference section with Cards linking to ai_endpoints and object_structure - Merge troubleshooting content from setup.mdx into index page - Remove outdated model menu screenshots * refactor(config): merge setup.mdx into librechat.yaml and add redirect - Delete setup.mdx (content merged into index.mdx) - Remove setup from meta.json pages array - Update ai_endpoints link from /setup to /librechat_yaml - Add redirect for old /setup URL in next.config.mjs * docs(endpoints): rewrite OpenRouter as end-to-end setup guide - Replace bare YAML snippet with 5-step Steps component guide - Add OPENROUTER_KEY vs OPENROUTER_API_KEY warning callout - Add Docker/Local restart Tabs and verification step - Add customization section and reference Cards - Remove deprecated GitHub screenshot image * docs(setup): rewrite Docker install with first-login flow and troubleshooting - Add Steps-based installation with clone, env, start, and verify steps - Document first account = admin behavior at localhost:3080 - Add librechat.yaml volume mounting section with override file pattern - Add troubleshooting for port conflicts, container crashes, missing env vars - Replace deprecated Additional Links with Cards component for next steps - Cross-link to librechat.yaml guide, Docker override guide, and .env reference * docs(endpoints): add file context and activation steps to custom endpoints - Add 'Which File Does What' callout explaining librechat.yaml, .env, and docker-compose.override.yml roles - Rewrite Step 4 as 'Restart and Verify' with Docker/Local Tabs - Add troubleshooting callout for missing endpoints - Replace deprecated AdditionalLinks with Cards for next steps - Link to Configuration Overview for file relationship context * docs(endpoints): fix OpenRouter Step tag indentation * fix(docs): replace empty user guides hub with Cards and remove stale screenshot - Rewrite user_guides/index.mdx as Cards hub with Guides and Popular Features sections - Add cross-links to Agents, Image Gen, Web Search, and MCP feature pages - Remove stale screenshot from LiteLLM page (110412045 asset) - Verify auth section Next button works (SAML/auth0 -> pre_configured_ai) - Verify S3 page has all required sections (no changes needed) * docs(features): add Quick Start guide and cross-links to image generation * docs(tools): rewrite Google Search with agent-first Steps and cross-links * chore: update .gitignore * fix: make Docker/Local tabs switch content when clicked The TabCompat wrapper was rendering <Tabs.Tab> as plain <div> elements, which never registered with fumadocs' internal tab context. Clicking tab triggers had no effect because the content panels didn't respond to state changes. Fix: assign the real fumadocs Tab component as TabsCompat.Tab via Object.assign, so <Tabs.Tab> in MDX renders the real Tab that registers with the parent Tabs context. Keep standalone <Tab> (from auto-generated code blocks with filename=) as a plain div fallback to avoid crashes when there is no parent Tabs context.
This commit is contained in:
Marco Beretta
3
.gitignore
vendored
3
.gitignore
vendored
@@ -26,6 +26,7 @@ yarn.lock
|
||||
# Testing & debugging artifacts
|
||||
playwright.config.ts
|
||||
test-results/
|
||||
playwright-report/
|
||||
tests/
|
||||
sidebar-final-audit/
|
||||
|
||||
@@ -65,4 +66,4 @@ coordination/orchestration/*
|
||||
claude-flow
|
||||
# Removed Windows wrapper files per user request
|
||||
hive-mind-prompt-*.txt
|
||||
e2e/
|
||||
e2e/.planning/
|
||||
|
||||
@@ -1,17 +1,67 @@
|
||||
---
|
||||
title: Overview
|
||||
icon: BookOpen
|
||||
description: Consult our advanced configuration guides for LibreChat
|
||||
description: How LibreChat's configuration files work together and how to apply changes
|
||||
---
|
||||
|
||||
Whether you are setting up a basic AI chat application or scaling an enterprise solution, these guides provide step-by-step instructions and in-depth details on every aspect of LibreChat.
|
||||
LibreChat uses four main configuration files. Each controls a different aspect of the application -- from environment variables to custom AI endpoints to Docker service overrides.
|
||||
|
||||
In this documentation, you will discover how to deploy LibreChat using Docker for a seamless and scalable installation, configure endpoints, and integrate social logins to enhance user accessibility and engagement.
|
||||
## Configuration Files
|
||||
|
||||
We also cover the essentials of setting up the LibreChat config file, which is the heart of customizing your AI chat solution to fit your operational needs. The moderation system configuration will ensure you maintain a safe and productive environment for your users.
|
||||
<FileTree>
|
||||
<FileTree.Folder name="LibreChat (project root)" defaultOpen>
|
||||
<FileTree.File name=".env" active />
|
||||
<FileTree.File name="librechat.yaml" active />
|
||||
<FileTree.File name="docker-compose.yml" />
|
||||
<FileTree.File name="docker-compose.override.yml" active />
|
||||
</FileTree.Folder>
|
||||
</FileTree>
|
||||
|
||||
Additionally, you will find resources on integrating the RAG API, enabling you to extend LibreChat's functionality and interactivity.
|
||||
**`.env`** -- Server-level settings: API keys, database connection strings, feature flags, and authentication secrets. This is the primary configuration file for most deployments. See the [.env reference](/docs/configuration/dotenv) for all available variables.
|
||||
|
||||
And a lot more!
|
||||
**`librechat.yaml`** -- Custom AI endpoints, model settings, interface options, and advanced features like MCP servers and agents. This file is optional -- LibreChat works with defaults if it does not exist. See the [librechat.yaml guide](/docs/configuration/librechat_yaml) for setup instructions.
|
||||
|
||||
Whether you are a beginner or a seasoned developer, these guides are designed to provide you with all the tools you need to succeed. Let's make your LibreChat experience smooth, efficient, and tailored to your goals. Thank you for choosing LibreChat, and happy configuring!
|
||||
**`docker-compose.yml`** -- Defines the Docker services (API server, database, search). Do not edit this file directly -- use an override file instead so your changes survive updates.
|
||||
|
||||
**`docker-compose.override.yml`** -- Your local customizations to Docker services: volume mounts, port mappings, environment overrides. Docker Compose merges this with the main file automatically. See the [Docker override guide](/docs/configuration/docker_override).
|
||||
|
||||
## Applying Changes
|
||||
|
||||
<Callout type="warning" title="Restart Required">
|
||||
|
||||
After editing any configuration file, you must restart LibreChat for changes to take effect.
|
||||
|
||||
<Tabs items={['Docker', 'Local']}>
|
||||
<Tabs.Tab>
|
||||
|
||||
```bash
|
||||
docker compose down && docker compose up -d
|
||||
```
|
||||
|
||||
</Tabs.Tab>
|
||||
<Tabs.Tab>
|
||||
|
||||
Stop the running process (Ctrl+C) and restart:
|
||||
|
||||
```bash
|
||||
npm run backend
|
||||
```
|
||||
|
||||
</Tabs.Tab>
|
||||
</Tabs>
|
||||
|
||||
</Callout>
|
||||
|
||||
## Next Steps
|
||||
|
||||
<Cards num={3}>
|
||||
<Cards.Card title="librechat.yaml Setup" href="/docs/configuration/librechat_yaml" arrow>
|
||||
Create and configure the main LibreChat config file
|
||||
</Cards.Card>
|
||||
<Cards.Card title="Docker Setup" href="/docs/quick_start/local_setup" arrow>
|
||||
Install and run LibreChat with Docker
|
||||
</Cards.Card>
|
||||
<Cards.Card title=".env Reference" href="/docs/configuration/dotenv" arrow>
|
||||
Environment variables for server configuration
|
||||
</Cards.Card>
|
||||
</Cards>
|
||||
|
||||
@@ -32,4 +32,4 @@ OPENAI_API_KEY=user_provided
|
||||
### Notes
|
||||
|
||||
- It's recommended you follow the [Custom Endpoints Quick Start Guide](/docs/quick_start/custom_endpoints) before proceeding with the examples below.
|
||||
- Important: make sure you setup the `librechat.yaml` file correctly: **[setup documentation](/docs/configuration/librechat_yaml/setup)**.
|
||||
- Important: make sure you setup the `librechat.yaml` file correctly: **[setup documentation](/docs/configuration/librechat_yaml)**.
|
||||
|
||||
@@ -21,6 +21,4 @@ description: Example configuration for LiteLLM
|
||||
summarize: false
|
||||
summaryModel: "gpt-3.5-turbo"
|
||||
modelDisplayLabel: "LiteLLM"
|
||||
```
|
||||
|
||||
|
||||
```
|
||||
@@ -1,34 +1,149 @@
|
||||
---
|
||||
title: Openrouter
|
||||
title: OpenRouter
|
||||
icon: OpenRouter
|
||||
description: Example configuration for Openrouter
|
||||
description: Complete setup guide for using OpenRouter as a custom endpoint in LibreChat
|
||||
---
|
||||
|
||||
> OpenRouter API key: [openrouter.ai/keys](https://openrouter.ai/keys)
|
||||
[OpenRouter](https://openrouter.ai/) provides access to hundreds of AI models through a single API. This guide walks you through setting up OpenRouter as a custom endpoint in LibreChat from scratch.
|
||||
|
||||
**Notes:**
|
||||
<Callout type="info" title="Prerequisites">
|
||||
|
||||
- **Known:** icon provided, fetching list of models is recommended as API token rates and pricing used for token credit balances when models are fetched.
|
||||
Before starting, make sure you have:
|
||||
- LibreChat installed and running (see [Docker setup](/docs/local/docker))
|
||||
- A `librechat.yaml` file created and mounted (see [librechat.yaml guide](/docs/configuration/librechat_yaml))
|
||||
|
||||
- `stop` is no longer included as a default parameter, so there is no longer a need to include it in [`dropParams`](/docs/configuration/librechat_yaml/object_structure/custom_endpoint#dropparams), unless you would like to completely prevent users from configuring this field.
|
||||
</Callout>
|
||||
|
||||
- **Known issue:** you should not use `OPENROUTER_API_KEY` as it will then override the `openAI` endpoint to use OpenRouter as well.
|
||||
## Setup
|
||||
|
||||
```yaml
|
||||
<Steps>
|
||||
<Step>
|
||||
|
||||
### Get an API Key
|
||||
|
||||
Create an account at [openrouter.ai](https://openrouter.ai/) and generate an API key from the [Keys page](https://openrouter.ai/keys).
|
||||
|
||||
Copy the key -- it starts with `sk-or-v1-`.
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
|
||||
### Add the Key to Your .env File
|
||||
|
||||
Open your `.env` file in the project root and add your OpenRouter API key:
|
||||
|
||||
```bash filename=".env"
|
||||
OPENROUTER_KEY=sk-or-v1-your-key-here
|
||||
```
|
||||
|
||||
<Callout type="error" title="Use OPENROUTER_KEY, Not OPENROUTER_API_KEY">
|
||||
|
||||
You must use `OPENROUTER_KEY` as the variable name. Using `OPENROUTER_API_KEY` will override the built-in OpenAI endpoint to use OpenRouter as well, which is almost certainly not what you want.
|
||||
|
||||
</Callout>
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
|
||||
### Add the Endpoint to librechat.yaml
|
||||
|
||||
Add the following to your `librechat.yaml` file. If the file already has content, merge the `endpoints` section with your existing configuration:
|
||||
|
||||
```yaml filename="librechat.yaml"
|
||||
version: 1.3.5
|
||||
cache: true
|
||||
endpoints:
|
||||
custom:
|
||||
- name: "OpenRouter"
|
||||
# For `apiKey` and `baseURL`, you can use environment variables that you define.
|
||||
# recommended environment variables:
|
||||
apiKey: "${OPENROUTER_KEY}" # NOT OPENROUTER_API_KEY
|
||||
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"
|
||||
```
|
||||
|
||||
|
||||
Key fields explained:
|
||||
|
||||
| Field | Purpose |
|
||||
|-------|---------|
|
||||
| `apiKey: "${OPENROUTER_KEY}"` | References the env var from Step 2. The `${}` syntax tells LibreChat to read the value from `.env`. |
|
||||
| `models.fetch: true` | Fetches the full model list from OpenRouter's API, so new models appear automatically. |
|
||||
| `dropParams: ["stop"]` | Removes the `stop` parameter from requests. OpenRouter models use varied stop tokens, so dropping this avoids compatibility issues. |
|
||||
| `modelDisplayLabel: "OpenRouter"` | The name shown in LibreChat's endpoint selector. |
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
|
||||
### Restart LibreChat
|
||||
|
||||
<Tabs items={['Docker', 'Local']}>
|
||||
<Tabs.Tab>
|
||||
|
||||
```bash
|
||||
docker compose down && docker compose up -d
|
||||
```
|
||||
|
||||
</Tabs.Tab>
|
||||
<Tabs.Tab>
|
||||
|
||||
Stop the running process (Ctrl+C) and restart:
|
||||
|
||||
```bash
|
||||
npm run backend
|
||||
```
|
||||
|
||||
</Tabs.Tab>
|
||||
</Tabs>
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
|
||||
### Verify It Works
|
||||
|
||||
Open LibreChat in your browser. You should see **OpenRouter** in the endpoint selector dropdown. Select it to see the available models.
|
||||
|
||||
If OpenRouter does not appear, check the server logs for configuration errors:
|
||||
|
||||
```bash
|
||||
docker compose logs api | grep -i "error\|openrouter"
|
||||
```
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Customization
|
||||
|
||||
### Using user_provided API Key
|
||||
|
||||
Instead of storing the key in `.env`, you can let each user provide their own key through the LibreChat UI:
|
||||
|
||||
```yaml
|
||||
apiKey: "user_provided"
|
||||
```
|
||||
|
||||
Users will see a key input field when selecting the OpenRouter endpoint.
|
||||
|
||||
### Limiting Available Models
|
||||
|
||||
Instead of fetching all models, you can specify a fixed list:
|
||||
|
||||
```yaml
|
||||
models:
|
||||
default: ["anthropic/claude-3.5-sonnet", "openai/gpt-4o", "meta-llama/llama-3-70b-instruct"]
|
||||
fetch: false
|
||||
```
|
||||
|
||||
## Reference
|
||||
|
||||
<Cards num={2}>
|
||||
<Cards.Card title="Custom Endpoint Fields" href="/docs/configuration/librechat_yaml/object_structure/custom_endpoint" arrow>
|
||||
All available fields for custom endpoint configuration
|
||||
</Cards.Card>
|
||||
<Cards.Card title="Full Example Config" href="/docs/configuration/librechat_yaml/example" arrow>
|
||||
Complete annotated librechat.yaml with multiple endpoints
|
||||
</Cards.Card>
|
||||
</Cards>
|
||||
|
||||
@@ -1,49 +1,205 @@
|
||||
---
|
||||
title: Custom Config
|
||||
icon: BookOpen
|
||||
description: Comprehensive guides for configuring the `librechat.yaml` file AKA the LibreChat Config file. This section is your one-stop resource for understanding and customizing endpoints & other integrations.
|
||||
weight: -11
|
||||
description: Create, mount, and configure the librechat.yaml file for custom AI endpoints and advanced LibreChat settings
|
||||
---
|
||||
|
||||
Welcome to the guide for configuring the **librechat.yaml** file in LibreChat.
|
||||
## What is librechat.yaml?
|
||||
|
||||
This file enables the integration of custom AI endpoints, enabling you to connect with any AI provider compliant with OpenAI API standards.
|
||||
The `librechat.yaml` file is LibreChat's main configuration file for custom AI endpoints, model settings, interface options, and advanced features like MCP servers and agents. It is optional -- LibreChat works with sensible defaults if the file does not exist.
|
||||
|
||||
## Key Features
|
||||
Follow the steps below to create the file, mount it for your deployment type, and verify it works.
|
||||
|
||||
- **Endpoint Integration**: Seamlessly integrate with a variety of AI providers compliant with OpenAI API standards, including Mistral AI, reverse proxies, and more.
|
||||
- **Advanced Customization**: Configure file handling, rate limiting, user registration, and interface elements to align with your preferences and requirements.
|
||||
- **Model Specifications**: Define detailed model configurations, presets, and behaviors to deliver a tailored AI experience.
|
||||
- **Agents**: Use Provider-agnostic, no-code assistants, with options to customize capabilities.
|
||||
- **MCP Servers**: Integrate with the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) for tool integrations.
|
||||
- **Assistants Integration**: Leverage the power of OpenAI's Assistants API, with options to customize capabilities, polling intervals, and timeouts.
|
||||
- **Azure OpenAI Support**: Integrate with Azure OpenAI Service, enabling access to multiple deployments, region models, and serverless inference endpoints.
|
||||
## Setup
|
||||
|
||||
<div style={{ display: "flex", justifyContent: "center", alignItems: "center", flexDirection: "column" }}>
|
||||
<div className="image-light-theme">
|
||||
<img src="https://github.com/danny-avila/LibreChat/assets/32828263/26336fa4-db61-438b-929c-0004aa4db56c" alt="modelmenu-light" style={{ width: "75%", height: "75%" }} />
|
||||
</div>
|
||||
<Steps>
|
||||
<Step>
|
||||
|
||||
<div className="image-dark-theme">
|
||||
<img src="https://github.com/danny-avila/LibreChat/assets/32828263/1e2fe33b-7073-4b4e-9ee1-7b7a99704bad" alt="modelmenu-dark" style={{ width: "75%", height: "75%" }} />
|
||||
</div>
|
||||
</div>
|
||||
### Locate or Create the File
|
||||
|
||||
Create a new `librechat.yaml` in your project root (the same directory as your `.env` file):
|
||||
|
||||
Future updates will streamline configuration further by migrating some settings from your [.env file](/docs/configuration/dotenv) to `librechat.yaml`.
|
||||
```bash
|
||||
touch librechat.yaml
|
||||
```
|
||||
|
||||
Stay tuned for ongoing enhancements to customize your LibreChat instance!
|
||||
You can also copy the [example config](/docs/configuration/librechat_yaml/example) as a starting point:
|
||||
|
||||
**Note:** To verify your YAML config, you can use the [YAML Validator](/toolkit/yaml_checker) or other online tools like [yamlchecker.com](https://yamlchecker.com/)
|
||||
```bash
|
||||
cp librechat.example.yaml librechat.yaml
|
||||
```
|
||||
|
||||
<Callout type="info" title="Alternative File Path">
|
||||
|
||||
You can set a custom file path using the `CONFIG_PATH` environment variable:
|
||||
|
||||
```bash filename=".env"
|
||||
CONFIG_PATH="/alternative/path/to/librechat.yaml"
|
||||
```
|
||||
|
||||
</Callout>
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
|
||||
### Mount the Config File
|
||||
|
||||
<Tabs items={['Docker', 'Local']}>
|
||||
<Tabs.Tab>
|
||||
|
||||
Docker needs a volume mount to access your `librechat.yaml` file inside the container.
|
||||
|
||||
**Copy the example override file:**
|
||||
|
||||
```bash
|
||||
cp docker-compose.override.yml.example docker-compose.override.yml
|
||||
```
|
||||
|
||||
**Edit `docker-compose.override.yml`** and ensure the librechat.yaml volume mount is uncommented:
|
||||
|
||||
```yaml filename="docker-compose.override.yml"
|
||||
services:
|
||||
api:
|
||||
volumes:
|
||||
- type: bind
|
||||
source: ./librechat.yaml
|
||||
target: /app/librechat.yaml
|
||||
```
|
||||
|
||||
This uses the [docker-compose.override.yml](/docs/configuration/docker_override) pattern -- Docker Compose automatically merges it with the main `docker-compose.yml`, so your customizations survive updates.
|
||||
|
||||
</Tabs.Tab>
|
||||
<Tabs.Tab>
|
||||
|
||||
Place `librechat.yaml` in the project root directory (the same directory as your `.env` file). No additional mounting is needed for local installations.
|
||||
|
||||
</Tabs.Tab>
|
||||
</Tabs>
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
|
||||
### Restart LibreChat
|
||||
|
||||
<Tabs items={['Docker', 'Local']}>
|
||||
<Tabs.Tab>
|
||||
|
||||
```bash
|
||||
docker compose down && docker compose up -d
|
||||
```
|
||||
|
||||
</Tabs.Tab>
|
||||
<Tabs.Tab>
|
||||
|
||||
Stop the running process (Ctrl+C) and restart:
|
||||
|
||||
```bash
|
||||
npm run backend
|
||||
```
|
||||
|
||||
</Tabs.Tab>
|
||||
</Tabs>
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
|
||||
### Verify It Works
|
||||
|
||||
Open LibreChat in your browser. If your configuration includes custom endpoints, you should see them in the model selector dropdown.
|
||||
|
||||
If the server fails to start, check the logs for validation errors:
|
||||
|
||||
```bash
|
||||
docker compose logs api
|
||||
```
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Example: Adding OpenRouter
|
||||
|
||||
This example walks through adding [OpenRouter](https://openrouter.ai/) as a custom endpoint -- one of the most popular configurations.
|
||||
|
||||
**1. Get an API key** from [openrouter.ai/keys](https://openrouter.ai/keys).
|
||||
|
||||
**2. Add the key to your `.env` file:**
|
||||
|
||||
```bash filename=".env"
|
||||
OPENROUTER_KEY=sk-or-v1-your-key-here
|
||||
```
|
||||
|
||||
<Callout type="warning" title="Environment Variable Name">
|
||||
|
||||
Use `OPENROUTER_KEY`, not `OPENROUTER_API_KEY`. Using `OPENROUTER_API_KEY` will override the OpenAI endpoint to use OpenRouter as well.
|
||||
|
||||
</Callout>
|
||||
|
||||
**3. Add the endpoint to `librechat.yaml`:**
|
||||
|
||||
```yaml filename="librechat.yaml"
|
||||
version: 1.3.5
|
||||
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"
|
||||
```
|
||||
|
||||
**4. Restart LibreChat** (see restart commands above) and select OpenRouter from the model selector.
|
||||
|
||||
For the full annotated config file with more endpoint examples, see the [example configuration](/docs/configuration/librechat_yaml/example).
|
||||
|
||||
## Reference
|
||||
|
||||
For detailed field-level documentation, see the reference pages below.
|
||||
|
||||
<Cards num={2}>
|
||||
<Cards.Card title="AI Endpoints" href="/docs/configuration/librechat_yaml/ai_endpoints" arrow>
|
||||
Compatible AI providers and example endpoint configurations
|
||||
</Cards.Card>
|
||||
<Cards.Card title="Object Structure" href="/docs/configuration/librechat_yaml/object_structure" arrow>
|
||||
Complete field reference for every librechat.yaml option
|
||||
</Cards.Card>
|
||||
</Cards>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Configuration Validation
|
||||
|
||||
<Callout type="error" title="Configuration Validation">
|
||||
**Important:** LibreChat will exit with an error (exit code 1) if the `librechat.yaml` configuration file contains validation errors. This fail-fast behavior helps catch configuration issues early and prevents running with unintended default settings.
|
||||
|
||||
If you need to temporarily bypass validation (e.g., while debugging configuration issues), you can set the `CONFIG_BYPASS_VALIDATION=true` environment variable. This will log a warning and continue with default configuration, preserving the legacy behavior.
|
||||
LibreChat exits with an error (exit code 1) if `librechat.yaml` contains validation errors. This fail-fast behavior catches configuration issues early.
|
||||
|
||||
To validate your YAML syntax before restarting, use the [YAML Validator](/toolkit/yaml_checker) or [yamlchecker.com](https://yamlchecker.com/).
|
||||
|
||||
</Callout>
|
||||
|
||||
### Server Exits Immediately on Startup
|
||||
|
||||
If your server exits immediately after starting, this is likely a configuration validation error.
|
||||
|
||||
**To diagnose:**
|
||||
|
||||
1. Check server logs: `docker compose logs api`
|
||||
2. Validate your YAML syntax with the [YAML Validator](/toolkit/yaml_checker)
|
||||
3. Common errors: incorrect indentation, missing colons, unknown keys, invalid values
|
||||
|
||||
**Temporary workaround** (not recommended for production):
|
||||
|
||||
```bash filename=".env"
|
||||
CONFIG_BYPASS_VALIDATION=true
|
||||
```
|
||||
|
||||
> ⚠️ **Note:** Using `CONFIG_BYPASS_VALIDATION=true` is not recommended for production. Fix your configuration errors instead.
|
||||
<Callout type="warning" title="Warning">
|
||||
|
||||
`CONFIG_BYPASS_VALIDATION=true` causes the server to skip validation and use default configuration. Always fix the validation errors instead.
|
||||
|
||||
</Callout>
|
||||
|
||||
@@ -3,7 +3,6 @@
|
||||
"icon": "FileCode",
|
||||
"pages": [
|
||||
"index",
|
||||
"setup",
|
||||
"example",
|
||||
"ai_endpoints",
|
||||
"object_structure"
|
||||
|
||||
@@ -1,76 +0,0 @@
|
||||
---
|
||||
title: "Setup"
|
||||
icon: Settings
|
||||
---
|
||||
|
||||
**The `librechat.yaml` file should be placed in the root of the project where the .env file is located.**
|
||||
|
||||
You can copy the [example config file](/docs/configuration/librechat_yaml/example) as a good starting point while reading the rest of the guide.
|
||||
|
||||
The example config file has some options ready to go for Mistral AI, Groq and Openrouter.
|
||||
|
||||
**Note:** You can set an alternate filepath for the `librechat.yaml` file through an environment variable:
|
||||
|
||||
```bash filename=".env"
|
||||
CONFIG_PATH="/alternative/path/to/librechat.yaml"
|
||||
```
|
||||
|
||||
## Docker Setup
|
||||
|
||||
For Docker, you need to make use of an [override file](/docs/configuration/docker_override), named `docker-compose.override.yml`, to ensure the config file works for you.
|
||||
|
||||
- First, make sure your containers stop running with `docker compose down`
|
||||
- Create or edit existing `docker-compose.override.yml` at the root of the project:
|
||||
|
||||
|
||||
```yaml filename="docker-compose.override.yml"
|
||||
version: '3.4'
|
||||
|
||||
services:
|
||||
api:
|
||||
volumes:
|
||||
- type: bind
|
||||
source: ./librechat.yaml
|
||||
target: /app/librechat.yaml
|
||||
```
|
||||
|
||||
- **Note:** If you are using `CONFIG_PATH` for an alternative filepath for this file, make sure to specify it accordingly.
|
||||
|
||||
- Start docker again, and you should see your config file settings apply
|
||||
|
||||
```bash filename="Restart the containers"
|
||||
docker compose up
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Server Exits Immediately on Startup
|
||||
|
||||
If your server exits immediately after starting with exit code 1, this is likely due to configuration validation errors in your `librechat.yaml` file.
|
||||
|
||||
**To diagnose the issue:**
|
||||
|
||||
1. **Check the server logs** for validation error messages:
|
||||
```bash filename="View Docker logs"
|
||||
docker compose logs api
|
||||
```
|
||||
|
||||
2. **Validate your YAML syntax** using the [YAML Validator](/toolkit/yaml_checker) or tools like [yamlchecker.com](https://yamlchecker.com/)
|
||||
|
||||
3. **Common validation errors include:**
|
||||
- Invalid YAML syntax (incorrect indentation, missing colons, etc.)
|
||||
- Unknown configuration keys or typos in property names
|
||||
- Invalid values for specific configuration options
|
||||
- Missing required fields
|
||||
|
||||
**Temporary workaround:**
|
||||
|
||||
If you need to start the server urgently while debugging configuration issues, you can bypass validation by setting:
|
||||
|
||||
```bash filename=".env"
|
||||
CONFIG_BYPASS_VALIDATION=true
|
||||
```
|
||||
|
||||
<Callout type="warning" title="Warning">
|
||||
Using `CONFIG_BYPASS_VALIDATION=true` will cause the server to log a warning and continue with default configuration. This is not recommended for production use. Always fix the validation errors in your configuration file.
|
||||
</Callout>
|
||||
@@ -1,64 +1,102 @@
|
||||
---
|
||||
title: Google Search
|
||||
icon: Search
|
||||
description: How to set up and use the Google Search Plugin, which allows you to query Google with GPT's help.
|
||||
description: Set up Google Custom Search as an agent tool in LibreChat
|
||||
---
|
||||
|
||||
Through the plugins endpoint, you can use google search for answers to your questions with assistance from GPT! To get started, you need to get a Google Custom Search API key, and a Google Custom Search Engine ID. You can then define these as follows in your `.env` file:
|
||||
```env
|
||||
GOOGLE_SEARCH_API_KEY="...."
|
||||
GOOGLE_CSE_ID="...."
|
||||
```
|
||||
|
||||
You first need to create a programmable search engine and get the search engine ID: **[https://developers.google.com/custom-search/docs/tutorial/creatingcse](https://developers.google.com/custom-search/docs/tutorial/creatingcse)**
|
||||
|
||||
Then you can get the API key, click the "Get a key" button on this page: **[https://developers.google.com/custom-search/v1/introduction](https://developers.google.com/custom-search/v1/introduction)**
|
||||
<Callout type="info" title="Looking for Web Search?">
|
||||
|
||||
### 1\. Go to the [Programmable Search Engine docs](https://developers.google.com/custom-search/docs/tutorial/creatingcse) to get a Search engine ID
|
||||
This page covers the **Google Custom Search** tool (agent plugin). For LibreChat's built-in **Web Search** feature (Serper/SearXNG + Firecrawl + Jina), see [Web Search](/docs/features/web_search).
|
||||
|
||||
</Callout>
|
||||
|
||||
### 2\. Click on "Control Panel" under "Defining a Programmable Engine in Control Panel"
|
||||
The Google Search tool lets your agents query Google using the Custom Search JSON API. You will need a Google Custom Search Engine ID and an API key.
|
||||
|
||||
## Setup
|
||||
|
||||
Click to sign in(make a Google acct if you do not have one):
|
||||
<Steps>
|
||||
<Step>
|
||||
|
||||
|
||||
### Create a Programmable Search Engine
|
||||
|
||||
Go to the [Programmable Search Engine control panel](https://programmablesearchengine.google.com/controlpanel/all) and sign in with your Google account.
|
||||
|
||||
### 3\. Register yourself a new account/Login to the Control Panel
|
||||
|
||||
|
||||
After logging in, you will be redirected to the Control Panel to create a new search engine:
|
||||
Click **Add** to create a new search engine. Fill in a name, select **Search the entire web**, and click **Create**.
|
||||
|
||||
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
|
||||
### 4\. Create a new search engine
|
||||
### Copy Your Search Engine ID
|
||||
|
||||
|
||||
Fill in a name, select to "Search the entire web" and hit "Create":
|
||||
|
||||
|
||||
|
||||
|
||||
### 5\. Copy your Search engine ID to your .env file
|
||||
After creating the engine, you will see your **Search engine ID**. Copy it -- you will add it to your `.env` file as `GOOGLE_CSE_ID`.
|
||||
|
||||
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
|
||||
### 6\. Go to [custom-search docs](https://developers.google.com/custom-search/v1/introduction) to get a Google search API key
|
||||
### Get a Google Search API Key
|
||||
|
||||
|
||||
### 7\. Click "Get a Key":
|
||||
Go to the [Custom Search JSON API introduction page](https://developers.google.com/custom-search/v1/introduction) and click **Get a Key**.
|
||||
|
||||
|
||||
|
||||
|
||||
### 8\. Name your project and agree to the Terms of Service
|
||||
Name your project, agree to the Terms of Service, and copy the API key.
|
||||
|
||||
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
|
||||
### 9\. Copy your Google search API key to your .env file
|
||||
### Add Environment Variables
|
||||
|
||||
|
||||
Add both values to your `.env` file:
|
||||
|
||||
```bash filename=".env"
|
||||
GOOGLE_SEARCH_API_KEY=your-api-key-here
|
||||
GOOGLE_CSE_ID=your-search-engine-id-here
|
||||
```
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
|
||||
### Add the Tool to an Agent
|
||||
|
||||
In LibreChat, go to the **Agents** panel and create or edit an agent. In the agent's **Tools** list, select **Google Search**.
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
|
||||
### Restart and Test
|
||||
|
||||
| Deployment | Command |
|
||||
|------------|---------|
|
||||
| Docker | `docker compose down && docker compose up -d` |
|
||||
| Local | Stop (Ctrl+C) then `npm run backend` |
|
||||
|
||||
Send a message like "Search for the latest news about AI" to your agent. The agent will use Google Custom Search to find and return relevant results.
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Callout type="warn" title="Common Issues">
|
||||
|
||||
If search returns no results, verify that your Programmable Search Engine is set to **Search the entire web** (not restricted to specific sites). Also confirm that both `GOOGLE_SEARCH_API_KEY` and `GOOGLE_CSE_ID` are set in your `.env` file and that you have restarted LibreChat after making changes.
|
||||
|
||||
</Callout>
|
||||
|
||||
## Related Pages
|
||||
|
||||
<Cards num={3}>
|
||||
<Cards.Card title="Web Search" href="/docs/features/web_search" arrow>
|
||||
LibreChat's built-in web search feature (Serper, SearXNG, Firecrawl)
|
||||
</Cards.Card>
|
||||
<Cards.Card title="Tools Overview" href="/docs/configuration/tools" arrow>
|
||||
All available agent tools and their configuration
|
||||
</Cards.Card>
|
||||
<Cards.Card title="Agents" href="/docs/features/agents" arrow>
|
||||
Create and configure AI agents with custom tools
|
||||
</Cards.Card>
|
||||
</Cards>
|
||||
|
||||
@@ -4,7 +4,51 @@ icon: Image
|
||||
description: Comprehensive guide to LibreChat's built-in image generation and editing tools
|
||||
---
|
||||
|
||||
## 🎨 Image Generation & Editing
|
||||
## Quick Start
|
||||
|
||||
Get image generation working in under 5 minutes with OpenAI Image Tools (recommended).
|
||||
|
||||
<Steps>
|
||||
<Step>
|
||||
|
||||
### Create an Agent
|
||||
|
||||
Go to the **Agents** panel in LibreChat and create a new agent. Give it a name like "Image Creator".
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
|
||||
### Add OpenAI Image Tools
|
||||
|
||||
In the agent's **Tools** list, select **OpenAI Image Tools**. This adds both image generation and image editing capabilities.
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
|
||||
### Set Your API Key
|
||||
|
||||
Add the following to your `.env` file:
|
||||
|
||||
```bash filename=".env"
|
||||
IMAGE_GEN_OAI_API_KEY=sk-your-openai-api-key
|
||||
```
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
|
||||
### Restart and Test
|
||||
|
||||
| Deployment | Command |
|
||||
|------------|---------|
|
||||
| Docker | `docker compose down && docker compose up -d` |
|
||||
| Local | Stop (Ctrl+C) then `npm run backend` |
|
||||
|
||||
Send a message like "Generate an image of a sunset over mountains" to your agent.
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
---
|
||||
|
||||
LibreChat comes with **built-in image tools** that you can add to an **[Agent](/docs/features/agents).**
|
||||
|
||||
@@ -375,3 +419,17 @@ Though you can customize the prompts for [OpenAI Image Tools](#advanced-configur
|
||||
Example:
|
||||
|
||||
> A cinematic photo of an antique library bathed in warm afternoon sunlight. Tall wooden shelves overflow with leather-bound books, and dust particles shimmer in the light. A single green-shaded banker's lamp illuminates an open atlas on a polished mahogany desk in the foreground. 85 mm lens, shallow depth of field, rich amber tones, ultra-high detail.
|
||||
|
||||
## Related Pages
|
||||
|
||||
<Cards num={3}>
|
||||
<Cards.Card title="Agents" href="/docs/features/agents" arrow>
|
||||
Create and configure AI agents with custom tools
|
||||
</Cards.Card>
|
||||
<Cards.Card title="MCP Servers" href="/docs/features/mcp" arrow>
|
||||
Bring your own tools via Model Context Protocol
|
||||
</Cards.Card>
|
||||
<Cards.Card title="Gemini Image Tools" href="/docs/configuration/tools/gemini_image_gen" arrow>
|
||||
Detailed setup guide for Google Gemini image generation
|
||||
</Cards.Card>
|
||||
</Cards>
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Docker
|
||||
icon: Container
|
||||
description: How to install LibreChat locally with Docker
|
||||
description: How to install LibreChat locally with Docker, verify your setup, and configure custom endpoints
|
||||
---
|
||||
|
||||
For most scenarios, Docker Compose is the recommended installation method due to its simplicity, ease of use, and reliability.
|
||||
@@ -11,41 +11,106 @@ For most scenarios, Docker Compose is the recommended installation method due to
|
||||
- [`Git`](https://git-scm.com/downloads)
|
||||
- [`Docker`](https://www.docker.com/products/docker-desktop/)
|
||||
|
||||
---
|
||||
Docker Desktop is recommended for most users. For remote server installations, see the [Ubuntu Docker Deployment Guide](/docs/remote/docker_linux).
|
||||
|
||||
## Installation Steps
|
||||
## Installation
|
||||
|
||||
Follow these steps to set up LibreChat with the default configuration:
|
||||
<Steps>
|
||||
<Step>
|
||||
|
||||
```bash filename="Clone the Repository"
|
||||
### Clone the Repository
|
||||
|
||||
```bash
|
||||
git clone https://github.com/danny-avila/LibreChat.git
|
||||
```
|
||||
|
||||
```bash filename="Navigate to the LibreChat Directory"
|
||||
cd LibreChat
|
||||
```
|
||||
|
||||
```bash filename="Create a .env File from .env.example"
|
||||
</Step>
|
||||
<Step>
|
||||
|
||||
### Create Your Environment File
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
> **Note:** **If you're using Windows, you might need to use `copy` instead of `cp`.**
|
||||
The default `.env` file works out of the box for a basic setup. For in-depth configuration, see the [.env reference](/docs/configuration/dotenv).
|
||||
|
||||
```sh filename="Start LibreChat"
|
||||
<Callout type="info" title="Windows">
|
||||
|
||||
On Windows, use `copy .env.example .env` if `cp` is not available.
|
||||
|
||||
</Callout>
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
|
||||
### Start LibreChat
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
<Callout type="success" title="Access LibreChat!" emoji="🎉">
|
||||
**Visit [http://localhost:3080/](http://localhost:3080/)**
|
||||
The first launch pulls Docker images and may take a few minutes. Subsequent starts are much faster.
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
|
||||
### Verify and Log In
|
||||
|
||||
Open your browser and visit [http://localhost:3080](http://localhost:3080). You should see the LibreChat login page.
|
||||
|
||||
<Callout type="info" title="First Account = Admin">
|
||||
|
||||
The first account you register becomes the admin account. There are no default credentials -- you create your own username and password during registration.
|
||||
|
||||
</Callout>
|
||||
|
||||
## Update LibreChat
|
||||
Click **Register** to create your account and start using LibreChat.
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Mounting librechat.yaml
|
||||
|
||||
To use a custom `librechat.yaml` configuration file with Docker, you need to mount it as a volume so the container can access it.
|
||||
|
||||
Copy the example override file and edit it:
|
||||
|
||||
```bash
|
||||
cp docker-compose.override.yml.example docker-compose.override.yml
|
||||
```
|
||||
|
||||
Ensure the librechat.yaml volume mount is uncommented in `docker-compose.override.yml`:
|
||||
|
||||
```yaml filename="docker-compose.override.yml"
|
||||
services:
|
||||
api:
|
||||
volumes:
|
||||
- type: bind
|
||||
source: ./librechat.yaml
|
||||
target: /app/librechat.yaml
|
||||
```
|
||||
|
||||
Restart for changes to take effect:
|
||||
|
||||
```bash
|
||||
docker compose down && docker compose up -d
|
||||
```
|
||||
|
||||
For full setup instructions including creating the file from scratch, see the [librechat.yaml guide](/docs/configuration/librechat_yaml). For more override options, see the [Docker override guide](/docs/configuration/docker_override).
|
||||
|
||||
## Updating LibreChat
|
||||
|
||||
The following commands will fetch the latest LibreChat project changes, including any necessary changes to the docker compose files, as well as the latest prebuilt images.
|
||||
|
||||
> **Note:** you may need to prefix commands with sudo according to your environment permissions.
|
||||
<Callout type="info" title="Permissions">
|
||||
|
||||
```bash filename="Stop the running container(s)""
|
||||
You may need to prefix commands with `sudo` according to your environment permissions.
|
||||
|
||||
</Callout>
|
||||
|
||||
```bash filename="Stop the running container(s)"
|
||||
docker compose down
|
||||
```
|
||||
|
||||
@@ -61,7 +126,7 @@ docker images -a --format "{{.ID}}" --filter "reference=*librechat*" | ForEach-O
|
||||
git pull
|
||||
```
|
||||
|
||||
```bash filename="Pull the latest LibreChat image""
|
||||
```bash filename="Pull the latest LibreChat image"
|
||||
docker compose pull
|
||||
```
|
||||
|
||||
@@ -69,19 +134,57 @@ docker compose pull
|
||||
docker compose up
|
||||
```
|
||||
|
||||
## Additional Setup
|
||||
## Troubleshooting
|
||||
|
||||
Unlock additional features by exploring our configuration guides to learn how to set up:
|
||||
### Port Already in Use
|
||||
|
||||
- Custom endpoints
|
||||
- Other advanced configuration options
|
||||
- And more
|
||||
If you see an error like `bind: address already in use` for port 3080, another application is using that port.
|
||||
|
||||
This will enable you to customize your LibreChat experience with optional features.
|
||||
Either stop the conflicting application, or change the port in `docker-compose.override.yml`:
|
||||
|
||||
**see also:**
|
||||
- [Docker Override](/docs/configuration/docker_override)
|
||||
- [User Authentication System Setup](/docs/configuration/authentication)
|
||||
- [AI Setup](/docs/configuration/pre_configured_ai)
|
||||
- [Custom Endpoints & Configuration](/docs/configuration/librechat_yaml)
|
||||
- [Manage Your MongoDB Database](/blog/2023-11-30_mongoexpress)
|
||||
```yaml filename="docker-compose.override.yml"
|
||||
services:
|
||||
api:
|
||||
ports:
|
||||
- "3081:3080"
|
||||
```
|
||||
|
||||
Then visit `http://localhost:3081` instead.
|
||||
|
||||
### Container Crashes on Startup
|
||||
|
||||
If containers exit immediately after starting, check the logs:
|
||||
|
||||
```bash
|
||||
docker compose logs api
|
||||
```
|
||||
|
||||
Common causes:
|
||||
|
||||
- Invalid `librechat.yaml` syntax -- validate with the [YAML Validator](/toolkit/yaml_checker)
|
||||
- Missing `.env` file -- ensure `.env` exists in the project root
|
||||
- Docker not running -- ensure Docker Desktop is open and running
|
||||
|
||||
### Missing Environment Variables
|
||||
|
||||
If features are not working as expected, check that required environment variables are set in your `.env` file.
|
||||
|
||||
```bash
|
||||
docker compose exec api env | grep -i "your_variable"
|
||||
```
|
||||
|
||||
See the [.env reference](/docs/configuration/dotenv) for all available variables and their defaults.
|
||||
|
||||
## Next Steps
|
||||
|
||||
<Cards num={3}>
|
||||
<Cards.Card title="Custom Endpoints" href="/docs/quick_start/custom_endpoints" arrow>
|
||||
Add OpenRouter, Ollama, and other AI providers
|
||||
</Cards.Card>
|
||||
<Cards.Card title="Configuration Overview" href="/docs/configuration" arrow>
|
||||
Understand how LibreChat's config files work together
|
||||
</Cards.Card>
|
||||
<Cards.Card title="Authentication Setup" href="/docs/configuration/authentication" arrow>
|
||||
Configure OAuth, LDAP, and other login methods
|
||||
</Cards.Card>
|
||||
</Cards>
|
||||
|
||||
@@ -1,28 +1,40 @@
|
||||
---
|
||||
title: "Custom Endpoints"
|
||||
icon: Plug
|
||||
description: Add custom AI providers like OpenRouter and Ollama to LibreChat using librechat.yaml
|
||||
---
|
||||
|
||||
import AdditionalLinks from '@/components/repeated/AdditionalLinks.mdx';
|
||||
LibreChat supports any OpenAI API-compatible service as a custom endpoint. You configure endpoints in `librechat.yaml`, store API keys in `.env`, and mount the config via `docker-compose.override.yml` for Docker deployments.
|
||||
|
||||
LibreChat supports OpenAI API compatible services using the `librechat.yaml` configuration file.
|
||||
<Callout type="info" title="Which File Does What?">
|
||||
|
||||
This guide assumes you have already set up LibreChat using Docker, as shown in the **[Local Setup Guide](/docs/quick_start/local_setup).**
|
||||
Custom endpoint setup involves three files, each with a specific role:
|
||||
|
||||
<Callout type="info" title="Configuration Files Clarification">
|
||||
LibreChat uses several configuration files, each with specific purposes:
|
||||
1. **`librechat.yaml`** -- Defines your custom endpoints (name, API URL, models, display settings)
|
||||
2. **`.env`** -- Stores sensitive values like API keys (referenced from librechat.yaml using `${VAR_NAME}` syntax)
|
||||
3. **`docker-compose.override.yml`** -- Mounts `librechat.yaml` into the Docker container (Docker users only)
|
||||
|
||||
For a full overview of how these files work together, see the [Configuration Overview](/docs/configuration).
|
||||
|
||||
1. **librechat.yaml** - Used for custom endpoints configuration and other application settings
|
||||
2. **.env file** - Used for server configuration, pre-configured endpoint API keys, and authentication settings
|
||||
3. **docker-compose.override.yml** - Used for Docker-specific configurations and mounting volumes
|
||||
</Callout>
|
||||
|
||||
## Step 1. Create or Edit a Docker Override File
|
||||
<Callout type="warning" title="Before You Start">
|
||||
|
||||
- Create a file named `docker-compose.override.yml` file at the project root (if it doesn't already exist).
|
||||
- Add the following content to the file:
|
||||
This guide assumes you have LibreChat installed and running. If not, complete the [Docker setup](/docs/local/docker) first.
|
||||
|
||||
```yaml
|
||||
</Callout>
|
||||
|
||||
## Step 1. Mount librechat.yaml (Docker Only)
|
||||
|
||||
Docker users need to mount `librechat.yaml` as a volume so the container can read it. Skip this step if you are running LibreChat locally without Docker.
|
||||
|
||||
```bash
|
||||
cp docker-compose.override.yml.example docker-compose.override.yml
|
||||
```
|
||||
|
||||
Edit `docker-compose.override.yml` and ensure the volume mount is uncommented:
|
||||
|
||||
```yaml filename="docker-compose.override.yml"
|
||||
services:
|
||||
api:
|
||||
volumes:
|
||||
@@ -31,102 +43,105 @@ services:
|
||||
target: /app/librechat.yaml
|
||||
```
|
||||
|
||||
> Learn more about the [Docker Compose Override File here](/docs/configuration/docker_override).
|
||||
Learn more: [Docker Override Guide](/docs/configuration/docker_override)
|
||||
|
||||
## Step 2. Configure `librechat.yaml`
|
||||
## Step 2. Configure librechat.yaml
|
||||
|
||||
- **Create a file named `librechat.yaml`** at the project root (if it doesn't already exist).
|
||||
- **Add your custom endpoints:** you can view compatible endpoints in the [AI Endpoints section](/docs/configuration/librechat_yaml/ai_endpoints).
|
||||
- The list is not exhaustive and generally every OpenAI API-compatible service should work.
|
||||
- There are many options for Custom Endpoints. View them all here: [Custom Endpoint Object Structure](/docs/configuration/librechat_yaml/object_structure/custom_endpoint).
|
||||
- As an example, here is a configuration for both **OpenRouter** and **Ollama**:
|
||||
Create a `librechat.yaml` file in the project root (if it does not exist) and add your endpoint configuration. See the [librechat.yaml guide](/docs/configuration/librechat_yaml) for detailed setup instructions.
|
||||
|
||||
```yaml
|
||||
version: 1.3.5
|
||||
cache: true
|
||||
endpoints:
|
||||
custom:
|
||||
- name: "OpenRouter"
|
||||
apiKey: "${OPENROUTER_KEY}"
|
||||
baseURL: "https://openrouter.ai/api/v1"
|
||||
models:
|
||||
default: ["gpt-3.5-turbo"]
|
||||
fetch: true
|
||||
titleConvo: true
|
||||
titleModel: "current_model"
|
||||
summarize: false
|
||||
summaryModel: "current_model"
|
||||
modelDisplayLabel: "OpenRouter"
|
||||
- name: "Ollama"
|
||||
apiKey: "ollama"
|
||||
baseURL: "http://host.docker.internal:11434/v1/"
|
||||
models:
|
||||
default: [
|
||||
"llama3:latest",
|
||||
"command-r",
|
||||
"mixtral",
|
||||
"phi3"
|
||||
]
|
||||
fetch: true # fetching list of models is not supported
|
||||
titleConvo: true
|
||||
titleModel: "current_model"
|
||||
```
|
||||
Here is an example with **OpenRouter** and **Ollama**:
|
||||
|
||||
<Callout type="warning" title="Important: API Key Configuration">
|
||||
When configuring API keys in custom endpoints, you have two options:
|
||||
```yaml filename="librechat.yaml"
|
||||
version: 1.3.5
|
||||
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"
|
||||
```
|
||||
|
||||
1. **Environment Variable Reference**: Use `${VARIABLE_NAME}` syntax to reference a variable from your .env file (recommended for security)
|
||||
```yaml
|
||||
apiKey: "${OPENROUTER_KEY}"
|
||||
```
|
||||
Browse all compatible providers in the [AI Endpoints](/docs/configuration/librechat_yaml/ai_endpoints) section. For the full field reference, see [Custom Endpoint Object Structure](/docs/configuration/librechat_yaml/object_structure/custom_endpoint).
|
||||
|
||||
2. **User Provided**: Set to `"user_provided"` (without the ${} syntax) to allow users to enter their own API key through the web interface
|
||||
```yaml
|
||||
apiKey: "user_provided"
|
||||
```
|
||||
<Callout type="warning" title="API Key Configuration">
|
||||
|
||||
3. **Direct Value**: Directly include the API key in the configuration file (not recommended for security reasons)
|
||||
```yaml
|
||||
apiKey: "your-actual-api-key"
|
||||
```
|
||||
When configuring API keys in custom endpoints, you have three options:
|
||||
|
||||
1. **Environment variable** (recommended): `apiKey: "${OPENROUTER_KEY}"` -- reads from `.env`
|
||||
2. **User provided**: `apiKey: "user_provided"` -- users enter their own key in the UI
|
||||
3. **Direct value** (not recommended): `apiKey: "sk-your-actual-key"` -- stored in plain text
|
||||
|
||||
This is different from pre-configured endpoints in the .env file where you would set `ENDPOINT_KEY=user_provided` (e.g., `OPENAI_API_KEY=user_provided`).
|
||||
</Callout>
|
||||
|
||||
## Step 3. Configure .env File
|
||||
## Step 3. Set Environment Variables
|
||||
|
||||
- **Edit your existing `.env` file** at the project root
|
||||
- Copy `.env.example` and rename to `.env` if it doesn't already exist.
|
||||
- According to the config above, the environment variable `OPENROUTER_KEY` is expected and should be set:
|
||||
Add the API keys referenced in your `librechat.yaml` to the `.env` file:
|
||||
|
||||
```bash
|
||||
```bash filename=".env"
|
||||
OPENROUTER_KEY=your_openrouter_api_key
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
- As way of example, this guide assumes you have setup Ollama independently and is accessible to you at `http://host.docker.internal:11434`
|
||||
- "host.docker.internal" is a special DNS name that resolves to the internal IP address used by the host.
|
||||
- You may need to change this to the actual IP address of your Ollama instance.
|
||||
- In a future guide, we will go into setting up Ollama along with LibreChat.
|
||||
Each `${VARIABLE_NAME}` in librechat.yaml must have a matching entry in `.env`.
|
||||
|
||||
## Step 4. Run the App
|
||||
## Step 4. Restart and Verify
|
||||
|
||||
- Now that your files are configured, you can run the app:
|
||||
After editing configuration files, you must restart LibreChat for changes to take effect.
|
||||
|
||||
<Tabs items={['Docker', 'Local']}>
|
||||
<Tabs.Tab>
|
||||
|
||||
```bash
|
||||
docker compose up
|
||||
docker compose down && docker compose up -d
|
||||
```
|
||||
|
||||
Or, if you were running the app before, you can restart the app with:
|
||||
</Tabs.Tab>
|
||||
<Tabs.Tab>
|
||||
|
||||
Stop the running process (Ctrl+C) and restart:
|
||||
|
||||
```bash
|
||||
docker compose restart
|
||||
npm run backend
|
||||
```
|
||||
|
||||
> Note: Make sure your Docker Desktop or Docker Engine is running before executing the command.
|
||||
</Tabs.Tab>
|
||||
</Tabs>
|
||||
|
||||
## Conclusion
|
||||
Open LibreChat in your browser. Your custom endpoints should appear in the endpoint selector dropdown.
|
||||
|
||||
**That's it!** You have now configured **Custom Endpoints** for your LibreChat instance.
|
||||
<Callout type="info" title="Not Seeing Your Endpoint?">
|
||||
|
||||
<AdditionalLinks />
|
||||
Check the server logs for configuration errors:
|
||||
|
||||
```bash
|
||||
docker compose logs api
|
||||
```
|
||||
|
||||
Common issues: YAML syntax errors, missing env vars, or `librechat.yaml` not mounted in Docker. Validate your YAML with the [YAML Validator](/toolkit/yaml_checker).
|
||||
|
||||
</Callout>
|
||||
|
||||
## Next Steps
|
||||
|
||||
<Cards num={2}>
|
||||
<Cards.Card title="AI Endpoints" href="/docs/configuration/librechat_yaml/ai_endpoints" arrow>
|
||||
Browse all compatible AI providers with example configurations
|
||||
</Cards.Card>
|
||||
<Cards.Card title="librechat.yaml Guide" href="/docs/configuration/librechat_yaml" arrow>
|
||||
Full setup guide and reference for the config file
|
||||
</Cards.Card>
|
||||
</Cards>
|
||||
|
||||
@@ -1,19 +1,38 @@
|
||||
---
|
||||
title: Overview
|
||||
icon: BookOpen
|
||||
description: Collection of user guides providing an overview of various features offered by LibreChat
|
||||
description: Guides and tutorials for LibreChat features
|
||||
---
|
||||
|
||||
import Image from 'next/image'
|
||||
Whether you are a new user or exploring advanced features, these guides help you get the most out of LibreChat.
|
||||
|
||||
Whether you're a new user or looking to explore more advanced features, this comprehensive collection is designed to help you navigate through the various functionalities of LibreChat seamlessly.
|
||||
## Guides
|
||||
|
||||
<div style={{padding: "20px", display: "flex", justifyContent: "center", alignItems: "center", flexDirection: "column"}}>
|
||||
<div className="image-light-theme">
|
||||
<Image src="https://github.com/danny-avila/LibreChat/assets/32828263/cf0f3231-287a-407f-bd4d-3d5bad94e893" alt="ipad-light" width={1024} height={512} style={{borderRadius: "5px"}} />
|
||||
</div>
|
||||
<Cards num={3}>
|
||||
<Cards.Card title="AI Overview" href="/docs/user_guides/ai_overview" arrow>
|
||||
Understand endpoints, presets, and how AI providers work in LibreChat
|
||||
</Cards.Card>
|
||||
<Cards.Card title="Presets" href="/docs/user_guides/presets" arrow>
|
||||
Save and load predefined conversation settings
|
||||
</Cards.Card>
|
||||
<Cards.Card title="MongoDB" href="/docs/user_guides/mongodb" arrow>
|
||||
Why LibreChat uses MongoDB and how data is stored
|
||||
</Cards.Card>
|
||||
</Cards>
|
||||
|
||||
<div className="image-dark-theme">
|
||||
<Image src="https://github.com/danny-avila/LibreChat/assets/32828263/a03ee02d-5099-4220-95b0-bfa2d3b00b4d" alt="ipad-dark" width={1024} height={512} style={{borderRadius: "5px"}} />
|
||||
</div>
|
||||
</div>
|
||||
## Popular Features
|
||||
|
||||
<Cards num={4}>
|
||||
<Cards.Card title="Agents" href="/docs/features/agents" arrow>
|
||||
Create AI agents with custom tools and capabilities
|
||||
</Cards.Card>
|
||||
<Cards.Card title="Image Generation" href="/docs/features/image_gen" arrow>
|
||||
Set up and use image generation tools in your agents
|
||||
</Cards.Card>
|
||||
<Cards.Card title="Web Search" href="/docs/features/web_search" arrow>
|
||||
Enable AI-powered web search in conversations
|
||||
</Cards.Card>
|
||||
<Cards.Card title="MCP" href="/docs/features/mcp" arrow>
|
||||
Connect external tools via Model Context Protocol
|
||||
</Cards.Card>
|
||||
</Cards>
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
import defaultMdxComponents from 'fumadocs-ui/mdx'
|
||||
import { Callout } from 'fumadocs-ui/components/callout'
|
||||
import { Step, Steps } from 'fumadocs-ui/components/steps'
|
||||
import { Tabs } from 'fumadocs-ui/components/tabs'
|
||||
import { Tabs, Tab } from 'fumadocs-ui/components/tabs'
|
||||
import { File as FumadocsFile, Folder, Files } from 'fumadocs-ui/components/files'
|
||||
import { Accordion, Accordions } from 'fumadocs-ui/components/accordion'
|
||||
import { OptionTable } from '@/components/table'
|
||||
@@ -64,15 +64,22 @@ function CalloutCompat({
|
||||
}
|
||||
|
||||
/**
|
||||
* Simple Tab/Tabs wrappers that render content directly.
|
||||
* The fumadocs-mdx compiler generates tab structures that may be incomplete
|
||||
* when the remarkCodeTab plugin isn't available. These wrappers render the
|
||||
* content as simple divs to avoid Radix UI context errors.
|
||||
* Tab/Tabs wrappers for MDX content.
|
||||
*
|
||||
* When `items` are provided (explicit `<Tabs items={[...]}>`), we render the
|
||||
* real fumadocs `<Tabs>` + `<Tab>` so that clicking tab triggers actually
|
||||
* switches the visible content.
|
||||
*
|
||||
* `<Tabs.Tab>` is used in MDX as a compound component. When it lives inside a
|
||||
* Tabs with `items`, it renders as the real fumadocs `<Tab>`. Otherwise it
|
||||
* falls back to a plain `<div>` (e.g. for auto-generated code tabs from
|
||||
* remarkCodeTab where the fumadocs context is not set up).
|
||||
*
|
||||
* We achieve this by mapping `Tabs` → `TabsCompat` and `Tabs.Tab` → `Tab`
|
||||
* (the real fumadocs Tab). `TabsCompat` wraps children with the real
|
||||
* `<Tabs>` when items exist. The fumadocs `<Tab>` auto-resolves its value
|
||||
* from the parent context — no extra plumbing needed.
|
||||
*/
|
||||
function TabCompat({ children, ...props }: { children?: ReactNode; [key: string]: any }) {
|
||||
return <div {...props}>{children}</div>
|
||||
}
|
||||
|
||||
function TabsCompat({
|
||||
children,
|
||||
items,
|
||||
@@ -93,7 +100,13 @@ function TabsCompat({
|
||||
// Fallback: render children directly for auto-generated tab structures
|
||||
return <div {...props}>{children}</div>
|
||||
}
|
||||
;(TabsCompat as any).Tab = TabCompat
|
||||
|
||||
/**
|
||||
* Compound component pattern: MDX resolves `<Tabs.Tab>` → `TabsCompat.Tab`.
|
||||
* We assign the real fumadocs `Tab` so it registers with the parent `<Tabs>`
|
||||
* context and tab switching works.
|
||||
*/
|
||||
const TabsWithTab = Object.assign(TabsCompat, { Tab })
|
||||
|
||||
function CardsCompat({
|
||||
children,
|
||||
@@ -214,8 +227,10 @@ export const mdxComponents = {
|
||||
Callout: CalloutCompat,
|
||||
Steps,
|
||||
Step,
|
||||
Tab: TabCompat,
|
||||
Tabs: TabsCompat,
|
||||
Tab: ({ children, ...props }: { children?: ReactNode; [key: string]: any }) => (
|
||||
<div {...props}>{children}</div>
|
||||
),
|
||||
Tabs: TabsWithTab,
|
||||
Cards: CardsWithCard,
|
||||
Card: CardCompat,
|
||||
FileTree: FileTreeWithChildren,
|
||||
|
||||
@@ -58,6 +58,7 @@ const nonPermanentRedirects = [
|
||||
['/docs/user_guides/rag_api', '/docs/features/rag_api'],
|
||||
['/docs/user_guides/plugins', '/docs/features/agents'],
|
||||
['/docs/features/plugins', '/docs/features/agents'],
|
||||
['/docs/configuration/librechat_yaml/setup', '/docs/configuration/librechat_yaml'],
|
||||
];
|
||||
|
||||
/**
|
||||
|
||||
Reference in New Issue
Block a user