How-To Guide
How to Connect Hermes Agent to Open WebUI
Connect Open WebUI to Hermes Agent through the OpenAI-compatible API server, fix Docker networking and API-key errors, and understand where tools run.
Quick answer
Enable Hermes Agent's OpenAI-compatible API server, start the Hermes gateway, verify /health and /v1/models, then add http://host.docker.internal:8642/v1 as an OpenAI connection in Open WebUI. Use the same secret for API_SERVER_KEY and Open WebUI's API key. Open WebUI is the chat frontend; Hermes remains the agent runtime, and its terminal, files, browser, memory, and skills run on the machine hosting the Hermes API server.
Open WebUI can be a self-hosted browser chat frontend for Hermes Agent without replacing Hermes or turning the official Dashboard into a chat app. The connection uses Hermes Agent's built-in OpenAI-compatible API server. Open WebUI sends a chat request; Hermes runs the agent loop and tools on the API-server host; the answer streams back to the browser. This guide follows the current official Hermes integration and keeps the product boundary explicit: use the Hermes Dashboard to configure and monitor a self-hosted runtime, Open WebUI for a community-operated chat frontend, or FlyHermes when you want managed browser/mobile access and uptime without operating both services.
Managed cloud · API costs included · Skill library · Cancel anytime
Before you start:
- ☑A working Hermes Agent installation and model/provider smoke test
- ☑Open WebUI admin access or permission to start its Docker container
- ☑Port 8642 available for Hermes and port 3000 available for Open WebUI
- ☑A strong API server key stored as a secret, never committed to the repository
Steps
- 1
Verify Hermes before adding a second service
Run
hermes doctorand a short CLI prompt first. If the provider, model, or API-key setup is already broken, Open WebUI only adds another symptom. Keep the first test local and use the intended Hermes profile. - 2
Enable the Hermes API server
Run
hermes config set API_SERVER_ENABLED trueandhermes config set API_SERVER_KEY your-secret-key. Hermes routes the secret to the profile.env. Restart an existing gateway so the new API-server settings load. - 3
Start the gateway and verify both endpoints
Run
hermes gateway. Checkcurl -s http://127.0.0.1:8642/health, then callhttp://127.0.0.1:8642/v1/modelswithAuthorization: Bearer your-secret-key. Do not continue until health returns OK and the authenticated model list includeshermes-agentor your profile/model name. - 4
Start Open WebUI with the correct host address
For Open WebUI in Docker and Hermes on the host, run
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. The/v1suffix and host mapping are essential. - 5
Add or verify the connection in Open WebUI
Open
http://localhost:3000, create the first admin account, then go to Admin Settings → Connections → OpenAI. Usehttp://host.docker.internal:8642/v1and the same API-server key. Select Chat Completions first; it is the recommended compatibility path. - 6
Prove one harmless tool call
Select the Hermes model and ask for a harmless runtime fact such as the current working directory. Confirm the result belongs to the Hermes API-server host. This is the critical security boundary: Open WebUI runs the interface, while Hermes tools run where the API server runs.
- 7
Choose the operating model
For private self-hosting, keep both services behind a private network, protect the Open WebUI admin account, and follow the self-hosted responsibility checklist. If the real requirement is managed browser/mobile access, connected channels, backups, and uptime, compare FlyHermes pricing before maintaining another container and public endpoint.
Pro Tips
- 💡Use
host.docker.internal, notlocalhost, when Open WebUI runs in Docker and Hermes runs on the host. - 💡Keep
/v1at the end of the OpenAI API URL. - 💡Set
ENABLE_OLLAMA_API=falseif you do not run Ollama; otherwise an empty Ollama backend can clutter the model picker. - 💡Open WebUI persists connection settings in its database after first launch. Update the saved Admin Settings connection instead of assuming changed environment variables will replace it.
- 💡Use a different API-server port for each Hermes profile in a multi-user deployment.
- 💡Do not expose port 8642 publicly without authentication, TLS, firewall rules, and a deliberate trust boundary.
- 💡The official self-hosted Dashboard/Web UI is a configuration and monitoring surface; Open WebUI is a separate chat frontend.
Troubleshooting
❌ No Hermes model appears in Open WebUI
✅ Confirm the connection URL ends in /v1, call /v1/models directly with the bearer key, and use host.docker.internal from Docker rather than localhost.
❌ Open WebUI says the API key is invalid
✅ Make OPENAI_API_KEY exactly match Hermes API_SERVER_KEY. If Open WebUI was already initialized, update the saved connection in Admin Settings because its database can retain the old key.
❌ The connection test passes but the model list is empty
✅ A basic connection test can pass without a working model-list request. Add the /v1 suffix, verify authenticated /v1/models, and disable the unused Ollama connection if it shadows the Hermes entry.
❌ Open WebUI cannot reach Hermes on Linux Docker
✅ Add --add-host=host.docker.internal:host-gateway, use host networking, or use the Docker bridge address. Also ensure Hermes is bound to an address reachable from the container and protected appropriately.
❌ Tools read files from the wrong machine
✅ That is the current architecture, not a frontend bug. Hermes tools run on the API-server host. Run the Hermes API server where the intended workspace lives, or use a supported remote terminal/backend deliberately.
❌ Chat works but responses are slow
✅ Inspect Hermes gateway logs and tool progress. A tool-using agent can perform several terminal, file, browser, or web steps before the final answer; distinguish agent work from network latency.
FAQ
Can Open WebUI connect to Hermes Agent?
Yes. Hermes Agent exposes an OpenAI-compatible API server with /v1/models and /v1/chat/completions, which Open WebUI can use as an OpenAI connection.
What URL should Open WebUI use for Hermes Agent?
Use http://localhost:8642/v1 when both processes share the host network. Use http://host.docker.internal:8642/v1 when Open WebUI runs in Docker and Hermes runs on the host.
Is Open WebUI the same as the Hermes Dashboard?
No. Open WebUI is a separate community chat frontend. The Hermes Dashboard is the official self-hosted configuration and monitoring surface for profiles, memory, skills, tools, cron, logs, and gateways.
Where do Hermes tools run when I chat through Open WebUI?
They run on the machine hosting the Hermes API server. The browser or Open WebUI container does not move terminal and file execution to the viewer's laptop.
Does Open WebUI remove the need to run the Hermes gateway?
No. The gateway hosts the Hermes API server. Open WebUI is only the frontend and cannot answer through Hermes when that runtime is stopped.
Should I use Open WebUI or FlyHermes?
Use Open WebUI when you want to operate a self-hosted chat frontend and Hermes runtime. Use FlyHermes when you want managed browser/mobile access and uptime without maintaining the gateway, containers, authentication, backups, and provider plumbing yourself.
Related setup and cost guides
Hermes Dashboard and Web UI
Understand the official self-hosted configuration and monitoring surface.
Use the Hermes Web UI
Open and troubleshoot the official Dashboard without confusing it with browser chat.
Self-hosted Hermes vs FlyHermes
Compare responsibility for uptime, security, backups, gateways, and provider operations.
Troubleshoot the Hermes gateway
Fix stale services, port conflicts, provider failures, and channel/API-server health.
FlyHermes managed pricing
Choose managed browser/mobile access when self-hosted operations are the blocker.