Guide · Open source

How to use hermes-webui: install, run and access Hermes Agent in a browser

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

hermes-webui is an open-source, MIT-licensed, dark-themed web interface for Hermes Agent, so you can use the agent from a browser or phone instead of a terminal. It is written in Python and plain JavaScript with no build step. This guide shows you how to clone and start it, stop it correctly, reach it remotely over an SSH tunnel, and understand where it fits.

Hermes WebUInesquena/hermes-webui · ★ 19.4k · MIT Install options & downloads

Quick start

1Confirm Hermes Agent is installed. WebUI uses your existing Hermes Agent setup and models, so set that up first. Make sure python3 is available.
2Clone the repository. Run git clone https://github.com/nesquena/hermes-webui.git hermes-webui, then enter the folder with cd hermes-webui.
3Run the bootstrap script. Start the app with python3 bootstrap.py. Stop it with Ctrl-C while it runs in the foreground.
4Optionally run as a daemon. On a VM or homelab, use ./ctl.sh start, then check it with ./ctl.sh status.
5Connect remotely. Reach the UI through an SSH tunnel as described in the full README, then open it in your browser or phone.

Check that you have Hermes Agent and Python 3 first

WebUI depends on Hermes Agent. It uses your existing Hermes setup and models, so it cannot run on its own without Hermes Agent installed.

The only listed prerequisite for the WebUI install is Python 3.

Hermes Agent installed and configured on the host
Python 3 available as python3

Install and start hermes-webui with bootstrap.py

Clone the repository, enter the project folder and run the bootstrap script. The README also lists ./start.sh as an alternative shell launcher.

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

Run it as a background daemon with ctl.sh

For a VM or homelab, ctl.sh wraps the daemon lifecycle. ctl.sh start runs in the background, writes its PID to ~/.hermes/webui.pid and logs to ~/.hermes/webui.log. The README says it works without fuser or pkill.

To bind to all interfaces, you can set an inline override such as HERMES_WEBUI_HOST=0.0.0.0 ./ctl.sh start. ctl.sh also respects a .env file.

./ctl.sh start: start the background daemon
./ctl.sh status: show PID, uptime, bound host and port, log path and /health
./ctl.sh logs --lines 100: tail the log
./ctl.sh restart and ./ctl.sh stop

./ctl.sh start
./ctl.sh status
./ctl.sh logs --lines 100
./ctl.sh restart
./ctl.sh stop

Stop the server the right way

Each launch method stops differently. Only ctl.sh start writes a PID file, so ./ctl.sh stop cannot stop a server started by bootstrap.py or start.sh directly.

For a foreground bootstrap.py run, press Ctrl-C. For a detached bootstrap.py or ./start.sh, find the process with lsof -i :8787 (or ss -tlnp) and kill it.

python3 bootstrap.py: Ctrl-C
./ctl.sh start: ./ctl.sh stop
Detached bootstrap.py or ./start.sh: find the PID with lsof -i :8787 and kill it

lsof -i :8787

Reach hermes-webui from your computer or phone

The README says you can access the UI securely through an SSH tunnel from your Hermes setup, and that a single command starts the UI and a single command sets up the tunnel. The tunnel command itself is not shown in the source excerpt, so check the full README or the linked setup docs for it.

The README also mentions remote, Tailscale and phone access in its configuration section, but that section is not included in the source excerpt. Use the documentation for those details.

Once connected, the interface offers a three-panel layout. The left sidebar holds sessions and navigation, the centre holds chat, and the right panel browses workspace files. Model, profile and workspace controls sit in the composer footer, and all settings are in the Hermes Control Center launcher at the sidebar bottom. The README also mentions setting a password in settings.

Left: sessions and navigation
Centre: chat
Right: workspace file browsing
Composer footer: model, profile and workspace controls, plus a context ring showing token usage
Hermes Control Center: settings and session tools

Understand how chat is routed

By default WebUI runs the Hermes agent in-process and reads your HERMES_HOME config directly. It does not send chat to an external Hermes API server. HERMES_API_URL only feeds the Tasks/cron health probe.

If you run an external endpoint, the README gives two options: add it under Settings then Providers as a custom OpenAI-compatible provider, or set HERMES_WEBUI_CHAT_BACKEND=gateway to route chat through a Hermes Gateway API server. The README says full agent-loop delegation is not yet shipped.

Default: in-process chat using your HERMES_HOME config
Option 1: custom OpenAI-compatible provider in Settings then Providers
Option 2: HERMES_WEBUI_CHAT_BACKEND=gateway

HERMES_WEBUI_CHAT_BACKEND=gateway

What people use it for

Chatting with your Hermes agent from a browser on a laptop
Using the agent from a phone on the same setup
Browsing and previewing workspace files next to a chat
Running a long-lived Hermes web interface on a homelab VM with ctl.sh

Frequently asked questions

Is hermes-webui free to use?

hermes-webui is released under the MIT licence, which the project lists on its page. The source does not list any prices for the project itself. Hermes Agent is a separate dependency, so check its own terms.

What do I need to install hermes-webui?

The listed prerequisite is Python 3, and you also need Hermes Agent installed because WebUI depends on it. Install is a git clone followed by python3 bootstrap.py.

Does hermes-webui work without Hermes Agent?

No. The project is a web interface for Hermes Agent and uses your existing Hermes setup and models. Without Hermes Agent installed it has nothing to connect to.

How do I run hermes-webui in the background?

Use ./ctl.sh start from the project folder. It runs as a background daemon, writes its PID to ~/.hermes/webui.pid and logs to ~/.hermes/webui.log. Check it with ./ctl.sh status.

Why won't ./ctl.sh stop stop my server?

ctl.sh only manages processes it started itself. If you launched with python3 bootstrap.py or ./start.sh in detached mode, find the PID with lsof -i :8787 or ss -tlnp and kill it.

Does hermes-webui send my chats to an external API?

Not by default. The README says chat runs in-process using your HERMES_HOME config. You can route chat through a Hermes Gateway with HERMES_WEBUI_CHAT_BACKEND=gateway, or add an external endpoint as a custom provider.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

hermes-webui suits people who already run Hermes Agent and want a browser or phone interface, especially developers who like a three-panel layout with workspace browsing, and self-hosters running a daemon on a VM or homelab. If you do not have Hermes Agent, or you want a standalone chat app with no server to run, pick another tool such as Open WebUI, LibreChat or the Hermes Agent CLI.

Install options & downloads