Hermes Agent OpenWebUI Integration Setup Guide

Open WebUI is a self-hosted, OpenAI-compatible chat interface that you can place in front of an LLM endpoint, and you can use it alongside Hermes Agent when you route through an OpenAI-compatible bridge rather than Hermes itself. Hermes Agent does not natively expose an HTTP or OpenAI-compatible API server, so a direct "point Open WebUI at Hermes" integration is not officially documented — the practical pattern is to point Open WebUI at the same model endpoint Hermes uses (Nous Portal, OpenRouter, OpenAI, or your own server) and keep Hermes' agentic work in its own surface. This guide covers what Open WebUI is, why operators pair it, how the connection actually works, and how Open WebUI compares to the official Hermes WebUI.

What Open WebUI Is

Open WebUI is an extensible, self-hosted AI platform designed to operate entirely offline, serving as a unified browser interface for multiple AI models. According to its official GitHub repository, it has 143,000+ stars and 20,700+ forks, making it one of the most widely deployed open-source LLM front-ends.

Its core features include role-based access control (RBAC), simultaneous multi-model conversations, local retrieval-augmented generation (RAG) across nine vector database options, web search integration, image generation, and Progressive Web App support for mobile. On backends, the Open WebUI documentation states it connects to Ollama and to any OpenAI-compatible API, including vLLM, LM Studio, GroqCloud, Mistral, and OpenRouter.

It installs via Docker (multiple tagged images including main, cuda, and ollama), Docker Compose, Kubernetes, or Python pip on Python 3.11+. That deployment flexibility is why it is a common front-end choice for self-hosters running their own model stack.

Why Pair Open WebUI With Hermes Agent

The main reason operators pair Open WebUI with a Hermes Agent setup is to get a polished, multi-user chat surface for plain LLM conversations while keeping Hermes for agentic, memory-rich work. Hermes Agent is built by Nous Research as a self-improving agent with a learning loop, 40+ built-in tools, skill creation, scheduled cron automation, and persistent user models across sessions — but its primary surfaces are a terminal UI and a messaging gateway (Telegram, Discord, Slack, WhatsApp, Signal, and email).

That leaves a gap: a browser-based, account-aware chat interface for quick model conversations, document Q&A, and team access. Open WebUI fills that gap well because it already speaks the OpenAI-compatible protocol that the same models behind Hermes use.

A second reason is model reuse. Hermes can use Nous Portal, OpenRouter, OpenAI, or your own endpoint and switch with the /model command. If you already run a model endpoint for Hermes, Open WebUI can point at the very same endpoint, giving you a clean chat UI without standing up new infrastructure.

How They Connect

The accurate connection model is that Open WebUI connects to an OpenAI-compatible model endpoint, not to Hermes Agent's agent loop directly. This distinction matters because Hermes Agent does not natively expose an HTTP server or OpenAI-compatible API — a fact confirmed by both the Hermes Agent repository and the official Hermes WebUI project, which states it "runs the Hermes agent in-process" and "does not connect to an external Hermes/agent OpenAI-compatible API server to run chat."

So there are two realistic, accurate patterns:

Pattern A — shared model endpoint (verified, simplest). Point Open WebUI at the same OpenAI-compatible endpoint Hermes uses (for example OpenRouter or your own vLLM/LM Studio server). Open WebUI handles plain chat; Hermes handles agentic tasks. They share models but operate as separate surfaces. This uses only documented Open WebUI behavior.

Pattern B — custom OpenAI-compatible proxy (general approach, not officially documented). If you want Open WebUI to "talk to Hermes," you would need to write or run a proxy that exposes an OpenAI-compatible /v1/chat/completions route and forwards turns into Hermes. This is not an officially supported integration, so treat it as a do-it-yourself bridge with no guarantees of stability across Hermes releases.

For Pattern A, the Open WebUI OpenAI-compatible connection guide documents the exact flow: go to Admin Settings, Connections, OpenAI, click Add Connection, and fill in the URL and API Key. The URL typically follows the https://api.provider.com/v1 pattern, and if the provider does not implement the /models endpoint you add model IDs manually to the Model IDs filter allowlist.

# Open WebUI environment configuration for an OpenAI-compatible endpoint
# (documented variables — substitute your own provider URL and key)
OPENAI_API_BASE_URL=https://your-provider.example.com/v1
OPENAI_API_KEY=sk-your-key-here

# Run Open WebUI via Docker
docker run -d -p 3000:8080 \
  -e OPENAI_API_BASE_URL="$OPENAI_API_BASE_URL" \
  -e OPENAI_API_KEY="$OPENAI_API_KEY" \
  -v open-webui:/app/backend/data \
  --name open-webui ghcr.io/open-webui/open-webui:main

Note: if Open WebUI runs in Docker and your model server runs on the host, the docs advise replacing localhost with host.docker.internal in the URL.

Open WebUI vs Hermes' Own Web UI

The official Hermes WebUI is the supported way to use Hermes' agent features from a browser, while Open WebUI is a general-purpose chat front-end that does not understand Hermes' skills or memory. According to the Hermes WebUI repository, it is a Nous Research project (15.2k stars, MIT) that runs the agent in-process and reads your HERMES_HOME config directly, exposing chat, a workspace file browser, a tasks panel for cron jobs, plus skills, memory, and profiles panels.

The practical takeaway: use Hermes WebUI when you want the full self-improving agent in a browser, and use Open WebUI when you want a multi-model, multi-user chat surface for plain LLM work. They solve different problems and can coexist.

Setup Walkthrough

Setting up the shared-endpoint pattern takes three steps: run Open WebUI, add an OpenAI-compatible connection, and confirm the model list. This is the only path that relies entirely on documented behavior, so it is the one to start with.

Step 1 — Deploy Open WebUI. Run the Docker image above (or install via pip install open-webui on Python 3.11+ and run open-webui serve). Open WebUI listens on port 8080 internally, mapped to 3000 in the example.

Step 2 — Add the connection. In the browser, go to Admin Settings, Connections, OpenAI, click Add Connection, paste your provider URL (ending in /v1) and API key, then Save. If models do not auto-populate, add the model IDs manually to the Model IDs filter allowlist.

Step 3 — Keep Hermes separate. Continue running Hermes through its TUI (hermes) or gateway (hermes gateway) for agentic work, pointing it at the same model with /model. For a browser surface over Hermes' actual agent features, install the official Hermes WebUI instead of trying to bridge Open WebUI into the agent loop. See our Hermes Agent setup guide for the base install.

Limitations and Tradeoffs

The biggest limitation is that there is no officially documented direct integration between Open WebUI and Hermes Agent's agent loop. Open WebUI talks to model endpoints, and Hermes does not ship an OpenAI-compatible server, so any "Open WebUI controls Hermes" setup is a custom proxy you build and maintain yourself — expect breakage across Hermes releases and no upstream support.

Do not use Open WebUI if your goal is Hermes' skills, persistent memory, profiles, or scheduled tasks from a browser. Those features live inside Hermes and are exposed by the official Hermes WebUI, not by a generic chat front-end. Open WebUI will only give you plain conversations with whatever model you connect.

Also verify licensing before commercial deployment: Open WebUI uses its own license with branding-preservation terms, which differs from Hermes Agent's MIT license. Versions move quickly — Open WebUI was at v0.9.6 and Hermes Agent at v0.17.0 (v2026.6.19) as of June 2026 — so re-check the docs before relying on any specific behavior.

Related Guides

• Hermes Agent Setup Guide
• How to Self-Host Hermes Agent on a $5 VPS
• Hermes Agent Telegram Bot Setup
• OpenClaw vs Hermes Agent: Memory, Skills, and Best Fit