Open WebUI with a Local Hunyuan: Put hy4 Behind a Self-Hosted Interface
Connect a locally running Hunyuan hy4 to Open WebUI: Docker deployment, pointing it at a local Ollama or llama.cpp endpoint, enabling models, admin model-list configuration, LAN access and authentication, plus troubleshooting for the configuration mistakes people hit most.
Open WebUI with a Local Hunyuan: Put hy4 Behind a Self-Hosted Interface
Open WebUI is the most popular self-hosted AI interface, and it has the shortest path to a local model: its native support was designed for Ollama, and connecting llama.cpp takes one OpenAI-compatible URL. With a local Hunyuan hy4 behind it, the result is conversation history, model weights, and all of your data staying on your own machine while the interface looks and behaves like a hosted chat product. This article covers the full configuration and the failure modes.
The 30-second version
Start Open WebUI in Docker, add an OpenAI connection under Admin Settings, Connections, with the base URL pointing at http://host.docker.internal:8080/v1 for llama.cpp, or use the built-in Ollama connection, then enable hy4-local under Models and start chatting. Never use 127.0.0.1 inside a container.
Option one: use Ollama directly
Open WebUI has a built-in Ollama connection, so it only needs an address:
docker run -d -p 3000:8080 \
-e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
-v open-webui:/app/backend/data \
--name open-webui \
ghcr.io/open-webui/open-webui:main
Open http://localhost:3000, register the first account (the first registered user becomes the administrator), then:
Confirm Ollama is running
On the host, runollama listand confirm hy4-local appears. If it does not, create it first withollama create hy4-local -f Modelfile.Check the connection
Open Admin Settings, Connections, and confirm the Ollama connection reports as connected.Enable the model
Go to Admin Settings, Models, find hy4-local, and switch it on.Start chatting
Create a new conversation and pick hy4-local from the model dropdown.
127.0.0.1 inside a container is the container
The most common failure is setting OLLAMA_BASE_URL to http://127.0.0.1:11434 and seeing the interface report no connection. The container's 127.0.0.1 refers to its own network namespace, not the host. Use host.docker.internal, and if your Docker version does not resolve that name, start the container with --add-host=host.docker.internal:host-gateway.
Option two: point it at llama.cpp
If you serve the model with llama-server instead of Ollama, add an OpenAI connection in Open WebUI:
Confirm llama-server is running
On the host run ./llama-server -m ./Q4_K_M.gguf --host 0.0.0.0 --port 8080 --ctx-size 32768 --jinja. Note the 0.0.0.0 bind, because a 127.0.0.1 bind is unreachable from the container.Add an OpenAI connection
Admin Settings, Connections, OpenAI, then add a connection with the base URL http://host.docker.internal:8080/v1 and any placeholder API key.Add the model manually
If the model list does not load, add the model name manually under Admin Settings, Models, matching the name llama-server was started with.Verify and enable
Return to the model list, enable it, and test it in a new conversation.
Why llama-server rather than vLLM behind Open WebUI
llama-server does not strictly validate model names, uses less memory, and starts fast, which suits a personal or small-team local interface. vLLM is the better choice for high-concurrency serving, but it validates model names strictly, so the name must match exactly when wiring it to an interface. Either works; pick by concurrency.
Option three: environment variables
In container deployments, injecting values through environment variables is more stable:
docker run -d -p 3000:8080 \
-e OPENAI_API_BASE_URL="http://host.docker.internal:8080/v1" \
-e OPENAI_API_KEY="ollama" \
-e OLLAMA_BASE_URL="http://host.docker.internal:11434" \
-e WEBUI_AUTH=true \
-v open-webui:/app/backend/data \
--add-host=host.docker.internal:host-gateway \
--name open-webui \
ghcr.io/open-webui/open-webui:main
Confirm variable names against your version's documentation
Open WebUI has adjusted environment variable names across releases, including the historical difference between OPENAI_API_BASE_URL and OPENAI_API_BASE. What is shown here is the current common form; check the official documentation for the version you deploy.
Configuration reference
| Situation | Server side | Open WebUI configuration | Base URL |
|---|---|---|---|
| Lowest effort | Ollama | Built-in Ollama connection | http://host.docker.internal:11434 |
| Tunable parameters | llama.cpp | New OpenAI connection | http://host.docker.internal:8080/v1 |
| Cloud models | EXAIV cloud | New OpenAI connection | https://exaiv.com/api/ai/v1 |
| Mixed | both | add both connections | as above |
Local and cloud can coexist
Open WebUI supports several connections at once. In the model dropdown, your local hy4 appears next to cloud models, so you can switch by data sensitivity. That is often more useful than committing to all-local or all-cloud.
LAN and public access
By default Open WebUI listens on port 8080 inside the container, mapped to the host with -p 3000:8080. To let other devices on your network in:
docker run -d -p 3000:8080 \
-e WEBUI_AUTH=true \
-e WEBUI_URL=http://192.168.1.10:3000 \
-v open-webui:/app/backend/data \
--name open-webui \
ghcr.io/open-webui/open-webui:main
Three things to do before exposing it publicly
First, turn on WEBUI_AUTH and give every account a strong password, since the first registered Open WebUI account has no password and is an administrator. Second, never expose your Ollama port directly to the internet: it has no authentication, so anyone can consume your compute. Third, if public access is genuinely required, put a reverse proxy in front for TLS and access control.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Ollama connection shows as down | Used 127.0.0.1 inside the container | Switch to host.docker.internal and add the host-gateway mapping |
| Model list is empty | Server down or wrong path | Verify the host port with curl, then add the model name manually |
| Garbled answers | Wrong chat template | Fix TEMPLATE or --jinja per the model card |
| Slow answers | Model running on CPU | Confirm the GPU is being used, or use a smaller quantization |
| Very slow first load | Model loading into memory | Expected behaviour |
| The interface spins forever | Context too large, running out of memory | Lower num_ctx or switch to a smaller quantization |
| Conversations bleed between users | Session storage sharing issue | Check the data volume mount and user permissions |
FAQ
Is configuring a local model different from configuring a cloud model in Open WebUI?
Why does the model list come back empty?
Why can I not use 127.0.0.1 in a container?
Can I use Open WebUI with cloud models as well?
Can I call Hunyuan through the EXAIV cloud?
Related reading
- Running hy4 with Ollama — wiring a local Hunyuan into Dify, Cursor, and other tools
- Open WebUI integration — the cloud model setup, which is a different path from this one
- hy4 GGUF local deployment — the quantization and memory preparation before you serve
- Dify integration — another self-hosted application platform
- hy4 local RAG in practice — giving the local model a knowledge base
- Tencent Hunyuan family overview — every Hunyuan product line in one place
Sources
Environment variable names and configuration options follow the official documentation for the version you deploy; this article reflects the state at sampling time.