Hermes Web UI is a free, open-source desktop app and self-hosted web dashboard for Hermes Agent.
It turns Hermes Agent CLI into a visual workspace for AI chat, platform channels, scheduled jobs, usage analytics, files, profiles, skills, memory, logs, and a web terminal.
Read More: Automate Anything: 10 Best & Open-source AI Agents
Hermes Agent can become hard to manage from the terminal once chats, models, credentials, memory, skills, profiles, uploads, and recurring tasks start to pile up.
Hermes Web UI solves that control problem by placing the agent runtime behind a browser UI, desktop app, npm package, or Docker deployment.
Features
- Manage real-time Hermes Agent chat sessions through Socket.IO streaming.
- Create, rename, delete, search, and switch chat sessions.
- Store Web UI sessions in a local SQLite database.
- Group sessions by platform source such as Telegram, Discord, Slack, and other channels.
- Render Markdown answers with syntax highlighting and code copy.
- Expand tool call details for arguments and results.
- Upload files inside the selected Hermes profile.
- Download uploaded files and agent-generated files across local, Docker, SSH, and Singularity backends.
- Select models from authorized Hermes profiles.
- View per-session model badges and context token usage.
- Configure Telegram, Discord, Slack, WhatsApp, Matrix, Feishu, WeChat, and WeCom channels.
- Track input tokens, output tokens, estimated costs, cache hit rate, model usage, and 30-day usage trends.
- Create, edit, pause, resume, delete, and manually trigger cron jobs.
- Manage model providers through presets, custom OpenAI-compatible endpoints, OAuth login, and default model switching.
- Create, rename, delete, clone, import, export, and switch Hermes profiles.
- Browse, upload, download, rename, copy, move, delete, and inspect files.
- Run multi-agent group chat rooms with mentions, invite codes, and SQLite persistence.
- Browse installed skills and attached skill files.
- View agent, server, and error logs with filters.
- Use token auth or username/password login.
- Change display, agent, memory, reset, privacy, model, profile, and provider settings.
- Run terminal sessions inside the browser through node-pty and xterm.
Use Cases
- Run Hermes Agent from a browser interface during long AI chat sessions.
- Manage multiple AI agent profiles for different workspaces or tasks.
- Connect Hermes Agent to messaging platforms from one configuration page.
- Schedule recurring AI jobs with cron expressions and quick presets.
- Monitor token usage and estimated model costs across sessions.
- Browse files created by agents across local and remote backends.
- Review logs when an agent bridge, provider, channel, or profile setting breaks.
How to Use It
1. Choose the install method:
The desktop app is the best starting point if you want the lowest setup friction. Hermes Studio Desktop bundles the Web UI runtime and uses the native Hermes data location for Hermes Agent data. Windows stores Hermes data under %LOCALAPPDATA%\hermes with %APPDATA%\hermes as fallback. macOS and Linux store Hermes data under ~/.hermes. The Web UI wrapper stores its own state under ~/.hermes-web-ui unless HERMES_WEB_UI_HOME changes that path.
2. Install through npm when you want CLI control:
Install the package globally.
npm install -g hermes-web-uiStart the Web UI.
hermes-web-ui startOpen the local dashboard.
http://localhost:86483. Use Docker Compose when you want an isolated deployment:
Run the pre-built image.
WEBUI_IMAGE=ekkoye8888/hermes-web-ui docker compose up -dBuild from source when you want local build control.
docker compose up -d --buildWatch the container logs.
docker compose logs -f hermes-webuiOpen the Docker deployment.
http://localhost:60604. Change the default login immediately:
The bootstrap username and password are admin and 123456. Change the default account after the first login. Keep the reset command available if a local setup becomes locked or unusable.
hermes-web-ui reset-default-login5. Confirm Hermes Agent runtime discovery:
Hermes Web UI looks for a Hermes Agent source checkout that contains run_agent.py, such as ~/.hermes/hermes-agent. The runtime can fall back to the Python environment used by the installed hermes command, then to the system Python. This matters when chat starts fail even though the dashboard loads.
6. Add providers before judging chat quality:
Open model management and add a provider from a preset or a custom OpenAI-compatible endpoint. The Web UI can discover models from ~/.hermes/auth.json and provider /v1/models endpoints. Check model visibility inside the selected profile before starting a serious chat.
7. Create separate profiles for different work:
Create one profile for general chat, another for automation, and another for experimental providers. Profile-scoped storage keeps uploads, sessions, jobs, providers, memory, skills, plugins, and model visibility separated.
8. Configure platform channels only after local chat works:
Set up Telegram, Discord, Slack, WhatsApp, Matrix, Feishu, WeChat, or WeCom after a local browser chat works. Channel credentials write to ~/.hermes/.env, and channel behavior settings write to ~/.hermes/config.yaml.
9. Use cron jobs for repeatable agent tasks:
Create a scheduled job only after the prompt works in a normal session. Trigger the job manually once, inspect the result, then enable the recurring schedule. This avoids repeated failures from a bad prompt, missing provider, broken profile, or wrong working directory.
10. Use logs before changing providers:
Open the logs page when a chat, bridge, provider, file action, or platform channel fails. Filter by log level, log file, and keyword before changing multiple settings at once.
Install and development commands
| Command | Purpose |
|---|---|
npm install -g hermes-web-ui | Install Hermes Web UI globally. |
hermes-web-ui start | Start the Web UI in background mode. |
hermes-web-ui start --port 9000 | Start the Web UI on port 9000. |
hermes-web-ui stop | Stop the background process. |
hermes-web-ui restart | Restart the background process. |
hermes-web-ui status | Check the running status. |
hermes-web-ui update | Update to the latest version and restart. |
hermes-web-ui upgrade | Run the update alias. |
hermes-web-ui -v | Show the version number. |
hermes-web-ui -h | Show help. |
hermes-web-ui clear-login-locks | Delete persisted login IP lock records. |
hermes-web-ui clear-login-locks --restart | Delete login locks and restart the running Web UI process. |
hermes-web-ui reset-default-login | Create or reset the default super administrator login. |
git clone https://github.com/EKKOLearnAI/hermes-web-ui.git | Clone the repository. |
cd hermes-web-ui | Enter the project directory. |
npm install | Install project dependencies. |
npm run dev | Start the development environment. |
npm run build | Build the project into dist/. |
Docker commands
WEBUI_IMAGE=ekkoye8888/hermes-web-ui docker compose up -ddocker compose up -d --builddocker compose logs -f hermes-webuiDevelopment ports
| Service | URL |
|---|---|
| Frontend | http://localhost:8649 |
| BFF Server | http://localhost:8647 |
| npm default app | http://localhost:8648 |
| Docker Compose app | http://localhost:6060 |
Environment variables
| Variable | Default | Purpose |
|---|---|---|
PORT | 8648 | Sets the Web UI listen port. |
BIND_HOST | 0.0.0.0 | Sets the Web UI bind host. |
HERMES_WEB_UI_HOME | ~/.hermes-web-ui | Sets the Web UI data home. |
HERMES_WEBUI_STATE_DIR | unset | Acts as a compatibility alias for HERMES_WEB_UI_HOME. |
UPLOAD_DIR | $HERMES_WEB_UI_HOME/upload | Sets the upload root. |
CORS_ORIGINS | * | Sets Koa CORS origins. |
AUTH_TOKEN | auto-generated | Sets an explicit bearer token. |
AUTH_JWT_SECRET | AUTH_TOKEN | Sets the JWT signing secret. |
PROFILE | default | Sets the startup Hermes profile. |
LOG_LEVEL | info | Sets the server log level. |
BRIDGE_LOG_LEVEL | $LOG_LEVEL or info | Sets the bridge log level. |
MAX_DOWNLOAD_SIZE | 200MB | Sets the maximum file download size. |
MAX_EDIT_SIZE | 10MB | Sets the maximum editable file size. |
WORKSPACE_BASE | /opt/data/workspace | Sets the workspace browsing base directory. |
HERMES_HOME | platform default | Sets the Hermes data home. |
HERMES_BIN | hermes | Sets a custom Hermes CLI binary path. |
HERMES_AGENT_ROOT | auto-discovered | Sets the Hermes Agent source checkout path. |
HERMES_AGENT_BRIDGE_PYTHON | auto-discovered | Sets the Python interpreter for the bridge. |
HERMES_AGENT_BRIDGE_UV | auto-discovered | Sets the uv executable for the bridge. |
UV | auto-discovered | Sets the fallback uv executable. |
PYTHON | auto-discovered | Sets the fallback Python executable. |
HERMES_AGENT_BRIDGE_ENDPOINT | platform default | Sets the agent bridge broker endpoint. |
HERMES_AGENT_BRIDGE_TIMEOUT_MS | 120000 | Sets the Node request timeout for the bridge broker. |
HERMES_AGENT_BRIDGE_CONNECT_RETRY_MS | 5000 | Sets the bridge socket retry window. |
HERMES_AGENT_BRIDGE_STARTUP_TIMEOUT_MS | 120000 | Sets the startup readiness timeout. |
HERMES_AGENT_BRIDGE_AUTO_RESTART | enabled | Controls bridge auto-restart after unexpected exit. |
HERMES_AGENT_BRIDGE_RESTART_DELAY_MS | 1000 | Sets the bridge restart backoff delay. |
HERMES_AGENT_BRIDGE_PLATFORM | cli | Sets the platform identity passed to Hermes Agent. |
HERMES_AGENT_BRIDGE_WORKER_TRANSPORT | platform default | Sets worker transport as TCP, IPC, or Unix socket. |
HERMES_AGENT_BRIDGE_WORKER_PORT_BASE | 18780 | Sets the base TCP worker port. |
HERMES_BRIDGE_PROVIDER | profile/default | Overrides the provider for bridge runs. |
HERMES_BRIDGE_TOOLSETS | profile/default | Overrides toolsets for bridge runs. |
HERMES_BRIDGE_MAX_TURNS | profile/default | Overrides max turns for bridge runs. |
HERMES_BRIDGE_SUPPRESS_PLATFORM_HINT | cli | Controls bridge platform hint suppression. |
HERMES_OPENROUTER_APP_REFERER | https://hermes-studio.ai | Sets the OpenRouter attribution referer. |
HERMES_OPENROUTER_APP_TITLE | Hermes Web UI | Sets the OpenRouter attribution title. |
HERMES_OPENROUTER_APP_CATEGORIES | cli-agent,personal-agent | Sets OpenRouter attribution categories. |
HERMES_WEB_UI_MANAGED_GATEWAY | platform/runtime dependent | Forces managed legacy gateway handling. |
HERMES_WEB_UI_STOP_GATEWAYS_ON_SHUTDOWN | enabled in production | Controls gateway shutdown behavior. |
GATEWAY_HOST | 127.0.0.1 | Sets the default gateway host in profile config. |
HERMES_WEB_UI_PREVIEW_REPO | package repository | Sets the GitHub repository for Version Preview. |
HERMES_WEB_UI_PREVIEW_AGENT_BRIDGE_TRANSPORT | platform default | Sets Version Preview broker transport. |
HERMES_WEB_UI_PREVIEW_AGENT_BRIDGE_ENDPOINT | isolated preview endpoint | Overrides the Version Preview broker endpoint. |
HERMES_WEB_UI_BACKEND_PORT | 8648 | Sets the backend port for the Vite dev proxy. |
HERMES_WEB_UI_FRONTEND_PORT | 8649 | Sets the frontend Vite dev server port. |
Platform channel configuration
| Platform | Configuration scope |
|---|---|
| Telegram | Bot token, mention control, reactions, free-response chats. |
| Discord | Bot token, mention, auto-thread, reactions, channel allow and ignore lists. |
| Slack | Bot token, mention control, bot message handling. |
| Enable switch, mention control, mention patterns. | |
| Matrix | Access token, homeserver, auto-thread, DM mention threads. |
| Feishu | App ID, app secret, mention control. |
| QR code login and credential saving. | |
| WeCom | Bot ID and bot secret. |
Alternatives and Related Resources
- Best OpenClaw Alternatives: Compare Hermes Agent against other local and safe agent workflows.
- Best CLI AI Coding Agents: Find terminal-first coding agents for developer workflows.
- Hermes Agent Quickstart: Set up the Hermes Agent runtime before using the dashboard.
Pros
- Hermes Agent control panel.
- Desktop and self-hosted options.
- Built-in usage analytics.
- Cron job management.
- Multi-profile support.
- Integrated file browser.
- Built-in web terminal.
Cons
- Commercial license required.
- Many configuration variables.
- Not a hosted chatbot.
FAQs
Q: Is Hermes Web UI free?
A: Hermes Web UI can be installed and used for personal, educational, and research purposes under BSL-1.1. Commercial use requires a separate license until the project changes to Apache-2.0 on May 10, 2029.
Q: Does Hermes Web UI require a sign-up?
A: Hermes Web UI uses local authentication through a token or username/password login. Model providers, OAuth logins, or external AI services can require separate accounts.
Q: Does Hermes Web UI include Hermes Agent?
A: The Docker Compose setup can run a single-container deployment with integrated Hermes Agent. The desktop and npm setups still need a working Hermes Agent runtime, source checkout, package install, or compatible Python environment.
Q: Can Hermes Web UI run local models?
A: Hermes Web UI can manage providers through credential pools, OpenAI-compatible endpoints, provider model discovery, and default model switching. Local model support depends on the provider endpoint exposed to Hermes Agent.
