Add HuggingMess Hermes Space wrapper

.dockerignore

@@ -0,0 +1,8 @@
+.git
+.DS_Store
+__pycache__
+*.pyc
+node_modules
+.env
+venv
+.venv

.gitignore

@@ -0,0 +1,8 @@
+.DS_Store
+__pycache__/
+*.py[cod]
+.env
+.venv/
+venv/
+node_modules/
+.cache/

CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0 - 2026-05-03
+
+- Initial HuggingMess Docker Space wrapper for Nous Research Hermes Agent.
+- Added HF Space dashboard, `/health`, `/status`, `/v1/*` proxy, and Telegram webhook proxy.
+- Added Cloudflare Worker setup for Telegram Bot API base URL proxying.
+- Added private HF Dataset backup and restore for Hermes state.
+- Added UptimeRobot monitor setup.

CODE_OF_CONDUCT.md

@@ -0,0 +1,5 @@
+# Code of Conduct
+
+Be respectful, practical, and kind. This project exists to make self-hosting Hermes on Hugging Face Spaces easier for people with different levels of infrastructure experience.
+
+Harassment, abuse, and deliberately unsafe guidance are not welcome.

CONTRIBUTING.md

@@ -0,0 +1,25 @@
+# Contributing
+
+Thanks for improving HuggingMess.
+
+## Local Checks
+
+Run these before submitting changes:
+
+```bash
+bash -n start.sh setup-uptimerobot.sh
+node --check health-server.js
+python3 -m py_compile hermes-sync.py cloudflare-proxy-setup.py
+```
+
+If Docker is available:
+
+```bash
+docker compose up --build
+```
+
+## Notes
+
+- Keep the wrapper thin; prefer the official `nousresearch/hermes-agent` image for Hermes itself.
+- Avoid committing secrets or generated `/opt/data` state.
+- Preserve Hugging Face Space metadata in `README.md`.

Dockerfile

@@ -0,0 +1,37 @@
+# HuggingMess - Hermes Agent Gateway for Hugging Face Spaces
+
+ARG HERMES_AGENT_VERSION=latest
+FROM nousresearch/hermes-agent:${HERMES_AGENT_VERSION}
+
+USER root
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ca-certificates \
+    curl \
+    jq \
+    && rm -rf /var/lib/apt/lists/* \
+    && uv pip install --python /opt/hermes/.venv/bin/python --no-cache-dir huggingface_hub
+
+COPY --chown=hermes:hermes start.sh /opt/huggingmess/start.sh
+COPY --chown=hermes:hermes health-server.js /opt/huggingmess/health-server.js
+COPY --chown=hermes:hermes hermes-sync.py /opt/huggingmess/hermes-sync.py
+COPY --chown=hermes:hermes cloudflare-proxy-setup.py /opt/huggingmess/cloudflare-proxy-setup.py
+COPY --chown=hermes:hermes setup-uptimerobot.sh /opt/huggingmess/setup-uptimerobot.sh
+
+RUN chmod +x \
+    /opt/huggingmess/start.sh \
+    /opt/huggingmess/hermes-sync.py \
+    /opt/huggingmess/cloudflare-proxy-setup.py \
+    /opt/huggingmess/setup-uptimerobot.sh
+
+ENV HERMES_HOME=/opt/data \
+    HUGGINGMESS_APP_DIR=/opt/huggingmess \
+    HERMES_AGENT_VERSION=${HERMES_AGENT_VERSION} \
+    PYTHONUNBUFFERED=1
+
+EXPOSE 7861
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=90s \
+  CMD curl -fsS http://localhost:7861/health || exit 1
+
+CMD ["/opt/huggingmess/start.sh"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Somrat
+
+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

@@ -1,11 +1,146 @@
 ---
 title: HuggingMess
 emoji: 📚
-colorFrom: red
-colorTo: blue
+colorFrom: blue
+colorTo: indigo
 sdk: docker
-pinned: false
-short_description: Run Harmess agent for free on HuggingFace Space
+app_port: 7861
+pinned: true
+license: mit
+secrets:
+  - name: LLM_API_KEY
+    description: "Your LLM provider API key. HuggingMess maps it to the right Hermes provider env var."
+  - name: LLM_MODEL
+    description: "Model ID, e.g. openrouter/anthropic/claude-sonnet-4 or anthropic/claude-opus-4.6."
+  - name: TELEGRAM_BOT_TOKEN
+    description: "Telegram bot token from @BotFather."
+  - name: TELEGRAM_ALLOWED_USERS
+    description: "Comma-separated numeric Telegram user IDs allowed to use the bot."
+  - name: GATEWAY_TOKEN
+    description: "Bearer token for the proxied Hermes API routes."
+  - name: HF_TOKEN
+    description: "Hugging Face token with write access for private Dataset backup."
+  - name: CLOUDFLARE_WORKERS_TOKEN
+    description: "Cloudflare API token for automatic Worker proxy setup."
+  - name: UPTIMEROBOT_API_KEY
+    description: "UptimeRobot Main API key for automatic keep-awake monitor setup."
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# HuggingMess
+
+HuggingMess runs [Nous Research Hermes Agent](https://github.com/NousResearch/hermes-agent) as a Hugging Face Docker Space. It follows the same practical shape as HuggingClaw: one public Space port, Telegram gateway support, Cloudflare Worker proxy setup, UptimeRobot keep-awake, and private HF Dataset backup for Hermes state.
+
+## Quick Start
+
+1. Duplicate this Space or push this folder to a new Docker Space.
+2. Add these secrets in Space Settings:
+
+| Secret | Required | Notes |
+| :--- | :--- | :--- |
+| `LLM_MODEL` | Yes | Examples: `openrouter/anthropic/claude-sonnet-4`, `anthropic/claude-opus-4.6`, `google/gemini-2.5-flash` |
+| `LLM_API_KEY` | Usually | Used to populate the provider-specific env var automatically |
+| `TELEGRAM_BOT_TOKEN` | For Telegram | Bot token from BotFather |
+| `TELEGRAM_ALLOWED_USERS` | Recommended | Comma-separated numeric Telegram user IDs |
+| `GATEWAY_TOKEN` | Recommended | Bearer token for `/v1/*` API routes |
+| `HF_TOKEN` | Optional | Enables private Dataset backup named `huggingmess-backup` |
+| `CLOUDFLARE_WORKERS_TOKEN` | Optional | Auto-creates a Worker proxy for Telegram Bot API traffic |
+| `UPTIMEROBOT_API_KEY` | Optional | Auto-creates a monitor for `/health` |
+
+## Telegram on HF Spaces
+
+When `TELEGRAM_BOT_TOKEN` and `SPACE_HOST` are present, HuggingMess defaults Telegram to webhook mode:
+
+```bash
+TELEGRAM_WEBHOOK_URL=https://your-space.hf.space/telegram
+TELEGRAM_WEBHOOK_PORT=8765
+```
+
+If you need polling instead, set:
+
+```bash
+TELEGRAM_MODE=polling
+```
+
+Hermes requires numeric Telegram IDs for allowlists. You can use either Hermes-native `TELEGRAM_ALLOWED_USERS` or the HuggingClaw-style aliases `TELEGRAM_USER_ID` / `TELEGRAM_USER_IDS`.
+
+## Cloudflare Proxy
+
+Hugging Face Spaces can be restrictive for outbound bot API traffic. Add `CLOUDFLARE_WORKERS_TOKEN`, and HuggingMess will:
+
+1. create a Cloudflare Worker,
+2. generate a shared proxy secret,
+3. set Hermes Telegram `base_url` to `https://worker.example.workers.dev/bot`,
+4. set `base_file_url` to `https://worker.example.workers.dev/file/bot`.
+
+Manual mode is also supported:
+
+```bash
+CLOUDFLARE_PROXY_URL=https://your-worker.workers.dev
+CLOUDFLARE_PROXY_SECRET=optional-shared-secret
+```
+
+The manual Worker source is included in `cloudflare-worker.js`.
+
+## Backup
+
+Set `HF_TOKEN` with write access to enable backup. HuggingMess syncs `/opt/data` to a private Dataset named `huggingmess-backup` every 180 seconds by default.
+
+| Variable | Default | Description |
+| :--- | :--- | :--- |
+| `BACKUP_DATASET_NAME` | `huggingmess-backup` | Dataset name under your HF account |
+| `SYNC_INTERVAL` | `180` | Backup interval in seconds |
+| `SYNC_INCLUDE_ENV` | `false` | Include `/opt/data/.env` in backup |
+
+By default `.env` is excluded from backups because HF Space secrets are already injected at runtime.
+
+## Keep Awake
+
+Add `UPTIMEROBOT_API_KEY`, and HuggingMess creates or reuses a monitor for:
+
+```text
+https://your-space.hf.space/health
+```
+
+Optional UptimeRobot variables:
+
+| Variable | Default | Description |
+| :--- | :--- | :--- |
+| `UPTIMEROBOT_MONITOR_NAME` | `HuggingMess <space>` | Friendly monitor name |
+| `UPTIMEROBOT_INTERVAL` | `300` | Monitor interval in seconds |
+| `UPTIMEROBOT_ALERT_CONTACTS` | unset | Dash-separated alert contact IDs |
+
+## Local Development
+
+```bash
+docker compose up --build
+```
+
+Then open:
+
+```text
+http://localhost:7861
+```
+
+## Useful Routes
+
+| Route | Purpose |
+| :--- | :--- |
+| `/` | HuggingMess dashboard |
+| `/health` | Health check for HF and UptimeRobot |
+| `/status` | JSON status |
+| `/dashboard/` | Proxied Hermes dashboard |
+| `/v1/models` | Proxied Hermes OpenAI-compatible API server |
+| `/telegram` | Telegram webhook endpoint |
+
+The `/v1/*` routes require:
+
+```text
+Authorization: Bearer <GATEWAY_TOKEN>
+```
+
+## Links
+
+- [Hermes Agent GitHub](https://github.com/NousResearch/hermes-agent)
+- [Hermes Agent Docs](https://hermes-agent.nousresearch.com/docs)
+- [Hermes Docker Docs](https://hermes-agent.nousresearch.com/docs/user-guide/docker/)
+- [Hermes Telegram Docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram)

SECURITY.md

@@ -0,0 +1,14 @@
+# Security
+
+HuggingMess runs a full agent gateway with tool access. Treat the Space and its secrets like a server.
+
+## Required Hardening
+
+- Set `GATEWAY_TOKEN`; `/v1/*` routes require `Authorization: Bearer <GATEWAY_TOKEN>`.
+- Set `TELEGRAM_ALLOWED_USERS` to numeric Telegram user IDs.
+- Keep your HF Dataset backup private.
+- Do not enable `SYNC_INCLUDE_ENV=true` unless you intentionally want `/opt/data/.env` backed up.
+
+## Reporting
+
+Open a private issue or contact the maintainer directly with reproduction steps and affected configuration.

cloudflare-proxy-setup.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+"""Create or reuse a Cloudflare Worker that proxies Telegram Bot API calls."""
+
+import json
+import os
+import re
+import secrets
+import sys
+import urllib.request
+from pathlib import Path
+
+API_BASE = "https://api.cloudflare.com/client/v4"
+ENV_FILE = Path("/tmp/huggingmess-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 "huggingmess-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 "huggingmess-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 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)
+        return 0
+
+    if not api_token:
+        return 0
+
+    try:
+        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.")
+
+        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())

cloudflare-worker.js

@@ -0,0 +1,78 @@
+addEventListener("fetch", (event) => {
+  event.respondWith(handleRequest(event.request));
+});
+
+const PROXY_SHARED_SECRET = "";
+const ALLOW_PROXY_ALL = false;
+const ALLOWED_TARGETS = [
+  "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",
+];
+
+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;
+  const telegramStylePath = url.pathname.startsWith("/bot") || url.pathname.startsWith("/file/bot");
+
+  if (PROXY_SHARED_SECRET) {
+    const providedSecret = request.headers.get("x-proxy-key") || url.searchParams.get("proxy_key") || "";
+    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 (telegramStylePath) {
+    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 });
+  }
+}

docker-compose.yml

@@ -0,0 +1,22 @@
+services:
+  huggingmess:
+    build:
+      context: .
+      args:
+        HERMES_AGENT_VERSION: ${HERMES_AGENT_VERSION:-latest}
+    image: huggingmess:local
+    ports:
+      - "7861:7861"
+    environment:
+      LLM_MODEL: ${LLM_MODEL:-openrouter/anthropic/claude-sonnet-4}
+      LLM_API_KEY: ${LLM_API_KEY:-}
+      GATEWAY_TOKEN: ${GATEWAY_TOKEN:-local-dev-token}
+      TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN:-}
+      TELEGRAM_ALLOWED_USERS: ${TELEGRAM_ALLOWED_USERS:-}
+      HF_TOKEN: ${HF_TOKEN:-}
+      SPACE_HOST: ${SPACE_HOST:-localhost:7861}
+    volumes:
+      - huggingmess-data:/opt/data
+
+volumes:
+  huggingmess-data:

health-server.js

@@ -0,0 +1,231 @@
+"use strict";
+
+const http = require("http");
+const fs = require("fs");
+const net = require("net");
+
+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 GATEWAY_HOST = "127.0.0.1";
+const startTime = Date.now();
+const API_SERVER_KEY = process.env.API_SERVER_KEY || "";
+
+const SYNC_STATUS_FILE = "/tmp/huggingmess-sync-status.json";
+const UPTIMEROBOT_STATUS_FILE = "/tmp/huggingmess-uptimerobot-status.json";
+
+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 proxyRequest(req, res, targetPort, rewritePath = (path) => path) {
+  const parsed = new URL(req.url, "http://localhost");
+  const targetPath = rewritePath(parsed.pathname) + parsed.search;
+  const headers = {
+    ...req.headers,
+    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 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 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 is enabled; waiting for the first sync." }
+    : { status: "disabled", message: "HF_TOKEN is not configured." });
+
+  return {
+    ok: gateway,
+    uptime: formatUptime(Date.now() - startTime),
+    gateway,
+    dashboard,
+    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,
+    uptimerobot: readJson(UPTIMEROBOT_STATUS_FILE, null),
+  };
+}
+
+function badge(label, state) {
+  const cls = state ? "ok" : "off";
+  return `<span class="badge ${cls}">${label}</span>`;
+}
+
+function renderDashboard(data) {
+  const syncStatus = String(data.backup?.status || "unknown").toUpperCase();
+  const dashboardLink = data.dashboard ? `<a class="button" href="/dashboard/">Open Hermes Dashboard</a>` : "";
+  const apiLink = data.gateway ? `<a class="button secondary" href="/v1/models">API Models</a>` : "";
+  const keepAlive = data.uptimerobot?.configured
+    ? `UptimeRobot is monitoring <code>${data.uptimerobot.url}</code>.`
+    : process.env.UPTIMEROBOT_API_KEY
+      ? "UptimeRobot setup is pending or failed; check logs."
+      : "Add UPTIMEROBOT_API_KEY to create a keep-awake monitor.";
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>HuggingMess</title>
+  <style>
+    :root { color-scheme: dark; --bg:#10141f; --panel:#171d2b; --line:#293246; --text:#f4f7fb; --muted:#9aa7bd; --good:#22c55e; --warn:#f59e0b; --bad:#ef4444; --accent:#38bdf8; }
+    * { 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); }
+    main { width:min(960px, calc(100% - 32px)); margin:0 auto; padding:36px 0; }
+    header { display:flex; justify-content:space-between; gap:16px; align-items:flex-start; margin-bottom:28px; }
+    h1 { margin:0; font-size:clamp(2rem, 6vw, 4.4rem); line-height:.95; letter-spacing:0; }
+    .subtitle { margin-top:12px; color:var(--muted); max-width:620px; line-height:1.5; }
+    .grid { display:grid; grid-template-columns:repeat(2, minmax(0, 1fr)); gap:14px; }
+    .card { border:1px solid var(--line); background:var(--panel); border-radius:8px; padding:18px; min-height:120px; }
+    .wide { grid-column:1 / -1; }
+    .label { color:var(--muted); font-size:.78rem; letter-spacing:.08em; text-transform:uppercase; margin-bottom:10px; }
+    .value { font-size:1.05rem; overflow-wrap:anywhere; }
+    code { background:#0b0f18; border:1px solid var(--line); border-radius:6px; padding:2px 6px; }
+    .row { display:flex; flex-wrap:wrap; gap:10px; align-items:center; }
+    .badge { display:inline-flex; border:1px solid var(--line); border-radius:999px; padding:5px 10px; font-size:.8rem; font-weight:700; }
+    .badge.ok { color:var(--good); border-color:rgba(34,197,94,.35); background:rgba(34,197,94,.08); }
+    .badge.off { color:var(--bad); border-color:rgba(239,68,68,.35); background:rgba(239,68,68,.08); }
+    .button { display:inline-flex; align-items:center; justify-content:center; min-height:42px; padding:0 14px; border-radius:7px; color:#07111f; background:var(--accent); text-decoration:none; font-weight:750; }
+    .button.secondary { color:var(--text); background:#222b3c; border:1px solid var(--line); }
+    @media (max-width: 720px) { header { display:block; } .grid { grid-template-columns:1fr; } }
+  </style>
+</head>
+<body>
+  <main>
+    <header>
+      <div>
+        <h1>HuggingMess</h1>
+        <div class="subtitle">Hermes Agent running as an always-on Hugging Face Docker Space, with Telegram gateway, state backup, Cloudflare proxy support, and keep-awake monitoring.</div>
+      </div>
+      <div class="row">${badge("Gateway", data.gateway)}${badge("Dashboard", data.dashboard)}${badge("Backup", data.backup?.status !== "disabled")}</div>
+    </header>
+    <section class="grid">
+      <div class="card"><div class="label">Uptime</div><div class="value">${data.uptime}</div></div>
+      <div class="card"><div class="label">Model</div><div class="value"><code>${data.model || "not set"}</code></div></div>
+      <div class="card"><div class="label">Provider</div><div class="value"><code>${data.provider}</code></div></div>
+      <div class="card"><div class="label">Telegram</div><div class="value">${data.telegram.configured ? "Configured" : "Not configured"}${data.telegram.webhook ? " via webhook" : ""}</div></div>
+      <div class="card wide"><div class="label">Backup</div><div class="value"><strong>${syncStatus}</strong><br>${data.backup?.message || ""}</div></div>
+      <div class="card wide"><div class="label">Keep Awake</div><div class="value">${keepAlive}</div></div>
+      <div class="card wide"><div class="label">Entrypoints</div><div class="row">${dashboardLink}${apiLink}<a class="button secondary" href="/status">Status JSON</a></div></div>
+    </section>
+  </main>
+</body>
+</html>`;
+}
+
+const server = http.createServer(async (req, res) => {
+  const parsed = new URL(req.url, "http://localhost");
+  const path = parsed.pathname;
+
+  if (path === "/health" || path === "/dashboard/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, uptime: data.uptime }));
+    return;
+  }
+
+  if (path === "/status" || path === "/dashboard/status") {
+    const data = await statusPayload();
+    res.writeHead(200, { "content-type": "application/json" });
+    res.end(JSON.stringify(data, null, 2));
+    return;
+  }
+
+  if (path === "/" || path === "/dashboard") {
+    const data = await statusPayload();
+    res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+    res.end(renderDashboard(data));
+    return;
+  }
+
+  if (path === "/telegram" || path.startsWith("/telegram/")) {
+    proxyRequest(req, res, TELEGRAM_WEBHOOK_PORT);
+    return;
+  }
+
+  if (path === "/dashboard/" || path.startsWith("/dashboard/")) {
+    proxyRequest(req, res, DASHBOARD_PORT, (p) => p.replace(/^\/dashboard/, "") || "/");
+    return;
+  }
+
+  if (path === "/v1" || path.startsWith("/v1/")) {
+    if (API_SERVER_KEY) {
+      const expected = `Bearer ${API_SERVER_KEY}`;
+      if (req.headers.authorization !== expected) {
+        res.writeHead(401, { "content-type": "application/json" });
+        res.end(JSON.stringify({ error: "unauthorized", message: "Use Authorization: Bearer <GATEWAY_TOKEN>." }));
+        return;
+      }
+    }
+    proxyRequest(req, res, GATEWAY_PORT);
+    return;
+  }
+
+  res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+  res.end("Not found");
+});
+
+server.listen(PORT, "0.0.0.0", () => {
+  console.log(`HuggingMess dashboard listening on 0.0.0.0:${PORT}`);
+});

hermes-sync.py

@@ -0,0 +1,303 @@
+#!/usr/bin/env python3
+"""HuggingMess Hermes state backup via Hugging Face Datasets."""
+
+import hashlib
+import json
+import logging
+import os
+import shutil
+import signal
+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")
+
+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/huggingmess-sync-status.json")
+INTERVAL = int(os.environ.get("SYNC_INTERVAL", "180"))
+INITIAL_DELAY = int(os.environ.get("SYNC_START_DELAY", "10"))
+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", "huggingmess-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",
+}
+EXCLUDED_TOP_LEVEL = {"logs"}
+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
+
+
+def write_status(status: str, message: str) -> None:
+    payload = {
+        "status": status,
+        "message": message,
+        "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+    }
+    tmp_path = STATUS_FILE.with_suffix(".tmp")
+    tmp_path.write_text(json.dumps(payload), encoding="utf-8")
+    tmp_path.replace(STATUS_FILE)
+
+
+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():
+        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="huggingmess-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)
+        shutil.copy2(path, target)
+    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 not HF_TOKEN:
+        write_status("disabled", "HF_TOKEN is not configured.")
+        return (last_fingerprint or "", last_marker or (0, 0, 0))
+
+    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.")
+        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.")
+        return (last_fingerprint, current_marker)
+
+    write_status("syncing", f"Uploading Hermes state to {repo_id}")
+    snapshot_dir = create_snapshot_dir(HERMES_HOME)
+    try:
+        try:
+            HF_API.upload_large_folder(
+                repo_id=repo_id,
+                repo_type="dataset",
+                folder_path=str(snapshot_dir),
+                num_workers=2,
+                print_report=False,
+            )
+        except AttributeError:
+            upload_folder(
+                folder_path=str(snapshot_dir),
+                repo_id=repo_id,
+                repo_type="dataset",
+                token=HF_TOKEN,
+                commit_message=f"HuggingMess sync {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}")
+    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 loop active for {repo_id} with {INTERVAL}s interval.")
+    except Exception as exc:
+        write_status("error", str(exc))
+        print(f"Hermes sync error: {exc}")
+        return 1
+
+    last_fingerprint = fingerprint_dir(HERMES_HOME)
+    last_marker = metadata_marker(HERMES_HOME)
+    time.sleep(INITIAL_DELAY)
+    print(f"Hermes state sync started: every {INTERVAL}s -> {repo_id}")
+
+    while not STOP_EVENT.is_set():
+        try:
+            last_fingerprint, last_marker = sync_once(last_fingerprint, last_marker)
+        except Exception as exc:
+            write_status("error", f"Sync failed: {exc}")
+            print(f"Hermes sync failed: {exc}")
+        if STOP_EVENT.wait(INTERVAL):
+            break
+    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())

setup-uptimerobot.sh

@@ -0,0 +1,73 @@
+#!/bin/bash
+set -euo pipefail
+
+API_URL="https://api.uptimerobot.com/v2"
+API_KEY="${UPTIMEROBOT_API_KEY:-}"
+SPACE_HOST_INPUT="${1:-${SPACE_HOST:-}}"
+STATUS_FILE="/tmp/huggingmess-uptimerobot-status.json"
+
+if [ -z "$API_KEY" ]; then
+  echo "Missing UPTIMEROBOT_API_KEY."
+  exit 1
+fi
+
+if [ -z "$SPACE_HOST_INPUT" ]; then
+  echo "Missing Space host."
+  exit 1
+fi
+
+SPACE_HOST_CLEAN="${SPACE_HOST_INPUT#https://}"
+SPACE_HOST_CLEAN="${SPACE_HOST_CLEAN#http://}"
+SPACE_HOST_CLEAN="${SPACE_HOST_CLEAN%%/*}"
+MONITOR_URL="https://${SPACE_HOST_CLEAN}/health"
+MONITOR_NAME="${UPTIMEROBOT_MONITOR_NAME:-HuggingMess ${SPACE_HOST_CLEAN}}"
+INTERVAL="${UPTIMEROBOT_INTERVAL:-300}"
+
+MONITORS_RESPONSE=$(curl -sS -X POST "${API_URL}/getMonitors" \
+  -d "api_key=${API_KEY}" \
+  -d "format=json" \
+  -d "logs=0" \
+  -d "response_times=0" \
+  -d "response_times_limit=1")
+
+MONITOR_ID=$(printf '%s' "$MONITORS_RESPONSE" | jq -r --arg url "$MONITOR_URL" '
+  (.monitors // []) | map(select(.url == $url)) | first | .id // empty
+')
+
+if [ -n "$MONITOR_ID" ]; then
+  printf '{"configured":true,"monitorId":"%s","url":"%s","alreadyExisted":true,"timestamp":"%s"}\n' \
+    "$MONITOR_ID" "$MONITOR_URL" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$STATUS_FILE"
+  echo "UptimeRobot monitor already exists for ${MONITOR_URL}"
+  exit 0
+fi
+
+CURL_ARGS=(
+  -sS
+  -X POST "${API_URL}/newMonitor"
+  -d "api_key=${API_KEY}"
+  -d "format=json"
+  -d "type=1"
+  -d "friendly_name=${MONITOR_NAME}"
+  -d "url=${MONITOR_URL}"
+  -d "interval=${INTERVAL}"
+)
+
+if [ -n "${UPTIMEROBOT_ALERT_CONTACTS:-}" ]; then
+  CURL_ARGS+=(-d "alert_contacts=${UPTIMEROBOT_ALERT_CONTACTS}")
+fi
+
+CREATE_RESPONSE=$(curl "${CURL_ARGS[@]}")
+CREATE_STATUS=$(printf '%s' "$CREATE_RESPONSE" | jq -r '.stat // "fail"')
+
+if [ "$CREATE_STATUS" != "ok" ]; then
+  printf '{"configured":false,"error":"creation failed","timestamp":"%s"}\n' \
+    "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$STATUS_FILE"
+  echo "Failed to create UptimeRobot monitor."
+  printf '%s\n' "$CREATE_RESPONSE"
+  exit 1
+fi
+
+NEW_ID=$(printf '%s' "$CREATE_RESPONSE" | jq -r '.monitor.id // empty')
+printf '{"configured":true,"monitorId":"%s","url":"%s","timestamp":"%s"}\n' \
+  "${NEW_ID:-}" "$MONITOR_URL" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$STATUS_FILE"
+echo "Created UptimeRobot monitor ${NEW_ID:-"(id unavailable)"} for ${MONITOR_URL}"

start.sh

@@ -0,0 +1,329 @@
+#!/bin/bash
+set -euo pipefail
+
+umask 0077
+
+APP_DIR="${HUGGINGMESS_APP_DIR:-/opt/huggingmess}"
+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}"
+SYNC_INTERVAL="${SYNC_INTERVAL:-180}"
+BACKUP_DATASET="${BACKUP_DATASET_NAME:-huggingmess-backup}"
+CF_PROXY_ENV_FILE="/tmp/huggingmess-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
+
+if [ -z "${API_SERVER_KEY:-}" ]; then
+  if [ -n "${GATEWAY_TOKEN:-}" ]; then
+    export API_SERVER_KEY="$GATEWAY_TOKEN"
+  else
+    API_SERVER_KEY="$(python - <<'PY'
+import secrets
+print(secrets.token_urlsafe(32))
+PY
+)"
+    export API_SERVER_KEY
+    echo "GATEWAY_TOKEN not set - generated an ephemeral API token for this boot."
+  fi
+fi
+
+echo ""
+echo "  =========================================="
+echo "           HuggingMess Hermes Gateway"
+echo "  =========================================="
+echo ""
+
+mkdir -p "$HERMES_HOME"/{cron,sessions,logs,hooks,memories,skills,skins,plans,workspace,home}
+
+if [ -n "${HF_TOKEN:-}" ]; then
+  echo "Restoring Hermes state from HF Dataset..."
+  python "$APP_DIR/hermes-sync.py" restore || true
+else
+  echo "HF_TOKEN not set - dataset persistence is disabled."
+fi
+
+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..."
+  python "$APP_DIR/cloudflare-proxy-setup.py" || true
+  if [ -f "$CF_PROXY_ENV_FILE" ]; then
+    . "$CF_PROXY_ENV_FILE"
+  fi
+fi
+
+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/.huggingmess-telegram-webhook-secret"
+  if [ -f "$SECRET_FILE" ]; then
+    export TELEGRAM_WEBHOOK_SECRET
+    TELEGRAM_WEBHOOK_SECRET="$(cat "$SECRET_FILE")"
+  else
+    TELEGRAM_WEBHOOK_SECRET="$(python - <<'PY'
+import secrets
+print(secrets.token_hex(32))
+PY
+)"
+    printf '%s' "$TELEGRAM_WEBHOOK_SECRET" > "$SECRET_FILE"
+    chmod 600 "$SECRET_FILE"
+    export TELEGRAM_WEBHOOK_SECRET
+  fi
+fi
+
+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)
+    [ -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}"
+    ;;
+  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}"
+    ;;
+  minimax)
+    [ -n "$LLM_API_KEY" ] && export MINIMAX_API_KEY="${MINIMAX_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}"
+    ;;
+  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
+
+if [ -z "$MODEL_FOR_CONFIG" ]; then
+  echo "Missing LLM_MODEL or HERMES_MODEL."
+  echo "Add it in HF Spaces -> Settings -> Variables or Secrets."
+  exit 1
+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
+
+python - <<'PY'
+import os
+from pathlib import Path
+
+import yaml
+
+home = Path(os.environ["HERMES_HOME"])
+path = home / "config.yaml"
+try:
+    config = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+except FileNotFoundError:
+    config = {}
+
+model = config.setdefault("model", {})
+model["default"] = os.environ["MODEL_FOR_CONFIG"]
+model["provider"] = os.environ["PROVIDER_FOR_CONFIG"]
+
+custom_base = os.environ.get("CUSTOM_BASE_URL", "").strip()
+if custom_base:
+    model["base_url"] = custom_base.rstrip("/")
+    if os.environ.get("CUSTOM_API_KEY"):
+        model["api_key"] = os.environ["CUSTOM_API_KEY"]
+    try:
+        model["context_length"] = int(os.environ.get("CUSTOM_MODEL_CONTEXT_LENGTH", "131072"))
+        model["max_tokens"] = int(os.environ.get("CUSTOM_MODEL_MAX_TOKENS", "8192"))
+    except ValueError:
+        pass
+
+config.setdefault("terminal", {})["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"))
+
+platforms = config.setdefault("platforms", {})
+
+if os.environ.get("TELEGRAM_BOT_TOKEN"):
+    telegram = platforms.setdefault("telegram", {})
+    telegram["enabled"] = True
+    extra = telegram.setdefault("extra", {})
+    if os.environ.get("TELEGRAM_BASE_URL"):
+        extra["base_url"] = os.environ["TELEGRAM_BASE_URL"]
+        extra["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", {})["allow_from"] = [
+            item.strip()
+            for item in os.environ["TELEGRAM_ALLOWED_USERS"].split(",")
+            if item.strip()
+        ]
+
+path.write_text(yaml.safe_dump(config, sort_keys=False), encoding="utf-8")
+path.chmod(0o600)
+PY
+
+echo ""
+echo "Hermes model : ${MODEL_FOR_CONFIG}"
+echo "Provider     : ${PROVIDER_FOR_CONFIG}"
+echo "Public port  : ${PUBLIC_PORT}"
+if [ -n "${TELEGRAM_BOT_TOKEN:-}" ]; then
+  echo "Telegram     : enabled"
+  if [ -n "${TELEGRAM_WEBHOOK_URL:-}" ]; then
+    echo "Telegram mode: webhook (${TELEGRAM_WEBHOOK_URL})"
+  else
+    echo "Telegram mode: polling"
+  fi
+else
+  echo "Telegram     : not configured"
+fi
+if [ -n "${HF_TOKEN:-}" ]; then
+  echo "Backup       : ${BACKUP_DATASET} every ${SYNC_INTERVAL}s"
+else
+  echo "Backup       : disabled"
+fi
+if [ -n "${CLOUDFLARE_PROXY_URL:-}" ]; then
+  echo "Proxy        : ${CLOUDFLARE_PROXY_URL}"
+fi
+if [ -n "${SPACE_HOST:-}" ]; then
+  echo "Space URL    : https://${SPACE_HOST}"
+fi
+echo ""
+
+graceful_shutdown() {
+  echo "Shutting down HuggingMess..."
+  if [ -n "${HF_TOKEN:-}" ]; then
+    python "$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
+
+node "$APP_DIR/health-server.js" &
+HEALTH_PID=$!
+
+if [ -n "${UPTIMEROBOT_API_KEY:-}" ] && [ -n "${SPACE_HOST:-}" ]; then
+  echo "Setting up UptimeRobot monitor..."
+  bash "$APP_DIR/setup-uptimerobot.sh" "${SPACE_HOST}" || true
+fi
+
+if [ -n "${WEBHOOK_URL:-}" ]; then
+  python - <<'PY' >/dev/null 2>&1 &
+import json, os, urllib.request
+body = json.dumps({
+    "event": "restart",
+    "status": "success",
+    "message": "HuggingMess Hermes gateway 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
+
+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=$!
+
+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
+
+if [ -n "${HF_TOKEN:-}" ]; then
+  python -u "$APP_DIR/hermes-sync.py" loop &
+fi
+
+wait "$GATEWAY_PID"