huggingface/chat-ui

📣 What is huggingface/chat‑ui?

A lightweight, open‑source web front‑end for chatting with any OpenAI‑compatible language‑model endpoint. It is built with SvelteKit and powers the public HuggingChat service (hf.co/chat). The UI handles user accounts, chat history, model selection, theming, and optional tool‑calling (MCP) or multimodal input, while delegating all inference to an external API that speaks the OpenAI /v1 protocol (e.g., Hugging Face Inference Router, llama.cpp server, Ollama, OpenRouter, etc.).

🎯 Core capabilities

Feature	How it works	Why it matters
Model‑agnostic backend	Connects to any service exposing the OpenAI `/v1` API via `OPENAI_BASE_URL` and `OPENAI_API_KEY`.	Lets you swap between hosted HF models, local `llama.cpp`, Ollama, or any commercial provider without code changes.
Chat persistence	Stores users, conversations, settings, and file uploads in MongoDB. By default it falls back to an embedded MongoDB that writes to `./db`.	Keeps history across sessions and works out‑of‑the‑box for local development.
Omni router (optional)	A built‑in heuristic that selects a route (default, multimodal, or tool‑enabled) and then a concrete model for each request. Configurable via JSON policy files and env vars.	Gives a single “Omni” model entry that automatically picks the best backend for images, function‑calling, or plain text.
MCP tool integration	Supports Model Context Protocol servers; the UI can call external tools (search, database lookup, etc.) and feed results back to the model using OpenAI function‑calling.	Enables richer, agentic conversations without writing custom backend code.
Theming & branding	Simple env vars (`PUBLIC_APP_NAME`, `PUBLIC_APP_ASSETS`, etc.) let you rename the app, swap logos, or toggle a data‑sharing opt‑in.	Makes it easy to embed the UI in a product or community site.
Docker ready	An official `ghcr.io/huggingface/chat-ui-db` image bundles the UI + an embedded MongoDB, exposing the same env‑var interface.	One‑command deployment to any container host or cloud service.
ML Intern mode	Experimental “assistant” that can generate and run Hugging Face Hub jobs (paper reproduction, fine‑tuning, dataset creation) within a conversation, respecting a per‑user compute budget.	Turns the chat UI into a low‑code ML workflow orchestrator.

🛠️ Getting started (quick‑start)

Create a .env.local with at least:

OPENAI_BASE_URL=https://router.huggingface.co/v1   # or any OpenAI‑compatible URL
OPENAI_API_KEY=hf_XXXXXXXXXXXXXXXXXXXXXXXXX      # your token or dummy key for local servers

Clone & install

git clone https://github.com/huggingface/chat-ui
cd chat-ui
npm install
npm run dev -- --open   # launches http://localhost:5173

(Optional) Add MongoDB – set MONGODB_URL to a remote Atlas cluster or run a local container:
```
docker run -d -p 27017:27017 --name mongo-chatui mongo:latest
```
If MONGODB_URL is omitted, an embedded DB is used automatically.

Deploy – for production run npm run build && npm run preview or use the provided Docker image:

docker run -p 3000:3000 \
  -e OPENAI_BASE_URL=… -e OPENAI_API_KEY=… \
  -v chat-ui-data:/data \
  ghcr.io/huggingface/chat-ui-db:latest

📚 Typical use‑cases

Self‑hosted ChatGPT‑like UI for a private model (e.g., a company’s internal LLM) without building a front‑end from scratch.
Demo platform for research models: plug a llama.cpp server or an Ollama model and let users interact via a polished web UI.
Tool‑augmented agents: expose search or code‑execution services through MCP and let the model call them automatically.
Multimodal experiments: route image inputs to a vision‑capable model via the Omni router.
ML Intern playground: let non‑technical users trigger fine‑tuning jobs or dataset builds directly from chat.

⚠️ Limitations & gotchas

Only OpenAI‑style APIs – providers that use a different protocol (e.g., native Hugging Face pipeline endpoints) are not supported.
No built‑in model discovery beyond /models – you must expose a /models list on your backend or manually configure the MODELS env var.
Router policy file is required for custom routing – the default branch ships no sample JSON; you need to create one if you want anything beyond the built‑in heuristic.
MCP support depends on the model’s function‑calling capability; if the selected model does not advertise tools, the UI will hide the feature.
Production deployment still needs a SvelteKit adapter (e.g., Vercel, Netlify, Cloudflare) – the README mentions this but does not provide a ready‑made config.

📦 TL;DR

huggingface/chat‑ui is a ready‑to‑run, SvelteKit‑based web chat front‑end that works with any OpenAI‑compatible LLM endpoint. It offers persistent history via MongoDB, optional smart routing (Omni), tool integration through MCP, theming, and a Docker image for easy deployment. Perfect for anyone who wants a polished chat interface without writing UI code, while still being able to plug in local or cloud LLMs, multimodal models, or agentic tool‑calling.