# Project pack: LibreChat @ eac18f4

Facts about **LibreChat** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> LibreChat looks and feels like ChatGPT, but it is yours. You bring your own AI keys (or a free model running on your own computer) and switch between OpenAI, Anthropic, Google and many others in the same chat. It keeps your chat history on your own server, lets the whole family have accounts, and can read files, search the web and build simple helpers ("agents") with their own instructions.

## Version and source
- Repository: https://github.com/danny-avila/LibreChat
- Pinned commit: `eac18f465667f5b8b463f2a9dfa2af1271e40a1b`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/danny-avila/LibreChat/archive/eac18f465667f5b8b463f2a9dfa2af1271e40a1b.zip
- Official docs: https://www.librechat.ai/docs
- Licence: **MIT**. Very permissive. You can use, change and share it, even commercially, as long as you keep the copyright notice. No obligation to publish your changes. (The root package.json says "ISC", but the LICENSE file at the pinned commit is MIT.)

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/danny-avila/LibreChat bespoke-librechat
  cd bespoke-librechat
  git checkout --detach eac18f465667f5b8b463f2a9dfa2af1271e40a1b
  # Prepare development requirements and local configuration first.
  # Setup notes: API on :3080; in another terminal: npm run frontend:dev (client on :3090). Needs MONGO_URI in .env
  npm ci && npm run build:packages && npm run backend:dev
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  git clone https://github.com/danny-avila/LibreChat.git && cd LibreChat
  git checkout eac18f465667f5b8b463f2a9dfa2af1271e40a1b
  cp .env.example .env
  # put a random value in ADMIN_PANEL_SESSION_SECRET (openssl rand -hex 32) and your AI keys in .env
  docker compose up -d
  # open http://localhost:3080 and create the first account (it becomes the admin)
  ```

- Needs: Docker with Docker Compose, About 4 GB of free RAM for the five containers (app, MongoDB, Meilisearch, vector database, RAG API), An API key for at least one AI provider, or Ollama running on the same computer, For development, Node.js 24 (.nvmrc) and npm
- Develop: `npm ci && npm run build:packages && npm run backend:dev   # API on :3080; in another terminal: npm run frontend:dev (client on :3090). Needs MONGO_URI in .env`
- Test: `npm run test:client && npm run test:api`
- Check/lint: `npm run lint`
- Stack: typescript, javascript (Node.js, Express, React, Vite, Tailwind CSS, Mongoose, Turborepo). Difficulty for a non-developer with an AI: **advanced**. A very large, fast-moving monorepo (api, client and several packages) with five containers in the default Docker setup. Almost everything a household wants (which models, names, welcome text, who can sign up, local models, web search, memory) is set in .env and librechat.yaml, without touching code. Code changes need Node 24 (see .nvmrc), a MongoDB and the package build order described in AGENTS.md.

## The project's own AI instructions
Read these in the repository before changing code: `AGENTS.md`, `CONTEXT.md`, `.github/CONTRIBUTING.md`.

## Customisation points (settings → extend → code)
- **env-basics** [settings]: Name, footer, who can sign up, and which built-in AI providers are on. → `.env (from .env.example), e.g. APP_TITLE, CUSTOM_FOOTER, ALLOW_REGISTRATION, provider keys`
- **librechat-yaml** [settings]: The main control panel: interface (welcome text, privacy and terms links, which buttons show), registration, model specs (ready-made "assistants" for the model menu), memory, web search and file limits. → `librechat.yaml (copy librechat.example.yaml; mount it with docker-compose.override.yml.example)`
- **local-and-custom-models** [settings]: Add Ollama, OpenRouter, Groq, Mistral or any OpenAI-compatible provider to the model menu. → `librechat.yaml → endpoints.custom (e.g. Ollama at http://host.docker.internal:11434/v1)`
- **agents-and-prompts** [settings]: Make helpers with their own instructions, files and tools, e.g. "Homework Helper" or "Recipe Planner". → `In the app → Agents panel and Prompts library (side panel); share with users and groups`
- **users-and-roles** [settings]: Create family accounts, set permissions per role, and optional token budgets per person. → `Admin panel (port 3000 in the default compose) and npm scripts in package.json (create-user, invite-user, set-balance)`
- **mcp-tools** [extend]: Plug in MCP servers so the AI can use other apps, such as a calendar, notes or Home Assistant. → `librechat.yaml → mcpServers (docs/mcp-apps.md)`
- **agents-api** [extend]: Call your agents from scripts or other apps. → `Agent Management API and OpenAPI docs (docs/skills-management-api.md); API keys in the app`
- **theme-and-text** [code]: Colours, fonts and wording beyond what the settings allow. → `client/src/style.css, client/tailwind.config.cjs, client/src/locales/en/translation.json`
- **chat-ui** [code]: Change the chat screens, e.g. a simpler start screen for children or older relatives. → `client/src/components/Chat/** (Landing.tsx is the start screen), client/src/components/Nav/**`
- **backend-features** [code]: New server behaviour. New options belong in configSchema so they can be set in librechat.yaml. → `packages/api/src/** (new behaviour), packages/data-schemas (database), packages/data-provider/src/config.ts (config schema); api/ is wiring only`

## Must keep working
- Existing users, conversations, agents and uploaded files. Back up MongoDB and the uploads folder before upgrades or code changes.
- CREDS_KEY and CREDS_IV must never change once set, or stored API keys become unreadable.
- Privacy between users. One person must never see another's chats, files or memories.
- Keep new backend logic in packages/api (TypeScript), not in the legacy api/ folder, as AGENTS.md requires.

## Staying updatable
Nearly all personalisation lives in .env and librechat.yaml, which survive updates. LibreChat welcomes AI-assisted pull requests, but only for issues you have been assigned; patches generated from the issue tracker without that are rejected (see .github/CONTRIBUTING.md). Keep personal UI changes in your own copy.

## Data, costs and safety
- Personal data: **yes**. Stored in: Accounts, conversations, presets, agents and memories in MongoDB (./data-node). Uploaded files and images in ./uploads and ./images. Document chunks for file search in the pgvector database (pgdata2 volume). Settings in .env and librechat.yaml. Chats can hold very personal things: health worries, money, family matters. Back up ./data-node, ./uploads, ./images, .env and librechat.yaml together (stop the containers first, or use mongodump). Keep CREDS_KEY/CREDS_IV safe; without them, saved API keys can't be read.
- Service: AI model providers (OpenAI, Anthropic, Google, Mistral, OpenRouter, Groq, DeepSeek…) (optional, pay-per-use with your own API key; each person can also enter their own key): The models you chat with. At least one provider or a local model is needed for the app to be useful.
- Service: Ollama or another local OpenAI-compatible server (optional, free (uses your own computer)): Run chat models privately on your own hardware instead of sending messages to a company.
- Service: Embeddings for file search (RAG API, OpenAI by default) (optional, small pay-per-use, or free with a local embeddings model): Lets you chat with uploaded PDFs and documents. The bundled rag_api container needs an embeddings provider.
- Service: Web search providers (e.g. Serper, SearXNG, Firecrawl, Jina) (optional, free tiers or pay-per-use; SearXNG is free and self-hosted): Lets the AI look things up on the internet and cite sources.
- Service: Email (SMTP) (optional, free with most providers): Password resets and email verification.
- Setting `PORT`: Port the app listens on (3080 by default).
- Setting `DOMAIN_CLIENT`: The address people open LibreChat at, e.g. https://chat.example.com. Keep DOMAIN_SERVER the same.
- Setting `DOMAIN_SERVER`: Address of the API, normally the same as DOMAIN_CLIENT.
- Setting `ADMIN_PANEL_SESSION_SECRET` (**secret**: the person enters it themselves, never in chat): Random string (32+ characters) for the bundled admin panel. Required by the default docker-compose.yml.
- Setting `CREDS_KEY` (**secret**: the person enters it themselves, never in chat): Encryption key for stored API keys. Blank means temporary generated values; set your own before real use.
- Setting `CREDS_IV` (**secret**: the person enters it themselves, never in chat): Partner value for CREDS_KEY. Set both once and never lose them, or saved keys can't be decrypted.
- Setting `JWT_SECRET` (**secret**: the person enters it themselves, never in chat): Signs login sessions. Set a long random value before real use.
- Setting `JWT_REFRESH_SECRET` (**secret**: the person enters it themselves, never in chat): Signs "stay logged in" tokens. Set a long random value before real use.
- Setting `ALLOW_REGISTRATION`: Set to false once your family has accounts, so strangers can't sign up.
- Setting `ALLOW_SOCIAL_LOGIN`: Allow logging in with Google, GitHub, Discord and similar (needs their client IDs).
- Setting `OPENAI_API_KEY` (**secret**: the person enters it themselves, never in chat): Your OpenAI key, or "user_provided" so each person enters their own.
- Setting `ANTHROPIC_API_KEY` (**secret**: the person enters it themselves, never in chat): Your Anthropic (Claude) key, or "user_provided".
- Setting `GOOGLE_KEY` (**secret**: the person enters it themselves, never in chat): Your Google Gemini key, or "user_provided".
- Setting `SEARCH`: true turns on searching across all your past messages (needs MEILI_MASTER_KEY).
- Setting `MEILI_MASTER_KEY` (**secret**: the person enters it themselves, never in chat): Password for the Meilisearch container that powers message search.
- Setting `APP_TITLE`: The name shown in the browser tab and on the login page.
- Setting `CUSTOM_FOOTER`: Your own footer text under the chat box.
- Setting `HELP_AND_FAQ_URL`: Where the "Help & FAQ" link goes (or "/" to hide it).
- Turn off ALLOW_REGISTRATION after creating your accounts, and use HTTPS behind a reverse proxy before opening it to the internet.
- Messages, uploaded files and memories are sent to whichever AI provider you pick for that chat. Use Ollama or another local model for anything you don't want to leave your home.
- API keys live in .env (and per-user keys encrypted with CREDS_KEY). Never paste .env into an AI chat, and set your own JWT and CREDS secrets before real use.
- Agents with code execution, MCP tools or attached workspaces can take real actions. Only enable them for people you trust.

---

# Customising LibreChat

LibreChat is a big, fast-moving project. The good news: **almost everything a household wants is a setting**, split between `.env` (secrets, sign-up rules, provider keys) and `librechat.yaml` (interface, models, agents, memory, search). Exhaust levels 1 and 2 before touching code.

## Level 1: Settings (no code)
- **Name and footer:** `APP_TITLE`, `CUSTOM_FOOTER` and `HELP_AND_FAQ_URL` in `.env`. Restart the containers.
- **Who can get in:** create your accounts first (the first account becomes the admin), then set `ALLOW_REGISTRATION=false`. `npm run create-user` and `npm run invite-user` add people later. Social login (`ALLOW_SOCIAL_LOGIN`) needs each provider's client ID.
- **Which AIs appear:** put keys in `.env` (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_KEY`…) or set them to `user_provided` so each person enters their own.
- **`librechat.yaml`:** copy `librechat.example.yaml` to `librechat.yaml` and mount it by copying `docker-compose.override.yml.example` to `docker-compose.override.yml`. Useful sections:
  - `interface:` welcome message (`customWelcome`), privacy policy and terms links, and which side-panel features show.
  - `endpoints.custom:` add Ollama (`baseURL: http://host.docker.internal:11434/v1`), OpenRouter, Groq, Mistral or any OpenAI-compatible server.
  - `modelSpecs:` ready-made presets that appear in the model menu, e.g. "Homework Helper" with its own instructions. You can make them the only choices.
  - `memory:`, `webSearch:`, `speech:`, `fileConfig:` and `balance:` (per-user token allowance; top up with `npm run set-balance`).
- **Agents and prompts:** in the app, the Agents panel builds helpers with instructions, files and tools; the Prompts library stores reusable prompts. Both can be shared with chosen users or groups.
- **Admin panel:** the default compose file starts it on port 3000 (needs `ADMIN_PANEL_SESSION_SECRET`). Manage users, groups, roles and many settings live.

## Level 2: Extend (no fork)
- **MCP servers** (`mcpServers:` in `librechat.yaml`, see `docs/mcp-apps.md`): give agents access to other apps such as a calendar, notes or a smart home.
- **Actions:** agents can call any web API described by an OpenAPI spec (`actions:` allow-list in `librechat.yaml`).
- **Agent Management API** (`docs/skills-management-api.md`): create and run agents from scripts.
- **Skills:** reusable `SKILL.md` instruction bundles for agents (`skill/README.md`).
- **Self-hosted web search:** point `webSearch` at a SearXNG instance instead of a paid search API.

## Level 3: Code
Read upstream `AGENTS.md` and `CONTEXT.md` first. They are strict about where code goes.

| Change | Where |
|---|---|
| Start screen | `client/src/components/Chat/Landing.tsx` |
| Chat screens and sidebar | `client/src/components/Chat/**`, `client/src/components/Nav/**`, `client/src/components/SidePanel/**` |
| Colours and fonts | `client/src/style.css`, `client/tailwind.config.cjs` |
| Wording | `client/src/locales/en/translation.json` (other languages are synced via Locize) |
| New server behaviour | `packages/api/src/**` (TypeScript). `api/` only wires routes to it |
| Database | `packages/data-schemas/` |
| New setting in `librechat.yaml` | `configSchema` in `packages/data-provider/src/config.ts`, with a default that keeps today's behaviour |
| Built-in tools | `api/app/clients/tools/structured/` (prefer MCP for new tools) |

## Running locally
- **Just use it:**
  1. `git clone https://github.com/danny-avila/LibreChat.git && cd LibreChat`
  2. `cp .env.example .env`, then set `ADMIN_PANEL_SESSION_SECRET` (`openssl rand -hex 32`) and at least one AI key.
  3. `docker compose up -d`, then open http://localhost:3080.
- **Develop:**
  1. Install Node 24 (`.nvmrc`) and have MongoDB reachable (`MONGO_URI` in `.env`).
  2. Run `npm ci`, then `npm run build:packages`.
  3. Start the API with `npm run backend:dev` (port 3080).
  4. Start the client with `npm run frontend:dev` (port 3090).
- **Check:** `npm run lint`, `npm run test:client`, `npm run test:api`, and `npx tsc --noEmit` in each package you changed.

## Pitfalls
- Never change `CREDS_KEY`/`CREDS_IV` after setting them; stored keys become unreadable.
- Don't edit `docker-compose.yml` directly. Use `docker-compose.override.yml` so updates apply cleanly.
- `librechat.yaml` has a `version:` line. After upgrading, compare with the new `librechat.example.yaml` and read the changelog for breaking changes.
- File search (the `rag_api` container) needs an embeddings provider. Without one, uploads for "chat with files" fail.
- Back up MongoDB (`./data-node`), `./uploads`, `./images`, `.env` and `librechat.yaml` before upgrades or code changes.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/librechat/eac18f4/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/librechat/eac18f4/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/librechat/eac18f4/r2/SKILL.md)