Can I use Open WebUI with a hosted AI agent?

Yes. Enable the Hermes API server, which speaks the OpenAI chat format, then add it in Open WebUI as an OpenAI-compatible connection using the base URL and your API key.

Does the API server give me the agent or just a model?

The agent. Requests go through your agent with its skills, memory and tools, not to a bare model passthrough.

What other clients work with it?

Any OpenAI-compatible client — mobile apps, scripts, internal tools — using the same base URL, API key and model name.

← Home

Guide

Connect Open WebUI to Your AI Agent

This one is not a chat platform. It is a front end — your own interface talking to your agent through an OpenAI-compatible endpoint, so you can use the chat UI you prefer instead of the one we ship.

How It Fits Together

Every Hermes instance can expose an API server that speaks the OpenAI chat format. Anything built to talk to OpenAI can therefore talk to your agent — Open WebUI, a mobile client, a script, an internal tool. The important part is that you are not talking to a raw model: you are talking to your agent, with its skills, memory and tools intact.

Open WebUI itself is software you run — on your own machine, a NAS, or a server. We host the agent; where the interface runs is your choice.

Enable the API Server

From your instance's Web Terminal:

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

Pick a long random value for the key. It is the only thing standing between the internet and an agent that costs money to run. Then restart the gateway so the change takes effect:

hermes gateway stop && hermes gateway

You can also set both from your bot's own dashboard under Channels, where the API server appears alongside the chat platforms.

Check It Is Up

Before touching Open WebUI, confirm the endpoint answers and lists a model. A health check that returns an ok status and a model list containing your agent means the server side is done — if that fails, no client will work, and you have saved yourself debugging the wrong end.

Point Open WebUI at It

In Open WebUI, add an OpenAI-compatible connection.
Set the base URL to your instance's API server address.
Set the API key to the one you configured above.
Pick the agent from the model list and start chatting.

The same three values work for any other OpenAI-compatible client, which is the real reason to turn this on.

Reachability

Open WebUI has to reach your instance. If you run it on your own laptop and the agent is hosted, that means the API server needs to be reachable from where the client runs — over a private network such as Tailscale, or an authenticated public endpoint. Contact support and we can help arrange it.

Troubleshooting

Open WebUI shows no models. The connection is wrong or the key does not match. Check the health endpoint directly first.
Connection refused or timeouts. The client cannot reach the instance — this is a network problem, not a configuration one.
It answers but forgets everything between messages. Check you are talking to the agent model rather than a bare model passthrough.
Unexpected usage on your account. The key leaked or was never set. Rotate it.

Need a Hand?

Contact support from your dashboard. Never paste the API key into chat — we will tell you where to set it.