Spaces:

ruang101
/

botgithub

Paused

+# HuggingMes + Hermes WebUI — merged deployment for Hugging Face Spaces
+# Base: NousResearch Hermes Agent (ships Hermes CLI, gateway, dashboard, Python venv)
+ARG HERMES_AGENT_VERSION=latest
+FROM nousresearch/hermes-agent:${HERMES_AGENT_VERSION}
+ARG WEBUI_REF=master
+USER root
+# System deps (mirrors HuggingMes) + git/nodejs for WebUI checkout + router
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ca-certificates \
+    curl \
+    jq \
+    git \
+    python3 \
+    nodejs \
+    npm \
+    chromium \
+    libnss3 \
+    libatk1.0-0 \
+    libatk-bridge2.0-0 \
+    libdrm2 \
+    libgbm1 \
+    libxcomposite1 \
+    libxdamage1 \
+    libxrandr2 \
+    libxkbcommon0 \
+    libx11-6 \
+    libxext6 \
+    libxfixes3 \
+    libasound2 \
+    fonts-dejavu-core \
+    fonts-liberation \
+    fonts-noto-color-emoji \
+    && rm -rf /var/lib/apt/lists/* \
+    && uv pip install --python /opt/hermes/.venv/bin/python --no-cache-dir \
+        huggingface_hub hf_transfer pyyaml
+# Clone nesquena/hermes-webui (install deps into the agent venv so imports resolve)
+RUN git clone --depth 1 --branch ${WEBUI_REF} \
+        https://github.com/nesquena/hermes-webui.git /opt/hermes-webui \
+ && ( [ -f /opt/hermes-webui/requirements.txt ] \
+      && /opt/hermes/.venv/bin/pip install --no-cache-dir -r /opt/hermes-webui/requirements.txt \
+      || true ) \
+ && chown -R hermes:hermes /opt/hermes-webui
+# HuggingMes-style integration scripts (vendored from somratpro/HuggingMes)
+RUN mkdir -p /opt/huggingmes
+COPY --chown=hermes:hermes start.sh                       /opt/huggingmes/start.sh
+COPY --chown=hermes:hermes health-server.js               /opt/huggingmes/health-server.js
+COPY --chown=hermes:hermes hermes-sync.py                 /opt/huggingmes/hermes-sync.py
+COPY --chown=hermes:hermes cloudflare-proxy-setup.py      /opt/huggingmes/cloudflare-proxy-setup.py
+COPY --chown=hermes:hermes cloudflare-keepalive-setup.py  /opt/huggingmes/cloudflare-keepalive-setup.py
+COPY --chown=hermes:hermes config.yaml.template           /opt/huggingmes/config.yaml.template
+COPY --chown=hermes:hermes SOUL.md                        /opt/huggingmes/SOUL.md
+RUN chmod +x \
+    /opt/huggingmes/start.sh \
+    /opt/huggingmes/hermes-sync.py \
+    /opt/huggingmes/cloudflare-proxy-setup.py \
+    /opt/huggingmes/cloudflare-keepalive-setup.py \
+ && sed -i 's/\r$//' /opt/huggingmes/start.sh
+# Idempotent kanban migration patch (same workaround HuggingMes ships)
+RUN python3 - <<'PY'
+from pathlib import Path
+import sys
+p = Path("/opt/hermes/hermes_cli/kanban_db.py")
+if not p.exists():
+    sys.exit(0)
+src = p.read_text(encoding="utf-8")
+sentinel = "# huggingmes-webui: idempotent-alter"
+if sentinel in src:
+    sys.exit(0)
+old = (
+    '    conn.execute(\n'
+    '        "ALTER TABLE tasks ADD COLUMN consecutive_failures "\n'
+    '        "INTEGER NOT NULL DEFAULT 0"\n'
+    '    )'
+)
+new = (
+    f'    try:  {sentinel}\n'
+    '        conn.execute(\n'
+    '            "ALTER TABLE tasks ADD COLUMN consecutive_failures "\n'
+    '            "INTEGER NOT NULL DEFAULT 0"\n'
+    '        )\n'
+    '    except Exception:\n'
+    '        pass'
+)
+if old in src:
+    p.write_text(src.replace(old, new), encoding="utf-8")
+    print("kanban patch: applied")
+PY
+# Quiet hermes-webui's per-request access log noise.
+# By default it prints `[webui] {"ts":...,"method":...}` for EVERY request,
+# which drowns the HF Logs tab once any browser tab is open polling
+# /api/dashboard/status, /api/health/agent, /api/sessions, /sw.js, etc.
+# Patch log_request() to drop 2xx responses for high-frequency poll paths.
+# Errors and chat/streaming paths still log normally.
+RUN python3 - <<'PY'
+from pathlib import Path
+import re
+import sys
+p = Path("/opt/hermes-webui/server.py")
+if not p.exists():
+    sys.exit(0)
+src = p.read_text(encoding="utf-8")
+sentinel = "# huggingmes-webui: quiet-poll-paths"
+if sentinel in src:
+    sys.exit(0)
+old = (
+    "    def log_request(self, code: str='-', size: str='-') -> None:\n"
+    "        \"\"\"Structured JSON logs for each request.\"\"\"\n"
+    "        import json as _json\n"
+    "        duration_ms = round((time.time() - getattr(self, '_req_t0', time.time())) * 1000, 1)\n"
+    "        record = _json.dumps({\n"
+    "            'ts': time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime()),\n"
+    "            'method': self.command or '-',\n"
+    "            'path': self.path or '-',\n"
+    "            'status': int(code) if str(code).isdigit() else code,\n"
+    "            'ms': duration_ms,\n"
+    "        })\n"
+    "        print(f'[webui] {record}', flush=True)"
+)
+new = (
+    "    _QUIET_POLL_PATHS = (  " + sentinel + "\n"
+    "        '/api/health/agent', '/api/dashboard/status',\n"
+    "        '/api/dashboard/config', '/api/sessions', '/api/profiles',\n"
+    "        '/api/profile/active', '/api/onboarding/status',\n"
+    "        '/api/insights', '/api/system/health',\n"
+    "        '/api/settings', '/api/projects', '/api/reasoning',\n"
+    "        '/api/models', '/api/chat/stream/status',\n"
+    "        '/api/git-info', '/sw.js', '/health',\n"
+    "    )\n"
+    "    _QUIET_PREFIXES = ('/static/', '/session/static/', '/assets/')\n"
+    "\n"
+    "    def log_request(self, code: str='-', size: str='-') -> None:\n"
+    "        \"\"\"Structured JSON logs for each request, skipping noisy polls.\"\"\"\n"
+    "        # Always log non-2xx so 401/404/5xx remain visible.\n"
+    "        try:\n"
+    "            status_int = int(code) if str(code).isdigit() else 0\n"
+    "        except Exception:\n"
+    "            status_int = 0\n"
+    "        path = (self.path or '').split('?', 1)[0]\n"
+    "        if 200 <= status_int < 400:\n"
+    "            if path in self._QUIET_POLL_PATHS:\n"
+    "                return\n"
+    "            for pref in self._QUIET_PREFIXES:\n"
+    "                if path.startswith(pref):\n"
+    "                    return\n"
+    "        import json as _json\n"
+    "        duration_ms = round((time.time() - getattr(self, '_req_t0', time.time())) * 1000, 1)\n"
+    "        record = _json.dumps({\n"
+    "            'ts': time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime()),\n"
+    "            'method': self.command or '-',\n"
+    "            'path': self.path or '-',\n"
+    "            'status': int(code) if str(code).isdigit() else code,\n"
+    "            'ms': duration_ms,\n"
+    "        })\n"
+    "        print(f'[webui] {record}', flush=True)"
+)
+if old in src:
+    p.write_text(src.replace(old, new), encoding="utf-8")
+    print("webui log-quiet patch: applied")
+else:
+    print("webui log-quiet patch: pattern not found, skipping")
+PY
+# Keep hermes CLI on PATH for all shell types (login/interactive/non-interactive)
+RUN echo 'export PATH="/opt/hermes/.venv/bin:/opt/data/.local/bin:$PATH"' \
+    > /etc/profile.d/hermes-venv.sh
+ENV HERMES_HOME=/opt/data \
+    HUGGINGMES_APP_DIR=/opt/huggingmes \
+    HERMES_WEBUI_REPO=/opt/hermes-webui \
+    HERMES_AGENT_VERSION=${HERMES_AGENT_VERSION} \
+    PYTHONUNBUFFERED=1 \
+    HF_HUB_ENABLE_HF_TRANSFER=1 \
+    PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH=/usr/bin/chromium
+EXPOSE 7861
+HEALTHCHECK --interval=30s --timeout=5s --start-period=120s \
+  CMD curl -fsS http://localhost:7861/health || exit 1
+USER hermes
+ENTRYPOINT ["/opt/huggingmes/start.sh"]

LICENSE ADDED Viewed

	@@ -0,0 +1,36 @@

+MIT License
+Copyright (c) 2026 F4bC0d3
+This project is a deployment recipe that combines three upstream open source
+projects:
+  - Hermes Agent by Nous Research (MIT) — https://github.com/NousResearch/hermes-agent
+  - Hermes WebUI by Nicolas Esquerre (MIT) — https://github.com/nesquena/hermes-webui
+  - HuggingMes by somratpro (MIT) — https://github.com/somratpro/HuggingMes
+The integration layer (Dockerfile, health-server.js routing additions for
+Hermes WebUI, start.sh launch sequence for the WebUI subprocess, README) is
+released under the MIT License below. The vendored files
+(hermes-sync.py, cloudflare-proxy-setup.py, cloudflare-keepalive-setup.py,
+plus large parts of start.sh and health-server.js) remain under their
+original MIT licenses from the upstream HuggingMes project.
+---
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md CHANGED Viewed

@@ -1,10 +1,292 @@
----
-title: Botgithub
-emoji: 📚
-colorFrom: indigo
-colorTo: indigo
-sdk: docker
-pinned: false
----
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

+---
+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](https://github.com/NousResearch/hermes-agent) by Nous Research — the AI brain
+> - [Hermes WebUI](https://github.com/nesquena/hermes-webui) by @nesquena — the chat interface
+> - [HuggingMes](https://github.com/somratpro/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
+[![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).
+### 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](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):
+| 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 within seconds of each change (change-driven, capped at 60 s)
+- 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`) |
+## Customizing the Agent Persona (SOUL.md)
+The agent's personality and behavior is defined by `SOUL.md`. A default persona is included in the project and deployed on first boot.
+**How it works:**
+1. On first boot, `SOUL.md` from the project is copied to `/opt/data/SOUL.md`
+2. Once deployed, it's backed up to your HF Dataset — edits persist across restarts
+3. The template is NOT re-deployed if `SOUL.md` already exists (your edits are safe)
+**To customize before deploying:**
+- Edit `SOUL.md` in your fork of this repo, then rebuild the Space
+**To customize after deploying:**
+- Edit `/opt/data/SOUL.md` via the dashboard's file editor, or SSH into the container
+- Changes are saved to your HF Dataset automatically
+## Configure LLM Provider via Config Editor
+> ### ⚠️ Provider keys go in HF Space Secrets, not the dashboard's Env tab
+>
+> The Hermes dashboard exposes an "Env" editor that writes to `/opt/data/.env`
+> inside the container. **That file is *not* backed up to your HF Dataset.**
+> On every Space sleep / rebuild the container's filesystem is wiped, the
+> `.env` is gone, and your `OLLAMA_API_KEY` / `OPENROUTER_API_KEY` /
+> `ANTHROPIC_API_KEY` / etc. disappear with it. The Space then 500s on the
+> first chat with `Provider 'X' is set in config.yaml but no API key was
+> found`.
+>
+> **Always add provider keys as HF Space Secrets** (Settings → Variables and
+> secrets → New secret). HF injects them as env vars at boot, never writes
+> them to disk on the Space, and they survive every restart.
+>
+> Use the dashboard's Env tab only for non-secret tweaks. The status page's
+> Backup tile will show a yellow warning whenever it detects keys sitting in
+> the ephemeral `.env` so you don't have to remember this on your own.
+>
+> If you accept the security tradeoff and want `.env` backed up anyway, set
+> `SYNC_INCLUDE_ENV=1` as a Space Variable. The dataset is private, but a
+> leak of that dataset URL is then a leak of every key in `.env`.
+If you prefer not to add API keys as HF Secrets, you can configure providers directly in Hermes after the Space starts:
+1. Open `/hm/app/config` in your Space
+2. Add your provider under the `llm` section:
+```yaml
+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](https://github.com/NousResearch/hermes-agent) for the full list.
+## Using the API from Code
+Your Space exposes an OpenAI-compatible API at `/v1/*`:
+```shell
+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"}]
+  }'
+```
+```python
+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`:
+```yaml
+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
+```shell
+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](https://nousresearch.com/)** for **[Hermes Agent](https://github.com/NousResearch/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](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.
+## License
+MIT — same as all upstream projects.

SOUL.md ADDED Viewed

	@@ -0,0 +1,48 @@

+# SYSTEM PROMPT: ATLAS - THE AUTONOMOUS GITHUB ARCHITECT
+## IDENTITY & PERSONA
+You are **Atlas**, the Senior Autonomous GitHub Manager. You do not wait for instructions; you own the repository’s health, momentum, and code quality. You are "Technical," detailed, and direct. You view the repository as a living organism that requires proactive care and creative optimization.
+## CORE OPERATIONAL PRINCIPLES
+- **Proactive Ownership**: You scan for issues, PRs, and repository drift before being asked.
+- **Resilient Execution**: You handle API rate limits via `credential_pool` rotation and debug failing CI pipelines until they pass.
+- **Autonomous Learning**: You use `skill_manage` to codify successful workflows into reusable skills and update `MEMORY.md` with project-specific lessons.
+- **Creative Innovation**: You proactively suggest refactors, GitHub Action improvements, and updates to `AGENTS.md` to enhance team productivity.
+## TOOLBELT
+- **GitHub Suite**: `github-auth`, `github-code-review`, `github-issues`, `github-pr-workflow`, `github-repo-management`.
+- **Management**: `kanban` (for task tracking), `cron` (for scheduled audits), `todo`.
+- **Orchestration**: `delegate_task` (to spawn specialized sub-agents for parallel code reviews or research).
+- **Evolution**: `skill_manage` (to create/patch your own procedures).
+## WORKFLOW: "START"
+Upon receiving the command "**START**", you must execute the following loop:
+1. **Pulse Check**: Scan `github-issues` for high-priority bugs and `github-pr-workflow` for pending reviews.
+2. **Kanban Sync**: Audit the current `kanban list`. Move stalled tasks and claim ready ones.
+3. **Strategic Planning**: Create a implementation plan using the `plan` skill for any unaddressed priorities.
+4. **Execution**:
+   - Perform automated triage and labelling.
+   - Execute code reviews with the `github-code-review` skill.
+   - If a build fails, use the `terminal` to investigate and `patch` to fix.
+5. **Self-Evolution**: If you encounter a new error pattern or complex fix, use `skill_manage` to save it as a procedural memory.
+## STANDARD REPORTING FORMAT (OUTPUT BAKU)
+Report your status at the end of every operational cycle using this structure:
+---
+### 🛰️ ATLAS REPO ADVISORY
+**Current Focus**: [Active Kanban Task ID & Title]
+**GitHub Pulse**: [N] Open Issues | [N] PRs Pending | [N] Merged
+**System Health**: [Build Status | CI/CD Warnings | Branch Hygiene]
+**Self-Evolve**: [Skills Created/Updated | New Memory Logged]
+**Autonomous Action**: [What you are doing next without awaiting approval]
+---
+## BEHAVIORAL GUARDRAILS
+- **Never ask for permission to triage**: If an issue lacks labels or a PR lacks a reviewer, fix it immediately.
+- **Self-Healing**: If a tool fails, consult `hermes doctor` logic or search `session_search` for previous successful workarounds.
+- **Context Integrity**: Keep `AGENTS.md` updated with the latest architecture decisions you've made or discovered.
+- **Becoming the Manager**: You are the guardian of the `main` branch. Treat every line of code as if it were your own creation.
+[AWAITING COMMAND: START]

cloakbrowser/SKILL.md ADDED Viewed

	@@ -0,0 +1,145 @@

+---
+name: cloakbrowser
+description: Stealth browser automation with CloakBrowser — bypasses bot detection (Cloudflare, reCAPTCHA, FingerprintJS). Use for web scraping, screenshot capture, site testing, and anti-detect browsing.
+---
+# CloakBrowser — Stealth Browser Automation
+CloakBrowser is a patched Chromium binary with 58 C++ source-level fingerprint patches. Drop-in Playwright replacement that passes Cloudflare Turnstile, reCAPTCHA v3 (0.9 score), FingerprintJS, BrowserScan, and 30+ detection sites.
+## Install
+```bash
+uv pip install --python /opt/hermes/.venv/bin/python3 /opt/data/workspace/github/cloakbrowser
+```
+Binary auto-downloads to `~/.cloakbrowser/` on first use.
+## Quick Usage (Python)
+```python
+from cloakbrowser import launch
+browser = launch(headless=True, humanize=True)
+page = browser.new_page()
+page.goto("https://protected-site.com")
+print(page.title())
+browser.close()
+```
+## CLI Wrapper
+Located at: `/opt/data/workspace/github/cloakbrowser/tools/cloak_browse.py`
+```bash
+# Fetch page text
+python3 /opt/data/workspace/github/cloakbrowser/tools/cloak_browse.py fetch https://example.com
+# Screenshot
+python3 /opt/data/workspace/github/cloakbrowser/tools/cloak_browse.py screenshot https://example.com -o /tmp/shot.png --viewport 1920x1080
+# Extract structured content (title, links, meta, text)
+python3 /opt/data/workspace/github/cloakbrowser/tools/cloak_browse.py extract https://example.com
+# Execute JS on page
+python3 /opt/data/workspace/github/cloakbrowser/tools/cloak_browse.py js https://example.com "document.title"
+# Run stealth fingerprint test
+python3 /opt/data/workspace/github/cloakbrowser/tools/cloak_browse.py stealth-test
+# Show binary info
+python3 /opt/data/workspace/github/cloakbrowser/tools/cloak_browse.py info
+```
+## Key Launch Options
+```python
+browser = launch(
+    headless=True,          # Headless mode (default True)
+    humanize=True,          # Human-like mouse/keyboard/scroll
+    proxy="http://user:pass@proxy:port",  # Residential proxy
+    geoip=True,             # Auto-detect timezone from proxy IP
+    args=["--remote-debugging-port=9242"],  # Extra Chrome args
+    extension_paths=["/path/to/ext"],       # Load Chrome extensions
+)
+```
+## Integration Patterns
+### With Crawl4AI
+```python
+from cloakbrowser import launch_async
+cb = await launch_async(headless=True, args=["--remote-debugging-port=9243"])
+# Connect Crawl4AI via CDP: http://127.0.0.1:9243
+```
+### With browser-use (AI agent)
+```python
+from cloakbrowser import launch_async
+cb = await launch_async(headless=True, args=["--remote-debugging-port=9242"])
+# Connect browser-use via CDP: http://127.0.0.1:9242
+```
+### Persistent context (cookies survive restart)
+```python
+from cloakbrowser import launch_persistent_context
+ctx = launch_persistent_context("./my-profile", headless=False)
+page = ctx.new_page()
+page.goto("https://site.com")
+ctx.close()  # Cookies saved to ./my-profile
+```
+## Stealth Verified
+- navigator.webdriver: False
+- Real plugins (5), languages, platform
+- WebGL: Google Inc. (NVIDIA) — real GPU vendor
+- Canvas fingerprint: unique per session (random seed)
+- Passes bot.incolumitas.com, BrowserScan, Cloudflare Turnstile
+## Hermes Integration (Default Browser)
+CloakBrowser is configured as the default browser for Hermes via `agent-browser` CLI.
+**Config file:** `/opt/data/.env`
+```
+AGENT_BROWSER_EXECUTABLE_PATH=/opt/data/home/.cloakbrowser/chromium-146.0.7680.177.5/chrome
+AGENT_BROWSER_ARGS=--no-sandbox,--fingerprint-platform=windows
+AGENT_BROWSER_ENGINE=chrome
+```
+**How it works:**
+- Hermes browser tools (`browser_navigate`, `browser_click`, etc.) use `agent-browser` CLI
+- `agent-browser` launches Chromium — `AGENT_BROWSER_EXECUTABLE_PATH` points it to CloakBrowser's stealth binary
+- `AGENT_BROWSER_ARGS` passes fingerprint spoofing flags
+- Result: all Hermes browser automation runs through stealth Chromium
+**Verify integration:**
+```bash
+# Check agent-browser uses CloakBrowser
+export AGENT_BROWSER_EXECUTABLE_PATH=/opt/data/home/.cloakbrowser/chromium-146.0.7680.177.5/chrome
+agent-browser --engine chrome --session test open "https://example.com"
+agent-browser --session test eval "navigator.webdriver"  # Should be false
+agent-browser --session test close
+```
+**Update binary path after CloakBrowser update:**
+```bash
+python3 -c "from cloakbrowser.config import get_binary_path; print(get_binary_path())"
+# Update AGENT_BROWSER_EXECUTABLE_PATH in /opt/data/.env with new path
+```
+## Pitfalls
+1. **Headless detection**: Some sites detect headless even with patches. Use `headless=False` for stubborn sites.
+2. **Datacenter IPs**: Residential proxy needed for sites that check IP reputation.
+3. **First run downloads ~120MB binary** to `~/.cloakbrowser/`. Subsequent runs use cache.
+4. **No pip**: Use `uv pip install --python /opt/hermes/.venv/bin/python3` instead of bare `pip`.
+5. **Playwright API**: CloakBrowser returns standard Playwright Browser/Context objects — same API.
+## Environment Variables
+- `CLOAKBROWSER_BINARY_PATH` — Use custom binary (skip download)
+- `CLOAKBROWSER_CACHE_DIR` — Custom cache directory
+- `CLOAKBROWSER_AUTO_UPDATE=false` — Disable auto-update checks
+- `CLOAKBROWSER_DOWNLOAD_URL` — Custom download mirror

cloudflare-keepalive-setup.py ADDED Viewed

	@@ -0,0 +1,225 @@

+#!/usr/bin/env python3
+from __future__ import annotations
+"""Create or reuse a Cloudflare Worker for Space keep-awake.
+Vendored verbatim from github.com/somratpro/HuggingMes.
+"""
+import json
+import os
+import re
+import sys
+import time
+import urllib.request
+import urllib.error
+from pathlib import Path
+API_BASE = "https://api.cloudflare.com/client/v4"
+KEEPALIVE_STATUS_FILE = Path("/tmp/huggingmes-cloudflare-keepalive-status.json")
+def cf_request(method: str, path: str, token: str, body: bytes | None = None, content_type: str = "application/json"):
+    req = urllib.request.Request(
+        f"{API_BASE}{path}",
+        data=body,
+        method=method,
+        headers={"Authorization": f"Bearer {token}", "Content-Type": content_type},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=30) as response:
+            payload = json.loads(response.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        try:
+            error_body = json.loads(e.read().decode("utf-8"))
+            errors = error_body.get("errors") or [{"message": "Unknown error"}]
+            error_msg = errors[0].get("message", "Unknown error") if errors else "Unknown error"
+        except Exception:
+            error_msg = f"HTTP {e.code}: {e.reason}"
+        raise RuntimeError(f"Cloudflare API {e.code}: {error_msg}")
+    if not payload.get("success"):
+        errors = payload.get("errors") or [{"message": "Unknown Cloudflare API error"}]
+        raise RuntimeError(errors[0].get("message", "Unknown Cloudflare API error"))
+    return payload["result"]
+def slugify(value: str) -> str:
+    cleaned = re.sub(r"[^a-z0-9-]+", "-", value.lower()).strip("-")
+    cleaned = re.sub(r"-{2,}", "-", cleaned)
+    return (cleaned or "huggingmes-keepalive")[:63].rstrip("-")
+def get_space_host() -> str:
+    space_host = os.environ.get("SPACE_HOST", "").strip()
+    if space_host:
+        return space_host
+    author = os.environ.get("SPACE_AUTHOR_NAME", "").strip()
+    repo = os.environ.get("SPACE_REPO_NAME", "").strip()
+    if author and repo:
+        return f"{author}-{repo}.hf.space".lower()
+    return ""
+def derive_keepalive_worker_name() -> str:
+    explicit = os.environ.get("CLOUDFLARE_KEEPALIVE_WORKER_NAME", "").strip()
+    if explicit:
+        return slugify(explicit)
+    space_host = get_space_host()
+    if space_host:
+        return slugify(f"{space_host.replace('.hf.space', '')}-keepalive")
+    return "huggingmes-keepalive"
+def render_keepalive_worker(target_url: str) -> str:
+    return f"""addEventListener("fetch", (event) => {{
+  event.respondWith(handleRequest(event.request));
+}});
+addEventListener("scheduled", (event) => {{
+  event.waitUntil(ping("cron"));
+}});
+const TARGET_URL = {json.dumps(target_url)};
+async function ping(source) {{
+  const startedAt = new Date().toISOString();
+  try {{
+    const response = await fetch(TARGET_URL, {{
+      method: "GET",
+      headers: {{
+        "user-agent": "HuggingMes Cloudflare KeepAlive",
+        "cache-control": "no-cache"
+      }},
+      cf: {{ cacheTtl: 0, cacheEverything: false }}
+    }});
+    return {{
+      ok: response.ok,
+      status: response.status,
+      source,
+      target: TARGET_URL,
+      timestamp: startedAt
+    }};
+  }} catch (error) {{
+    return {{
+      ok: false,
+      status: 0,
+      source,
+      target: TARGET_URL,
+      timestamp: startedAt,
+      error: error.message
+    }};
+  }}
+}}
+async function handleRequest(request) {{
+  const url = new URL(request.url);
+  if (url.pathname === "/" || url.pathname === "/health" || url.pathname === "/ping") {{
+    const result = await ping("manual");
+    return new Response(JSON.stringify(result, null, 2), {{
+      status: result.ok ? 200 : 502,
+      headers: {{ "content-type": "application/json; charset=utf-8" }}
+    }});
+  }}
+  return new Response("Not found", {{ status: 404 }});
+}}
+"""
+def write_keepalive_status(payload: dict) -> None:
+    payload = {
+        **payload,
+        "timestamp": payload.get("timestamp") or time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+    }
+    KEEPALIVE_STATUS_FILE.write_text(json.dumps(payload), encoding="utf-8")
+    try:
+        KEEPALIVE_STATUS_FILE.chmod(0o600)
+    except OSError:
+        pass
+def resolve_account_and_subdomain(api_token: str) -> tuple[str, str]:
+    account_id = os.environ.get("CLOUDFLARE_ACCOUNT_ID", "").strip()
+    if not account_id:
+        accounts = cf_request("GET", "/accounts", api_token)
+        if not accounts:
+            raise RuntimeError("No Cloudflare account is available for this token.")
+        account_id = accounts[0]["id"]
+    subdomain_info = cf_request("GET", f"/accounts/{account_id}/workers/subdomain", api_token)
+    subdomain = (subdomain_info or {}).get("subdomain", "").strip()
+    if not subdomain:
+        raise RuntimeError("Cloudflare Workers subdomain is not configured. Enable workers.dev first.")
+    return account_id, subdomain
+def setup_keepalive_worker(api_token: str, account_id: str, subdomain: str) -> None:
+    enabled = os.environ.get("CLOUDFLARE_KEEPALIVE_ENABLED", "true").strip().lower()
+    if enabled in {"0", "false", "no", "off"}:
+        write_keepalive_status({"configured": False, "status": "disabled", "message": "Cloudflare keep-awake is disabled."})
+        return
+    space_host = get_space_host()
+    if not space_host:
+        write_keepalive_status({"configured": False, "status": "skipped", "message": "SPACE_HOST could not be determined."})
+        return
+    cron = os.environ.get("CLOUDFLARE_KEEPALIVE_CRON", "*/10 * * * *").strip()
+    space_host = space_host.removeprefix("https://").removeprefix("http://").split("/")[0]
+    target_url = os.environ.get("CLOUDFLARE_KEEPALIVE_URL", f"https://{space_host}/health").strip()
+    worker_name = derive_keepalive_worker_name()
+    worker_source = render_keepalive_worker(target_url)
+    cf_request(
+        "PUT",
+        f"/accounts/{account_id}/workers/scripts/{worker_name}",
+        api_token,
+        body=worker_source.encode("utf-8"),
+        content_type="application/javascript",
+    )
+    cf_request(
+        "POST",
+        f"/accounts/{account_id}/workers/scripts/{worker_name}/subdomain",
+        api_token,
+        body=json.dumps({"enabled": True, "previews_enabled": True}).encode("utf-8"),
+    )
+    cf_request(
+        "PUT",
+        f"/accounts/{account_id}/workers/scripts/{worker_name}/schedules",
+        api_token,
+        body=json.dumps([{"cron": cron}]).encode("utf-8"),
+    )
+    worker_url = f"https://{worker_name}.{subdomain}.workers.dev"
+    write_keepalive_status(
+        {
+            "configured": True,
+            "status": "configured",
+            "workerName": worker_name,
+            "workerUrl": worker_url,
+            "targetUrl": target_url,
+            "cron": cron,
+            "message": f"Cloudflare Worker cron pings {target_url} on {cron}.",
+        }
+    )
+def main() -> int:
+    api_token = os.environ.get("CLOUDFLARE_WORKERS_TOKEN", "").strip()
+    if not api_token:
+        return 0
+    try:
+        account_id, subdomain = resolve_account_and_subdomain(api_token)
+        setup_keepalive_worker(api_token, account_id, subdomain)
+        return 0
+    except Exception as exc:
+        print(f"Cloudflare keepalive setup failed: {exc}", file=sys.stderr)
+        write_keepalive_status({"configured": False, "status": "error", "message": str(exc)})
+        return 1
+if __name__ == "__main__":
+    raise SystemExit(main())

cloudflare-proxy-setup.py ADDED Viewed

	@@ -0,0 +1,203 @@

+#!/usr/bin/env python3
+from __future__ import annotations
+"""Create or reuse Cloudflare Workers for Telegram proxy and Space keep-awake.
+Vendored verbatim from github.com/somratpro/HuggingMes.
+"""
+import json
+import os
+import re
+import secrets
+import sys
+import time
+import urllib.request
+from pathlib import Path
+API_BASE = "https://api.cloudflare.com/client/v4"
+ENV_FILE = Path("/tmp/huggingmes-cloudflare-proxy.env")
+DEFAULT_ALLOWED = [
+    "api.telegram.org",
+    "discord.com",
+    "discordapp.com",
+    "gateway.discord.gg",
+    "status.discord.com",
+    "slack.com",
+    "api.slack.com",
+    "web.whatsapp.com",
+    "graph.facebook.com",
+    "graph.instagram.com",
+    "api.openai.com",
+    "googleapis.com",
+    "google.com",
+    "googleusercontent.com",
+    "gstatic.com",
+]
+def cf_request(method: str, path: str, token: str, body: bytes | None = None, content_type: str = "application/json"):
+    req = urllib.request.Request(
+        f"{API_BASE}{path}",
+        data=body,
+        method=method,
+        headers={"Authorization": f"Bearer {token}", "Content-Type": content_type},
+    )
+    with urllib.request.urlopen(req, timeout=30) as response:
+        payload = json.loads(response.read().decode("utf-8"))
+    if not payload.get("success"):
+        errors = payload.get("errors") or [{"message": "Unknown Cloudflare API error"}]
+        raise RuntimeError(errors[0].get("message", "Unknown Cloudflare API error"))
+    return payload["result"]
+def slugify(value: str) -> str:
+    cleaned = re.sub(r"[^a-z0-9-]+", "-", value.lower()).strip("-")
+    cleaned = re.sub(r"-{2,}", "-", cleaned)
+    return (cleaned or "huggingmes-proxy")[:63].rstrip("-")
+def derive_worker_name() -> str:
+    explicit = os.environ.get("CLOUDFLARE_WORKER_NAME", "").strip()
+    if explicit:
+        return slugify(explicit)
+    space_host = os.environ.get("SPACE_HOST", "").strip()
+    if space_host:
+        return slugify(f"{space_host.replace('.hf.space', '')}-proxy")
+    return "huggingmes-proxy"
+def render_worker(secret_value: str, allowed_targets: list[str], allow_proxy_all: bool) -> str:
+    return f"""addEventListener("fetch", (event) => {{
+  event.respondWith(handleRequest(event.request));
+}});
+const PROXY_SHARED_SECRET = {json.dumps(secret_value)};
+const ALLOW_PROXY_ALL = {"true" if allow_proxy_all else "false"};
+const ALLOWED_TARGETS = {json.dumps(allowed_targets)};
+function isAllowedHost(hostname) {{
+  const normalized = String(hostname || "").trim().toLowerCase();
+  if (!normalized) return false;
+  if (ALLOW_PROXY_ALL) return true;
+  return ALLOWED_TARGETS.some((domain) => normalized === domain || normalized.endsWith(`.${{domain}}`));
+}}
+async function handleRequest(request) {{
+  const url = new URL(request.url);
+  const queryTarget = url.searchParams.get("proxy_target");
+  const targetHost = request.headers.get("x-target-host") || queryTarget;
+  if (PROXY_SHARED_SECRET) {{
+    const providedSecret = request.headers.get("x-proxy-key") || url.searchParams.get("proxy_key") || "";
+    const telegramStylePath = url.pathname.startsWith("/bot") || url.pathname.startsWith("/file/bot");
+    if (providedSecret !== PROXY_SHARED_SECRET && !(telegramStylePath && !targetHost)) {{
+      return new Response("Unauthorized: Invalid proxy key", {{ status: 401 }});
+    }}
+  }}
+  let targetBase = "";
+  if (targetHost) {{
+    if (!isAllowedHost(targetHost)) {{
+      return new Response(`Forbidden: Host ${{targetHost}} is not allowed.`, {{ status: 403 }});
+    }}
+    targetBase = `https://${{targetHost}}`;
+  }} else if (url.pathname.startsWith("/bot") || url.pathname.startsWith("/file/bot")) {{
+    targetBase = "https://api.telegram.org";
+  }} else {{
+    return new Response("Invalid request: No target host provided.", {{ status: 400 }});
+  }}
+  const cleanSearch = new URLSearchParams(url.search);
+  cleanSearch.delete("proxy_target");
+  cleanSearch.delete("proxy_key");
+  const searchStr = cleanSearch.toString();
+  const targetUrl = targetBase + url.pathname + (searchStr ? `?${{searchStr}}` : "");
+  const headers = new Headers(request.headers);
+  for (const header of ["cf-connecting-ip", "cf-ray", "cf-visitor", "host", "x-real-ip", "x-target-host", "x-proxy-key"]) {{
+    headers.delete(header);
+  }}
+  try {{
+    return await fetch(new Request(targetUrl, {{
+      method: request.method,
+      headers,
+      body: request.body,
+      redirect: "follow",
+    }}));
+  }} catch (error) {{
+    return new Response(`Proxy Error: ${{error.message}}`, {{ status: 502 }});
+  }}
+}}
+"""
+def write_env(proxy_url: str, proxy_secret: str) -> None:
+    ENV_FILE.write_text(
+        f'export CLOUDFLARE_PROXY_URL="{proxy_url}"\nexport CLOUDFLARE_PROXY_SECRET="{proxy_secret}"\n',
+        encoding="utf-8",
+    )
+    ENV_FILE.chmod(0o600)
+def resolve_account_and_subdomain(api_token: str) -> tuple[str, str]:
+    account_id = os.environ.get("CLOUDFLARE_ACCOUNT_ID", "").strip()
+    if not account_id:
+        accounts = cf_request("GET", "/accounts", api_token)
+        if not accounts:
+            raise RuntimeError("No Cloudflare account is available for this token.")
+        account_id = accounts[0]["id"]
+    subdomain_info = cf_request("GET", f"/accounts/{account_id}/workers/subdomain", api_token)
+    subdomain = (subdomain_info or {}).get("subdomain", "").strip()
+    if not subdomain:
+        raise RuntimeError("Cloudflare Workers subdomain is not configured. Enable workers.dev first.")
+    return account_id, subdomain
+def main() -> int:
+    existing_url = os.environ.get("CLOUDFLARE_PROXY_URL", "").strip()
+    existing_secret = os.environ.get("CLOUDFLARE_PROXY_SECRET", "").strip()
+    api_token = os.environ.get("CLOUDFLARE_WORKERS_TOKEN", "").strip()
+    if existing_url:
+        write_env(existing_url, existing_secret)
+    if not api_token:
+        return 0
+    try:
+        account_id, subdomain = resolve_account_and_subdomain(api_token)
+        if not existing_url:
+            allowed_raw = os.environ.get("CLOUDFLARE_PROXY_DOMAINS", "").strip()
+            allow_proxy_all = allowed_raw == "*"
+            extra = [] if allow_proxy_all else [v.strip() for v in allowed_raw.split(",") if v.strip()]
+            allowed = list(dict.fromkeys(DEFAULT_ALLOWED + extra))
+            worker_name = derive_worker_name()
+            proxy_secret = existing_secret or secrets.token_urlsafe(24)
+            cf_request(
+                "PUT",
+                f"/accounts/{account_id}/workers/scripts/{worker_name}",
+                api_token,
+                body=render_worker(proxy_secret, allowed, allow_proxy_all).encode("utf-8"),
+                content_type="application/javascript",
+            )
+            cf_request(
+                "POST",
+                f"/accounts/{account_id}/workers/scripts/{worker_name}/subdomain",
+                api_token,
+                body=json.dumps({"enabled": True, "previews_enabled": True}).encode("utf-8"),
+            )
+            write_env(f"https://{worker_name}.{subdomain}.workers.dev", proxy_secret)
+        return 0
+    except Exception as exc:
+        print(f"Cloudflare proxy setup failed: {exc}", file=sys.stderr)
+        return 1
+if __name__ == "__main__":
+    raise SystemExit(main())

config.yaml.template ADDED Viewed

	@@ -0,0 +1,281 @@

+# ══════════════════════════════════════════════════════════════════════
+# HuggingMes + Hermes WebUI — Configuration Template
+# ══════════════════════════════════════════════════════════════════════
+# This template is deployed to /opt/data/config.yaml in the HF Space.
+# Environment variables from .env.local override values at boot time.
+#
+# Priority: Environment variables > This config > Hermes defaults
+#
+# Documentation: https://hermes-agent.nousresearch.com/docs/user-guide/configuration
+# ══════════════════════════════════════════════════════════════════════
+# ── Model Configuration ──────────────────────────────────────────────
+# The LLM model and provider to use.
+# Override via env: LLM_MODEL, HERMES_MODEL, CUSTOM_BASE_URL, CUSTOM_API_KEY
+#
+# Examples:
+#   openrouter/free              → OpenRouter free-tier models
+#   anthropic/claude-sonnet-4    → Anthropic Claude
+#   openai/gpt-4o               → OpenAI GPT-4o
+#   deepseek/deepseek-chat      → DeepSeek
+#   google/gemini-2.0-flash      → Google Gemini
+#
+# For custom endpoints (e.g., Xiaomi MiMo, NVIDIA NIM):
+#   Set CUSTOM_BASE_URL and CUSTOM_API_KEY in .env.local
+#   The start.sh script will auto-configure model.base_url and model.api_key
+model:
+  default: "mimo-v2.5-pro"
+  provider: "custom"               # Using Xiaomi MiMo custom endpoint
+  # base_url: ""                   # Auto-set from CUSTOM_BASE_URL
+  # api_key: ""                    # Auto-set from CUSTOM_API_KEY
+  # context_length: 1000000        # Auto-set from CUSTOM_MODEL_CONTEXT_LENGTH
+  # max_tokens: 8192               # Auto-set from CUSTOM_MODEL_MAX_TOKENS
+# ── Agent Behavior ────────────────────────────────────────────────────
+agent:
+  max_turns: 90                # Maximum conversation turns per session
+  tool_use_enforcement: auto   # auto, required, or off
+# ── Terminal Configuration ────────────────────────────────────────────
+# Working directory for shell commands and file operations.
+# Override via env: MESSAGING_CWD
+terminal:
+  backend: local               # local, docker, or ssh
+  cwd: "/opt/data/workspace"   # Default workspace directory
+  timeout: 180                 # Command timeout in seconds
+# ── Context Compression ──────────────────────────────────────────────
+# Automatically compress long conversations to stay within token limits.
+compression:
+  enabled: true
+  threshold: 0.50              # Trigger compression at 50% of context window
+  target_ratio: 0.20           # Compress to 20% of original size
+# ── Display Settings ─────────────────────────────────────────────────
+# UI and notification preferences.
+# Override via env: HERMES_BACKGROUND_NOTIFICATIONS
+display:
+  skin: default                # UI theme (default, minimal, etc.)
+  tool_progress: true          # Show tool execution progress
+  show_reasoning: false        # Show model reasoning steps
+  show_cost: true              # Show token cost per request
+  background_process_notifications: "result"  # result, none, or progress
+# ── Security Settings ────────────────────────────────────────────────
+# CRITICAL: Always enable secret redaction to prevent credential leakage.
+security:
+  redact_secrets: true         # Auto-mask API keys in tool output
+  redact_pii: false            # Auto-mask PII (phone numbers, emails)
+  tirith_enabled: false        # Enable Tirith security scanner
+# ── Approval Mode ─────────────────────────────────────────────────────
+# Control how destructive commands are handled.
+# Options: manual (always prompt), smart (LLM decides), off (no prompts)
+approvals:
+  mode: smart                  # Recommended: smart for autonomous operation
+# ── Memory Configuration ─────────────────────────────────────────────
+# Persistent memory across sessions.
+memory:
+  memory_enabled: true         # Enable cross-session memory
+  user_profile_enabled: true   # Enable user profile persistence
+  provider: builtin            # builtin, honcho, mem0
+# ── Checkpoints ──────────────────────────────────────────────────────
+# Filesystem snapshots for rollback capability.
+checkpoints:
+  enabled: true
+  max_snapshots: 10            # Maximum checkpoints to keep
+  auto_prune: true             # Auto-cleanup old checkpoints
+# ── Sessions ─────────────────────────────────────────────────────────
+# Session management and cleanup.
+sessions:
+  auto_prune: true             # Auto-cleanup old sessions
+  prune_days: 3               # Delete sessions older than N days
+# ── Model Catalog ────────────────────────────────────────────────────
+# Disable to reduce context bloat.
+model_catalog:
+  enabled: false               # Set true to show model picker in UI
+# ── Delegation (Subagents) ───────────────────────────────────────────
+# Configuration for delegated subtasks.
+delegation:
+  max_iterations: 50           # Max tool calls per subagent
+  max_spawn_depth: 1           # Max nesting depth (1 = no nesting)
+  max_concurrent_children: 3   # Max parallel subagents
+# ── Platform Configuration ───────────────────────────────────────────
+# Messaging platform integrations.
+# Telegram is auto-configured from TELEGRAM_BOT_TOKEN env var.
+platforms:
+  telegram:
+    enabled: false             # Auto-enabled when TELEGRAM_BOT_TOKEN is set
+    # extra:
+    #   base_url: ""           # Auto-set from TELEGRAM_BASE_URL
+    #   base_file_url: ""      # Auto-set from TELEGRAM_BASE_FILE_URL
+  # Uncomment to enable other platforms:
+  # discord:
+  #   enabled: true
+  #   extra:
+  #     bot_token: "${DISCORD_BOT_TOKEN}"
+  #
+  # slack:
+  #   enabled: true
+  #   extra:
+  #     bot_token: "${SLACK_BOT_TOKEN}"
+# ── Telegram Access Control ──────────────────────────────────────────
+# Comma-separated user IDs allowed to interact with the bot.
+# Override via env: TELEGRAM_ALLOWED_USERS, TELEGRAM_USER_ID
+telegram:
+  allow_from: []               # Empty = allow all (not recommended for production)
+# ── STT (Speech-to-Text) ─────────────────────────────────────────────
+# Voice message transcription.
+stt:
+  enabled: false               # Enable voice transcription
+  provider: local              # local, groq, openai, mistral
+  local:
+    model: base                # tiny, base, small, medium, large-v3
+# ── TTS (Text-to-Speech) ─────────────────────────────────────────────
+# Voice response generation.
+tts:
+  provider: edge               # edge, elevenlabs, openai, minimax, mistral, neutts
+# ── MCP Servers ──────────────────────────────────────────────────────
+# Model Context Protocol servers for extended tool access.
+# IMPORTANT: Use 'mcp_servers:' key, NOT 'mcp:'
+mcp_servers:
+ cloudflare:
+   url: https://mcp.cloudflare.com/mcp
+   timeout: 120
+   headers:
+     Authorization: Bearer ${CLOUDFLARE_API_TOKEN}
+ n8n:
+   url: https://ruang101-n8n.hf.space/mcp-server/http
+   timeout: 120
+   headers:
+     Authorization: Bearer ${N8N_MCP_API_KEY}
+ tavily:
+   url: https://mcp.tavily.com/mcp/?tavilyApiKey=${TAVILY_API_KEY}
+ exa:
+   url: https://mcp.exa.ai/mcp?tools=web_search_exa,web_fetch_exa,web_search_advanced_exa
+   headers:
+     x-api-key: ${EXA_API_KEY2}
+ anysearch:
+   url: https://api.anysearch.com/mcp
+   headers:
+     Authorization: Bearer ${ANYSERCH_API_KEY}
+ google-maps-tools:
+   url: https://mapstools.googleapis.com/mcp
+   type: http
+secrets:
+  bitwarden:
+    enabled: true
+    access_token_env: BWS_ACCESS_TOKEN
+    project_id: afa31408-cc79-4dfb-8a35-b4590142ba94
+    cache_ttl_seconds: 300
+    override_existing: true
+    auto_install: true
+    server_url: ''
+# ── Toolsets ─────────────────────────────────────────────────────────
+# Explicit tool list. Remove tools to reduce model schema size.
+# Default: all tools enabled.
+# toolsets:
+#   - hermes-cli
+#   - browser
+#   - file
+#   - terminal
+#   - code_execution
+#   - delegation
+#   - memory
+#   - session_search
+#   - skills
+#   - web
+#   - vision
+#   - image_gen
+#   - tts
+#   - cronjob
+#   - todo
+# ── Auxiliary Models ─────────────────────────────────────────────────
+# Models for vision, compression, session search, etc.
+auxiliary:
+  vision:
+    provider: auto             # auto, openrouter, google, etc.
+    model: ""                  # Leave empty for auto-detection
+  compression:
+    provider: auto
+    model: ""
+# ── Cloudflare Integration ───────────────────────────────────────────
+# For Telegram proxy and keepalive.
+# Override via env: CLOUDFLARE_WORKERS_TOKEN, CLOUDFLARE_PROXY_URL
+# cloudflare:
+#   proxy_url: ""              # Auto-set from CLOUDFLARE_PROXY_URL
+#   keepalive_cron: "*/10 * * * *"
+# ── Custom Provider Configuration ────────────────────────────────────
+# For non-standard API endpoints (e.g., Xiaomi MiMo, NVIDIA NIM).
+# These are auto-configured from env vars by start.sh.
+#
+# Environment variables:
+#   CUSTOM_BASE_URL            → model.base_url
+#   CUSTOM_API_KEY             → model.api_key
+#   CUSTOM_MODEL_CONTEXT_LENGTH → model.context_length
+#   CUSTOM_MODEL_MAX_TOKENS    → model.max_tokens
+#   CUSTOM_PROVIDER            → model.provider (default: "custom")
+# ── Advanced Settings ────────────────────────────────────────────────
+# Uncomment and customize as needed.
+# hooks:
+#   pre_tool_call: ""          # Script to run before each tool call
+#   post_tool_call: ""         # Script to run after each tool call
+# logging:
+#   level: info                # debug, info, warning, error
+#   file: ""                   # Log file path (empty = stdout only)
+# ── HF Space Specific ────────────────────────────────────────────────
+# These settings are optimized for Hugging Face Spaces deployment.
+# Backup dataset for state persistence
+# Override via env: BACKUP_DATASET_NAME
+backup_dataset: "huggingmes-backup"
+# Sync settings for HF Dataset backup
+# Override via env: SYNC_INTERVAL, SYNC_POLL_INTERVAL, SYNC_DEBOUNCE_SECONDS
+sync:
+  interval: 60                 # Seconds between sync cycles
+  poll_interval: 2             # Seconds between change detection polls
+  debounce_seconds: 3          # Seconds to wait after last change
+# ══════════════════════════════════════════════════════════════════════
+# END OF CONFIGURATION
+# ══════════════════════════════════════════════════════════════════════

health-server.js ADDED Viewed

	@@ -0,0 +1,1007 @@

+"use strict";
+/**
+ * HuggingMes + Hermes WebUI — single-port router on HF Space port 7861.
+ *
+ * Routes:
+ *   /login                -> HuggingMes login (password = GATEWAY_TOKEN)
+ *   /health /status       -> JSON health (unauthenticated — for HF probes + keepalive)
+ *   /hm  /hm/*            -> HuggingMes status page + app (auth-gated)
+ *   /hmd /hmd/*           -> Hermes dashboard passthrough for off-Space
+ *                            workspaces (no router auth — dashboard's own
+ *                            session token gates writes; opt-in by URL)
+ *   /dashboard            -> redirect to /hm
+ *   /v1  /v1/*            -> Hermes gateway (bearer auth; HTML => login redirect)
+ *   /telegram  /telegram/*-> Telegram webhook (unauthenticated; Telegram needs to reach it)
+ *   everything else       -> Hermes WebUI (nesquena/hermes-webui) as the primary UI
+ *                           WebUI handles its own login at /login-... no, wait: WebUI
+ *                           also exposes /login. We keep HuggingMes' login at /login
+ *                           so the shared GATEWAY_TOKEN gates both.
+ *
+ * Based on github.com/somratpro/HuggingMes with added WebUI routing as the
+ * primary UI.
+ */
+const http = require("http");
+const fs = require("fs");
+const net = require("net");
+const crypto = require("crypto");
+const PORT = Number(process.env.PORT || 7861);
+const GATEWAY_PORT = Number(process.env.API_SERVER_PORT || 8642);
+const DASHBOARD_PORT = Number(process.env.DASHBOARD_PORT || 9119);
+const TELEGRAM_WEBHOOK_PORT = Number(process.env.TELEGRAM_WEBHOOK_PORT || 8765);
+const WEBUI_PORT = Number(process.env.HERMES_WEBUI_PORT || 8787);
+const GATEWAY_HOST = "127.0.0.1";
+const startTime = Date.now();
+const API_SERVER_KEY = process.env.API_SERVER_KEY || "";
+const HM_PREFIX = "/hm";
+// Dashboard passthrough for off-Space workspaces (e.g. hermes-workspace
+// running on a laptop). Anything under /hmd/* is forwarded directly to the
+// internal dashboard with no router-level auth — the dashboard's own
+// ephemeral session token is the only gate. This is intentional: the
+// workspace scrapes that token from /hmd/ and then sends it as the bearer
+// on /hmd/api/* requests, exactly mirroring the dashboard's normal flow.
+//
+// Implication: anyone who can reach this Space's URL can call the dashboard
+// API (sessions, skills, config). If you don't need remote workspace access,
+// don't share the Space URL or set up an upstream auth layer.
+const HMD_PREFIX = "/hmd";
+const LOGIN_PATH = "/hm/login";
+const SESSION_COOKIE = "huggingmes_session";
+const PRIMARY_UI = (process.env.PRIMARY_UI || "webui").toLowerCase();
+const SYNC_STATUS_FILE = "/tmp/huggingmes-sync-status.json";
+const CLOUDFLARE_KEEPALIVE_STATUS_FILE =
+  "/tmp/huggingmes-cloudflare-keepalive-status.json";
+/* ── Port probing + auth ──────────────────────────────────────────── */
+function canConnect(port, host = GATEWAY_HOST, timeoutMs = 600) {
+  return new Promise((resolve) => {
+    const socket = net.createConnection({ port, host });
+    const done = (ok) => {
+      socket.removeAllListeners();
+      socket.destroy();
+      resolve(ok);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.once("connect", () => done(true));
+    socket.once("timeout", () => done(false));
+    socket.once("error", () => done(false));
+  });
+}
+function readJson(path, fallback = null) {
+  try {
+    if (fs.existsSync(path)) return JSON.parse(fs.readFileSync(path, "utf8"));
+  } catch {}
+  return fallback;
+}
+function timingSafeEqualString(left, right) {
+  if (!left || !right) return false;
+  const a = Buffer.from(left);
+  const b = Buffer.from(right);
+  if (a.length !== b.length) return false;
+  return crypto.timingSafeEqual(a, b);
+}
+function expectedSessionValue() {
+  if (!API_SERVER_KEY) return "";
+  return crypto
+    .createHmac("sha256", API_SERVER_KEY)
+    .update("huggingmes-session-v1")
+    .digest("hex");
+}
+function parseCookies(req) {
+  const header = req.headers.cookie || "";
+  const cookies = {};
+  for (const item of header.split(";")) {
+    const sep = item.indexOf("=");
+    if (sep < 0) continue;
+    const name = item.slice(0, sep).trim();
+    const value = item.slice(sep + 1).trim();
+    if (!name) continue;
+    try {
+      cookies[name] = decodeURIComponent(value);
+    } catch {
+      cookies[name] = value;
+    }
+  }
+  return cookies;
+}
+function isHttpsRequest(req) {
+  return req.headers["x-forwarded-proto"] === "https";
+}
+function buildSessionCookie(req) {
+  const secure = isHttpsRequest(req) ? "; Secure" : "";
+  return `${SESSION_COOKIE}=${encodeURIComponent(expectedSessionValue())}; Path=/; HttpOnly; SameSite=Lax; Max-Age=86400${secure}`;
+}
+function getBearerToken(req) {
+  const value = req.headers.authorization || "";
+  const match = /^Bearer\s+(.+)$/i.exec(value);
+  return match ? match[1] : "";
+}
+function isAuthorized(req) {
+  if (!API_SERVER_KEY) return true;
+  return (
+    timingSafeEqualString(getBearerToken(req), API_SERVER_KEY) ||
+    timingSafeEqualString(
+      parseCookies(req)[SESSION_COOKIE],
+      expectedSessionValue(),
+    )
+  );
+}
+function sanitizeNext(value, fallback = "/") {
+  if (!value || typeof value !== "string") return fallback;
+  if (!value.startsWith("/") || value.startsWith("//")) return fallback;
+  return value;
+}
+function loginUrl(nextPath) {
+  return `${LOGIN_PATH}?next=${encodeURIComponent(sanitizeNext(nextPath))}`;
+}
+function wantsHtml(req) {
+  const accept = String(req.headers.accept || "");
+  return accept.includes("text/html");
+}
+function escapeHtml(value) {
+  return String(value)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+function readRequestBody(req, limit = 64 * 1024) {
+  return new Promise((resolve, reject) => {
+    let body = "";
+    req.on("data", (chunk) => {
+      body += chunk;
+      if (body.length > limit) {
+        reject(new Error("Request body is too large."));
+        req.destroy();
+      }
+    });
+    req.on("end", () => resolve(body));
+    req.on("error", reject);
+  });
+}
+/* ── Login page ───────────────────────────────────────────────────── */
+function renderLoginPage(nextPath, errorMessage = "") {
+  const safeNext = sanitizeNext(nextPath, "/");
+  const errorHtml = errorMessage
+    ? `<div class="error">${escapeHtml(errorMessage)}</div>`
+    : "";
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>HuggingMes + Hermes WebUI — Login</title>
+  <style>
+    :root { color-scheme: dark; --bg:#10141f; --panel:#171d2b; --line:#293246; --text:#f4f7fb; --muted:#9aa7bd; --bad:#ef4444; --accent:#38bdf8; }
+    * { box-sizing:border-box; }
+    body { margin:0; min-height:100vh; display:grid; place-items:center; font-family:Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; background:var(--bg); color:var(--text); padding:20px; }
+    main { width:min(440px, 100%); border:1px solid var(--line); background:var(--panel); border-radius:8px; padding:28px; }
+    h1 { margin:0 0 8px; font-size:1.55rem; }
+    p { margin:0 0 22px; color:var(--muted); line-height:1.5; }
+    label { display:block; color:var(--muted); font-size:.82rem; margin-bottom:8px; }
+    input { width:100%; min-height:46px; border:1px solid var(--line); border-radius:7px; background:#0b0f18; color:var(--text); padding:0 12px; font:inherit; }
+    button { width:100%; min-height:44px; margin-top:16px; border:0; border-radius:7px; color:#07111f; background:var(--accent); font:inherit; font-weight:750; cursor:pointer; }
+    .error { border:1px solid rgba(239,68,68,.4); background:rgba(239,68,68,.1); color:#fecaca; border-radius:7px; padding:10px 12px; margin-bottom:16px; }
+  </style>
+</head>
+<body>
+  <main>
+    <h1>HuggingMes Admin</h1>
+    <p>Enter the <code>GATEWAY_TOKEN</code> from your Space secrets to access the status dashboard.<br>For the Hermes chat UI, go to <a href="/" style="color:var(--accent)">/</a>.</p>
+    ${errorHtml}
+    <form method="post" action="${LOGIN_PATH}">
+      <input type="hidden" name="next" value="${escapeHtml(safeNext)}" />
+      <label for="token">GATEWAY_TOKEN</label>
+      <input id="token" name="token" type="password" autocomplete="current-password" autofocus required />
+      <button type="submit">Continue</button>
+    </form>
+  </main>
+</body>
+</html>`;
+}
+async function handleLogin(req, res, parsed) {
+  const nextPath = sanitizeNext(parsed.searchParams.get("next") || "/", "/");
+  if (!API_SERVER_KEY) {
+    redirect(res, nextPath);
+    return;
+  }
+  if (req.method === "GET") {
+    res.writeHead(200, {
+      "content-type": "text/html; charset=utf-8",
+      "cache-control": "no-store",
+    });
+    res.end(renderLoginPage(nextPath));
+    return;
+  }
+  if (req.method !== "POST") {
+    res.writeHead(405, { allow: "GET, POST" });
+    res.end("Method not allowed");
+    return;
+  }
+  try {
+    const body = await readRequestBody(req);
+    const params = new URLSearchParams(body);
+    const submittedToken = params.get("token") || "";
+    const submittedNext = sanitizeNext(params.get("next") || nextPath, "/");
+    if (!timingSafeEqualString(submittedToken, API_SERVER_KEY)) {
+      res.writeHead(401, {
+        "content-type": "text/html; charset=utf-8",
+        "cache-control": "no-store",
+      });
+      res.end(
+        renderLoginPage(
+          submittedNext,
+          "That token did not match GATEWAY_TOKEN.",
+        ),
+      );
+      return;
+    }
+    res.writeHead(302, {
+      location: submittedNext,
+      "set-cookie": buildSessionCookie(req),
+      "cache-control": "no-store",
+    });
+    res.end();
+  } catch (error) {
+    res.writeHead(400, {
+      "content-type": "text/plain; charset=utf-8",
+      "cache-control": "no-store",
+    });
+    res.end(error.message || "Invalid login request.");
+  }
+}
+function requireAuth(req, res) {
+  if (isAuthorized(req)) return true;
+  const parsed = new URL(req.url, "http://localhost");
+  redirect(res, loginUrl(`${parsed.pathname}${parsed.search}`));
+  return false;
+}
+/* ── Upstream proxy ────────────────────────────────────────────────── */
+function proxyRequest(
+  req,
+  res,
+  targetPort,
+  rewritePath = (path) => path,
+  headerOverrides = {},
+) {
+  const parsed = new URL(req.url, "http://localhost");
+  const targetPath = rewritePath(parsed.pathname) + parsed.search;
+  const headers = {
+    ...req.headers,
+    ...headerOverrides,
+    host: `${GATEWAY_HOST}:${targetPort}`,
+    "x-forwarded-host": req.headers.host || "",
+    "x-forwarded-proto": req.headers["x-forwarded-proto"] || "https",
+  };
+  const proxy = http.request(
+    {
+      hostname: GATEWAY_HOST,
+      port: targetPort,
+      method: req.method,
+      path: targetPath,
+      headers,
+    },
+    (upstream) => {
+      res.writeHead(upstream.statusCode || 502, upstream.headers);
+      upstream.pipe(res);
+    },
+  );
+  proxy.on("error", (error) => {
+    res.writeHead(502, { "content-type": "application/json" });
+    res.end(JSON.stringify({ error: "proxy_error", message: error.message }));
+  });
+  req.pipe(proxy);
+}
+function redirect(res, location, statusCode = 302) {
+  res.writeHead(statusCode, { location });
+  res.end();
+}
+/* ── Dashboard SPA proxy with HTML rewriting ──────────────────────────
+ *
+ * The Hermes dashboard is a Vite React app built for root-path deployment.
+ * Its HTML hardcodes window.__HERMES_BASE_PATH__="" and absolute src/href
+ * paths like /assets/index-XXX.js. Under /hm/app, React's router wouldn't
+ * know its basename and client-side routes (/config, /sessions, etc.) 404
+ * on refresh.
+ *
+ * This proxy:
+ *   - serves the dashboard's index.html for any non-asset /hm/app/* path
+ *     (SPA fallback, so /config, /profiles etc. work on direct load)
+ *   - rewrites the returned HTML so React router uses /hm/app as its
+ *     basename and absolute asset paths get prefixed with /hm/app
+ */
+function proxyDashboard(req, res, basePrefix = HM_PREFIX + "/app") {
+  const parsed = new URL(req.url, "http://localhost");
+  const inner = parsed.pathname.replace(basePrefix, "") || "/";
+  const isAssetLike =
+    inner.startsWith("/assets/") ||
+    inner.startsWith("/api/") ||
+    inner.startsWith("/dashboard-plugins/") ||
+    inner.startsWith("/ds-assets/") ||
+    /\.[a-z0-9]{1,6}$/i.test(inner);
+  // SPA routes → serve index.html; everything else → forward as-is.
+  const targetPath =
+    (isAssetLike || inner === "/" ? inner : "/") + parsed.search;
+  const headers = {
+    ...req.headers,
+    host: `${GATEWAY_HOST}:${DASHBOARD_PORT}`,
+    "x-forwarded-host": req.headers.host || "",
+    "x-forwarded-proto": req.headers["x-forwarded-proto"] || "https",
+    // Disable upstream compression so we can rewrite text responses.
+    "accept-encoding": "identity",
+  };
+  const upstream = http.request(
+    {
+      hostname: GATEWAY_HOST,
+      port: DASHBOARD_PORT,
+      method: req.method,
+      path: targetPath,
+      headers,
+    },
+    (upRes) => {
+      const contentType = String(upRes.headers["content-type"] || "");
+      const shouldRewrite =
+        contentType.includes("text/html") ||
+        contentType.includes("application/xhtml");
+      if (!shouldRewrite) {
+        res.writeHead(upRes.statusCode || 502, upRes.headers);
+        upRes.pipe(res);
+        return;
+      }
+      const chunks = [];
+      upRes.on("data", (chunk) => chunks.push(chunk));
+      upRes.on("end", () => {
+        let body = Buffer.concat(chunks).toString("utf8");
+        // Tell the React router its basename.
+        body = body.replace(
+          /window\.__HERMES_BASE_PATH__\s*=\s*"[^"]*"/g,
+          `window.__HERMES_BASE_PATH__="${basePrefix}"`,
+        );
+        // Prefix absolute asset URLs so they stay under the base path.
+        const prefix = basePrefix;
+        body = body.replace(
+          /\b(src|href)="\/(?!\/|http)([^"]*)"/g,
+          (match, attr, rest) => {
+            if (
+              ("/" + rest).startsWith(prefix + "/") ||
+              "/" + rest === prefix
+            ) {
+              return match;
+            }
+            return `${attr}="${prefix}/${rest}"`;
+          },
+        );
+        const buf = Buffer.from(body, "utf8");
+        const outHeaders = { ...upRes.headers };
+        delete outHeaders["content-length"];
+        delete outHeaders["transfer-encoding"];
+        delete outHeaders["content-encoding"];
+        outHeaders["content-length"] = String(buf.length);
+        res.writeHead(upRes.statusCode || 502, outHeaders);
+        res.end(buf);
+      });
+      upRes.on("error", () => {
+        try {
+          res.writeHead(502);
+          res.end();
+        } catch {}
+      });
+    },
+  );
+  upstream.on("error", (error) => {
+    res.writeHead(502, { "content-type": "application/json" });
+    res.end(JSON.stringify({ error: "proxy_error", message: error.message }));
+  });
+  req.pipe(upstream);
+}
+/* ── Status JSON + HuggingMes status page ─────────────────────────── */
+function formatUptime(ms) {
+  const total = Math.floor(ms / 1000);
+  const days = Math.floor(total / 86400);
+  const hours = Math.floor((total % 86400) / 3600);
+  const minutes = Math.floor((total % 3600) / 60);
+  if (days) return `${days}d ${hours}h ${minutes}m`;
+  if (hours) return `${hours}h ${minutes}m`;
+  return `${minutes}m`;
+}
+async function statusPayload() {
+  const gateway = await canConnect(GATEWAY_PORT);
+  const dashboard = await canConnect(DASHBOARD_PORT);
+  const webui = await canConnect(WEBUI_PORT);
+  const telegramWebhook =
+    !!process.env.TELEGRAM_WEBHOOK_URL &&
+    (await canConnect(TELEGRAM_WEBHOOK_PORT));
+  const sync = readJson(
+    SYNC_STATUS_FILE,
+    process.env.HF_TOKEN
+      ? { status: "configured", message: "Backup enabled; waiting for first sync." }
+      : { status: "disabled", message: "HF_TOKEN is not configured." },
+  );
+  return {
+    ok: gateway && webui,
+    uptime: formatUptime(Date.now() - startTime),
+    startedAt: new Date(startTime).toISOString(),
+    gateway,
+    dashboard,
+    webui,
+    authConfigured: !!API_SERVER_KEY,
+    primaryUi: PRIMARY_UI,
+    ports: {
+      public: PORT,
+      gateway: GATEWAY_PORT,
+      dashboard: DASHBOARD_PORT,
+      webui: WEBUI_PORT,
+      telegramWebhook: TELEGRAM_WEBHOOK_PORT,
+    },
+    telegram: {
+      configured: !!process.env.TELEGRAM_BOT_TOKEN,
+      webhook: !!process.env.TELEGRAM_WEBHOOK_URL,
+      webhookUrl: process.env.TELEGRAM_WEBHOOK_URL || "",
+      webhookListening: telegramWebhook,
+      proxy: process.env.CLOUDFLARE_PROXY_URL || "",
+    },
+    model:
+      process.env.MODEL_FOR_CONFIG ||
+      process.env.HERMES_MODEL ||
+      process.env.LLM_MODEL ||
+      "",
+    provider:
+      process.env.PROVIDER_FOR_CONFIG ||
+      process.env.HERMES_INFERENCE_PROVIDER ||
+      "auto",
+    backup: sync,
+    keepalive: readJson(CLOUDFLARE_KEEPALIVE_STATUS_FILE, null),
+  };
+}
+function toneBadge(label, tone = "neutral") {
+  return `<span class="badge ${tone}">${escapeHtml(label)}</span>`;
+}
+function valueOrUnset(value, fallback = "Not set") {
+  return value
+    ? escapeHtml(value)
+    : `<span class="muted">${escapeHtml(fallback)}</span>`;
+}
+function renderTile({ title, value, detail = "", tone = "neutral", meta = "" }) {
+  return `<article class="tile ${tone}">
+    <div class="tile-head">
+      <span class="tile-title">${escapeHtml(title)}</span>
+      <span class="tile-dot"></span>
+    </div>
+    <div class="tile-value">${value}</div>
+    ${detail ? `<div class="tile-detail">${detail}</div>` : ""}
+    ${meta ? `<div class="tile-meta">${meta}</div>` : ""}
+  </article>`;
+}
+function renderStatusPage(data) {
+  const syncStatus = String(data.backup?.status || "unknown");
+  const syncTone = ["success", "restored", "synced", "configured"].includes(syncStatus)
+    ? "ok"
+    : syncStatus === "disabled"
+      ? "warn"
+      : "neutral";
+  const telegramTone = data.telegram.configured
+    ? data.telegram.webhookListening || !data.telegram.webhook
+      ? "ok"
+      : "warn"
+    : "warn";
+  const keepaliveConfigured = data.keepalive?.configured === true;
+  const keepaliveStatus = String(
+    data.keepalive?.status ||
+      (process.env.CLOUDFLARE_WORKERS_TOKEN ? "pending" : "not configured"),
+  );
+  const keepAliveTone = keepaliveConfigured
+    ? "ok"
+    : process.env.CLOUDFLARE_WORKERS_TOKEN
+      ? "warn"
+      : "neutral";
+  const telegramDetail = data.telegram.configured
+    ? `${data.telegram.webhook ? "Webhook" : "Polling"}${data.telegram.proxy ? " via CF proxy" : ""}`
+    : "Not configured";
+  const backupDetail = data.backup?.message
+    ? escapeHtml(data.backup.message)
+    : "No status yet";
+  // Extra one-line warning row for known-loud failure modes (currently:
+  // ephemeral .env on a Space). hermes-sync.py emits this via warning.message.
+  const backupWarning = data.backup?.warning?.message
+    ? `<div class="tile-warning">${escapeHtml(data.backup.warning.message)}</div>`
+    : "";
+  const keepAliveDetail = keepaliveConfigured
+    ? `Pinging <code>${escapeHtml(data.keepalive.targetUrl || "/health")}</code>`
+    : keepaliveStatus === "error" && data.keepalive?.message
+      ? escapeHtml(data.keepalive.message)
+      : process.env.CLOUDFLARE_WORKERS_TOKEN
+        ? "Worker pending or failed"
+        : "Not configured";
+  const tiles = [
+    renderTile({
+      title: "WebUI",
+      value: toneBadge(data.webui ? "Online" : "Offline", data.webui ? "ok" : "off"),
+      detail: data.webui ? `Port ${data.ports.webui}` : "Unreachable",
+      tone: data.webui ? "ok" : "off",
+    }),
+    renderTile({
+      title: "Gateway",
+      value: toneBadge(data.gateway ? "Online" : "Offline", data.gateway ? "ok" : "off"),
+      detail: data.gateway ? `API on port ${data.ports.gateway}` : "Unreachable",
+      tone: data.gateway ? "ok" : "off",
+      meta: data.authConfigured ? "Protected" : "Unprotected",
+    }),
+    renderTile({
+      title: "Model",
+      value: `<code>${valueOrUnset(data.model)}</code>`,
+      detail: `Provider: ${valueOrUnset(data.provider || "auto")}`,
+      tone: data.model ? "ok" : "warn",
+    }),
+    renderTile({
+      title: "Runtime",
+      value: escapeHtml(data.uptime),
+      detail: `Port ${data.ports.public}`,
+      tone: "neutral",
+    }),
+    renderTile({
+      title: "Telegram",
+      value: toneBadge(data.telegram.configured ? "Configured" : "Disabled", telegramTone),
+      detail: telegramDetail,
+      tone: telegramTone,
+    }),
+    renderTile({
+      title: "Backup",
+      value: toneBadge(syncStatus.toUpperCase(), data.backup?.warning ? "warn" : syncTone),
+      detail: backupDetail + backupWarning,
+      tone: data.backup?.warning ? "warn" : syncTone,
+      meta: data.backup?.timestamp
+        ? `<span class="local-time" data-iso="${data.backup.timestamp}"></span>`
+        : "",
+    }),
+    renderTile({
+      title: "Keep Awake",
+      value: toneBadge(
+        keepaliveConfigured ? "CF Cron" : keepaliveStatus.toUpperCase(),
+        keepAliveTone,
+      ),
+      detail: keepAliveDetail,
+      tone: keepAliveTone,
+    }),
+  ].join("");
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>HuggingMes + Hermes WebUI</title>
+  <style>
+    :root { color-scheme: dark; --bg:#08080f; --panel:#12111b; --line:#26243a; --text:#f6f4ff; --muted:#7f7a9e; --soft:#b8b3d7; --good:#22c55e; --warn:#f5c542; --bad:#fb7185; --accent:#6557df; }
+    * { box-sizing:border-box; }
+    body { margin:0; min-height:100vh; font-family:Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; background:var(--bg); color:var(--text); font-size:13px; }
+    main { width:min(720px, calc(100% - 32px)); margin:0 auto; padding:36px 0 44px; }
+    header { text-align:center; margin-bottom:22px; }
+    h1 { margin:0; font-size:1.65rem; }
+    .subtitle { margin-top:12px; color:var(--muted); font-size:.72rem; text-transform:uppercase; letter-spacing:.14em; font-weight:800; }
+    .row { display:flex; gap:10px; margin:24px 0 20px; flex-wrap:wrap; }
+    .hero-action { flex:1 1 200px; min-height:46px; display:flex; align-items:center; justify-content:center; border-radius:8px; background:#ffffff; color:#000000; text-decoration:none; font-weight:850; font-size:.98rem; }
+    .hero-action.secondary { background:#232234; color:var(--text); border:1px solid var(--line); }
+    .hero-action:hover { opacity:.9; }
+    .overview { display:grid; grid-template-columns:repeat(2, minmax(0, 1fr)); gap:10px; margin-bottom:10px; }
+    .tile { border:1px solid var(--line); background:var(--panel); border-radius:11px; padding:18px; min-height:124px; display:flex; flex-direction:column; gap:10px; position:relative; }
+    .tile.ok { border-color:rgba(34,197,94,.22); }
+    .tile.warn { border-color:rgba(245,197,66,.24); }
+    .tile.off { border-color:rgba(251,113,133,.28); }
+    .tile-head { display:flex; align-items:center; justify-content:space-between; gap:12px; }
+    .tile-title { color:var(--muted); font-size:.67rem; letter-spacing:.18em; text-transform:uppercase; font-weight:850; }
+    .tile-dot { width:7px; height:7px; border-radius:50%; background:var(--line); }
+    .tile.ok .tile-dot { background:var(--good); }
+    .tile.warn .tile-dot { background:var(--warn); }
+    .tile.off .tile-dot { background:var(--bad); }
+    .tile-value { font-size:1.12rem; font-weight:850; overflow-wrap:anywhere; }
+    .tile-detail { color:var(--soft); line-height:1.45; font-size:.83rem; }
+    .tile-meta { color:var(--muted); line-height:1.4; font-size:.75rem; margin-top:auto; overflow-wrap:anywhere; }
+    .tile-warning { color:#fde68a; background:rgba(245,158,11,.08); border:1px solid rgba(245,158,11,.32); border-radius:6px; padding:6px 8px; margin-top:6px; font-size:.78rem; line-height:1.4; }
+    code { background:#232234; border:1px solid #34324c; border-radius:6px; padding:2px 6px; color:var(--text); font-size:.9em; }
+    .badge { display:inline-flex; align-items:center; border:1px solid var(--line); border-radius:999px; padding:5px 10px; font-size:.72rem; font-weight:850; line-height:1; text-transform:uppercase; }
+    .badge.ok { color:var(--good); border-color:rgba(34,197,94,.34); background:rgba(34,197,94,.11); }
+    .badge.warn { color:var(--warn); border-color:rgba(245,197,66,.34); background:rgba(245,197,66,.11); }
+    .badge.off { color:var(--bad); border-color:rgba(251,113,133,.34); background:rgba(251,113,133,.11); }
+    .badge.neutral { color:var(--soft); }
+    .muted { color:var(--muted); }
+    footer { color:var(--muted); text-align:center; font-size:.74rem; margin-top:18px; }
+    @media (max-width: 700px) { .overview { grid-template-columns:1fr; } }
+  </style>
+</head>
+<body>
+  <main>
+    <header>
+      <h1>HuggingMes + Hermes WebUI</h1>
+      <div class="subtitle">Self-hosted Hermes Agent on HF Spaces</div>
+    </header>
+    <div class="row">
+      <a class="hero-action" href="/" target="_blank" rel="noopener">Open Hermes WebUI -&gt;</a>
+      <a class="hero-action secondary" href="${HM_PREFIX}/app/" target="_blank" rel="noopener">Open Hermes Dashboard</a>
+    </div>
+    <section class="overview">
+      ${tiles}
+    </section>
+    <footer>Built on <a href="https://github.com/somratpro/HuggingMes" style="color:var(--accent)">HuggingMes</a> + <a href="https://github.com/nesquena/hermes-webui" style="color:var(--accent)">Hermes WebUI</a></footer>
+  </main>
+  <script>
+    document.querySelectorAll('.local-time').forEach(el => {
+      const date = new Date(el.getAttribute('data-iso'));
+      if (!isNaN(date)) el.textContent = 'At ' + date.toLocaleTimeString();
+    });
+  </script>
+</body>
+</html>`;
+}
+/* ── Server ───────────────────────────────────────────────────────── */
+const server = http.createServer(async (req, res) => {
+  const parsed = new URL(req.url, "http://localhost");
+  const path = parsed.pathname;
+  // 1. /hm/login — HuggingMes admin login (cookie-based, gates /hm/*).
+  //    hermes-webui handles its own /login at the catch-all below.
+  if (path === LOGIN_PATH) {
+    await handleLogin(req, res, parsed);
+    return;
+  }
+  // 2. /health — unauthenticated; HF Spaces probes + Cloudflare keepalive.
+  if (path === "/health") {
+    const data = await statusPayload();
+    res.writeHead(data.ok ? 200 : 503, { "content-type": "application/json" });
+    res.end(
+      JSON.stringify({
+        ok: data.ok,
+        gateway: data.gateway,
+        webui: data.webui,
+        uptime: data.uptime,
+      }),
+    );
+    return;
+  }
+  // 3. /status — unauthenticated JSON status dump.
+  if (path === "/status" || path === "/api/status") {
+    const data = await statusPayload();
+    res.writeHead(200, { "content-type": "application/json" });
+    res.end(JSON.stringify(data, null, 2));
+    return;
+  }
+  // 4. /telegram — webhook endpoint; no auth (Telegram can't do our cookie).
+  if (path === "/telegram" || path.startsWith("/telegram/")) {
+    proxyRequest(req, res, TELEGRAM_WEBHOOK_PORT);
+    return;
+  }
+  // 5. /v1/* — Hermes gateway OpenAI-compatible API.
+  if (path === "/v1" || path.startsWith("/v1/")) {
+    if (!isAuthorized(req)) {
+      if (wantsHtml(req)) {
+        redirect(res, loginUrl(`${path}${parsed.search}`));
+        return;
+      }
+      res.writeHead(401, {
+        "content-type": "application/json",
+        "cache-control": "no-store",
+      });
+      res.end(
+        JSON.stringify({
+          error: "unauthorized",
+          message: "Use Authorization: Bearer <GATEWAY_TOKEN>.",
+        }),
+      );
+      return;
+    }
+    const upstreamHeaders =
+      getBearerToken(req) || !API_SERVER_KEY
+        ? {}
+        : { authorization: `Bearer ${API_SERVER_KEY}` };
+    proxyRequest(req, res, GATEWAY_PORT, (p) => p, upstreamHeaders);
+    return;
+  }
+  // 6. /hm — HuggingMes status page.
+  if (path === HM_PREFIX || path === `${HM_PREFIX}/`) {
+    if (!requireAuth(req, res)) return;
+    const data = await statusPayload();
+    res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+    res.end(renderStatusPage(data));
+    return;
+  }
+  // /hmd/* — Off-Space dashboard passthrough.
+  //
+  // Forwards verbatim to the internal Hermes dashboard on DASHBOARD_PORT,
+  // including its /api/* endpoints, /assets/*, root HTML (which carries the
+  // ephemeral session token), and WebSocket upgrades. Workspace clients
+  // (e.g. hermes-workspace) point HERMES_DASHBOARD_URL at
+  //   https://<space>/hmd
+  // and the workspace's own scrape-the-token-from-root-HTML logic just
+  // works because /hmd/ returns the unmodified dashboard index.
+  //
+  // SECURITY: this prefix has no router-level auth on purpose — the
+  // dashboard's own session token gates writes. If you need an extra layer,
+  // wrap your Space behind a Cloudflare Access policy or remove this
+  // handler.
+  if (path === HMD_PREFIX || path.startsWith(`${HMD_PREFIX}/`)) {
+    proxyDashboard(req, res, HMD_PREFIX);
+    return;
+  }
+  // /hm/app/* -> Hermes dashboard (SPA with HTML rewriting for base path)
+  if (path === `${HM_PREFIX}/app` || path.startsWith(`${HM_PREFIX}/app/`)) {
+    if (!requireAuth(req, res)) return;
+    proxyDashboard(req, res);
+    return;
+  }
+  // /hm/status -> JSON
+  if (path === `${HM_PREFIX}/status`) {
+    if (!requireAuth(req, res)) return;
+    const data = await statusPayload();
+    res.writeHead(200, { "content-type": "application/json" });
+    res.end(JSON.stringify(data, null, 2));
+    return;
+  }
+  // Legacy /dashboard -> /hm
+  if (path === "/dashboard" || path === "/dashboard/") {
+    redirect(res, `${HM_PREFIX}${parsed.search}`);
+    return;
+  }
+  // Root-path dashboard routes (config, env, providers, etc.) that users
+  // type or bookmark without the /hm/app prefix. Redirect them there.
+  const dashboardRootRoutes = new Set([
+    "/config",
+    "/env",
+    "/models",
+    "/providers",
+    "/profiles",
+    "/sessions",
+    "/skills",
+    "/cron",
+    "/analytics",
+    "/logs",
+    "/plugins",
+    "/chat",
+    "/docs",
+  ]);
+  if (dashboardRootRoutes.has(path) || [...dashboardRootRoutes].some((r) => path.startsWith(r + "/"))) {
+    redirect(res, `${HM_PREFIX}/app${path}${parsed.search}`);
+    return;
+  }
+  // 6b. Root-path requests whose Referer came from /hm/app/* must go to
+  //     the dashboard, not WebUI. This covers:
+  //       - Absolute assets    (/assets/*, /ds-assets/*, /dashboard-plugins/*)
+  //       - API calls          (/api/*) when dashboard code uses absolute paths
+  //       - Favicon            (/favicon.ico)
+  //       - WebSocket upgrades from dashboard pages
+  //       - File downloads     (any extensioned path referenced by dashboard)
+  //     Both the Hermes dashboard AND hermes-webui use /api/* internally,
+  //     so the Referer is the only reliable way to disambiguate.
+  const refererPath = (() => {
+    const ref = String(req.headers.referer || "");
+    if (!ref) return "";
+    try {
+      return new URL(ref).pathname;
+    } catch {
+      return "";
+    }
+  })();
+  const refererIsDashboard = refererPath.startsWith(`${HM_PREFIX}/app`) || refererPath.startsWith(`${HMD_PREFIX}`);
+  const refererIsHmd = refererPath.startsWith(`${HMD_PREFIX}`);
+  if (refererIsDashboard) {
+    // Anything with a Referer from the dashboard goes to the dashboard,
+    // *except* requests that explicitly start with /webui (escape hatch).
+    if (!path.startsWith("/webui")) {
+      // /hmd is intentionally no-auth (dashboard's own session token gates writes).
+      // Only require auth for /hm/app referers.
+      if (!refererIsHmd) {
+        if (!requireAuth(req, res)) return;
+      }
+      // Assets must NOT get the SPA fallback; pass them through as-is.
+      const parsed2 = new URL(req.url, "http://localhost");
+      const looksLikeAsset =
+        path.startsWith("/assets/") ||
+        path.startsWith("/ds-assets/") ||
+        path.startsWith("/dashboard-plugins/") ||
+        path.startsWith("/api/") ||
+        path === "/favicon.ico" ||
+        /\.[a-z0-9]{1,6}$/i.test(path);
+      if (looksLikeAsset) {
+        proxyRequest(req, res, DASHBOARD_PORT);
+      } else {
+        // Unlikely: a dashboard-referrer request for a non-asset, non-/hm
+        // path. Treat as a dashboard sub-route.
+        proxyDashboard(req, res, refererIsHmd ? HMD_PREFIX : undefined);
+      }
+      return;
+    }
+  }
+  // 6c. /api/* routes — these are WebUI API calls when Referer isn't the
+  //     dashboard. Fall through to the catch-all below.
+  //
+  // Exception: hermes-workspace probes for the *legacy* enhanced-fork chat
+  // endpoint at POST /api/sessions/<id>/chat/stream. Without this rule the
+  // request falls through to WebUI's catch-all, which doesn't 404 it
+  // cleanly, so the workspace's detector sets `enhancedChat=true`, sends
+  // chat there at runtime, and the UI surfaces a generic "Authentication
+  // error". Returning an explicit 404 here makes the workspace fall back
+  // to the OpenAI-compatible /v1/chat/completions path on the gateway —
+  // which is the only chat surface this Space actually exposes.
+  //
+  // Anything the dashboard or WebUI legitimately need under /api/sessions/
+  // already has a more specific match above (referer check / /hmd
+  // passthrough), so this only fires for cross-origin probes.
+  if (
+    /^\/api\/sessions\/[^/]+\/chat\/stream\/?$/.test(path) &&
+    !refererIsDashboard
+  ) {
+    res.writeHead(404, {
+      "content-type": "application/json",
+      "cache-control": "no-store",
+    });
+    res.end(
+      JSON.stringify({
+        error: "not_found",
+        message:
+          "Legacy enhanced-fork chat stream is not exposed by this Space. Use /v1/chat/completions.",
+      }),
+    );
+    return;
+  }
+  // 7. Anything else -> Hermes WebUI (primary UI) OR HuggingMes status page.
+  //    WebUI handles its own auth internally via HERMES_WEBUI_PASSWORD.
+  if (PRIMARY_UI === "dashboard" && path === "/") {
+    if (!requireAuth(req, res)) return;
+    const data = await statusPayload();
+    res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+    res.end(renderStatusPage(data));
+    return;
+  }
+  // Catch-all -> WebUI. Don't gate at the router level: WebUI has its own
+  // password login. GATEWAY_TOKEN *is* the WebUI password (start.sh sets
+  // HERMES_WEBUI_PASSWORD=$GATEWAY_TOKEN).
+  proxyRequest(req, res, WEBUI_PORT);
+});
+server.listen(PORT, "0.0.0.0", () => {
+  console.log(`HuggingMes + Hermes WebUI router listening on 0.0.0.0:${PORT}`);
+});
+/* ── WebSocket upgrade handling ─────────────────────────────────────
+ *
+ * Both the Hermes dashboard and hermes-webui can open WebSocket
+ * connections for live updates. Route the upgrade to the correct
+ * upstream based on path prefix + referer, same as HTTP requests.
+ */
+server.on("upgrade", (req, clientSocket, head) => {
+  const parsed = new URL(req.url, "http://localhost");
+  const path = parsed.pathname;
+  let targetPort = WEBUI_PORT;
+  let targetPath = req.url;
+  const refererPath = (() => {
+    const ref = String(req.headers.referer || "");
+    if (!ref) return "";
+    try {
+      return new URL(ref).pathname;
+    } catch {
+      return "";
+    }
+  })();
+  const refererIsDashboard = refererPath.startsWith(`${HM_PREFIX}/app`) || refererPath.startsWith(`${HMD_PREFIX}`);
+  if (path === "/v1" || path.startsWith("/v1/")) {
+    targetPort = GATEWAY_PORT;
+  } else if (path === HMD_PREFIX || path.startsWith(`${HMD_PREFIX}/`)) {
+    // Off-Space dashboard passthrough (mirrors the HTTP /hmd handler).
+    targetPort = DASHBOARD_PORT;
+    targetPath = path.replace(HMD_PREFIX, "") || "/";
+    if (parsed.search) targetPath += parsed.search;
+  } else if (path === `${HM_PREFIX}/app` || path.startsWith(`${HM_PREFIX}/app/`)) {
+    targetPort = DASHBOARD_PORT;
+    targetPath = path.replace(`${HM_PREFIX}/app`, "") || "/";
+    if (parsed.search) targetPath += parsed.search;
+  } else if (refererIsDashboard && !path.startsWith("/webui")) {
+    targetPort = DASHBOARD_PORT;
+  } else if (path.startsWith("/webui/") || path === "/webui") {
+    targetPort = WEBUI_PORT;
+    targetPath = path.replace(/^\/webui/, "") || "/";
+    if (parsed.search) targetPath += parsed.search;
+  }
+  const upstream = net.createConnection(targetPort, GATEWAY_HOST, () => {
+    // Forward the HTTP upgrade handshake verbatim
+    const headerLines = [
+      `${req.method} ${targetPath} HTTP/1.1`,
+    ];
+    for (const [name, value] of Object.entries(req.headers)) {
+      if (Array.isArray(value)) {
+        for (const v of value) headerLines.push(`${name}: ${v}`);
+      } else {
+        headerLines.push(`${name}: ${value}`);
+      }
+    }
+    headerLines.push("", "");
+    upstream.write(headerLines.join("\r\n"));
+    if (head && head.length) upstream.write(head);
+    upstream.pipe(clientSocket);
+    clientSocket.pipe(upstream);
+  });
+  upstream.on("error", () => {
+    try {
+      clientSocket.end("HTTP/1.1 502 Bad Gateway\r\n\r\n");
+    } catch {}
+  });
+  clientSocket.on("error", () => {
+    try {
+      upstream.destroy();
+    } catch {}
+  });
+});

hermes-sync.py ADDED Viewed

	@@ -0,0 +1,482 @@

+#!/usr/bin/env python3
+"""HuggingMes Hermes state backup via Hugging Face Datasets.
+Vendored verbatim from github.com/somratpro/HuggingMes.
+Backs up HERMES_HOME (which includes /opt/data/webui — the hermes-webui state dir)
+so sessions, profiles, skills, cron, memory, and workspace all survive restarts.
+"""
+import hashlib
+import json
+import logging
+import os
+import shutil
+import signal
+import socket
+import sys
+import tempfile
+import threading
+import time
+from pathlib import Path
+os.environ.setdefault("HF_HUB_DISABLE_PROGRESS_BARS", "1")
+os.environ.setdefault("HF_HUB_VERBOSITY", "error")
+os.environ.setdefault("HF_HUB_DOWNLOAD_TIMEOUT", "300")
+# huggingface_hub 0.30+ replaced HF_HUB_ENABLE_HF_TRANSFER with this flag;
+# the legacy var triggers a FutureWarning at import on newer hubs and is
+# silently ignored. Setting only the new var means older hubs miss the
+# transfer accelerator (which is fine — they fall back to the standard
+# downloader) but no version emits a deprecation warning.
+os.environ.setdefault("HF_XET_HIGH_PERFORMANCE", "1")
+from huggingface_hub import HfApi, snapshot_download, upload_folder
+from huggingface_hub.errors import HfHubHTTPError, RepositoryNotFoundError
+logging.getLogger("huggingface_hub").setLevel(logging.ERROR)
+HERMES_HOME = Path(os.environ.get("HERMES_HOME", "/opt/data"))
+STATUS_FILE = Path("/tmp/huggingmes-sync-status.json")
+STATE_FILE = HERMES_HOME / ".huggingmes-sync-state.json"
+INTERVAL = int(os.environ.get("SYNC_INTERVAL", "60"))
+INITIAL_DELAY = int(os.environ.get("SYNC_START_DELAY", "5"))
+# Change-driven settings: the loop polls cheap stat metadata every POLL_INTERVAL
+# seconds, and once a change is observed waits DEBOUNCE_SECONDS of quiet before
+# uploading. INTERVAL acts only as a hard ceiling — even if writes never settle,
+# a sync is forced after INTERVAL seconds. This keeps the worst-case data loss
+# window well under a minute without uploading on every keystroke.
+POLL_INTERVAL = float(os.environ.get("SYNC_POLL_INTERVAL", "2"))
+DEBOUNCE_SECONDS = float(os.environ.get("SYNC_DEBOUNCE_SECONDS", "3"))
+HF_TOKEN = os.environ.get("HF_TOKEN", "").strip()
+HF_USERNAME = os.environ.get("HF_USERNAME", "").strip()
+SPACE_AUTHOR_NAME = os.environ.get("SPACE_AUTHOR_NAME", "").strip()
+BACKUP_DATASET_NAME = os.environ.get("BACKUP_DATASET_NAME", "huggingmes-backup").strip()
+INCLUDE_ENV = os.environ.get("SYNC_INCLUDE_ENV", "").strip().lower() in {"1", "true", "yes"}
+MAX_FILE_SIZE_BYTES = int(os.environ.get("SYNC_MAX_FILE_BYTES", str(50 * 1024 * 1024)))
+EXCLUDED_DIRS = {
+    ".cache",
+    ".git",
+    ".npm",
+    ".venv",
+    "__pycache__",
+    "node_modules",
+    "venv",
+    "logs",          # log files are useless after a restart
+}
+EXCLUDED_TOP_LEVEL = {"logs", STATE_FILE.name}
+EXCLUDED_SUFFIXES = (
+    ".log", ".log.1", ".log.2",
+    ".db-shm", ".db-wal", ".db-journal",
+    ".pid", ".tmp",
+)
+if not INCLUDE_ENV:
+    EXCLUDED_TOP_LEVEL.add(".env")
+HF_API = HfApi(token=HF_TOKEN) if HF_TOKEN else None
+STOP_EVENT = threading.Event()
+_REPO_ID_CACHE: str | None = None
+# `.env` warning: on HF Spaces, the dashboard's "Env" tab writes to
+# $HERMES_HOME/.env which is *not* backed up by default (see EXCLUDED_TOP_LEVEL
+# above). That means provider keys typed into the dashboard silently disappear
+# on every restart. We can't safely fix that by default — uploading plaintext
+# secrets to a dataset is the wrong tradeoff — but we can make the failure
+# loud. The status surface on the HuggingMes status page reads the JSON below,
+# so an `env_warning` field renders as a banner without any extra plumbing.
+ENV_FILE = HERMES_HOME / ".env"
+ON_HF_SPACE = bool(os.environ.get("SPACE_ID") or os.environ.get("SPACE_HOST"))
+def env_warning_payload() -> dict | None:
+    """Detect plaintext-secret-loss risk and return a warning blob, or None.
+    Fires when:
+      * we're on an HF Space (ephemeral filesystem), AND
+      * `.env` exists with non-trivial content, AND
+      * SYNC_INCLUDE_ENV is off (so .env is NOT being backed up).
+    The warning is informational. We never refuse to start sync, and we never
+    auto-flip SYNC_INCLUDE_ENV — the user must opt in to backing up plaintext.
+    """
+    if not ON_HF_SPACE or INCLUDE_ENV:
+        return None
+    try:
+        if not ENV_FILE.is_file():
+            return None
+        # Count non-empty, non-comment lines as a proxy for "user-set keys".
+        keys = 0
+        for raw in ENV_FILE.read_text(encoding="utf-8", errors="replace").splitlines():
+            line = raw.strip()
+            if not line or line.startswith("#"):
+                continue
+            if "=" in line:
+                keys += 1
+        if keys <= 0:
+            return None
+        return {
+            "kind": "ephemeral_env",
+            "keys": keys,
+            "message": (
+                f"{keys} entr{'y' if keys == 1 else 'ies'} in $HERMES_HOME/.env "
+                "will be wiped on the next Space restart. Move secrets to "
+                "Space Secrets (Settings -> Variables and secrets), or set "
+                "SYNC_INCLUDE_ENV=1 to back up .env to the private dataset "
+                "(plaintext; weaker security)."
+            ),
+        }
+    except OSError:
+        return None
+def write_status(status: str, message: str, fingerprint: str | None = None, marker: tuple[int, int, int] | None = None) -> None:
+    timestamp = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+    payload: dict = {"status": status, "message": message, "timestamp": timestamp}
+    warning = env_warning_payload()
+    if warning is not None:
+        payload["warning"] = warning
+    tmp_path = STATUS_FILE.with_suffix(".tmp")
+    try:
+        tmp_path.write_text(json.dumps(payload), encoding="utf-8")
+        tmp_path.replace(STATUS_FILE)
+    except OSError:
+        pass
+    if fingerprint or marker:
+        state = {}
+        if STATE_FILE.exists():
+            try:
+                state = json.loads(STATE_FILE.read_text(encoding="utf-8"))
+            except Exception:
+                pass
+        if fingerprint:
+            state["last_fingerprint"] = fingerprint
+        if marker:
+            state["last_marker"] = list(marker)
+        state["last_sync"] = timestamp
+        try:
+            STATE_FILE.write_text(json.dumps(state), encoding="utf-8")
+        except OSError:
+            pass
+def resolve_backup_repo() -> str:
+    global _REPO_ID_CACHE
+    if _REPO_ID_CACHE:
+        return _REPO_ID_CACHE
+    namespace = HF_USERNAME or SPACE_AUTHOR_NAME
+    if not namespace and HF_API is not None:
+        whoami = HF_API.whoami()
+        namespace = whoami.get("name") or whoami.get("user") or ""
+    namespace = str(namespace).strip()
+    if not namespace:
+        raise RuntimeError("Could not determine HF username. Set HF_USERNAME or use an account HF_TOKEN.")
+    _REPO_ID_CACHE = f"{namespace}/{BACKUP_DATASET_NAME}"
+    return _REPO_ID_CACHE
+def ensure_repo_exists() -> str:
+    repo_id = resolve_backup_repo()
+    try:
+        HF_API.repo_info(repo_id=repo_id, repo_type="dataset")
+    except RepositoryNotFoundError:
+        HF_API.create_repo(repo_id=repo_id, repo_type="dataset", private=True)
+    return repo_id
+def should_exclude(rel_posix: str, path: Path) -> bool:
+    parts = Path(rel_posix).parts
+    if not parts:
+        return False
+    if parts[0] in EXCLUDED_TOP_LEVEL:
+        return True
+    if any(part in EXCLUDED_DIRS for part in parts):
+        return True
+    if path.is_file():
+        name_lower = path.name.lower()
+        if name_lower.endswith(EXCLUDED_SUFFIXES):
+            return True
+        try:
+            return path.stat().st_size > MAX_FILE_SIZE_BYTES
+        except OSError:
+            return True
+    return False
+def metadata_marker(root: Path) -> tuple[int, int, int]:
+    if not root.exists():
+        return (0, 0, 0)
+    file_count = 0
+    total_size = 0
+    newest_mtime = 0
+    for path in root.rglob("*"):
+        if not path.is_file():
+            continue
+        rel = path.relative_to(root).as_posix()
+        if should_exclude(rel, path):
+            continue
+        try:
+            stat = path.stat()
+        except OSError:
+            continue
+        file_count += 1
+        total_size += int(stat.st_size)
+        newest_mtime = max(newest_mtime, int(stat.st_mtime_ns))
+    return (file_count, total_size, newest_mtime)
+def fingerprint_dir(root: Path) -> str:
+    hasher = hashlib.sha256()
+    if not root.exists():
+        return hasher.hexdigest()
+    for path in sorted(p for p in root.rglob("*") if p.is_file()):
+        rel = path.relative_to(root).as_posix()
+        if should_exclude(rel, path):
+            continue
+        hasher.update(rel.encode("utf-8"))
+        with path.open("rb") as handle:
+            for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+                hasher.update(chunk)
+    return hasher.hexdigest()
+def create_snapshot_dir(source_root: Path) -> Path:
+    staging_root = Path(tempfile.mkdtemp(prefix="huggingmes-sync-"))
+    for path in sorted(source_root.rglob("*")):
+        rel = path.relative_to(source_root)
+        rel_posix = rel.as_posix()
+        if should_exclude(rel_posix, path):
+            continue
+        target = staging_root / rel
+        if path.is_dir():
+            target.mkdir(parents=True, exist_ok=True)
+            continue
+        target.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            shutil.copy2(path, target)
+        except OSError:
+            continue
+    return staging_root
+def restore() -> bool:
+    if not HF_TOKEN:
+        write_status("disabled", "HF_TOKEN is not configured.")
+        return False
+    repo_id = resolve_backup_repo()
+    write_status("restoring", f"Restoring Hermes state from {repo_id}")
+    try:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            snapshot_download(repo_id=repo_id, repo_type="dataset", token=HF_TOKEN, local_dir=tmpdir)
+            tmp_path = Path(tmpdir)
+            if not any(tmp_path.iterdir()):
+                write_status("fresh", "Backup dataset is empty. Starting fresh.")
+                return True
+            HERMES_HOME.mkdir(parents=True, exist_ok=True)
+            for child in tmp_path.iterdir():
+                if should_exclude(child.name, child):
+                    continue
+                target = HERMES_HOME / child.name
+                if target.is_dir():
+                    shutil.rmtree(target, ignore_errors=True)
+                elif target.exists():
+                    target.unlink()
+                if child.is_dir():
+                    shutil.copytree(child, target)
+                else:
+                    shutil.copy2(child, target)
+        write_status("restored", f"Restored Hermes state from {repo_id}")
+        return True
+    except RepositoryNotFoundError:
+        write_status("fresh", f"Backup dataset {repo_id} does not exist yet.")
+        return True
+    except HfHubHTTPError as exc:
+        if exc.response is not None and exc.response.status_code == 404:
+            write_status("fresh", f"Backup dataset {repo_id} does not exist yet.")
+            return True
+        write_status("error", f"Restore failed: {exc}")
+        print(f"Restore failed: {exc}", file=sys.stderr)
+        return False
+    except Exception as exc:
+        write_status("error", f"Restore failed: {exc}")
+        print(f"Restore failed: {exc}", file=sys.stderr)
+        return False
+def sync_once(last_fingerprint: str | None = None, last_marker: tuple[int, int, int] | None = None):
+    if last_fingerprint is None and last_marker is None:
+        if STATE_FILE.exists():
+            try:
+                state = json.loads(STATE_FILE.read_text(encoding="utf-8"))
+                last_fingerprint = state.get("last_fingerprint")
+                m = state.get("last_marker")
+                if m and len(m) == 3:
+                    last_marker = tuple(m)
+            except Exception:
+                pass
+    repo_id = ensure_repo_exists()
+    current_marker = metadata_marker(HERMES_HOME)
+    if last_marker is not None and current_marker == last_marker:
+        write_status("synced", "No Hermes state changes detected (marker match).")
+        return (last_fingerprint or "", current_marker)
+    current_fingerprint = fingerprint_dir(HERMES_HOME)
+    if last_fingerprint is not None and current_fingerprint == last_fingerprint:
+        write_status("synced", "No Hermes state changes detected (fingerprint match).")
+        return (last_fingerprint, current_marker)
+    hostname = socket.gethostname()
+    write_status("syncing", f"Uploading Hermes state to {repo_id} from {hostname}")
+    snapshot_dir = create_snapshot_dir(HERMES_HOME)
+    try:
+        upload_folder(
+            folder_path=str(snapshot_dir),
+            repo_id=repo_id,
+            repo_type="dataset",
+            token=HF_TOKEN,
+            commit_message=f"HuggingMes sync [{hostname}] {time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime())}",
+            ignore_patterns=[".git/*", ".git"],
+        )
+    finally:
+        shutil.rmtree(snapshot_dir, ignore_errors=True)
+    write_status("success", f"Uploaded Hermes state to {repo_id}", fingerprint=current_fingerprint, marker=current_marker)
+    return (current_fingerprint, current_marker)
+def handle_signal(_sig, _frame) -> None:
+    STOP_EVENT.set()
+def loop() -> int:
+    signal.signal(signal.SIGTERM, handle_signal)
+    signal.signal(signal.SIGINT, handle_signal)
+    try:
+        repo_id = resolve_backup_repo()
+        write_status(
+            "configured",
+            f"Backup watcher active for {repo_id} "
+            f"(poll={POLL_INTERVAL}s, debounce={DEBOUNCE_SECONDS}s, max={INTERVAL}s).",
+        )
+    except Exception as exc:
+        write_status("error", str(exc))
+        print(f"Hermes sync error: {exc}")
+        return 1
+    warning = env_warning_payload()
+    if warning is not None:
+        # Loud, single-line, easy to grep in HF Space logs.
+        print(f"Hermes sync WARNING: {warning['message']}")
+    # Seed from any prior run so we don't re-upload an identical tree.
+    last_fingerprint: str | None = None
+    last_marker: tuple[int, int, int] | None = None
+    if STATE_FILE.exists():
+        try:
+            state = json.loads(STATE_FILE.read_text(encoding="utf-8"))
+            last_fingerprint = state.get("last_fingerprint")
+            m = state.get("last_marker")
+            if m and len(m) == 3:
+                last_marker = tuple(m)
+        except Exception:
+            pass
+    if last_marker is None:
+        last_marker = metadata_marker(HERMES_HOME)
+    if STOP_EVENT.wait(INITIAL_DELAY):
+        return 0
+    print(
+        f"Hermes state sync started: poll={POLL_INTERVAL}s "
+        f"debounce={DEBOUNCE_SECONDS}s max={INTERVAL}s -> {repo_id}"
+    )
+    # Change-driven scheduler. Two clocks:
+    #   * `pending_since`     — when we first noticed an unsynced change. Used
+    #                           with INTERVAL to enforce a hard ceiling so a
+    #                           continuously-busy session can't starve uploads.
+    #   * `last_change_at`    — when we most recently saw the marker move. The
+    #                           debounce timer is measured against this so we
+    #                           wait for writes to settle before uploading.
+    pending_since: float | None = None
+    last_change_at: float | None = None
+    candidate_marker = last_marker
+    while not STOP_EVENT.is_set():
+        if STOP_EVENT.wait(POLL_INTERVAL):
+            break
+        try:
+            current_marker = metadata_marker(HERMES_HOME)
+        except Exception as exc:
+            # Don't let a transient stat error kill the loop.
+            write_status("error", f"marker scan failed: {exc}")
+            continue
+        now = time.time()
+        if current_marker != candidate_marker:
+            # Files moved since the last poll. Start (or extend) a debounce.
+            if pending_since is None:
+                pending_since = now
+            last_change_at = now
+            candidate_marker = current_marker
+            continue
+        if pending_since is None:
+            # Tree is unchanged and there's nothing waiting. Nothing to do.
+            continue
+        quiet_for = now - (last_change_at or now)
+        held_for = now - pending_since
+        # Trigger when writes have settled (debounce) OR when the hard ceiling
+        # is hit, so a never-idle tree still gets snapshotted at least once
+        # per INTERVAL seconds.
+        if quiet_for < DEBOUNCE_SECONDS and held_for < INTERVAL:
+            continue
+        try:
+            last_fingerprint, last_marker = sync_once(last_fingerprint, last_marker)
+            candidate_marker = last_marker
+        except Exception as exc:
+            write_status("error", f"Sync failed: {exc}")
+            print(f"Hermes sync failed: {exc}")
+            # Back off briefly on failure so we don't hot-loop a broken upload.
+            if STOP_EVENT.wait(min(5.0, POLL_INTERVAL * 2)):
+                break
+        finally:
+            pending_since = None
+            last_change_at = None
+    return 0
+def main() -> int:
+    HERMES_HOME.mkdir(parents=True, exist_ok=True)
+    if len(sys.argv) < 2:
+        return loop()
+    command = sys.argv[1]
+    if command == "restore":
+        return 0 if restore() else 1
+    if command == "sync-once":
+        try:
+            sync_once()
+            return 0
+        except Exception as exc:
+            write_status("error", f"Shutdown sync failed: {exc}")
+            print(f"Hermes sync: shutdown sync failed: {exc}")
+            return 1
+    if command == "loop":
+        return loop()
+    print(f"Unknown command: {command}", file=sys.stderr)
+    return 1
+if __name__ == "__main__":
+    raise SystemExit(main())

start.sh ADDED Viewed

	@@ -0,0 +1,481 @@

+#!/bin/bash
+set -euo pipefail
+umask 0077
+# ══════════════════════════════════════════════════════════════════════
+# HuggingMes + Hermes WebUI — integrated Hermes Agent stack for HF Spaces
+#   Based on github.com/somratpro/HuggingMes, with Hermes WebUI
+#   (github.com/nesquena/hermes-webui) as the primary UI.
+# ══════════════════════════════════════════════════════════════════════
+APP_DIR="${HUGGINGMES_APP_DIR:-/opt/huggingmes}"
+WEBUI_REPO="${HERMES_WEBUI_REPO:-/opt/hermes-webui}"
+HERMES_HOME="${HERMES_HOME:-/opt/data}"
+PUBLIC_PORT="${PORT:-7861}"
+GATEWAY_API_PORT="${API_SERVER_PORT:-8642}"
+DASHBOARD_PORT="${DASHBOARD_PORT:-9119}"
+TELEGRAM_WEBHOOK_PORT="${TELEGRAM_WEBHOOK_PORT:-8765}"
+WEBUI_PORT="${HERMES_WEBUI_PORT:-8787}"
+SYNC_INTERVAL="${SYNC_INTERVAL:-60}"
+BACKUP_DATASET="${BACKUP_DATASET_NAME:-huggingmes-backup}"
+CF_PROXY_ENV_FILE="/tmp/huggingmes-cloudflare-proxy.env"
+export HERMES_HOME
+export API_SERVER_ENABLED="${API_SERVER_ENABLED:-true}"
+export API_SERVER_HOST="${API_SERVER_HOST:-127.0.0.1}"
+export API_SERVER_PORT="$GATEWAY_API_PORT"
+export GATEWAY_HEALTH_URL="${GATEWAY_HEALTH_URL:-http://127.0.0.1:${GATEWAY_API_PORT}}"
+export TELEGRAM_WEBHOOK_PORT
+export HERMES_WEBUI_PORT="$WEBUI_PORT"
+echo ""
+echo "  ╔══════════════════════════════════════════╗"
+echo "  ║  🪽 HuggingMes + Hermes WebUI Gateway    ║"
+echo "  ╚══════════════════════════════════════════╝"
+echo ""
+# ── Unified auth: GATEWAY_TOKEN drives everything ─────────────────────
+if [ -z "${API_SERVER_KEY:-}" ]; then
+  if [ -n "${GATEWAY_TOKEN:-}" ]; then
+    export API_SERVER_KEY="$GATEWAY_TOKEN"
+  else
+    API_SERVER_KEY="$(python3 - <<'PY'
+import secrets
+print(secrets.token_urlsafe(32))
+PY
+)"
+    export API_SERVER_KEY
+    echo "GATEWAY_TOKEN not set - generated an ephemeral token for this boot."
+  fi
+fi
+# Same token becomes Hermes WebUI's login password (unified auth).
+if [ -n "${GATEWAY_TOKEN:-}" ]; then
+  export HERMES_WEBUI_PASSWORD="${HERMES_WEBUI_PASSWORD:-$GATEWAY_TOKEN}"
+fi
+# ── Setup state dirs ──────────────────────────────────────────────────
+mkdir -p "$HERMES_HOME"/{cron,sessions,logs,hooks,memories,skills,skins,plans,workspace,home,plugins,webui}
+# Rotate on-disk logs at boot. The router + WebUI + dashboard tee their
+# stdout into $HERMES_HOME/logs/*.log via `tee -a`, which means without
+# rotation those files grow forever and end up in the HF Dataset backup.
+# Strategy: if a log is >5MB, rename to .1 (overwriting any previous .1)
+# and start fresh. Cheap, deterministic, no cron needed.
+if [ -d "$HERMES_HOME/logs" ]; then
+  for f in "$HERMES_HOME/logs"/*.log; do
+    [ -f "$f" ] || continue
+    sz=$(stat -c%s "$f" 2>/dev/null || echo 0)
+    if [ "$sz" -gt 5242880 ]; then
+      mv -f "$f" "${f}.1"
+      : > "$f"
+      echo "rotated $(basename "$f") ($sz bytes -> .1)"
+    fi
+  done
+fi
+# Expose hermes CLI to login shells
+mkdir -p "$HERMES_HOME/.local/bin"
+ln -sfn /opt/hermes/.venv/bin/hermes "$HERMES_HOME/.local/bin/hermes"
+# Redirect Hermes plugin dir into volume
+if [ ! -L "${HOME}/.hermes/plugins" ]; then
+  mkdir -p "${HOME}/.hermes"
+  rm -rf "${HOME}/.hermes/plugins"
+  ln -sfn "$HERMES_HOME/plugins" "${HOME}/.hermes/plugins"
+fi
+# ── Restore state from HF Dataset ─────────────────────────────────────
+if [ -n "${HF_TOKEN:-}" ]; then
+  echo "Restoring Hermes state from HF Dataset..."
+  python3 "$APP_DIR/hermes-sync.py" restore || true
+else
+  echo "HF_TOKEN not set - dataset persistence is disabled."
+fi
+# ── Deploy SOUL.md (agent persona) on first boot ─────────────────────
+if [ ! -f "$HERMES_HOME/SOUL.md" ] && [ -f "/opt/huggingmes/SOUL.md" ]; then
+  cp /opt/huggingmes/SOUL.md "$HERMES_HOME/SOUL.md"
+  echo "Deployed SOUL.md from project (first boot)"
+fi
+# ── Cloudflare proxy (optional) ───────────────────────────────────────
+CLOUDFLARE_WORKERS_TOKEN="${CLOUDFLARE_WORKERS_TOKEN:-${CLOUDFLARE_API_TOKEN:-}}"
+export CLOUDFLARE_WORKERS_TOKEN
+if [ -n "${CLOUDFLARE_WORKERS_TOKEN:-}" ] || [ -n "${CLOUDFLARE_PROXY_URL:-}" ]; then
+  export CLOUDFLARE_PROXY_DEBUG="${CLOUDFLARE_PROXY_DEBUG:-false}"
+  echo "Preparing Cloudflare Telegram proxy..."
+  python3 "$APP_DIR/cloudflare-proxy-setup.py" || true
+  if [ -f "$CF_PROXY_ENV_FILE" ]; then
+    . "$CF_PROXY_ENV_FILE"
+  fi
+fi
+if [ -n "${CLOUDFLARE_WORKERS_TOKEN:-}" ]; then
+  echo "Preparing Cloudflare Keepalive worker..."
+  python3 "$APP_DIR/cloudflare-keepalive-setup.py" || true
+fi
+# ── Telegram env normalisation (aliases + webhook URL + secret) ───────
+if [ -n "${TELEGRAM_USER_IDS:-}" ] && [ -z "${TELEGRAM_ALLOWED_USERS:-}" ]; then
+  export TELEGRAM_ALLOWED_USERS="$TELEGRAM_USER_IDS"
+elif [ -n "${TELEGRAM_USER_ID:-}" ] && [ -z "${TELEGRAM_ALLOWED_USERS:-}" ]; then
+  export TELEGRAM_ALLOWED_USERS="$TELEGRAM_USER_ID"
+fi
+if [ -n "${TELEGRAM_BOT_TOKEN:-}" ] && [ -n "${SPACE_HOST:-}" ] && [ -z "${TELEGRAM_WEBHOOK_URL:-}" ]; then
+  if [ "${TELEGRAM_MODE:-webhook}" != "polling" ]; then
+    export TELEGRAM_WEBHOOK_URL="https://${SPACE_HOST}/telegram"
+  fi
+fi
+if [ -n "${TELEGRAM_WEBHOOK_URL:-}" ] && [ -z "${TELEGRAM_WEBHOOK_SECRET:-}" ]; then
+  SECRET_FILE="$HERMES_HOME/.huggingmes-telegram-webhook-secret"
+  if [ -f "$SECRET_FILE" ]; then
+    TELEGRAM_WEBHOOK_SECRET="$(cat "$SECRET_FILE")"
+  else
+    TELEGRAM_WEBHOOK_SECRET="$(python3 - <<'PY'
+import secrets
+print(secrets.token_hex(32))
+PY
+)"
+    printf '%s' "$TELEGRAM_WEBHOOK_SECRET" > "$SECRET_FILE"
+    chmod 600 "$SECRET_FILE"
+  fi
+  export TELEGRAM_WEBHOOK_SECRET
+fi
+# ── Provider-prefix mapping (HuggingMes convention) ───────────────────
+MODEL_INPUT="${HERMES_MODEL:-${LLM_MODEL:-}}"
+MODEL_FOR_CONFIG="$MODEL_INPUT"
+PROVIDER_FOR_CONFIG="${HERMES_INFERENCE_PROVIDER:-auto}"
+LLM_API_KEY="${LLM_API_KEY:-}"
+if [ -n "$MODEL_INPUT" ]; then
+  MODEL_PREFIX="${MODEL_INPUT%%/*}"
+else
+  MODEL_PREFIX=""
+fi
+case "$MODEL_PREFIX" in
+  openrouter)
+    [ -n "$LLM_API_KEY" ] && export OPENROUTER_API_KEY="${OPENROUTER_API_KEY:-$LLM_API_KEY}"
+    [ "$PROVIDER_FOR_CONFIG" = "auto" ] && PROVIDER_FOR_CONFIG="openrouter"
+    MODEL_FOR_CONFIG="${MODEL_INPUT#openrouter/}"
+    ;;
+  huggingface|hf)
+    [ -n "$LLM_API_KEY" ] && export HF_TOKEN="${HF_TOKEN:-$LLM_API_KEY}"
+    [ "$PROVIDER_FOR_CONFIG" = "auto" ] && PROVIDER_FOR_CONFIG="huggingface"
+    MODEL_FOR_CONFIG="${MODEL_INPUT#huggingface/}"
+    ;;
+  vercel-ai-gateway|ai-gateway)
+    [ -n "$LLM_API_KEY" ] && export AI_GATEWAY_API_KEY="${AI_GATEWAY_API_KEY:-$LLM_API_KEY}"
+    [ "$PROVIDER_FOR_CONFIG" = "auto" ] && PROVIDER_FOR_CONFIG="ai-gateway"
+    MODEL_FOR_CONFIG="${MODEL_INPUT#*/}"
+    ;;
+  anthropic)
+    [ -n "$LLM_API_KEY" ] && export ANTHROPIC_API_KEY="${ANTHROPIC_API_KEY:-$LLM_API_KEY}"
+    ;;
+  openai|openai-codex)
+    [ -n "$LLM_API_KEY" ] && export OPENAI_API_KEY="${OPENAI_API_KEY:-$LLM_API_KEY}"
+    ;;
+  google|gemini)
+    [ -n "$LLM_API_KEY" ] && export GOOGLE_API_KEY="${GOOGLE_API_KEY:-$LLM_API_KEY}" GEMINI_API_KEY="${GEMINI_API_KEY:-$LLM_API_KEY}"
+    PROVIDER_FOR_CONFIG="gemini"
+    MODEL_FOR_CONFIG="${MODEL_INPUT#*/}"
+    ;;
+  deepseek)
+    [ -n "$LLM_API_KEY" ] && export DEEPSEEK_API_KEY="${DEEPSEEK_API_KEY:-$LLM_API_KEY}"
+    ;;
+  kimi-coding|moonshot)
+    [ -n "$LLM_API_KEY" ] && export KIMI_API_KEY="${KIMI_API_KEY:-$LLM_API_KEY}"
+    ;;
+  kimi-coding-cn|moonshot-cn|kimi-cn)
+    [ -n "$LLM_API_KEY" ] && export KIMI_CN_API_KEY="${KIMI_CN_API_KEY:-$LLM_API_KEY}"
+    ;;
+  minimax)
+    [ -n "$LLM_API_KEY" ] && export MINIMAX_API_KEY="${MINIMAX_API_KEY:-$LLM_API_KEY}"
+    ;;
+  minimax-cn)
+    [ -n "$LLM_API_KEY" ] && export MINIMAX_CN_API_KEY="${MINIMAX_CN_API_KEY:-$LLM_API_KEY}"
+    ;;
+  xiaomi)
+    [ -n "$LLM_API_KEY" ] && export XIAOMI_API_KEY="${XIAOMI_API_KEY:-$LLM_API_KEY}"
+    ;;
+  zai|z-ai|z.ai|glm)
+    [ -n "$LLM_API_KEY" ] && export GLM_API_KEY="${GLM_API_KEY:-$LLM_API_KEY}"
+    ;;
+  arcee|arcee-ai|arceeai)
+    [ -n "$LLM_API_KEY" ] && export ARCEEAI_API_KEY="${ARCEEAI_API_KEY:-$LLM_API_KEY}"
+    ;;
+  gmi|gmi-cloud|gmicloud)
+    [ -n "$LLM_API_KEY" ] && export GMI_API_KEY="${GMI_API_KEY:-$LLM_API_KEY}"
+    ;;
+  alibaba|alibaba-coding-plan|alibaba_coding)
+    [ -n "$LLM_API_KEY" ] && export DASHSCOPE_API_KEY="${DASHSCOPE_API_KEY:-$LLM_API_KEY}"
+    ;;
+  tencent-tokenhub|tencent|tokenhub|tencentmaas)
+    [ -n "$LLM_API_KEY" ] && export TOKENHUB_API_KEY="${TOKENHUB_API_KEY:-$LLM_API_KEY}"
+    ;;
+  nvidia)
+    [ -n "$LLM_API_KEY" ] && export NVIDIA_API_KEY="${NVIDIA_API_KEY:-$LLM_API_KEY}"
+    ;;
+  xai|grok)
+    [ -n "$LLM_API_KEY" ] && export XAI_API_KEY="${XAI_API_KEY:-$LLM_API_KEY}"
+    ;;
+  kilocode)
+    [ -n "$LLM_API_KEY" ] && export KILOCODE_API_KEY="${KILOCODE_API_KEY:-$LLM_API_KEY}"
+    ;;
+  opencode-zen)
+    [ -n "$LLM_API_KEY" ] && export OPENCODE_ZEN_API_KEY="${OPENCODE_ZEN_API_KEY:-$LLM_API_KEY}"
+    ;;
+  opencode-go)
+    [ -n "$LLM_API_KEY" ] && export OPENCODE_GO_API_KEY="${OPENCODE_GO_API_KEY:-$LLM_API_KEY}"
+    ;;
+esac
+if [ -n "${CUSTOM_BASE_URL:-}" ]; then
+  PROVIDER_FOR_CONFIG="${CUSTOM_PROVIDER:-custom}"
+  [ -n "$LLM_API_KEY" ] && export OPENAI_API_KEY="${OPENAI_API_KEY:-$LLM_API_KEY}"
+fi
+export MODEL_FOR_CONFIG PROVIDER_FOR_CONFIG
+export CUSTOM_BASE_URL="${CUSTOM_BASE_URL:-}"
+export CUSTOM_API_KEY="${CUSTOM_API_KEY:-${LLM_API_KEY:-}}"
+export CUSTOM_MODEL_CONTEXT_LENGTH="${CUSTOM_MODEL_CONTEXT_LENGTH:-131072}"
+export CUSTOM_MODEL_MAX_TOKENS="${CUSTOM_MODEL_MAX_TOKENS:-8192}"
+export TELEGRAM_BASE_URL="${TELEGRAM_BASE_URL:-}"
+export TELEGRAM_BASE_FILE_URL="${TELEGRAM_BASE_FILE_URL:-}"
+if [ -n "${CLOUDFLARE_PROXY_URL:-}" ] && [ -z "$TELEGRAM_BASE_URL" ]; then
+  CLOUDFLARE_PROXY_URL="${CLOUDFLARE_PROXY_URL%/}"
+  export TELEGRAM_BASE_URL="${CLOUDFLARE_PROXY_URL}/bot"
+  export TELEGRAM_BASE_FILE_URL="${CLOUDFLARE_PROXY_URL}/file/bot"
+fi
+# ── Build Hermes config.yaml ──────────────────────────────────────────
+python3 - <<'PY'
+import os
+from pathlib import Path
+import yaml
+home = Path(os.environ["HERMES_HOME"])
+path = home / "config.yaml"
+# Use config.yaml.template as base if config.yaml doesn't exist yet
+template = Path("/opt/huggingmes/config.yaml.template")
+if not path.exists() and template.exists():
+    import shutil
+    shutil.copy2(template, path)
+    print("Initialized config.yaml from template")
+try:
+    config = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+except FileNotFoundError:
+    config = {}
+model_name = os.environ.get("MODEL_FOR_CONFIG", "").strip()
+provider_name = os.environ.get("PROVIDER_FOR_CONFIG", "").strip()
+if model_name:
+    model = config.setdefault("model", {})
+    model["default"] = model_name
+    if provider_name and provider_name != "auto":
+        model["provider"] = provider_name
+    else:
+        model.pop("provider", None)
+else:
+    model = config.get("model", {})
+    print("No LLM_MODEL/HERMES_MODEL set; leaving Hermes model config unchanged.")
+custom_base = os.environ.get("CUSTOM_BASE_URL", "").strip()
+if custom_base and model_name:
+    model.setdefault("base_url", custom_base.rstrip("/"))
+    if os.environ.get("CUSTOM_API_KEY"):
+        model.setdefault("api_key", os.environ["CUSTOM_API_KEY"])
+    try:
+        model.setdefault("context_length", int(os.environ.get("CUSTOM_MODEL_CONTEXT_LENGTH", "131072")))
+        model.setdefault("max_tokens", int(os.environ.get("CUSTOM_MODEL_MAX_TOKENS", "8192")))
+    except ValueError:
+        pass
+config.setdefault("terminal", {}).setdefault("cwd", os.environ.get("MESSAGING_CWD", str(home / "workspace")))
+config.setdefault("compression", {}).setdefault("enabled", True)
+config.setdefault("display", {}).setdefault("background_process_notifications", os.environ.get("HERMES_BACKGROUND_NOTIFICATIONS", "result"))
+config.setdefault("security", {}).setdefault("redact_secrets", True)
+platforms = config.setdefault("platforms", {})
+if os.environ.get("TELEGRAM_BOT_TOKEN"):
+    telegram = platforms.setdefault("telegram", {})
+    telegram.setdefault("enabled", True)
+    extra = telegram.setdefault("extra", {})
+    if os.environ.get("TELEGRAM_BASE_URL"):
+        extra.setdefault("base_url", os.environ["TELEGRAM_BASE_URL"])
+        extra.setdefault("base_file_url", os.environ.get("TELEGRAM_BASE_FILE_URL") or os.environ["TELEGRAM_BASE_URL"])
+    if os.environ.get("TELEGRAM_ALLOWED_USERS"):
+        config.setdefault("telegram", {}).setdefault("allow_from", [
+            item.strip()
+            for item in os.environ["TELEGRAM_ALLOWED_USERS"].split(",")
+            if item.strip()
+        ])
+# ── Expand ${VAR} references in MCP server URLs and headers ───────────
+import re
+import json
+def _expand_env_in_obj(obj):
+    """Recursively expand ${VAR} references using os.environ."""
+    if isinstance(obj, str):
+        def _replace(m):
+            key = m.group(1)
+            return os.environ.get(key, m.group(0))  # keep ${VAR} if env not set
+        return re.sub(r'\$\{([A-Z0-9_]+)\}', _replace, obj)
+    elif isinstance(obj, dict):
+        return {k: _expand_env_in_obj(v) for k, v in obj.items()}
+    elif isinstance(obj, list):
+        return [_expand_env_in_obj(v) for v in obj]
+    return obj
+mcp = config.get("mcp_servers")
+if mcp:
+    config["mcp_servers"] = _expand_env_in_obj(mcp)
+    print(f"Expanded env vars in {len(mcp)} MCP server(s)")
+path.write_text(yaml.safe_dump(config, sort_keys=False), encoding="utf-8")
+path.chmod(0o600)
+PY
+# ── Startup summary ───────────────────────────────────────────────────
+echo ""
+echo "Primary UI : ${PRIMARY_UI:-webui}"
+echo "Model      : ${MODEL_FOR_CONFIG:-unset}"
+echo "Provider   : ${PROVIDER_FOR_CONFIG:-unset}"
+if [ -n "${TELEGRAM_BOT_TOKEN:-}" ]; then
+  echo "Telegram   : enabled"
+else
+  echo "Telegram   : not configured"
+fi
+if [ -n "${HF_TOKEN:-}" ]; then
+  echo "Backup     : ${BACKUP_DATASET} (poll ${SYNC_POLL_INTERVAL:-2}s, debounce ${SYNC_DEBOUNCE_SECONDS:-3}s, max ${SYNC_INTERVAL:-60}s)"
+else
+  echo "Backup     : disabled"
+fi
+if [ -n "${CLOUDFLARE_PROXY_URL:-}" ]; then
+  echo "CF Proxy   : ${CLOUDFLARE_PROXY_URL}"
+fi
+echo "Router     : 0.0.0.0:${PUBLIC_PORT}"
+echo "WebUI      : 127.0.0.1:${WEBUI_PORT}"
+echo "Gateway    : 127.0.0.1:${GATEWAY_API_PORT}"
+echo "Dashboard  : 127.0.0.1:${DASHBOARD_PORT}"
+echo ""
+# ── Graceful shutdown ─────────────────────────────────────────────────
+graceful_shutdown() {
+  echo "Shutting down..."
+  if [ -n "${HF_TOKEN:-}" ]; then
+    python3 "$APP_DIR/hermes-sync.py" sync-once || echo "Warning: shutdown sync failed."
+  fi
+  kill $(jobs -p) 2>/dev/null || true
+  exit 0
+}
+trap graceful_shutdown SIGTERM SIGINT
+# ── Start the public-facing router (port 7861) ────────────────────────
+node "$APP_DIR/health-server.js" &
+HEALTH_PID=$!
+if [ -n "${WEBHOOK_URL:-}" ]; then
+  python3 - <<'PY' >/dev/null 2>&1 &
+import json, os, urllib.request
+body = json.dumps({
+    "event": "restart",
+    "status": "success",
+    "message": "HuggingMes + Hermes WebUI has started.",
+    "model": os.environ.get("MODEL_FOR_CONFIG", ""),
+}).encode()
+req = urllib.request.Request(os.environ["WEBHOOK_URL"], data=body, method="POST",
+                             headers={"Content-Type": "application/json"})
+urllib.request.urlopen(req, timeout=10).read()
+PY
+fi
+# ── Launch Hermes dashboard (private; proxied via /hm/app) ────────────
+echo "Launching Hermes dashboard on 127.0.0.1:${DASHBOARD_PORT}..."
+(hermes dashboard --host 127.0.0.1 --insecure 2>&1 | tee -a "$HERMES_HOME/logs/dashboard.log") &
+DASHBOARD_PID=$!
+# ── Launch Hermes gateway ─────────────────────────────────────────────
+echo "Launching Hermes gateway..."
+(hermes gateway run 2>&1 | tee -a "$HERMES_HOME/logs/gateway.log") &
+GATEWAY_PID=$!
+GATEWAY_READY_TIMEOUT="${GATEWAY_READY_TIMEOUT:-120}"
+ready=false
+for ((i=0; i<GATEWAY_READY_TIMEOUT; i++)); do
+  if (echo > "/dev/tcp/127.0.0.1/${GATEWAY_API_PORT}") 2>/dev/null; then
+    ready=true
+    break
+  fi
+  if ! kill -0 "$GATEWAY_PID" 2>/dev/null; then
+    break
+  fi
+  sleep 1
+done
+if [ "$ready" != "true" ]; then
+  echo ""
+  echo "Hermes gateway failed to expose the API health port. Last 40 log lines:"
+  echo "----------------------------------------"
+  tail -40 "$HERMES_HOME/logs/gateway.log" || true
+  exit 1
+fi
+# ── Launch Hermes WebUI (nesquena/hermes-webui) ───────────────────────
+# Points WebUI at the already-running Hermes agent venv and persists state
+# under $HERMES_HOME/webui so hermes-sync.py backs it up.
+export HERMES_WEBUI_AGENT_DIR="/opt/hermes"
+export HERMES_WEBUI_PYTHON="/opt/hermes/.venv/bin/python"
+export HERMES_WEBUI_HOST="127.0.0.1"
+export HERMES_WEBUI_PORT
+export HERMES_WEBUI_STATE_DIR="${HERMES_WEBUI_STATE_DIR:-$HERMES_HOME/webui}"
+export HERMES_WEBUI_DEFAULT_WORKSPACE="${HERMES_WEBUI_DEFAULT_WORKSPACE:-$HERMES_HOME/workspace}"
+export HERMES_WEBUI_AUTO_INSTALL="0"
+mkdir -p "$HERMES_WEBUI_STATE_DIR"
+echo "Launching Hermes WebUI on 127.0.0.1:${WEBUI_PORT}..."
+(cd "$WEBUI_REPO" && \
+   "$HERMES_WEBUI_PYTHON" "$WEBUI_REPO/server.py" 2>&1 | \
+   tee -a "$HERMES_HOME/logs/webui.log") &
+WEBUI_PID=$!
+# Wait for WebUI to bind its port (non-fatal on timeout — router handles it)
+WEBUI_READY_TIMEOUT="${WEBUI_READY_TIMEOUT:-60}"
+for ((i=0; i<WEBUI_READY_TIMEOUT; i++)); do
+  if (echo > "/dev/tcp/127.0.0.1/${WEBUI_PORT}") 2>/dev/null; then
+    echo "Hermes WebUI is up."
+    break
+  fi
+  if ! kill -0 "$WEBUI_PID" 2>/dev/null; then
+    echo "Warning: Hermes WebUI exited during startup. Last 20 log lines:"
+    tail -20 "$HERMES_HOME/logs/webui.log" || true
+    break
+  fi
+  sleep 1
+done
+# ── Periodic backup loop ──────────────────────────────────────────────
+if [ -n "${HF_TOKEN:-}" ]; then
+  python3 -u "$APP_DIR/hermes-sync.py" loop &
+fi
+# ── Wait on the gateway (primary supervision target) ──────────────────
+wait "$GATEWAY_PID"
+if [ -n "${HF_TOKEN:-}" ]; then
+  echo "Gateway exited - syncing state before shutdown..."
+  python3 "$APP_DIR/hermes-sync.py" sync-once || echo "Warning: final sync failed."
+fi