Spaces:

f4b404
/

hermes

Running

App Files Files Community

hermes / README.md

Farhan Beg

Update README.md

b2e073e unverified 6 days ago

preview code

raw

history blame contribute delete

11 kB

metadata

title: HuggingMes Hermes WebUI
emoji: 🪽
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7861
pinned: true
license: mit

Run your own AI agent with a chat interface on Hugging Face Spaces — for free.

This is not original work. It combines three great open-source projects into one easy-to-deploy package:

Hermes Agent by Nous Research — the AI brain

Hermes WebUI by @nesquena — the chat interface

HuggingMes by @somratpro — the Hugging Face wrapper

All credit goes to the original creators. This repo just wires them together.

Quick Setup (5 minutes)

1. Duplicate the Space

Click the badge above, name your space → pick CPU Basic (Free) → and keep it public(else the .hf.space urls won't work).

2. Add Your Secrets

Go to Settings → Variables and secrets in your new Space and add these:

Secret	What It's For	How to Get It
`GATEWAY_TOKEN`	Your password for logging into the chat	Make up any strong password
`HF_TOKEN`	Saves your chats and settings so they don't disappear	Go here → Create new token → Pick write
`CLOUDFLARE_WORKERS_TOKEN`	Keeps your Space awake and lets Telegram work	Create a token here choose Edit Cloudflare Workers template

3. Add an AI Provider

Your agent needs an AI model to talk to. Add one of these API keys as a secret (or configure later in the dashboard):

Secret	Provider
`OPENAI_API_KEY`	OpenAI (GPT models)
`ANTHROPIC_API_KEY`	Anthropic (Claude models)
`MOONSHOT_API_KEY`	Moonshot / Kimi

Or configure manually later at /hm/app/config inside your Space.

4. Start It Up

Hit Restart this Space in Hugging Face. Wait 5–8 minutes for the first build.

When you see this in the Logs tab, you're ready:

HuggingMes + Hermes WebUI router listening on 0.0.0.0:7861

Open your Space URL (https://your-name.hf.space) in a new tab, enter your GATEWAY_TOKEN, and start chatting. Open Hermes Dashboard from here (https://f4b404-hermes.hf.space/hm/app)

Pro tip: Bookmark the direct *.hf.space URL — it works better on mobile than the Hugging Face embed.

What You Get

URL	What It Is
`/`	Chat UI — main interface for talking to your agent
`/hm`	Status dashboard — see what's running
`/hm/app/`	Settings — add AI models, set up cron jobs, manage profiles
`/v1/*`	API endpoint — connect other apps to your agent
`/telegram`	Telegram bot (if you added `TELEGRAM_BOT_TOKEN`)

Your Data Is Safe

When HF_TOKEN is set:

All your chats, files, settings, and agent memory are backed up to a private Hugging Face Dataset every 10 minutes
If the Space restarts, everything comes back exactly as you left it

Common Issues

Problem	Fix
Login keeps looping	Open the Space URL in a new tab (Hugging Face iframe blocks cookies)
Space goes to sleep after a few hours	Make sure `CLOUDFLARE_WORKERS_TOKEN` is set
Agent doesn't reply to questions	Check that you added an AI provider API key
Dashboard shows blank pages	Hard-refresh and clear service workers in browser dev tools

Want It on Your Phone?

Use the same (https://your-name.hf.space) url in android and then you can install it as Progressive Web App(PWA) or just use the same url on any browser for normal chat using the web.

🔧 Advanced Setup & Technical Details

Skip this section if you just want to chat. The steps above are enough to get started. This part is for developers, power users, and anyone who wants to customize or understand the internals.

Optional Secrets (Power Users)

Secret	What It Does
`CLOUDFLARE_ACCOUNT_ID`	Explicit Cloudflare account ID if you have multiple
`TELEGRAM_BOT_TOKEN`	Enables the Telegram bridge so you can chat with Hermes from Telegram
`TELEGRAM_ALLOWED_USERS`	Comma-separated numeric Telegram user IDs allowed to use the bot
`PRIMARY_UI`	Set to `dashboard` to make `/` show the HuggingMes status page instead of the chat UI. Default is `webui`.
`SYNC_INTERVAL`	Backup cadence in seconds (default 600, range 60–86400)
`HERMES_AGENT_VERSION`	Pin the upstream Hermes Agent base image to a specific tag for reproducibility (default `latest`)
`BACKUP_DATASET_NAME`	Name of the private HF Dataset used for persistence (default `huggingmes-backup`)

Configure LLM Provider via Config Editor

If you prefer not to add API keys as HF Secrets, you can configure providers directly in Hermes after the Space starts:

Open /hm/app/config in your Space
Add your provider under the llm section:

llm:
  openai:
    api_key: "${OPENAI_API_KEY}"
  anthropic:
    api_key: "${ANTHROPIC_API_KEY}"
  moonshot:
    api_key: "${MOONSHOT_API_KEY}"
    base_url: "https://api.moonshot.cn/v1"

If you set the API keys as HF Secrets, you can reference them with ${VAR_NAME} as shown above. Hermes supports many providers — see the Hermes Agent docs for the full list.

Using the API from Code

Your Space exposes an OpenAI-compatible API at /v1/*:

curl https://<you>-<name>.hf.space/v1/chat/completions \
  -H "Authorization: Bearer $GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hermes",
    "messages": [{"role": "user", "content": "hello"}]
  }'

from openai import OpenAI

client = OpenAI(
    base_url="https://<you>-<name>.hf.space/v1",
    api_key="<your GATEWAY_TOKEN>",
)
resp = client.chat.completions.create(
    model="hermes",
    messages=[{"role": "user", "content": "hello"}],
)

Adding MCP Servers

MCP (Model Context Protocol) servers extend your agent's capabilities. Add them via the config editor at /hm/app/config:

mcp:
  servers:
    fetch:
      command: uvx
      args: ["mcp-server-fetch"]
    filesystem:
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/opt/data/workspace"]

uvx and npx are pre-installed in the image.

Persistence Details

When HF_TOKEN is set:

On boot, the Space downloads the latest snapshot from your private HF Dataset and restores it into /opt/data/.
Every SYNC_INTERVAL seconds (default 600), it detects state changes and uploads a new snapshot.
On graceful shutdown (SIGTERM), it does one final sync before exit.

What gets backed up: chat sessions, agent memory, workspace files, profiles, skills, cron jobs, Hermes config. The dataset is private to your HF account.

Architecture

Single port (7861) Node.js router fronts multiple backends:

HF Space port 7861
        │
        ▼
   health-server.js  (router + auth + status page)
        │
        ├─► /                  → Hermes WebUI         (127.0.0.1:8787)
        ├─► /hm                → HuggingMes status    (in-process)
        ├─► /hm/app/*          → Hermes dashboard     (127.0.0.1:9119)  [SPA-rewritten]
        ├─► /v1/*              → Hermes gateway API   (127.0.0.1:8642)  [bearer auth]
        ├─► /telegram          → Telegram webhook     (127.0.0.1:8765)
        └─► /health, /status   → in-process JSON

start.sh boots Hermes Agent's gateway + dashboard + WebUI as subprocesses, then the router on top. hermes-sync.py runs the periodic HF Dataset upload loop. Cloudflare and Telegram setup runs once at boot if their respective secrets are set.

Local Testing

git clone https://github.com/F4bC0d3/huggingmes-hermes-webui.git
cd huggingmes-hermes-webui
cp .env.example .env
# edit .env with GATEWAY_TOKEN and provider API keys (e.g., OPENAI_API_KEY, ANTHROPIC_API_KEY)
docker build -t huggingmes-hermes-webui .
docker run --rm -p 7861:7861 --env-file .env huggingmes-hermes-webui
# open http://localhost:7861

Extended Troubleshooting

Symptom	Cause / Fix
Build fails on `nousresearch/hermes-agent:latest`	Set `HERMES_AGENT_VERSION` to a specific tag and restart
Container Running but `/` returns 502	Hermes WebUI didn't bind. Check Logs tab for `webui.log` output — usually missing/wrong provider API key or LLM config
`/v1/*` returns 401	Need `Authorization: Bearer <GATEWAY_TOKEN>` header
`/api/status` 404s in logs	Cosmetic — old browser tab polling. Ignored.
Login loops on `/login`	Browser embedded in HF iframe blocks cookies. Open the Space in a new tab.
Dashboard pages blank or 404 on refresh	Should be fixed by the SPA rewriter in health-server.js. Hard-refresh and unregister service worker if cached: DevTools → Application → Service Workers → Unregister
Space sleeps after a few hours	Free tier limitation. Add `CLOUDFLARE_WORKERS_TOKEN` to provision a keep-alive cron worker
Telegram bot doesn't respond	HF Spaces blocks `api.telegram.org` egress. Add `CLOUDFLARE_WORKERS_TOKEN` to auto-provision an outbound proxy
Two Spaces overwriting each other's backup	Set different `BACKUP_DATASET_NAME` on each
Agent responds but cannot answer questions	No LLM provider configured. Add provider API keys and restart, or configure via `/hm/app/config`

Credits

Nous Research for Hermes Agent — the agent runtime, the persistent memory system, the multi-provider LLM routing, the cron and skills systems. None of this exists without their work.
@nesquena for Hermes WebUI — the chat interface you actually see and use. Three-panel layout, SSE streaming, slash commands, profile management, theme system, mobile responsive design — all theirs.
@somratpro for HuggingMes — the HF Space packaging, the HF Dataset backup engine (hermes-sync.py), the Cloudflare proxy and keepalive setup, the Telegram integration, and the gateway auth wrapper.

This repo's only contribution is the integration layer: a Node.js router that fronts both UIs on a single HF Space port, unified auth where one GATEWAY_TOKEN gates everything, and minor tweaks to start.sh to launch hermes-webui alongside the existing HuggingMes processes. If you find this useful, star the upstream projects.

License

MIT — same as all upstream projects.