chat-ui README

The project's README from github.com/huggingface/chat-ui. As one markdown file: README.md.

Chat UI

Chat UI repository thumbnail

A chat interface for LLMs. It is a SvelteKit app and it powers the HuggingChat app on hf.co/chat.

  1. Quickstart
  2. Database Options
  3. Launch
  4. Optional Docker Image
  5. Extra parameters
  6. Building

[!NOTE] Chat UI only supports OpenAI-compatible APIs via OPENAI_BASE_URL and the /models endpoint. Provider-specific integrations (legacy MODELS env var, GGUF discovery, embeddings, web-search helpers, etc.) are removed, but any service that speaks the OpenAI protocol (llama.cpp server, Ollama, OpenRouter, etc.) will work by default.

[!NOTE] The old version is still available on the legacy branch

Quickstart

Chat UI speaks to OpenAI-compatible APIs only. The fastest way to get running is with the Hugging Face Inference Providers router plus your personal Hugging Face access token.

Step 1 – Create .env.local:

OPENAI_BASE_URL=https://router.huggingface.co/v1
OPENAI_API_KEY=hf_************************

OPENAI_API_KEY can come from any OpenAI-compatible endpoint you plan to call. Pick the combo that matches your setup and drop the values into .env.local:

Provider Example OPENAI_BASE_URL Example key env
Hugging Face Inference Providers router https://router.huggingface.co/v1 OPENAI_API_KEY=hf_xxx (or HF_TOKEN legacy alias)
llama.cpp server (llama.cpp --server --api) http://127.0.0.1:8080/v1 OPENAI_API_KEY=sk-local-demo (any string works; llama.cpp ignores it)
Ollama (with OpenAI-compatible bridge) http://127.0.0.1:11434/v1 OPENAI_API_KEY=ollama
OpenRouter https://openrouter.ai/api/v1 OPENAI_API_KEY=sk-or-v1-...
Poe https://api.poe.com/v1 OPENAI_API_KEY=pk_...

Check the root .env template for the full list of optional variables you can override.

Step 2 – Install and launch the dev server:

git clone https://github.com/huggingface/chat-ui
cd chat-ui
npm install
npm run dev -- --open

You now have Chat UI running locally. Open the browser and start chatting.

Database Options

Chat history, users, settings, files, and stats all live in MongoDB. You can point Chat UI at any MongoDB 6/7 deployment.

[!TIP] For quick local development, you can skip this section. When MONGODB_URL is not set, Chat UI falls back to an embedded MongoDB that persists to ./db.

MongoDB Atlas (managed)

  1. Create a free cluster at mongodb.com.
  2. Add your IP (or 0.0.0.0/0 for development) to the network access list.
  3. Create a database user and copy the connection string.
  4. Paste that string into MONGODB_URL in .env.local. Keep the default MONGODB_DB_NAME=chat-ui or change it per environment.

Atlas keeps MongoDB off your laptop, which is ideal for teams or cloud deployments.

Local MongoDB (container)

If you prefer to run MongoDB in a container:

docker run -d -p 27017:27017 --name mongo-chatui mongo:latest

Then set MONGODB_URL=mongodb://localhost:27017 in .env.local.

Launch

After configuring your environment variables, start Chat UI with:

npm install
npm run dev

The dev server listens on http://localhost:5173 by default. Use npm run build / npm run preview for production builds.

Optional Docker Image

The chat-ui-db image bundles MongoDB inside the container:

docker run \
  -p 3000:3000 \
  -e OPENAI_BASE_URL=https://router.huggingface.co/v1 \
  -e OPENAI_API_KEY=hf_*** \
  -v chat-ui-data:/data \
  ghcr.io/huggingface/chat-ui-db:latest

All environment variables accepted in .env.local can be provided as -e flags.

Extra parameters

Theming

You can use a few environment variables to customize the look and feel of chat-ui. These are by default:

PUBLIC_APP_NAME=ChatUI
PUBLIC_APP_ASSETS=chatui
PUBLIC_APP_DESCRIPTION="Making the community's best AI chat models available to everyone."
PUBLIC_APP_DATA_SHARING=

Models

Models are discovered from ${OPENAI_BASE_URL}/models, and you can optionally override their metadata via the MODELS env var (JSON5). Legacy provider‑specific integrations and GGUF discovery are removed. Authorization uses OPENAI_API_KEY (preferred). HF_TOKEN remains a legacy alias.

LLM Router (Optional)

Chat UI can perform server-side smart routing using a local heuristic — no separate router service or selection model is called. The UI exposes a virtual model alias called "Omni" (configurable) that, when selected, chooses the best route/model for each message: image inputs go to a multimodal route, MCP-tool-enabled requests go to an agentic route, and everything else goes to a default route.

When you select Omni in the UI, Chat UI will:

Tool and multimodal shortcuts:

MCP Tools (Optional)

Chat UI can call tools exposed by Model Context Protocol (MCP) servers and feed results back to the model using OpenAI function calling. You can preconfigure trusted servers via env, let users add their own, and optionally have the Omni router auto‑select a tools‑capable model.

Configure servers (base list for all users):

# JSON array of servers: name, url, optional headers
MCP_SERVERS=[
  {"name": "Web Search (Exa)", "url": "https://mcp.exa.ai/mcp"},
  {"name": "Hugging Face MCP Login", "url": "https://hf.co/mcp?login"}
]

# Forward the signed-in user's Hugging Face token to the official HF MCP login endpoint
# when no Authorization header is set on that server entry.
MCP_FORWARD_HF_USER_TOKEN=true

Enable router tool path (Omni):

Use tools in the UI:

Per‑model overrides:

Building

To create a production version of your app:

npm run build

You can preview the production build with npm run preview.

To deploy your app, you may need to install an adapter for your target environment.

chat-ui (huggingface/chat-ui)

Searching Database…

11K ·GitHub
Chat-ui
Что это такое?Chat UI — это интерфейс чата с открытым исходным кодом, на котором построено приложение HuggingChat от Hugging Face (hf.co/chat). Это веб-приложение на SvelteKit, которое можно развернуть на своём сервере, чтобы общаться с LLM через любой API, совместимый с OpenAI.
Это библиотека, которую я подключаю в проект, или отдельное приложение, которое я запускаю?Это самостоятельное веб-приложение на SvelteKit, а не библиотека. Его развёртывают у себя (через npm или Docker) и указывают адрес эндпоинта модели, совместимого с OpenAI.
Как это запустить?Создайте файл .env.local с переменными OPENAI_BASE_URL и OPENAI_API_KEY, которые указывают на эндпоинт, совместимый с OpenAI (например, HF Inference Providers, llama.cpp, Ollama, OpenRouter), затем выполните npm install и npm run dev.
Что нужно помимо Node.js — база данных, API-ключ?Нужны API-ключ и эндпоинт, совместимые с OpenAI, для модели, а также MongoDB 6/7 для хранения чатов, пользователей и настроек. Если не задать MONGODB_URL, приложение использует встроенную MongoDB, которая сохраняет данные в ./db. Это удобно для быстрого локального тестирования.
Поддерживаются ли ещё интеграции, специфичные для провайдеров, например GGUF или встроенный веб-поиск?Нет. Устаревшие функции, привязанные к конкретным провайдерам (старая переменная окружения MODELS, поиск GGUF, эмбеддинги, вспомогательные модули веб-поиска), удалены. Сейчас поддерживаются только API, совместимые с OpenAI, но прежний набор функций сохранён в старой ветке проекта.
Что такое маршрутизатор моделей Omni?Omni — это виртуальный псевдоним модели, который с помощью локальной эвристики выбирает лучший маршрут для каждого сообщения: изображения отправляются мультимодальной модели, запросы с включёнными инструментами MCP — агентной модели, а всё остальное обрабатывает модель по умолчанию. Если маршрут не срабатывает, включается автоматический запасной вариант.
Может ли Chat UI вызывать внешние инструменты?Да, через серверы Model Context Protocol (MCP). Можно заранее настроить доверенные серверы или дать пользователям добавлять свои. Модель вызывает их инструменты через вызов функций OpenAI (function calling), а результаты показываются прямо в чате.
Можно ли изменить интерфейс под свой проект?Да. Переменные окружения PUBLIC_APP_NAME и PUBLIC_APP_ASSETS позволяют сменить название приложения, логотип и набор фавиконок, а PUBLIC_APP_DATA_SHARING добавляет в настройки пользователя переключатель согласия на передачу данных.
Есть ли готовый Docker-образ?Да, образ chat-ui-db включает MongoDB внутри контейнера, поэтому весь стек запускается одной командой Docker, а переменные окружения передаются флагами -e.
What are similar projects?gpt4free, open-glean, chatgpt-web, anythingmcp, jevbox, typebot.io, LibreChat, whirl
Which topics is it in?sveltekit, svelte, mongodb, chat, tailwindcss, chatgpt, openai-compatible, large-language-models, model-context-protocol, chatbot, huggingface, docker-compose
Creator
huggingface
Size
16.4 MB
Stars
11K
Updated
CommitOct 15Releasev0.10.0May 11
Age
3y
Commits · 90 Days