Hermes Token UI

A local, self-hosted web dashboard that aggregates:

• Token usage from your local Hermes Agent session database (~/.hermes/state.db)
• AI benchmarks from the public HuggingFace Open LLM Leaderboard dataset
• Latest model releases from HuggingFace (and optionally OpenRouter)
• arXiv news (manually curated JSON)
• Model discovery via HuggingFace search and a curated OpenAI catalog

Built as a single-file Python server (server.py) + a static single-page HTML/JS UI (index.html). No JavaScript build step. SQLite for users + caching.

---

Features

Tab	Source	Notes
Tokens	~/.hermes/state.db (your local Hermes DB)	Per-model + per-source breakdown, daily/hourly chart, donut, recent sessions
News	Local news.json	Curated arXiv entries + trends, search + category filter + clickable tags
Model Finder	HuggingFace /api/models + curated OpenAI catalog	Free HF tier (no key needed)
AI Benchmarks	HuggingFace datasets/open-llm-leaderboard/contents	~4500 evaluated open-weights models, 6 v2 benchmarks (IFEval, BBH, MATH Lvl 5, GPQA, MUSR, MMLU-PRO)
Latest Models	HuggingFace /api/models?sort=createdAt (always on) + OpenRouter /api/v1/models (opt-in)	Auto-refresh at configured local hours

Other features: user accounts with scrypt-hashed passwords, per-user bearer tokens, admin panel, SSE-based auto-refresh, login rate-limiting.

---

Quick start

git clone https://github.com/<you>/hermes-token-ui.git
cd hermes-token-ui
python3 server.py --port 8765 --host 127.0.0.1 \
    --bootstrap-admin YOURNAME \
    --bootstrap-password 'your-strong-password'

Open http://127.0.0.1:8765/ and sign in with the bootstrap credentials.

The bootstrap admin's bearer token is printed to stdout on first creation — copy it if you want to use the API directly.

Security note: the first user is created as admin. If you ever forget the bootstrap password, delete users.db and re-bootstrap, but you'll lose all accounts.

---

Data sources & legal

This tool pulls from public APIs and datasets. You are responsible for complying with each provider's Terms of Service.

Source	What we fetch	ToS / License
~/.hermes/state.db	Your local Hermes Agent sessions	n/a (your data)
HuggingFace datasets/open-llm-leaderboard/contents	~1 MB parquet, evaluated model scores	Apache-2.0 dataset, public API — HF ToS allows automated retrieval
HuggingFace /api/models	Public model list (newest + by query)	HF ToS allows automated retrieval
OpenRouter /api/v1/models	Model catalog with pricing	OFF BY DEFAULT. Opt-in with --enable-openrouter. See OpenRouter section below.
arXiv	n/a (news is curated locally in news.json)	n/a

OpenRouter

OpenRouter's terms prohibit automated scraping without permission. This tool uses their public /api/v1/models endpoint which is the same API their customers use, but the safe default is off — enable only if you accept the small risk and don't run this on a high-traffic public deployment.

# Enable OpenRouter for the "Latest Models" tab:
python3 server.py --enable-openrouter ...

The HuggingFace tab stays fully functional with --enable-openrouter absent.

---

Setup

Requirements

• Python 3.11+
• pip install pyarrow (only for the AI Benchmarks tab — pulls + parses the HF parquet file)

Optional dependencies

None. The server uses the Python standard library except for pyarrow.

CLI flags

--port N                   TCP port (default 8765)
--host ADDR                bind address (default 127.0.0.1; refuse to bind to 0.0.0.0 without auth)
--user NAME                basic-auth username (legacy, ignored if --bootstrap-admin is used)
--password PASS            basic-auth password (legacy, ignored if --bootstrap-password is used)
--no-self-register         disable /register self-service (admin-only account creation)
--bootstrap-admin NAME     bootstrap admin username (creates the first admin in users.db)
--bootstrap-password PASS  bootstrap admin password
--bootstrap-token TOKEN    bootstrap admin bearer token (auto-generated if omitted)
--bench-refresh-interval N seconds between AI benchmark auto-refreshes (default 86400 = 24h; 0 = off)
--latest-refresh-hours H   comma-separated local hours for daily latest-models refresh (default "6,20"; empty = off)
--enable-openrouter        include OpenRouter in the "Latest Models" tab (off by default; see legal section)

Environment variables

Variable	Equivalent flag
HERMES_TOKEN_UI_USER	--user (legacy bootstrap)
HERMES_TOKEN_UI_PASSWORD	--password (legacy bootstrap)
HERMES_TOKEN_UI_BOOTSTRAP_USER	--bootstrap-admin
HERMES_TOKEN_UI_BOOTSTRAP_PASSWORD	--bootstrap-password
HERMES_TOKEN_UI_BOOTSTRAP_TOKEN	--bootstrap-token
HERMES_TOKEN_UI_COOKIE_SECRET	fixed cookie HMAC secret (set on multi-instance deployments)

---

Usage

Web UI

1. Sign in at /login.
2. Generate your personal bearer token under Account → Rotate.
3. Use it in API calls:

curl -H "Authorization: Bearer YOUR_TOKEN" http://127.0.0.1:8765/api/summary

API endpoints

All endpoints below require authentication (cookie session, HTTP Basic, or Authorization: Bearer <token>).

Method	Path	Notes
GET	/api/summary	Token totals + per-model breakdown
GET	/api/timeseries?bucket=hour|day&days=30&model=NAME	Time series for charting
GET	/api/sessions?limit=30&model=NAME	Recent sessions
GET	/api/news	Cached arXiv news from news.json
GET	/api/benchmarks	Cached Open LLM Leaderboard data
GET	/api/benchmarks/status	Refresh metadata only
GET | POST	/api/benchmarks/refresh	Force-refresh (writes benchmarks.json)
GET	/api/latest	Cached latest-models data (HF + OR if enabled)
GET	/api/latest/status	Refresh metadata only
GET | POST	/api/latest/refresh	Force-refresh (writes latest.json)
GET	/api/find/hf?q=...&limit=10	HuggingFace model search (live API)
GET	/api/find/openai?q=...	Curated OpenAI catalog filter
GET	/api/me	Current user + self_register flag
GET	/api/admin/users	List users (admin only)
POST	/api/admin/users/create	Create user (admin only)
POST	/api/admin/users/{id}/{disable|enable|promote|demote|delete|reset_token|reset_password}	Admin actions
GET	/health	Public health check ({"ok": true, "auth": ...})

Admin panel

Visit /admin while signed in as admin to:

• Create users (with optional admin flag)
• Promote / demote / disable / enable / delete users
• Reset a user's bearer token (one-time reveal in the alert dialog)
• Reset a user's password (you choose the new password)

---

Security

• Password hashing: scrypt (memory-hard, per-user salt, stdlib hashlib.scrypt).
• Session cookies: HttpOnly + SameSite=Strict + HMAC-signed (32-byte secret).
• Bearer tokens: 32-byte URL-safe random, per-user, rotatable via UI or admin.
• Rate-limiting: 5 failed logins per minute per remote IP returns 429.
• Bind safety: --host 0.0.0.0 refuses to start unless auth is enabled.
• Open redirect protection: next= after login only accepts relative paths.
• HTML escaping: all dynamic strings rendered in inline HTML are escaped via the server-side esc() helper.

For a public-facing deployment:

1. Set strong bootstrap credentials.
2. Disable self-registration with --no-self-register.
3. Run behind a TLS-terminating reverse proxy (nginx, Caddy).
4. Set HERMES_TOKEN_UI_COOKIE_SECRET to a fixed value across instances.

---

Files

.
├── server.py              # main HTTP server (stdlib + pyarrow)
├── auth.py                # user DB + scrypt password hashing + auth helpers
├── benchmarks.py          # HuggingFace Open LLM Leaderboard scraper
├── latest.py              # HuggingFace (+ optional OpenRouter) latest-models scraper
├── index.html             # static single-page UI
├── news.json              # (you create) curated arXiv entries
├── benchmarks.json        # (auto-generated) cached OLM leaderboard
├── latest.json            # (auto-generated) cached latest models
├── users.db               # (auto-generated) SQLite user accounts
├── .gitignore             # excludes users.db, JSON caches, secrets
├── LICENSE                # MIT
├── BENCHMARKS-README.md   # AI benchmarks tab deep-dive
└── CREDENTIALS.txt        # (your local copy, never commit) bootstrap info

---

License

MIT — see LICENSE.