How to Connect Hermes Agent to Open WebUI

To connect Hermes Agent to Open WebUI, turn on the Hermes Agent API server, start the Hermes gateway, and add Hermes as an OpenAI-compatible API provider in Open WebUI.

Use this connection URL:

http://localhost:8642/v1

If Open WebUI runs in Docker and Hermes Agent runs on your host machine, use:

http://host.docker.internal:8642/v1

Set the Open WebUI API key to the same value as your Hermes Agent API_SERVER_KEY. After saving the connection, the hermes-agent model should appear in Open WebUI's model selector.

Hermes Agent is built for agentic work. It can use tools, access memory, work with files, run terminal commands, search the web, and execute multi-step workflows. Open WebUI gives you the other half of the experience: a clean browser-based chat frontend with conversation history, user accounts, model switching, and a familiar interface.

That makes the Hermes Agent Open WebUI setup useful because it separates the backend agent from the frontend chat experience. Hermes Agent does the work. Open WebUI gives users a polished place to interact with it.

This is especially helpful if you want to demo Hermes Agent to a team, build an internal AI assistant, or give non-technical users access to an agent without asking them to use the terminal. It is also a practical option if you want to run Hermes Agent without DevOps or later move toward a more managed deployment.

When you connect Hermes Agent to Open WebUI, you get a local or self-hosted AI workflow with:

This is not just another model connection. Hermes Agent acts more like an agent backend. Open WebUI sends the message, Hermes decides what actions to take, and then the final response appears in the chat.

For a deeper overview of what Hermes can do, read about Hermes Agent features and use cases.

Open WebUI supports providers that follow the OpenAI-compatible Chat Completions API. Hermes Agent can expose its own API server using that same format.

The flow looks like this:

User
  -> Open WebUI chat frontend
  -> Hermes Agent API server
  -> Hermes Agent runtime, tools, memory, and model provider

Open WebUI sends requests to Hermes Agent via endpoints such as /v1/models and /v1/chat/completions. Hermes Agent handles the request with its configured model and available tools, then streams the result back to Open WebUI.

This is why the integration is fast to set up. Open WebUI does not need a special Hermes-only connector. It just needs Hermes Agent to expose an OpenAI-compatible API.

Before connecting Open WebUI to Hermes Agent, make sure you have:

If you are running on Windows, check the current Hermes Agent installation guidance. Hermes commonly expects a Unix-like environment, so Windows users may need WSL2 depending on their setup.

First, confirm Hermes Agent is installed:

hermes --version

If Hermes is not installed yet, complete the official Hermes Agent quickstart before continuing.

You should also make sure Hermes has a working model provider. Hermes Agent can work with OpenAI-compatible providers, local models, and other configured model backends. The Open WebUI connection will only be useful if Hermes itself can already respond to prompts.

Open your Hermes Agent environment file:

~/.hermes/.env

Add these values:

API_SERVER_ENABLED=true
API_SERVER_KEY=your-secret-key

Replace your-secret-key with a strong random key. This key is important because Open WebUI will use it to authenticate with Hermes Agent.

You can also customise the host and port if needed:

API_SERVER_HOST=127.0.0.1
API_SERVER_PORT=8642

For most local setups, the defaults are fine.

Now start the Hermes Agent API server:

hermes gateway

You should see output similar to:

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

Keep this process running. Open WebUI can only talk to Hermes Agent while the Hermes gateway is active.

For a long-running setup, consider using tmux, screen, a system service, or a managed deployment. If your goal is production use, this is where a Deploy Hermes Agent workflow becomes useful.

Before touching Open WebUI, test the Hermes Agent API server directly.

Check the health endpoint:

curl http://localhost:8642/health

A healthy response should look like:

{"status":"ok"}

Then check the model list:

curl http://localhost:8642/v1/models \
  -H "Authorization: Bearer your-secret-key"

You should see a model entry for hermes-agent.

You can also test chat completions:

curl http://localhost:8642/v1/chat/completions \
  -H "Authorization: Bearer your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"hermes-agent","messages":[{"role":"user","content":"Hello from Open WebUI test"}]}'

If this works, Hermes Agent is ready for Open WebUI.

Create a new chat in Open WebUI and open the model selector. Choose hermes-agent.

Send a simple test prompt:

What tools are available to you?

Then try a more workflow-style prompt:

Help me plan a small Python project and list the files I need to create.

This is where the Open WebUI Hermes Agent setup becomes more interesting than a normal model connection. Hermes Agent may use tools, reason through steps, and show inline tool progress before returning the final response.

If you want Open WebUI in Docker and Hermes Agent running on the host machine, you can use a compose setup like this:

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
    extra_hosts:
      - "host.docker.internal:host-gateway"
    restart: always

volumes:
  open-webui:

Then run:

docker compose up -d

Open http://localhost:3000.

Important note about environment variables: The OPENAI_API_BASE_URL and OPENAI_API_KEY environment variables only take effect the very first time Open WebUI starts. After that, connection settings are stored in its internal database. If you need to change the connection later, use the Admin Settings UI - editing the environment variables and restarting the container won't update an existing installation. For a full self-hosted deployment, see Open WebUI hosting.

All the steps above assume you're comfortable with terminal commands, environment files, and gateway processes. If you'd rather not manage any of that infrastructure, you can deploy Hermes Agent through a managed platform and simply paste the provided API URL into Open WebUI's connection settings - the same Step 5, but without needing to touch Steps 1 through 4. Your agent runs 24/7 with backups, SSL, and updates handled for you, and Open WebUI becomes a pure frontend to a fully maintained backend.

The Hermes Agent + Open WebUI combination makes sense for specific people and situations.

It's great for:

It might not be for:

Make sure your URL includes /v1: http://localhost:8642/v1

Then test:

curl http://localhost:8642/v1/models \
  -H "Authorization: Bearer your-secret-key"

If Open WebUI cannot auto-detect models, manually add hermes-agent to the model filter or allowlist.

Check that the Hermes gateway is still running (hermes gateway). Then confirm the API key in Open WebUI exactly matches API_SERVER_KEY in your .env. Do not add extra spaces or quotation marks unless your environment format requires them.

If Open WebUI runs in Docker, replace http://localhost:8642/v1 with http://host.docker.internal:8642/v1. On Linux without Docker Desktop, you may need --add-host=host.docker.internal:host-gateway or host networking.

This can be normal. Hermes Agent may be running tool calls, reading files, searching, or planning before it sends the final answer. Unlike a plain chat model, Hermes often does actual work behind the scenes.

If you set OPENAI_API_BASE_URL in your Docker environment variables but the connection isn't working, remember: those variables only apply on the container's very first startup. After that, connection settings are stored in Open WebUI's internal database. Use the Admin Settings UI to add or edit connection environment variable changes, which won't override the database once Open WebUI has been initialised.

Usually, no. Open WebUI talks to the Hermes Agent server-to-server. CORS is mainly relevant if a browser frontend calls the Hermes Agent directly.

Do not expose the Hermes Agent API server to the public internet without protection.

For safer production use:

Hermes Agent may have access to local files, terminal operations, memory, and tools. Treat it like a real backend service, not just a model endpoint.

You can build a custom Hermes Agent frontend, but many teams do not need to start there.

Open WebUI already gives you login and user management, conversation history, model selection, a familiar chat layout, and provider configuration. Hermes Agent adds tool use, memory, skills, agentic workflows, an OpenAI-compatible API, and inline tool progress.

That combination is the point. Open WebUI handles the interface. Hermes Agent handles the work. For most teams, this is faster than building a custom UI and more useful than connecting Open WebUI to a plain model server.

Can Open WebUI connect to Hermes Agent?

Yes. Open WebUI can connect to Hermes Agent through the Hermes Agent API server because Hermes exposes an OpenAI-compatible API endpoint.

What URL should I use?

Use http://localhost:8642/v1. If Open WebUI runs in Docker, use http://host.docker.internal:8642/v1.

What model name should I select?

Use hermes-agent. If you are running multiple Hermes profiles, each profile may advertise its own model name.

Is Hermes Agent a model or an agent?

Hermes Agent is an agent backend. It uses an LLM provider, but its value comes from tools, memory, skills, and workflow execution.

Do I need a separate Hermes Agent frontend?

No. Open WebUI can act as the Hermes Agent frontend for chat-based workflows.

Is this production-ready?

It can be, but only with proper authentication, network controls, HTTPS, and deployment management. For production, consider a more structured way to deploy the Hermes Agent.

The fastest way to connect Hermes Agent to Open WebUI is to enable the Hermes Agent API server, start hermes gateway, and add Hermes as an OpenAI-compatible provider in Open WebUI.

For local setups, use http://localhost:8642/v1. For Docker-based Open WebUI setups, use http://host.docker.internal:8642/v1.

This gives you a practical workflow: Hermes Agent becomes the agent backend, and Open WebUI becomes the chat frontend. You get a clean interface, model switching, conversation management, and access to Hermes Agent's tool-driven capabilities without building a custom UI from scratch. If you'd rather skip the terminal work entirely, you can deploy Hermes Agent on managed infrastructure and still connect to Open WebUI in the same way - just with zero server maintenance on your side.