docs: rewrite README + add suspension disclaimer

- Add prominent 'Read this before you deploy' section warning that HF
accounts are being suspended for always-on free-tier agent Spaces;
the Cloudflare keep-alive worker is the likely trigger. Recommend a
throwaway account or paid tier, and keeping off-platform backups.
- Update 'What You Get' to include /hm/logs, /hm/desktop-app-setup, /hmd.
- Add Hermes desktop app section (stable persisted session token,
/hm/desktop-app-setup, local-vs-remote feature split).
- Note OAuth + ~/.hermes persistence and config.yaml redaction in the
data-safety section, with the caveat that a suspended account loses
the backup dataset too.
- Add Ollama prefix + full provider-prefix list to quick start, plus an
Ollama subsection.
- Add debugging-without-SSH endpoints table (/hm/logs,
/hm/debug/model-options[-trace], /status).
- Update persistence details: atomic restore, hot-path pruning,
Tini + SIGTERM, file lock.
- Update architecture diagram/prose: Tini as PID 1, wait -n watchdog,
/hmd route, in-process log/debug viewers.
- Add suspension + desktop-app rows to troubleshooting table.
- Add HERMES_DASHBOARD_SESSION_TOKEN and WRITE_SECRETS_TO_ENV to the
optional secrets table.
- Rewrite credits paragraph to reflect this repo's actual contribution
(router, unified auth, stable token, OAuth persistence, log/debug
endpoints, security hardening) instead of 'minor tweaks.'

README.md

@@ -20,13 +20,28 @@ All credit goes to the original creators. This repo just wires them together.
 
 ---
 
+## ⚠️ Read this before you deploy
+
+**Hugging Face accounts are getting suspended for running this kind of always-on agent on free Spaces.** It is not hypothetical — people (myself included) have had Spaces flagged and accounts warned or suspended, sometimes with no warning and no usable appeal path.
+
+This project runs Hermes Agent, a WebUI, and a Cloudflare keep-alive worker specifically to defeat the free-tier sleep timer. That is exactly the pattern Hugging Face's trust & safety team has been flagging as abuse of free compute. Treat it accordingly:
+
+- **Do not deploy this on an account you cannot afford to lose.** Use a throwaway HF account, or pay for a Pro/Spaces Compute tier and follow their ToS. Do not put your main account, your models, your datasets, or your other Spaces at risk.
+- **Free-tier always-on hosting of a personal agent is against the spirit (and increasingly the letter) of HF's ToS.** The Cloudflare keep-alive worker in this repo exists to keep a free Space awake 24/7 — that is the part most likely to trigger a suspension.
+- **Your private backup Dataset may also be at risk.** If the account is suspended you can lose access to your chats, memory, and workspace along with the Space. Keep an off-platform backup if any of that matters to you.
+- **I am not responsible if your account gets suspended.** You are. This is a personal project shared as-is; deploying it is your decision and your risk.
+
+If you want a safer alternative, run the same stack on any cheap VPS ($2–5/mo) — the Dockerfile and `start.sh` work outside HF with minor env changes. See the discussion in the repo for migration notes.
+
+---
+
 ## Quick Setup (5 minutes)
 
 ### 1. Duplicate the Space
 
 [![Duplicate this Space](https://huggingface.co/datasets/huggingface/badges/resolve/main/duplicate-this-space-xl.svg)](https://huggingface.co/spaces/f4b404/hermes?duplicate=true)
 
-Click the badge above, name your space → pick **CPU Basic (Free)** → and keep it public(else the .hf.space urls won't work).
+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
 
@@ -35,20 +50,21 @@ 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](https://huggingface.co/settings/tokens) → Create new token → Pick write|
+| `HF_TOKEN` | Saves your chats and settings so they don't disappear | [Go here](https://huggingface.co/settings/tokens) → Create new token → Pick write |
 | `CLOUDFLARE_WORKERS_TOKEN` | Keeps your Space awake and lets Telegram work | [Create a token here](https://dash.cloudflare.com/profile/api-tokens) 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):
+Your agent needs an AI model to talk to. The simplest way is to set `LLM_MODEL` and `LLM_API_KEY` as secrets — `start.sh` parses the `provider/model` prefix and exports the right provider env var automatically:
 
-| Secret | Provider |
-|--------|----------|
-| `OPENAI_API_KEY` | OpenAI (GPT models) |
-| `ANTHROPIC_API_KEY` | Anthropic (Claude models) |
-| `MOONSHOT_API_KEY` | Moonshot / Kimi |
+```
+LLM_MODEL=openrouter/anthropic/claude-sonnet-4
+LLM_API_KEY=sk-or-...
+```
 
-Or configure manually later at `/hm/app/config` inside your Space.
+Supported prefixes include `openrouter/`, `anthropic/`, `openai/`, `huggingface/` (`hf/`), `google/` (`gemini/`), `deepseek/`, `zai/` (`glm/`), `kimi-coding/` (`moonshot/`), `minimax/`, `nvidia/`, `xai/` (`grok/`), and `ollama/` (Session 2+).
+
+Or set the provider-specific key directly (e.g. `ANTHROPIC_API_KEY`) and configure the model later at `/hm/app/config` inside your Space.
 
 ### 4. Start It Up
 
@@ -60,8 +76,7 @@ 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`)
-
+Open the Hermes Dashboard from `https://your-name.hf.space/hm/app`.
 
 > **Pro tip:** Bookmark the direct `*.hf.space` URL — it works better on mobile than the Hugging Face embed.
 
@@ -72,18 +87,42 @@ Open Hermes Dashboard from here (`https://f4b404-hermes.hf.space/hm/app`)
 | 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`) |
+| `/hm` | Status dashboard — see what's running, backup state, desktop-app token |
+| `/hm/app/` | Hermes dashboard — add AI models, set up cron jobs, manage profiles, config editor |
+| `/hm/logs` | In-browser log viewer (dashboard / gateway / webui logs) — no HF Pro SSH needed |
+| `/hm/desktop-app-setup` | One-page setup guide for the Hermes desktop app with copy-paste token |
+| `/hmd` | Passthrough to the dashboard for the Hermes desktop app (uses its own session token) |
+| `/v1/*` | OpenAI-compatible API endpoint — connect other apps to your agent |
+| `/telegram` | Telegram bot webhook (if you added `TELEGRAM_BOT_TOKEN`) |
+| `/health` `/status` | Health probe + JSON status dump (public) |
+
+---
+
+## Connecting the Hermes Desktop App
+
+The Hermes desktop app (v0.16.0+) can connect to your Space as a remote gateway. The session token is **stable across restarts**, so you configure once and it persists.
+
+1. Open `https://your-name.hf.space/hm/desktop-app-setup` — log in with `GATEWAY_TOKEN`. It shows the Remote Gateway URL and the session token, ready to copy-paste.
+2. In the desktop app: Settings → Gateway → Remote gateway.
+   - URL: `https://your-name.hf.space/hmd`
+   - Session token: paste from step 1.
+3. Verify: WebSocket connects, chat works, model picker loads.
+
+The token is auto-generated on first boot and persisted to your HF Dataset. To pin your own value, set `HERMES_DASHBOARD_SESSION_TOKEN` as a Space Secret.
+
+Note: the desktop app is a **chat-first thin client** — chat and settings work remotely; the file browser and terminal panel show your *local* machine. For remote file/terminal access, use the WebUI in a browser.
 
 ---
 
-## Your Data Is Safe
+## Your Data Is Safe (on the Space — see the disclaimer above)
 
 When `HF_TOKEN` is set:
-- All your chats, files, settings, and agent memory are backed up to a **private** Hugging Face Dataset within seconds of each change (change-driven, capped at 60 s)
-- If the Space restarts, everything comes back exactly as you left it
+
+- All your chats, files, settings, agent memory, OAuth tokens, and config are backed up to a **private** Hugging Face Dataset within seconds of each change (change-driven, capped at 60 s).
+- If the Space restarts, everything comes back exactly as you left it — including OAuth logins done via the dashboard (Claude, ChatGPT, xAI, Nous Portal, etc.), since the entire `~/.hermes` directory is backed up.
+- `config.yaml` is backed up too, with `model.api_key` stripped from the staged copy before upload — the real key comes from the process environment at runtime.
+
+**Reminder:** the dataset lives on your HF account. If the account is suspended (see the disclaimer at the top), you can lose access to it along with the Space. Keep an off-platform copy of anything you can't afford to lose.
 
 ---
 
@@ -92,15 +131,16 @@ When `HF_TOKEN` is set:
 | 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 |
+| Space goes to sleep after a few hours | Make sure `CLOUDFLARE_WORKERS_TOKEN` is set — but note this is also what tends to trigger suspensions |
 | 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 |
+| `/api/model/options` 500 | Known upstream issue; use `/hm/debug/model-options-trace` to see the traceback |
 
 ---
 
 ## 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.
+Use the same `https://your-name.hf.space` URL on Android, then install it as a Progressive Web App (PWA), or just use the URL in any mobile browser for normal chat.
 
 ---
 
@@ -119,6 +159,18 @@ Use the same (`https://your-name.hf.space`) url in android and then you can inst
 | `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`) |
+| `HERMES_DASHBOARD_SESSION_TOKEN` | Pin the desktop-app session token to a known value (otherwise auto-generated and persisted) |
+| `WRITE_SECRETS_TO_ENV` | Opt-in (Space Variable) — materialize provider keys from env into the dashboard's `.env` so they show up in the Env tab. Default off. |
+
+## Ollama Support
+
+`LLM_MODEL=ollama/llama3` works out of the box. The `ollama/` prefix sets `CUSTOM_BASE_URL` to `http://127.0.0.1:11434/v1`, strips the prefix from the model name, and passes `LLM_API_KEY` through as `OPENAI_API_KEY` (Ollama ignores it).
+
+Ollama is not bundled in the container. For a remote Ollama server:
+```
+LLM_MODEL=ollama/llama3
+CUSTOM_BASE_URL=http://your-ollama-host:11434/v1
+```
 
 ## Configure LLM Provider via Config Editor
 
@@ -206,15 +258,26 @@ mcp:
 
 `uvx` and `npx` are pre-installed in the image.
 
+## Debugging Without HF Pro SSH
+
+HF Free tier doesn't allow SSH. Browser-based debug endpoints (all gated by `GATEWAY_TOKEN`):
+
+| URL | What |
+|-----|------|
+| `/hm/logs` | List and view `dashboard.log` / `gateway.log` / `webui.log`. Append `?tail=N` to limit lines. |
+| `/hm/debug/model-options` | Probes the dashboard's `/api/model/options` and shows raw HTTP status/headers/body. |
+| `/hm/debug/model-options-trace` | Runs `build_models_payload()` inline with a full Python traceback — reveals the cause of the 500. |
+| `/status` | JSON dump of gateway/dashboard/webui connectivity, uptime, ports, telegram config, backup status. |
+
 ## 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.
+*   **On boot**, the Space downloads the latest snapshot from your private HF Dataset and restores it into `/opt/data/` (atomic per-entry, with rollback on failure).
+*   **Every `SYNC_INTERVAL` seconds** (default 600), it detects state changes and uploads a new snapshot. The hot path prunes `node_modules`/`.venv`/`__pycache__` so it doesn't walk them every poll.
+*   **On graceful shutdown** (SIGTERM, forwarded by Tini), it does one final sync before exit. A file lock prevents the loop and the shutdown sync from racing.
 
-What gets backed up: chat sessions, agent memory, workspace files, profiles, skills, cron jobs, Hermes config. The dataset is private to your HF account.
+What gets backed up: chat sessions, agent memory, workspace files, profiles, skills, cron jobs, OAuth tokens (`~/.hermes`), and Hermes `config.yaml` (with `model.api_key` redacted from the staged copy). `config.yaml`'s secret and the Telegram webhook secret are explicitly excluded from the upload. The dataset is private to your HF account.
 
 ## Architecture
 
@@ -224,17 +287,19 @@ Single port (7861) Node.js router fronts multiple backends:
 HF Space port 7861
         │
         ▼
-   health-server.js  (router + auth + status page)
+   health-server.js  (router + auth + status page + WS proxy)
         │
         ├─► /                  → Hermes WebUI         (127.0.0.1:8787)
-        ├─► /hm                → HuggingMes status    (in-process)
+        ├─► /hm, /hm/logs,     → HuggingMes status    (in-process)
+        │     /hm/debug/*        + log/debug viewers
         ├─► /hm/app/*          → Hermes dashboard     (127.0.0.1:9119)  [SPA-rewritten]
+        ├─► /hmd/*             → Hermes dashboard     (127.0.0.1:9119)  [passthrough, desktop app]
         ├─► /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.
+`start.sh` boots Hermes Agent's gateway + dashboard + WebUI as subprocesses under Tini (PID 1, forwards SIGTERM, reaps zombies), then the router on top. A `wait -n` watchdog kills the container if any child dies after boot, so a broken UI no longer hides behind a green `/health`. `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
 
@@ -252,16 +317,18 @@ docker run --rm -p 7861:7861 --env-file .env huggingmes-hermes-webui
 
 | Symptom | Cause / Fix |
 | --- | --- |
+| Account suspended / Space flagged | See the disclaimer at the top. Running always-on agents on free Spaces is being flagged as abuse. Use a throwaway account or a paid tier, or move to a VPS. |
 | 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 |
+| Container Running but `/` returns 502 | Hermes WebUI didn't bind. Check `/hm/logs` for `webui.log` — 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 |
+| Space sleeps after a few hours | Free tier limitation. Add `CLOUDFLARE_WORKERS_TOKEN` to provision a keep-alive cron worker. Note: this is also what tends to trigger suspensions. |
 | 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` |
+| Desktop app can't connect | Token rotated? Re-fetch from `/hm/desktop-app-setup`. WebSocket Origin must match — Electron `file://` and `localhost:port` origins are allowed. |
 
 ## Credits
 
@@ -269,8 +336,8 @@ docker run --rm -p 7861:7861 --env-file .env huggingmes-hermes-webui
 *   **[@nesquena](https://github.com/nesquena)** for **[Hermes WebUI](https://github.com/nesquena/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](https://github.com/somratpro)** for **[HuggingMes](https://github.com/somratpro/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.
+This repo's 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, a stable persisted session token for the desktop app, OAuth/token persistence across restarts, browser-based log/debug endpoints for no-SSH debugging, and a security/robustness hardening pass (WebSocket auth, Origin validation, atomic restore, Tini + watchdog, secret-redaction on backup). If you find this useful, star the upstream projects.
 
 ## License
 
-MIT — same as all upstream projects.
+MIT — same as all upstream projects.