# How to set up Hermes Agent with Open WebUI and the API server

> Use Open WebUI with the Hermes API server. Set a strong key, keep loopback private and understand Docker reachability and host tool access.

Canonical: https://hermeswatcher.com/learn/hermes-agent-open-webui-setup  
Section: Learn · Messaging & the gateway  
Last reviewed: Oct 29, 2026  
Basis: Explained from the official Hermes Agent docs and repository (Nous Research). Steps follow the linked official sources.

## What you need

Open WebUI is a browser chat interface. It connects to the Hermes gateway's OpenAI-compatible HTTP API, which accepts requests in the OpenAI client format. Hermes still needs its own model provider and any tool backends your tasks require. Open WebUI does not supply those by itself.

The API is an agent runtime, not a pure model proxy. Tools run on the Hermes API-server host. If Open WebUI is on a laptop and Hermes is on a server, terminal commands, file operations, browser tools and local MCP tools operate on that server. They do not gain access to the laptop's workspace. Choose the host and profile before granting access. Compare interfaces at [messaging platforms](https://hermeswatcher.com/messaging.md).

For an API client rather than a browser interface, see the [official API server examples](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server).

If port 8080 is taken, follow [Open WebUI's documentation](https://docs.openwebui.com/getting-started/quick-start/) to serve on another port.

- A working Hermes installation and configured model provider on the intended host.
- A private Open WebUI installation, or uv available to follow the vendor's Python launch example below.
- A fresh API bearer key. A bearer key grants whoever holds it access to the endpoint, so treat it as a password.
- A network route from the Open WebUI backend to Hermes. Start with both on one host when possible, keeping the API on loopback.

## Create a strong key and enable the API

Generate a fresh random secret on your own host. Hermes requires `API_SERVER_KEY` to be at least 16 characters and rejects known placeholders, even on localhost. The command below produces a longer random value. Never use a short example key from a quick start.

Enable the API only in the default profile. For a secondary profile served by it, follow the named-profile instructions under access below.

Generate the private API key, requires OpenSSL:

```
openssl rand -hex 32
```

Enable the API server:

```
hermes config set API_SERVER_ENABLED true
```

Save the generated key with `hermes config set API_SERVER_KEY <your-generated-key>`, which writes the secret to the active profile's `.env`. The default profile uses `~/.hermes/.env`. Use that same value later in Open WebUI. Keep it out of Git, browser-side JavaScript, screenshots and shared logs. Do not substitute a model-provider key for this separate client-access key.

`API_SERVER_HOST` defaults to `127.0.0.1` and `API_SERVER_PORT` to `8642`. Loopback means only programs sharing that host's network can connect directly. Keep that default for a same-host setup. A key is required even there. Restart an already-running gateway after changing configuration.

## Start Hermes and check the local endpoint

Start the gateway in the foreground so you can inspect startup errors. If a managed gateway is already running, use `hermes gateway restart` rather than launching another copy.

First foreground launch:

```
hermes gateway
```

In another terminal on the Hermes host:

```
curl -s http://127.0.0.1:8642/health
```

Authenticated model list, replace the key (official Open WebUI guide):

```
curl -H "Authorization: Bearer <your-API_SERVER_KEY>" http://127.0.0.1:8642/v1/models
```

Look for the API listener at `http://127.0.0.1:8642`. Check `/v1/models` with an Authorization header whose value is `Bearer ` followed by your actual `API_SERVER_KEY`. It should list the profile name, or `hermes-agent` for the default profile. A health response alone does not check authenticated model listing.

If the listener refuses to start, inspect the key-strength error rather than weakening authentication. A 401 from model listing means the presented key or routed profile does not match. Check the active profile and saved key on both sides without sharing them.

## Start Open WebUI and connect it

For a same-host Python setup with uv already installed, the vendor quick start gives the launch commands below. Choose the one for your operating system. `DATA_DIR` is where Open WebUI keeps chats and settings.

macOS or Linux, vendor uv launch example:

```
DATA_DIR=~/.open-webui uvx --python 3.12 open-webui@latest serve
```

Windows PowerShell, vendor uv launch example:

```
$env:DATA_DIR="C:\open-webui\data"; uvx --python 3.12 open-webui@latest serve
```

The vendor's Python example serves the interface at `http://localhost:8080`. Create the first admin account before allowing anyone else to reach it. Keep the interface private using your host's network controls and retain login requirements.

In Open WebUI, open Profile avatar → Admin Settings → Connections → under OpenAI API, the wrench (Manage) → + Add New Connection. Add a connection with URL `http://127.0.0.1:8642/v1` for the same-host Python setup. Enter the exact Hermes `API_SERVER_KEY`, check the connection and save.

Include `/v1` in the base URL. Select the profile model and start with Chat Completions, the recommended mode in the Hermes guide. Open WebUI sends requests from its backend to Hermes, so this integration does not need `API_SERVER_CORS_ORIGINS`. Do not enable broad browser origins to solve a backend connection failure.

## Docker and remote reachability

Inside a Docker container, localhost refers to the container rather than the host. The Hermes Docker example uses `http://host.docker.internal:8642/v1`, `OPENAI_API_BASE_URL` and `OPENAI_API_KEY`. On Linux, its host mapping example is `--add-host=host.docker.internal:host-gateway`.

On Linux, the official page lists host networking: use `--network=host` and `OPENAI_API_BASE_URL=http://localhost:8642/v1`. This keeps Hermes on loopback. With host networking, container port mapping does not apply: Open WebUI listens on its own port directly on the host. A Docker host-name mapping alone does not make a loopback listener reachable.

If you change `API_SERVER_HOST` for container or remote access, restrict who can reach that interface with firewall or private-network controls and use encrypted transport across untrusted networks. A public HTTPS URL is an internet-reachable encrypted address; it still needs access controls. Do not expose this terminal-capable API publicly just to make Docker connect. Keep the bearer key required. Follow the linked official guides after choosing the protected network path.

- Check authenticated `/v1/models` from the Open WebUI backend's network, not only from a terminal on the Hermes host.
- Use the address reachable by that backend and retain `/v1`. `OPENAI_API_KEY` must match the intended profile's `API_SERVER_KEY`.
- Existing Open WebUI connection settings are stored in its database. Changing container environment variables alone may not replace a saved URL or key. Edit the saved connection in the Admin UI; preserve the data volume.
- If you are not running Ollama, set `ENABLE_OLLAMA_API=false` or disable Ollama under Admin Settings → Connections.

## Choose who can talk to the agent

The API server uses a bearer key rather than a messenger's numeric-user allowlist or DM pairing flow. The equivalent access decision is which trusted users and client backends can use the profile's key and tools. An allowlist means a list of approved people or origins; a browser-origin list controls browser requests, not who possesses the API credential.

Keep Open WebUI authentication enabled and grant backend access only to people you trust with that Hermes profile. Do not assume separate WebUI accounts isolate a shared Hermes profile's memory, skills, credentials or files.

For each extra profile, put only a fresh `API_SERVER_KEY` in that profile's `.env`. Do not enable `api_server` in it: the default profile's listener serves it at `/p/<profile>/v1`. The default key is rejected on named-profile prefixes. Confirm which profiles the gateway serves and assign only the intended connections to users. Do not copy older per-port or separate-service examples as a required topology.

## Send a first message and understand the features

Choose the advertised profile model and send a harmless text prompt. Confirm a final reply appears in that chat and inspect Hermes logs for errors. A green connection check is not enough. If you later check workspace behavior, use a harmless read-only request and confirm that the reported location is the intended Hermes host.

- The agent uses that host/profile's configured tools, memory and skills. Streaming can show tool progress before final text.
- Chat Completions is the recommended starting mode. Responses is experimental in Open WebUI; the Hermes guide notes that Open WebUI still sends full history rather than relying on `previous_response_id` for continuation.
- The gateway overview has no feature-table row for Open WebUI plus API server. Do not infer voice, images, files, reactions or chat-platform threads from another adapter's row. Frontend and model support matter.
- The model shown by the endpoint names the profile by default. Bare model names on Chat Completions and Responses do not necessarily select another backend model. See the API reference for configured routes, explicit provider selection and the `direct_model_requests` option.

## Keep it running

The bot is silent while its computer sleeps or is switched off. Keep the Hermes host awake and online whenever you need replies. A background service does not prevent sleep.

After checking foreground behavior, stop that foreground gateway before starting its installed service. These commands manage Hermes, not Open WebUI. Keep the WebUI backend and protected network route running too.

Install the Hermes gateway service:

```
hermes gateway install
```

Start the service:

```
hermes gateway start
```

Check running state:

```
hermes gateway status
```

Apply Hermes configuration changes:

```
hermes gateway restart
```

If the Hermes computer is off, asleep or offline, no agent requests or scheduled jobs can run there. If the Open WebUI backend is down, its chat interface cannot reach the agent even if Hermes is healthy. A service does not keep a powered-off host running.

Windows Task Scheduler starts the gateway launcher and does not supervise later gateway crashes. Check the actual process state and start it if necessary. Keep the profile .env and Open WebUI data directory private. See [How to run Hermes Agent 24/7 on a VPS or home server](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md).

## If it doesn't answer

- API never listens: check `API_SERVER_ENABLED`, active profile, key length and placeholder rejection, then restart the running gateway.
- 401 or invalid key: compare the saved Open WebUI connection key with the intended profile's key. For `/p/<profile>/v1`, use that named profile's key.
- No models: retain `/v1`, inspect authenticated `/v1/models`, and check the backend-to-Hermes network path. Docker localhost and loopback binding are different issues.
- Saved correction has no effect: update the Open WebUI connection database through the Admin UI. Do not delete chats or its volume as a first repair.
- Model appears but no reply: inspect Hermes provider credentials, tool errors and logs. A task may still be using tools; health and connectivity do not establish final completion.
- For the wider gateway checklist, see [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md). For scheduled destinations, see [Hermes Agent task finished but no message arrived](https://hermeswatcher.com/troubleshoot/task-finished-but-no-delivery.md).

## Official docs

Reviewed Oct 29, 2026 against the official Hermes docs.

[Official Hermes Open WebUI and the API server docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/open-webui)

## Related guides

- [All messaging platforms](https://hermeswatcher.com/messaging.md)
- [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md)
- [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md)
- [Hermes Agent task finished but no message arrived](https://hermeswatcher.com/troubleshoot/task-finished-but-no-delivery.md)
- [Hermes Agent profiles: separate agents for separate jobs](https://hermeswatcher.com/learn/profiles-separate-agents.md)
- [Hermes Agent security: approvals, allowlists, sandboxing](https://hermeswatcher.com/learn/security-model-approvals-and-sandboxing.md)
- [How to run Hermes Agent 24/7 on a VPS or home server](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md)

## Related tools

- [API server: use Hermes from any OpenAI-compatible client](https://hermeswatcher.com/tools/api-server.md)
- [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md)
- [Command approvals: decide what the agent may run unattended](https://hermeswatcher.com/tools/approvals-security.md)

## Sources

- [Open WebUI integration, official Hermes guide](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/open-webui)
- [Open WebUI guide at the research snapshot](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/website/docs/user-guide/messaging/open-webui.md)
- [API server reference](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server)
- [API key strength guard (pinned implementation)](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/gateway/platforms/api_server.py#L3908-L3934)
- [Multi-profile gateway operation](https://hermes-agent.nousresearch.com/docs/user-guide/multi-profile-gateways)
- [Gateway service lifecycle](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/)
- [Open WebUI vendor quick start](https://docs.openwebui.com/getting-started/quick-start/)
- [website/docs/user-guide/multi-profile-gateways.md](https://raw.githubusercontent.com/NousResearch/hermes-agent/main/website/docs/user-guide/multi-profile-gateways.md)
- [Open WebUI official uv installation instructions](https://raw.githubusercontent.com/open-webui/docs/main/docs/getting-started/quick-start/tab-python/Uv.md)

---

HermesWatcher is an independent guide. It is not affiliated with or endorsed by Nous Research. The [official Hermes Agent documentation](https://hermes-agent.nousresearch.com/docs) and [repository](https://github.com/NousResearch/hermes-agent) from Nous Research are the authority; each page here lists the official sources it was written from. If this site and the official docs disagree, trust the official docs. Index for agents: https://hermeswatcher.com/llms.txt