.env

# Use .env.local to change these variables
# DO NOT EDIT THIS FILE WITH SENSITIVE DATA

### Models ###
# Models are sourced exclusively from an OpenAI-compatible base URL.
# Example: https://router.huggingface.co/v1
OPENAI_BASE_URL=https://router.huggingface.co/v1

# Canonical auth token for any OpenAI-compatible provider
OPENAI_API_KEY=#your provider API key (works for HF router, OpenAI, LM Studio, etc.). 
# When set to true, user token will be used for inference calls
USE_USER_TOKEN=false
# Automatically redirect to oauth login page if user is not logged in, when set to "true"
AUTOMATIC_LOGIN=false

### MongoDB ###
MONGODB_URL=#your mongodb URL here, use chat-ui-db image if you don't want to set this
MONGODB_DB_NAME=chat-ui
MONGODB_DIRECT_CONNECTION=false


## Public app configuration ##
PUBLIC_APP_NAME=ChatUI # name used as title throughout the app
PUBLIC_APP_ASSETS=chatui # used to find logos & favicons in static/$PUBLIC_APP_ASSETS
PUBLIC_APP_DESCRIPTION="Making the community's best AI chat models available to everyone."# description used throughout the app
PUBLIC_ORIGIN=
PUBLIC_SHARE_PREFIX=
PUBLIC_GOOGLE_ANALYTICS_ID=
PUBLIC_PLAUSIBLE_SCRIPT_URL=
PUBLIC_APPLE_APP_ID=
# Caveat text shown below the chat input on new chats.
# Defaults to "Generated content may be inaccurate or false." if unset.
PUBLIC_CAVEAT=
# Feature announcements shown as a toast on the home screen (no conversation open).
# JSON5 array of { title, description, link?, cta?, maxDate? }; the last valid entry is shown.
# cta overrides the link label (defaults to "Learn more").
# maxDate auto-hides the announcement after that date; a date-only value like "2026-12-31"
# is inclusive (hides at the end of that day, UTC).
# Example: PUBLIC_FEATURE_ANNOUNCEMENTS=[{"title":"Gemma-4-31B at 700 tokens/s","description":"Run Gemma-4-31B at 700 tokens/s thanks to Cerebras inference.","link":"/models/google/gemma-4-31B-it","cta":"Go to the model","maxDate":"2026-12-31"}]
PUBLIC_FEATURE_ANNOUNCEMENTS=

COUPLE_SESSION_WITH_COOKIE_NAME=
# when OPEN_ID is configured, users are required to login after the welcome modal
OPENID_CLIENT_ID="" # You can set to "__CIMD__" for automatic oauth app creation when deployed, see https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/
OPENID_CLIENT_SECRET=
# "jobs" lets the app start Hugging Face Jobs as the user, which ML Intern and any Hub MCP job
# tool need; without it every submission returns 403. Add "contribute-repos" to let users deploy
# artifacts to a Space (the app can create Spaces and update only the ones it created). Both
# require the OAuth app to permit the scope, and both are Hugging Face OIDC scopes: drop them for
# a generic provider that lacks them.
OPENID_SCOPES="openid profile inference-api read-mcp read-billing jobs"
USE_USER_TOKEN=
AUTOMATIC_LOGIN=# if true authentication is required on all routes

### Local Storage ###
MONGO_STORAGE_PATH= # where is the db folder stored

## Models overrides
MODELS=

## Task model
# Optional: set to the model id/name from the `${OPENAI_BASE_URL}/models` list
# to use for internal tasks (title summarization, etc). If not set, the current model will be used
TASK_MODEL=

## LLM Router Configuration
# Path to routes policy (JSON array). Required when the router is enabled; must point to a valid JSON file.
# The router uses heuristic-based selection to pick the best model for each request.
LLM_ROUTER_ROUTES_PATH=

# Default route to use when no specific heuristic matches (defaults to "default")
LLM_ROUTER_DEFAULT_ROUTE=default
# Model to use as fallback if the selected route's models are unavailable
LLM_ROUTER_FALLBACK_MODEL=

# Enable router multimodal handling (set to true to allow image inputs via router)
LLM_ROUTER_ENABLE_MULTIMODAL=
# Required when LLM_ROUTER_ENABLE_MULTIMODAL=true: id or name of the multimodal model to use for image requests
LLM_ROUTER_MULTIMODAL_MODEL=

# Enable router tool support (set to true to allow tool calling via router)
LLM_ROUTER_ENABLE_TOOLS=
# Required when tools are active: id or name of the model to use for MCP tool calls.
LLM_ROUTER_TOOLS_MODEL=

# Router UI overrides (client-visible)
# Public display name for the router entry in the model list. Defaults to "Omni".
PUBLIC_LLM_ROUTER_DISPLAY_NAME=Omni
# Optional: public logo URL for the router entry. If unset, the UI shows a Carbon icon.
PUBLIC_LLM_ROUTER_LOGO_URL=
# Public alias id used for the virtual router model (Omni). Defaults to "omni".
PUBLIC_LLM_ROUTER_ALIAS_ID=omni

### Transcription ###
# Voice-to-text transcription using Whisper models
# If set, enables the microphone button in the chat input
# Example: openai/whisper-large-v3-turbo
TRANSCRIPTION_MODEL=
# Optional: Base URL for transcription API (defaults to HF inference)
# Default: https://router.huggingface.co/hf-inference/models
TRANSCRIPTION_BASE_URL=

### Authentication ###
# Parameters to enable open id login
OPENID_CONFIG=
# if it's defined, only these emails will be allowed to use login
ALLOWED_USER_EMAILS=[]
# If it's defined, users with emails matching these domains will also be allowed to use login
ALLOWED_USER_DOMAINS=[]
# valid alternative redirect URLs for OAuth, used for HuggingChat apps
ALTERNATIVE_REDIRECT_URLS=[] 
### Cookies
# name of the cookie used to store the session
COOKIE_NAME=hf-chat
# If the value of this cookie changes, the session is destroyed. Useful if chat-ui is deployed on a subpath
# of your domain, and you want chat ui sessions to reset if the user's auth changes
COUPLE_SESSION_WITH_COOKIE_NAME=
# specify secure behaviour for cookies 
COOKIE_SAMESITE=# can be "lax", "strict", "none" or left empty
COOKIE_SECURE=# set to true to only allow cookies over https
TRUSTED_EMAIL_HEADER=# header to use to get the user email, only use if you know what you are doing

### Admin stuff ###
ADMIN_CLI_LOGIN=true # set to false to disable the CLI login
ADMIN_TOKEN=#We recommend leaving this empty, you can get the token from the terminal.

### Feature Flags ###
LLM_SUMMARIZATION=true # generate conversation titles with LLMs

ALLOW_IFRAME=true # Allow the app to be embedded in an iframe

# Artifacts (models emit self-contained apps/docs/diagrams rendered in a side panel)
# are opt-in per model: set `"supportsArtifacts": true` on a model entry in the
# MODELS overrides below.

# Base servers list (JSON array). Example: MCP_SERVERS=[{"name": "Web Search (Exa)", "url": "https://mcp.exa.ai/mcp"}, {"name": "Hugging Face", "url": "https://hf.co/mcp"}]
MCP_SERVERS=
# When true, forward the logged-in user's Hugging Face access token
MCP_FORWARD_HF_USER_TOKEN=
# Exa API key (injected at runtime into mcp.exa.ai URLs as ?exaApiKey=)
EXA_API_KEY=
# How long an MCP tool call may go without the server responding (default: 120000 = 2
# minutes). Time spent waiting on a user to answer an elicitation does not count against it.
MCP_TOOL_TIMEOUT_MS=
# GitHub personal access token for the code-grounding tools that ML Assistant
# conversations use to read example scripts from upstream repositories.
#
# Create it with NO scopes at all. Every endpoint these tools call already answers
# unauthenticated on a public repo, so a scope would grant nothing they need; the
# token is here only for the rate limit, which it raises from 60 requests an hour
# to 5,000 (and search from 10 a minute to 30). In particular do NOT tick
# `public_repo` — despite the name it is read/WRITE access to every public repo
# you can reach. A fine-grained token wants "Public repositories (read-only)" and
# no permissions added.
#
# This is an application credential, not the user's — there is no per-user GitHub
# OAuth anywhere. Granting private-repo access would be a different decision, and
# would need one. Leave it empty and the tools are not offered to the model.
GITHUB_TOKEN=

# Set to "true" to allow MCP server URLs over http on localhost / private LAN addresses.
# Local development and the e2e harness only — never enable in production.
MCP_ALLOW_INSECURE_URLS=
# Set to "true" to stop advertising the `elicitation` client capability, so servers can
# never interrupt a tool call to ask the user for input.
MCP_DISABLE_ELICITATION=
# How long (ms) an elicitation prompt stays answerable (default: 3600000 = 1 hour), so
# someone who walks away can still answer when they get back. Independent of
# MCP_TOOL_TIMEOUT_MS — the tool call's deadline is paused while the prompt is open.
# On a 2026-era connection this is the ONLY bound: the server answered with
# `input_required` and is no longer waiting, so nothing else expires. On a 2025-era one
# the server's own timeout on its request (60s by SDK default) usually gives up first.
MCP_ELICITATION_TIMEOUT_MS=
# How often (ms) to sweep for generations whose pod died mid-run and mark them
# interrupted. Default 60000.
GENERATION_REAP_INTERVAL_MS=
# How often to look for parked turns whose timer is due. Default 10000. The
# interval is the floor on how late a wake can be, so it wants to stay well
# below the shortest wait a tool can ask for.
PARKED_SWEEP_INTERVAL_MS=
# A run with no heartbeat for this long (ms) is presumed dead and finalized.
# Must stay well above GENERATION_HEARTBEAT_MS or live runs get reaped. Default 90000.
GENERATION_REAP_AFTER_MS=
# How often (ms) a running generation touches its heartbeat. Default 10000.
GENERATION_HEARTBEAT_MS=
ENABLE_DATA_EXPORT=true

### Rate limits ### 
# See `src/lib/server/usageLimits.ts`
# {
#   conversations: number, # how many conversations
#   messages: number, # how many messages in a conversation
#   assistants: number, # how many assistants
#   messageLength: number, # how long can a message be before we cut it off
#   messagesPerMinute: number, # how many messages per minute
#   tools: number # how many tools
# }
USAGE_LIMITS={}

### HuggingFace specific ###
## Feature flag & admin settings
# Used for setting early access & admin flags to users
HF_ORG_ADMIN=
HF_ORG_EARLY_ACCESS=
WEBHOOK_URL_REPORT_ASSISTANT=#provide slack webhook url to get notified for reports/feature requests


### Metrics ###
METRICS_ENABLED=false
METRICS_PORT=5565
LOG_LEVEL=info


### Parquet export ###
# Not in use anymore but useful to export conversations to a parquet file as a HuggingFace dataset
PARQUET_EXPORT_DATASET=
PARQUET_EXPORT_HF_TOKEN=
ADMIN_API_SECRET=# secret to admin API calls, like computing usage stats or exporting parquet data

### Config ###
ENABLE_CONFIG_MANAGER=true

### Docker build variables ### 
# These values cannot be updated at runtime
# They need to be passed when building the docker image
# See https://github.com/huggingface/chat-ui/main/.github/workflows/deploy-prod.yml#L44-L47
APP_BASE="" # base path of the app, e.g. /chat, left blank as default
# Compiles in ML Assistant mode: the composer header strip with the preset switch
# and, once a task is running, its plan progress. Off unless set to "true".
# Mode conversations carry a compute budget the user grants in the composer
# (default $0 — every hf_jobs / hf_sandbox submission is refused until one is
# set). Enforced server-side: submissions reserve their worst case (flavor
# price x timeout) and settle to actual runtime.
# Mode conversations always get the Hub MCP server at
# https://huggingface.co/mcp?login&bouquet=intern (the Hub's `intern` tool bouquet),
# merged over any same-named MCP_SERVERS entry.
ML_ASSISTANT_MODE=
# Models ML Intern conversations may run on, JSON5 array; first entry is the
# default. Each entry pins the inference provider the model was verified on for
# 1M-token tool loops (scripts/probe-model.ts) — the user's provider preference
# and "auto" are ignored for mode conversations. `parameters` merge over the
# catalog entry's. `provider` is required; the router alias is rejected. The pin
# only applies against the Hugging Face router (HuggingChat) — self-hosted
# deployments get the model set without it. Empty: the mode refuses to start a
# conversation and the composer hides the switch.
# e.g. [{"id":"zai-org/GLM-5.3-Flash","provider":"together"},{"id":"moonshotai/Kimi-K3","provider":"together"}]
ML_ASSISTANT_MODELS=
### Body size limit for SvelteKit https://svelte.dev/docs/kit/adapter-node#Environment-variables-BODY_SIZE_LIMIT
BODY_SIZE_LIMIT=15728640
PUBLIC_COMMIT_SHA=

### LEGACY parameters
ALLOW_INSECURE_COOKIES=false # LEGACY! Use COOKIE_SECURE and COOKIE_SAMESITE instead
PARQUET_EXPORT_SECRET=#DEPRECATED, use ADMIN_API_SECRET instead
RATE_LIMIT= # /!\ DEPRECATED definition of messages per minute. Use USAGE_LIMITS.messagesPerMinute instead
OPENID_NAME_CLAIM="name" # Change to "username" for some providers that do not provide name
OPENID_PROVIDER_URL=https://huggingface.co # for Google, use https://accounts.google.com
OPENID_TOLERANCE=
OPENID_RESOURCE=
EXPOSE_API=# deprecated, API is now always exposed