HeyRocky

Open WebUI as a Hermes Agent Frontend

Open WebUI can connect to Hermes through the built-in OpenAI-compatible API server. The result is a familiar browser interface backed by a full Hermes agent runtime rather than a simple text-generation proxy.

Official documentation: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/open-webui

The execution-host rule

When Open WebUI sends a request, Hermes creates an agent on the API-server host. Terminal commands, file access, browser automation, local MCP servers, and other tools run there. They do not run on the laptop merely because the browser interface is open on that laptop.

This distinction must be visible in the deployment design. A remote API server is “remote brain and remote hands,” not a safe tunnel into the local workstation.

Connection checklist

  • Enable the Hermes API server.
  • Generate and store a strong API server key.
  • Keep the default loopback bind unless remote access is intentionally designed.
  • Restart the gateway after changing API-server settings.
  • Verify /health without authentication assumptions.
  • Verify /v1/models with a bearer token.
  • Point Open WebUI at a base URL ending in /v1.
  • Match Open WebUI’s API key to the Hermes server key.
  • Document exactly which host owns the tools and files.

Deployment and profile boundaries

Open WebUI connects server-to-server, so browser CORS configuration is not the primary concern for the standard integration. Network exposure and bearer-token handling still matter. If the API server leaves loopback, place it behind deliberate transport security and access controls.

For multiple users, prefer separate Hermes profiles and API ports when memory, skills, credentials, or workspaces must be isolated. Open WebUI’s own user accounts do not automatically create separate Hermes profiles or separate tool authority.

Common pitfalls

  • Omitting /v1 and seeing a successful connection test but no models.
  • Using localhost from inside a container and accidentally pointing back into that container.
  • Assuming Open WebUI executes tools on the browser user’s machine.
  • Exposing the API server publicly with only a weak shared key.
  • Editing container environment variables after first launch and forgetting Open WebUI persisted its old connection in its database.
  • Treating one Hermes profile as multi-tenant isolation.

Verification steps

  1. Query /health on the Hermes host.
  2. Query /v1/models with the configured bearer token.
  3. Confirm the Hermes profile appears in Open WebUI’s model picker.
  4. Ask for a harmless working-directory check and confirm it reports the API host.
  5. Test one non-destructive file or web tool against a known test workspace.
  6. Verify an invalid key receives 401.
  7. Restart Open WebUI and Hermes and confirm the connection persists.
  8. For multi-profile setups, verify one user cannot access another profile’s model, memory, or files.

A polished frontend does not change the underlying authority model. Treat Open WebUI as a client window into the exact machine and profile where Hermes runs.

Related pages