Skip to content
BSWEN
Blog

How to Install and Run Hermes WebUI on Linux, macOS, or WSL2

Cowrie
Cowrie
Dev @ Bswen

Purpose

This post shows how to install and run Hermes WebUI on Linux, macOS, or WSL2. I will cover the bootstrap script, the daemon launcher, and how to run an isolated trial without touching your existing setup.

Environment

  • Hermes WebUI v0.51.192
  • Python 3.12+
  • Linux, macOS, or WSL2
  • Hermes Agent already installed (the WebUI is a thin interface layer)

What Happened?

I cloned the repository and tried to get the server running. The README mentions a bootstrap.py script that handles auto-discovery of the agent directory, Python executable, state directory, default workspace, and port.

Here is the happy path:

Clone and bootstrap
git clone https://github.com/nesquena/hermes-webui.git hermes-webui
cd hermes-webui
python3 bootstrap.py

The bootstrap performs 5 steps:

  1. Detects the Hermes Agent installation
  2. Finds or creates a Python environment
  3. Starts the WebUI server
  4. Waits for the /health endpoint to respond
  5. Opens your browser

How to Run It?

For an interactive first run, bootstrap.py is enough. For a background daemon on a homelab server, I use ctl.sh:

Daemon mode
./ctl.sh start
./ctl.sh status
./ctl.sh logs --lines 100
./ctl.sh stop

ctl.sh wraps the daemon lifecycle without requiring fuser or pkill. It is a thin wrapper around bootstrap.py that handles PID tracking.

If you want to try the WebUI without affecting your existing Hermes state, you can override the environment variables:

Isolated trial
HERMES_HOME=/tmp/hermes-webui-agent-home \
HERMES_WEBUI_STATE_DIR=/tmp/hermes-webui-agent-state \
HERMES_WEBUI_PORT=8789 \
python3 bootstrap.py

You can also launch manually without the bootstrap script:

Manual launch
HERMES_WEBUI_PORT=8787 venv/bin/python /path/to/hermes-webui/server.py

Common Mistakes

I ran into two issues when setting this up:

  1. Using sudo docker compose up -d without setting absolute paths — this expands ${HOME} to /root, so Docker mounts /root/.hermes instead of your real home directory.

  2. Using system Python instead of the agent venv Python when launching manually. The WebUI shares dependencies with the agent, so using the wrong Python can cause import errors.

Summary

In this post, I showed how to install and run Hermes WebUI on Linux, macOS, or WSL2. The key point is that bootstrap.py handles the heavy lifting, and ctl.sh gives you daemon mode for servers. Whether you want an interactive first run or a background service, the provided launchers get you from clone to chat in under a minute.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: