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

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.

For an API client rather than a browser interface, see the official API server examples↗ (opens in a new tab).

If port 8080 is taken, follow Open WebUI's documentation↗ (opens in a new tab) 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.

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. For scheduled destinations, see Hermes Agent task finished but no message arrived.

Official docs

Reviewed Oct 29, 2026 against the official Hermes docs.

Official Hermes Open WebUI and the API server docs↗ (opens in a new tab)

Related guides

• All messaging platforms
• Hermes Agent messaging gateway explained
• Hermes Agent bot not responding in your chat app
• Hermes Agent task finished but no message arrived
• Hermes Agent profiles: separate agents for separate jobs
• Hermes Agent security: approvals, allowlists, sandboxing
• How to run Hermes Agent 24/7 on a VPS or home server

Spotted something wrong or out of date? Tell us on X at @HermesWatcher↗ (opens in a new tab) and we will fix it.

New Hermes Agent updates every day on X. Follow @HermesWatcher