Deploy and Host Hugging Face Chat UI on Railway

Chat UI is the open source app that powers HuggingChat. It is a fast SvelteKit chat interface for any OpenAI-compatible API, with conversation history, file attachments, shareable conversations and MCP tool support. Bring a Hugging Face token, an OpenAI key, or point it at your own LiteLLM or Ollama endpoint.

About Hosting Hugging Face Chat UI

Hosting Chat UI means running the app next to MongoDB, which stores conversations, settings, sessions and uploaded files. This template uses the official ghcr.io/huggingface/chat-ui image pinned to a fixed build, a dedicated MongoDB service with its own volume and generated credentials, and a small Caddy gateway.

The gateway matters: Chat UI has no login of its own unless you connect an OpenID Connect provider, so an exposed instance lets anyone chat on your API key. Here the Chat UI service has no public domain. The gateway is the only public service, asks for a generated username and password, and streams model responses through without buffering.

What's Included

Chat UI (ghcr.io/huggingface/chat-ui:sha-90b4c86): the app, private, healthcheck on /healthcheck
MongoDB (mongo:8.0.34): private, authentication on, one volume at /data/db
chat-ui-gateway (caddy:2.11-alpine): public, basic auth with a generated password

First Steps After Deploy

Open the chat-ui-gateway service and copy UI_USERNAME and UI_PASSWORD from its Variables tab.
Open the gateway's public domain and sign in with those values.
Set OPENAI_API_KEY on the Chat UI service. With the default Hugging Face router this is a Hugging Face access token that has the Inference Providers permission. The app boots and lists models without it, but messages fail until it is set.
Optional: point OPENAI_BASE_URL at another OpenAI-compatible provider. Set the URL and the key in the same change, because Chat UI loads the model list at startup and exits if that request is refused.

Common Use Cases

Private ChatGPT style interface for a team, on models you choose
Front end for an LLM gateway such as LiteLLM, Bifrost or OpenRouter
Chat with open models through Hugging Face Inference Providers
MCP tools in chat: connect MCP servers and let tool capable models call them

Key Environment Variables

# Chat UI
OPENAI_BASE_URL=https://router.huggingface.co/v1
OPENAI_API_KEY=                 # your provider key, needed to chat
MONGODB_URL=${{MongoDB.MONGO_URL}}
PUBLIC_ORIGIN=https://${{chat-ui-gateway.RAILWAY_PUBLIC_DOMAIN}}
MCP_OAUTH_ENCRYPTION_KEY=${{secret(48)}}
PORT=3000
HOST=::

# MongoDB
MONGO_INITDB_ROOT_USERNAME=chatui
MONGO_INITDB_ROOT_PASSWORD=${{secret(32)}}

# chat-ui-gateway
UI_USERNAME=admin
UI_PASSWORD=${{secret(24)}}

Optional on Chat UI: TASK_MODEL (model used for titles), MODELS (per model overrides), MCP_SERVERS (default MCP servers), and OPENID_CLIENT_ID, OPENID_CLIENT_SECRET, OPENID_PROVIDER_URL, OPENID_SCOPES for per user login through OpenID Connect.

Dependencies for Hugging Face Chat UI Hosting

MongoDB: required, included
An OpenAI-compatible provider key: optional at boot, required to get answers
OpenID Connect provider: optional, for per user accounts

Deployment Dependencies

Implementation Details

Without OpenID Connect, each browser gets its own anonymous session, kept in a cookie for two weeks. Conversations belong to that session, so a different browser starts with an empty history. Configure OpenID Connect if several people need their own accounts.

MongoDB's root password is applied on the first boot only. A custom domain belongs on the chat-ui-gateway service, and PUBLIC_ORIGIN on Chat UI should then be updated to match.

Why Deploy Hugging Face Chat UI on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Hugging Face Chat UI on Railway, you get the HuggingChat interface with a private MongoDB, generated credentials, a password gateway, health checks and managed SSL, ready for the provider key of your choice.