Open WebUI

Open WebUI ↗ (126k★) is the most popular self-hosted chat interface for AI. With Hermes Agent's built-in API server, you can use Open WebUI as a polished web frontend for your agent — complete with conversation management, user accounts, and a modern chat interface.

flowchart LR
    A["Open WebUI<br/>browser UI<br/>port 3000"]
    B["hermes-agent<br/>gateway API server<br/>port 8642"]
    A -->|POST /v1/chat/completions| B
    B -->|SSE streaming response| A

Open WebUI connects to Hermes Agent's API server just like it would connect to OpenAI. Hermes handles the requests with its full toolset — terminal, file operations, web search, memory, skills — and returns the final response.

:::important Runtime location The API server is a Hermes agent runtime, not a pure LLM proxy. For each request, Hermes creates a server-side AIAgent on the API-server host. Tool calls run where that API server is running.

For example, if a laptop points Open WebUI or another OpenAI-compatible client at a Hermes API server on a remote machine, pwd, file tools, browser tools, local MCP tools, and other workspace tools run on the remote API-server host, not on the laptop. :::

Open WebUI talks to Hermes server-to-server, so you do not need API_SERVER_CORS_ORIGINS for this integration.

1. Enable the API server

hermes config set API_SERVER_ENABLED true
hermes config set API_SERVER_KEY your-secret-key

hermes config set auto-routes the flag to config.yaml and the secret to ~/.hermes/.env. If the gateway is already running, restart it so the change takes effect:

hermes gateway stop && hermes gateway

2. Start Hermes Agent gateway

hermes gateway

You should see:

[API Server] API server listening on http://127.0.0.1:8642

3. Verify the API server is reachable

curl -s http://127.0.0.1:8642/health
# {"status": "ok", ...}

curl -s -H "Authorization: Bearer your-secret-key" http://127.0.0.1:8642/v1/models
# {"object":"list","data":[{"id":"hermes-agent", ...}]}

If /health fails, the gateway didn't pick up API_SERVER_ENABLED=true — restart it. If /v1/models returns 401, your Authorization header doesn't match API_SERVER_KEY.

4. Start Open WebUI

docker run -d -p 3000:8080 \
  -e OPENAI_API_BASE_URL=http://host.docker.internal:8642/v1 \
  -e OPENAI_API_KEY=your-secret-key \
  -e ENABLE_OLLAMA_API=false \
  --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

ENABLE_OLLAMA_API=false suppresses the default Ollama backend, which would otherwise show up empty and clutter the model picker. Omit it if you actually have Ollama running alongside.

First launch takes 15–30 seconds: Open WebUI downloads sentence-transformer embedding models (~150MB) the first time it starts. Wait for docker logs open-webui to settle before opening the UI.

5. Open the UI

Go to http://localhost:3000. Create your admin account (the first user becomes admin). You should see your agent in the model dropdown (named after your profile, or hermes-agent for the default profile). Start chatting!

For a more permanent setup, create a docker-compose.yml:

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    volumes:
      - open-webui:/app/backend/data
    environment:
      - OPENAI_API_BASE_URL=http://host.docker.internal:8642/v1
      - OPENAI_API_KEY=your-secret-key
      - ENABLE_OLLAMA_API=false
    extra_hosts:
      - "host.docker.internal:host-gateway"
    restart: always

volumes:
  open-webui:

Then:

docker compose up -d

If you prefer to configure the connection through the UI instead of environment variables:

1. Log in to Open WebUI at http://localhost:3000
2. Click your profile avatar → Admin Settings
3. Go to Connections
4. Under OpenAI API, click the wrench icon (Manage)
5. Click + Add New Connection
6. Enter:
7. URL: http://host.docker.internal:8642/v1
8. API Key: the exact same value as API_SERVER_KEY in Hermes
9. Click the checkmark to verify the connection
10. Save

Your agent model should now appear in the model dropdown (named after your profile, or hermes-agent for the default profile).

Open WebUI supports two API modes when connecting to a backend:

Using Chat Completions (recommended)

This is the default and requires no extra configuration. Open WebUI sends standard OpenAI-format requests and Hermes Agent responds accordingly. Each request includes the full conversation history.

Using Responses API

To use the Responses API mode:

1. Go to Admin Settings → Connections → OpenAI → Manage
2. Edit your hermes-agent connection
3. Change API Type from "Chat Completions" to "Responses (Experimental)"
4. Save

With the Responses API, Open WebUI sends requests in the Responses format (input array + instructions), and Hermes Agent can preserve full tool call history across turns via previous_response_id. When stream: true, Hermes also streams spec-native function_call and function_call_output items, which enables custom structured tool-call UI in clients that render Responses events.

When you send a message in Open WebUI:

1. Open WebUI sends a POST /v1/chat/completions request with your message and conversation history
2. Hermes Agent creates a server-side AIAgent instance using the API server's profile, model/provider config, memory, skills, and configured API-server toolsets
3. The agent processes your request — it may call tools (terminal, file operations, web search, etc.) on the API-server host
4. As tools execute, inline progress messages stream to the UI so you can see what the agent is doing (e.g. ` 💻 ls -la , 🔍 Python 3.12 release `)
5. The agent's final text response streams back to Open WebUI
6. Open WebUI displays the response in its chat interface

Your agent has access to the same tools and capabilities as that API-server Hermes instance. If the API server is remote, those tools are remote too.

If you need tools to run against your local workspace today, run Hermes locally and point it at a pure LLM provider or pure OpenAI-compatible model proxy (for example vLLM, LiteLLM, Ollama, llama.cpp, OpenAI, OpenRouter, etc.). A future split-runtime mode for "remote brain, local hands" is being tracked in #18715 ↗; it is not the behavior of the current API server.

Hermes Agent (API server)

Open WebUI

No models appear in the dropdown

• Check the URL has /v1 suffix: http://host.docker.internal:8642/v1 (not just :8642)
• Verify the gateway is running: curl http://localhost:8642/health should return {"status": "ok"}
• Check model listing: curl -H "Authorization: Bearer your-secret-key" http://localhost:8642/v1/models should return a list with hermes-agent
• Docker networking: From inside Docker, localhost means the container, not your host. Use host.docker.internal or --network=host.
• Empty Ollama backend shadowing the picker: If you omitted ENABLE_OLLAMA_API=false, Open WebUI shows an empty Ollama section above your Hermes models. Restart the container with -e ENABLE_OLLAMA_API=false or disable Ollama in Admin Settings → Connections.

Connection test passes but no models load

This is almost always the missing /v1 suffix. Open WebUI's connection test is a basic connectivity check — it doesn't verify model listing works.

Response takes a long time

Hermes Agent may be executing multiple tool calls (reading files, running commands, searching the web) before producing its final response. This is normal for complex queries. The response appears all at once when the agent finishes.

"Invalid API key" errors

Make sure your OPENAI_API_KEY in Open WebUI matches the API_SERVER_KEY in Hermes Agent.

To run separate Hermes instances per user — each with their own config, memory, and skills — use profiles. Each profile runs its own API server on a different port and automatically advertises the profile name as the model in Open WebUI.

1. Create profiles and configure API servers

API_SERVER_* are env vars, not YAML config keys, so write them to each profile's .env. Pick ports outside the default-platform range (8644 is the webhook adapter, 8645 is wecom-callback, 8646 is msgraph-webhook), e.g. 8650+:

hermes profile create alice
cat >> ~/.hermes/profiles/alice/.env <<EOF
API_SERVER_ENABLED=true
API_SERVER_PORT=8650
API_SERVER_KEY=alice-secret
EOF

hermes profile create bob
cat >> ~/.hermes/profiles/bob/.env <<EOF
API_SERVER_ENABLED=true
API_SERVER_PORT=8651
API_SERVER_KEY=bob-secret
EOF

2. Start each gateway

hermes -p alice gateway &
hermes -p bob gateway &

3. Add connections in Open WebUI

In Admin Settings → Connections → OpenAI API → Manage, add one connection per profile:

The model dropdown will show alice and bob as distinct models. You can assign models to Open WebUI users via the admin panel, giving each user their own isolated Hermes agent.

On Linux without Docker Desktop, host.docker.internal doesn't resolve by default. Options:

# Option 1: Add host mapping
docker run --add-host=host.docker.internal:host-gateway ...

# Option 2: Use host networking
docker run --network=host -e OPENAI_API_BASE_URL=http://localhost:8642/v1 ...

# Option 3: Use Docker bridge IP
docker run -e OPENAI_API_BASE_URL=http://172.17.0.1:8642/v1 ...