Repository navigation
Service Open Webui
Port: 63096
SOURCE variable: OPEN_WEB_UI_SOURCE
SOURCE options: container, disabled
Main browser chat UI. It adapts to the configured LLM provider and to the enabled stack services. Its model list comes from the LiteLLM gateway.
| Path | URL | Notes |
|---|---|---|
| Direct | http://localhost:63096 | Container source only. |
| Kong | http://chat.localhost:63000 | Needs ./start.sh --setup-hosts. |
The URLs show the ports for the default BASE_PORT=63000. See the canonical port table at Ports and Routes.
Sign in with the admin account that open-webui-init creates: OPEN_WEB_UI_ADMIN_EMAIL (default admin@localhost) and OPEN_WEB_UI_ADMIN_PASSWORD from .env. The bootstrapper replaces the placeholder password admin with a generated one at start.
OPEN_WEB_UI_SOURCE=container|disabled. Other settings are the OPEN_WEB_UI_* variables in .env (see the env-vars reference).
Saved admin settings override .env. Open WebUI keeps its connection, audio and image settings as persistent config. ENABLE_PERSISTENT_CONFIG defaults to true, and Atlas does not change it. The injected env vars only seed the first boot. After an admin saves the Connections, Audio or Images page, the stored value wins. Later STT/TTS source switches, PARAKEET_API_TOKEN regenerations and LITELLM_MASTER_KEY changes are then ignored. Update the page, or reset the value in Admin Settings.
Shared Redis database. Open WebUI's websocket store uses Redis database OPEN_WEB_UI_REDIS_DB (default 2) with the key prefix openwebui. LightRAG's KV and doc-status storage also uses database 2. To keep them apart, set OPEN_WEB_UI_REDIS_DB to another database number.
When Hermes Agent is enabled (HERMES_SOURCE != disabled), it appears in the model dropdown as hermes-agent through the LiteLLM gateway; no per-WebUI wiring is needed. The model-list cache TTL is 5 minutes (OPEN_WEB_UI_MODEL_CACHE_TTL=300), so a newly enabled Hermes can take that long to appear. Set the TTL to 0 during development.
Built-in image generation does not work out of the box. When ComfyUI is enabled, the compose fragment sets ENABLE_IMAGE_GENERATION with the ComfyUI engine. The bootstrapper sets OPEN_WEB_UI_ENABLE_IMAGE_GENERATION, which is false when COMFYUI_SOURCE=disabled. It sets no COMFYUI_WORKFLOW, COMFYUI_WORKFLOW_NODES or IMAGE_GENERATION_MODEL. Open WebUI then submits its stock workflow (checkpoint model.safetensors, no prompt node mapping), which ComfyUI rejects.
To fix it, configure a workflow under Admin Settings → Images (for example from extras/workflows/default-text-to-image.json). Alternatively, use the bundled ComfyUI tool, which goes through the Backend. Saved Images settings, kept in Open WebUI's database, override the env value.
Bundled tools. Open WebUI offers every Tools method whose name does not start with __ to the model. The bundled tools therefore keep helpers (the Backend header builder, the blocking research runner) outside the Tools class. Long research calls run in a worker thread, so they do not stall the server's event loop.
Backend token. The bundled memory and ComfyUI tools call the Backend from Open WebUI's server process with the auto-generated BACKEND_OPEN_WEBUI_API_TOKEN. The header goes on every Backend request and never reaches browser JavaScript. The tool code may delegate the authenticated Open WebUI user id. The Backend accepts this token only on memory and legacy ComfyUI routes.
Identity sync. open-webui-init installs an idempotent trigger and backfill that copy valid Open WebUI user UUIDs into public.users, so memory rows keep their foreign-key owner. public.users has row-level security, so supabase-db-init gives the Open WebUI database role its own policy ("Atlas open-webui identity sync"). In the auth schema, the role can read only auth.users.id, not password hashes or recovery tokens.
Memory extraction runs after the reply, in two daemon workers with a four-job queue. When the queue is full, the job is skipped with a short diagnostic. A Backend non-success response counts as an extraction failure. Chat replies never wait for extraction.
The tool and function folders are mounted read-only; open-webui-init registers them through the API.
The STT API key depends on the STT source:
- For either Parakeet source,
OPEN_WEB_UI_STT_API_KEYis derived from the generatedPARAKEET_API_TOKEN. - For other enabled STT engines, it is the compatibility value
sk-unused. - When STT is disabled, it is blank.
The value is injected only into Open WebUI's server process. Do not expose it through browser-side tools or logs.
extras/functions/atlas_safe_prompt_middleware.py is the Atlas Safe Prompt Middleware Filter Function. open-webui-init registers it at startup, inactive and not global. It runs on a chat only after an admin does all three steps in Open WebUI's Functions settings:
- Turn on its
enabledvalve (defaultfalse). - Activate the function.
- Make it global, or attach it to models.
The same activation applies to every registered Filter Function, including Memory Auto-Extraction.
When enabled, the filter runs inside Open WebUI before requests reach LiteLLM. It redacts obvious accidental secrets from user messages, such as bearer tokens, sk-... API keys, AWS access keys and password assignments. It covers Open WebUI chat traffic only. LiteLLM remains the universal model gateway, and LiteLLM + Langfuse remains the stack-wide observability path for tracing, latency and cost. OpenLIT remains deferred as a separate service.
Atlas ships no Open WebUI Pipelines: upstream now marks Pipelines as legacy for new deployments and recommends in-process Functions, Tools, OpenAPI servers or MCP servers. So standalone Pipelines are intentionally not added, and the middleware runs in Open WebUI with no extra worker container, port, Kong alias or SOURCE variable.
Support tier: experimental — Capability contract declared; no cited cold-start, workflow, or upgrade qualification run yet (evidence at v0.1.0).
| Capability | Status | Verification | Notes |
|---|---|---|---|
| Unified browser chat through LiteLLM | supported | tested | Atlas initializes an Open WebUI administrator and routes its OpenAI-compatible model traffic through the LiteLLM catalog, including Hermes when enabled. |
| Source-aware speech and image features | partial | tested | Open WebUI receives the selected speech endpoints and ComfyUI settings. Model readiness, disabled providers, source-specific credentials, saved admin settings, and the unconfigured built-in ComfyUI workflow can leave individual features unavailable. |
| Backend memory and research tools | partial | tested | Bundled server-side tools use scoped Backend tokens and synchronized user identities, but extraction is bounded best-effort and research depends on Local Deep Researcher availability. |
| Safe prompt secret redaction | partial | tested | The registered filter redacts common secret patterns only after an administrator enables its default-off valve. It covers Open WebUI user messages, not stack-wide traffic. |
| Open WebUI access control | supported | tested | Direct and CORS-only chat.localhost paths rely on Open WebUI's own account and session authentication; Kong provides routing but no additional login layer. |
| Chat data and upload persistence | partial | documented | Application state uses Postgres and a named Open WebUI data volume, but MinIO/S3 storage, replicated file state, and a tested restore workflow are not configured. |
| Shared multi-replica WebUI availability | not-supported | documented | Redis backs websocket coordination, but Atlas runs one Open WebUI process and one init job without a certified horizontally scaled application or file-storage topology. |
# Check service status
docker compose ps open-web-ui
# Check logs
docker compose logs -f open-web-ui open-webui-initFor general startup and routing issues, see Troubleshooting.
| Service | Category |
|---|---|
| redis | data |
| supabase | data |
| litellm | llm |
| comfyui | media |
| stt-provider | media |
| tts-provider | media |
| backend | apps |
| local-deep-researcher | apps |
| Service | Category |
|---|---|
| kong | infra |
Open the full-size diagram for a full-screen view.
-
open-webui ↔ searxng — Why: Open WebUI consumes SearXNG as a first-class web-search provider for in-chat grounding, but the stack only wires SearXNG to local-deep-researcher today. Mechanism:
ENABLE_WEB_SEARCH=true+WEB_SEARCH_ENGINE=searxng+SEARXNG_QUERY_URL=http://searxng:8080/search?q=<query>&format=json. Effort: small. Confidence: high. -
open-webui ↔ jupyterhub — Why: Open WebUI ships a Jupyter-backed code-execution engine. It runs LLM-emitted Python in a real kernel with persistent state, instead of the in-browser Pyodide sandbox. Mechanism:
CODE_EXECUTION_ENGINE=jupyter+CODE_EXECUTION_JUPYTER_URL=http://jupyterhub:8888+CODE_EXECUTION_JUPYTER_AUTH=token(mirror forCODE_INTERPRETER_*). Effort: medium. Confidence: high. -
open-webui ↔ minio — Why: Chat uploads, generated images and TTS audio live in a Docker volume and vanish on
--cold. Open WebUI supports S3 storage natively, and MinIO is already in the stack. Mechanism:STORAGE_PROVIDER=s3+S3_ENDPOINT_URL=http://minio:9000+S3_BUCKET_NAME=openwebuiwith MinIO credentials, plus anmc mbinit step. Effort: small. Confidence: high. -
open-webui ↔ n8n — Why: n8n workflows could appear in chat as Open WebUI Tools. Users could then trigger automations ("email this summary", "create a Jira ticket") without writing Python. Mechanism: register an OpenAPI tool server pointing at an n8n webhook that serves
openapi.json(via a workflow-to-schema wrapper). Effort: medium. Confidence: medium. -
open-webui ↔ neo4j — Why: The existing
memory_tool.pywrites flat memories to Postgres; a Neo4j-backed graph would link entity → fact → source-conversation and power richer recall. Mechanism: extendextras/tools/memory_tool.pyto call a backend endpoint that writes Cypher tobolt://neo4j-graph-db:7687. Effort: medium. Confidence: medium.
- mcpo (details) — Headline: Open WebUI's MCP-to-OpenAPI proxy exposes any stdio/SSE MCP server as a REST tool server consumable by Open WebUI and LiteLLM. Wires into: open-webui, hermes, litellm, n8n, kong.
- OIDC / SSO via Supabase Auth — Why pursue: Supabase GoTrue is already running, and Open WebUI supports generic OAuth/OIDC. One login could unify Open WebUI, n8n and JupyterHub identity. Effort: medium.
- Native MCP client — Why pursue: Open WebUI ships a built-in MCP client. Wiring it to stack-local MCP servers (filesystem, git) gives chat real tools without per-tool Python glue. Effort: small.
- Hybrid BM25 + vector reranking — Why pursue: Open WebUI's built-in hybrid search and cross-encoder reranker are off, leaving knowledge-base recall worse than it needs to be. Effort: small.
-
Channels / multi-user workspaces — Why pursue: Channels turn the WebUI into a team space with
@modelmentions and pair naturally with the Supabase auth gap above. Effort: medium. - Notes with agentic access — Why pursue: The built-in rich-text notes editor that LLMs can read and write replaces ad-hoc scratchpads with zero new infrastructure. Effort: small.