Upload 6 files

cloudflare-keepalive-setup.py

@@ -0,0 +1,222 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+"""Create or reuse a Cloudflare Worker for Space keep-awake."""
+
+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:
+            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-proxy")[: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

@@ -0,0 +1,213 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+"""Create or reuse Cloudflare Workers for Telegram proxy and Space keep-awake."""
+
+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")
+ENV_FILE = Path("/tmp/huggingmes-cloudflare-proxy.env")
+DEFAULT_ALLOWED = [
+    # Messaging & social — primary use-case for Cloudflare proxy on HF Spaces
+    # (geo-restrictions on Telegram, Discord, WhatsApp, etc.)
+    "api.telegram.org",
+    "discord.com",
+    "discordapp.com",
+    "gateway.discord.gg",
+    "status.discord.com",
+    "slack.com",
+    "api.slack.com",
+    "web.whatsapp.com",
+    # Social — confirmed/likely blocked by HF firewall
+    "graph.facebook.com",
+    "graph.instagram.com",
+    "api.twitter.com",
+    "api.x.com",
+    # Google
+    "googleapis.com",
+    "google.com",
+    "googleusercontent.com",
+    "gstatic.com",
+    # Email HTTP APIs (SMTP ports are blocked)
+    "api.resend.com",
+    "api.sendgrid.com",
+    # NOTE: AI-provider domains (api.openai.com, api.anthropic.com, etc.) are
+    # intentionally NOT included here. Proxying AI calls routes API keys through
+    # the Cloudflare Worker without explicit opt-in. Users who need AI API calls
+    # proxied can add specific domains via CLOUDFLARE_PROXY_DOMAINS env var.
+]
+
+
+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())

env-builder.html

@@ -0,0 +1,853 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>HuggingMes · ENV Builder</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600;700&family=Syne:wght@400;500;600;700;800&display=swap" rel="stylesheet">
+
+<style>
+*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+:root {
+  --bg:        #0b0c0f;
+  --bg2:       #111318;
+  --bg3:       #181c23;
+  --bg4:       #1e2330;
+  --border:    #252b38;
+  --border2:   #2e3648;
+  --amber:     #f5a623;
+  --amber2:    #ffbe55;
+  --amber-dim: rgba(245,166,35,.12);
+  --amber-glow:rgba(245,166,35,.22);
+  --green:     #3dd68c;
+  --red:       #f05f5f;
+  --blue:      #5b8af5;
+  --text:      #e4e8f0;
+  --text2:     #8d97ad;
+  --text3:     #535f76;
+  --mono:      'JetBrains Mono', monospace;
+  --sans:      'Syne', sans-serif;
+  --r:         8px;
+  --r2:        12px;
+  --sidebar-w: 220px;
+  --panel-w:   340px;
+}
+
+html { scroll-behavior: smooth; height: 100%; }
+
+body {
+  font-family: var(--sans);
+  background: var(--bg);
+  color: var(--text);
+  height: 100vh;
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+}
+
+.topbar {
+  position: sticky;
+  top: 0;
+  z-index: 100;
+  height: 52px;
+  background: rgba(11,12,15,.9);
+  backdrop-filter: blur(14px);
+  border-bottom: 1px solid var(--border);
+  display: flex;
+  align-items: center;
+  padding: 0 20px;
+  gap: 16px;
+  flex-shrink: 0;
+}
+
+.topbar-logo {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  flex-shrink: 0;
+}
+
+.topbar-logo .logo-emoji { font-size: 24px; line-height: 1; }
+
+.topbar-wordmark {
+  font-weight: 800;
+  font-size: 14px;
+  letter-spacing: -.2px;
+  color: var(--text);
+  white-space: nowrap;
+}
+
+.topbar-wordmark em {
+  color: var(--amber);
+  font-style: normal;
+}
+
+.topbar-divider {
+  width: 1px;
+  height: 22px;
+  background: var(--border2);
+}
+
+.topbar-title {
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--text2);
+  letter-spacing: .5px;
+  text-transform: uppercase;
+}
+
+.topbar-spacer { flex: 1; }
+
+.topbar-pill {
+  font-family: var(--mono);
+  font-size: 10px;
+  color: var(--amber);
+  background: var(--amber-dim);
+  border: 1px solid var(--amber-glow);
+  border-radius: 20px;
+  padding: 3px 10px;
+  letter-spacing: .5px;
+}
+
+.layout {
+  display: flex;
+  flex: 1;
+  min-height: 0;
+  height: calc(100vh - 52px);
+}
+
+.sidebar-wrap {
+  width: var(--sidebar-w);
+  flex-shrink: 0;
+  border-right: 1px solid var(--border);
+  background: var(--bg2);
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+.sidebar-scroll {
+  flex: 1;
+  overflow-y: auto;
+  padding: 14px 10px;
+}
+
+.sidebar-scroll::-webkit-scrollbar { width: 4px; }
+.sidebar-scroll::-webkit-scrollbar-track { background: transparent; }
+.sidebar-scroll::-webkit-scrollbar-thumb { background: var(--border2); border-radius: 4px; }
+
+.sb-label {
+  font-size: 9px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 1.2px;
+  color: var(--text3);
+  padding: 0 8px 10px;
+}
+
+.nav-btn {
+  width: 100%;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 10px;
+  border: none;
+  background: transparent;
+  cursor: pointer;
+  border-radius: var(--r);
+  text-align: left;
+  color: var(--text2);
+  font-family: var(--sans);
+  font-size: 12.5px;
+  font-weight: 500;
+  transition: background .15s, color .15s;
+  margin-bottom: 2px;
+}
+
+.nav-btn:hover { background: var(--bg3); color: var(--text); }
+.nav-btn.active {
+  background: var(--amber-dim);
+  color: var(--amber);
+  border: 1px solid var(--amber-glow);
+}
+
+.nav-icon { font-size: 13px; flex-shrink: 0; }
+.nav-label { flex: 1; }
+.nav-count {
+  font-family: var(--mono);
+  font-size: 10px;
+  font-weight: 600;
+  color: var(--text3);
+  background: var(--bg3);
+  border-radius: 10px;
+  padding: 1px 6px;
+  min-width: 20px;
+  text-align: center;
+  transition: background .2s, color .2s;
+}
+.nav-btn.active .nav-count {
+  background: var(--amber-glow);
+  color: var(--amber2);
+}
+
+.main {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  overflow: hidden;
+}
+
+.toolbar {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 12px 20px;
+  border-bottom: 1px solid var(--border);
+  background: var(--bg2);
+  flex-shrink: 0;
+  flex-wrap: wrap;
+}
+
+.search-wrap {
+  position: relative;
+  flex: 1;
+  min-width: 160px;
+  max-width: 340px;
+}
+
+.search-icon {
+  position: absolute;
+  left: 10px;
+  top: 50%;
+  transform: translateY(-50%);
+  color: var(--text3);
+  pointer-events: none;
+  font-size: 12px;
+}
+
+#search {
+  width: 100%;
+  background: var(--bg3);
+  border: 1px solid var(--border2);
+  border-radius: var(--r);
+  padding: 7px 10px 7px 30px;
+  font-family: var(--mono);
+  font-size: 12px;
+  color: var(--text);
+  outline: none;
+  transition: border-color .15s;
+}
+
+#search:focus { border-color: var(--amber); }
+#search::placeholder { color: var(--text3); }
+
+.tb-sep {
+  width: 1px;
+  height: 24px;
+  background: var(--border2);
+}
+
+.btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  padding: 6px 13px;
+  border-radius: var(--r);
+  border: 1px solid var(--border2);
+  background: var(--bg3);
+  color: var(--text2);
+  font-family: var(--sans);
+  font-size: 11.5px;
+  font-weight: 600;
+  cursor: pointer;
+  transition: all .15s;
+  white-space: nowrap;
+}
+
+.btn:hover { background: var(--bg4); color: var(--text); border-color: var(--border2); }
+
+.btn-amber {
+  background: var(--amber);
+  color: #0b0c0f;
+  border-color: var(--amber);
+}
+.btn-amber:hover { background: var(--amber2); border-color: var(--amber2); }
+
+.btn-ghost {
+  background: transparent;
+  border-color: transparent;
+  color: var(--text3);
+}
+.btn-ghost:hover { background: var(--bg3); color: var(--text2); border-color: var(--border2); }
+
+.content-wrap {
+  flex: 1;
+  display: flex;
+  min-height: 0;
+  overflow: hidden;
+}
+
+.sections-scroll {
+  flex: 1;
+  overflow-y: auto;
+  padding: 16px 20px 80px;
+  min-width: 0;
+}
+
+.sections-scroll::-webkit-scrollbar { width: 5px; }
+.sections-scroll::-webkit-scrollbar-track { background: transparent; }
+.sections-scroll::-webkit-scrollbar-thumb { background: var(--border2); border-radius: 4px; }
+
+.sec { margin-bottom: 28px; }
+.sec.sec-hidden { display: none !important; }
+
+.sec-header {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin-bottom: 12px;
+}
+
+.sec-icon { font-size: 14px; }
+.sec-title {
+  font-size: 11px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 1.2px;
+  color: var(--text3);
+}
+
+.sec-line {
+  flex: 1;
+  height: 1px;
+  background: var(--border);
+}
+
+.cards {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
+  gap: 10px;
+}
+
+.env-card {
+  background: var(--bg2);
+  border: 1px solid var(--border);
+  border-radius: var(--r2);
+  padding: 12px;
+  transition: border-color .2s, background .2s;
+}
+
+.env-card:hover { border-color: var(--border2); }
+.env-card.hidden { display: none; }
+
+.env-card.selected {
+  border-color: var(--amber-glow);
+  background: linear-gradient(135deg, var(--bg2) 80%, rgba(245,166,35,.04));
+}
+
+.card-top {
+  display: flex;
+  align-items: flex-start;
+  gap: 9px;
+  margin-bottom: 9px;
+}
+
+.card-check {
+  width: 15px;
+  height: 15px;
+  accent-color: var(--amber);
+  flex-shrink: 0;
+  margin-top: 2px;
+  cursor: pointer;
+}
+
+.card-info { flex: 1; min-width: 0; }
+
+.card-key {
+  font-family: var(--mono);
+  font-size: 11.5px;
+  font-weight: 600;
+  color: var(--text);
+  letter-spacing: .3px;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.card-lbl {
+  font-size: 11px;
+  color: var(--text3);
+  margin-top: 2px;
+  line-height: 1.35;
+}
+
+.badge {
+  flex-shrink: 0;
+  font-family: var(--mono);
+  font-size: 9px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: .6px;
+  padding: 2px 7px;
+  border-radius: 20px;
+}
+
+/* Tag badge styles */
+.badge-critical  { background: rgba(240,80,80,.14);  color: #f05f5f; border: 1px solid rgba(240,80,80,.3); }
+.badge-credential{ background: rgba(220,140,60,.13); color: #e09040; border: 1px solid rgba(220,140,60,.28); }
+.badge-feature   { background: rgba(70,140,250,.12); color: #5a9eff; border: 1px solid rgba(70,140,250,.25); }
+.badge-optional  { background: rgba(61,214,140,.10); color: #3dd68c; border: 1px solid rgba(61,214,140,.22); }
+.badge-advanced  { background: rgba(160,100,230,.12);color: #b07ae0; border: 1px solid rgba(160,100,230,.25); }
+.badge-build     { background: rgba(240,185,60,.12); color: #e0b030; border: 1px solid rgba(240,185,60,.28); }
+
+/* Card left-border accents */
+.env-card:has(.badge-critical)  { border-left: 3px solid rgba(240,80,80,.4); }
+.env-card:has(.badge-critical):hover { border-left-color: rgba(240,80,80,.7); }
+.env-card:has(.badge-critical).selected { border-left-color: #f05f5f; }
+.env-card:has(.badge-credential){ border-left: 3px solid rgba(220,140,60,.3); }
+
+/* Section count badge */
+.sec-count {
+  font-family: var(--mono);
+  font-size: 10px;
+  color: var(--text3);
+  background: var(--bg3);
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  padding: 1px 7px;
+}
+
+/* Tag legend */
+.tag-legend {
+  margin-bottom: 14px;
+  background: var(--bg2);
+  border: 1px solid var(--border);
+  border-radius: var(--r);
+  overflow: hidden;
+}
+.legend-summary {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 7px 12px;
+  cursor: pointer;
+  list-style: none;
+  user-select: none;
+  outline: none;
+}
+.legend-summary::-webkit-details-marker { display: none; }
+.legend-chips { display: flex; gap: 5px; flex-wrap: wrap; flex: 1; }
+.legend-hint { font-size: 10px; color: var(--text3); white-space: nowrap; flex-shrink: 0; }
+.tag-legend[open] .legend-hint { opacity: 0; }
+.legend-body {
+  padding: 8px 12px 10px;
+  border-top: 1px solid var(--border);
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+.legend-row { display: flex; align-items: center; gap: 10px; font-size: 11px; color: var(--text2); }
+.legend-row .badge { flex-shrink: 0; width: 74px; text-align: center; }
+.legend-tip { font-size: 9.5px; color: var(--text3); margin-top: 4px; padding-top: 6px; border-top: 1px solid var(--border); }
+.toolbar-hint { color: var(--text3); font-size: 12px; margin-right: 6px; white-space: nowrap; }
+
+.card-input { position: relative; }
+
+.card-input input[type="text"],
+.card-input input[type="password"],
+.card-input input[type="number"],
+.card-input textarea,
+.card-input select {
+  width: 100%;
+  background: var(--bg3);
+  border: 1px solid var(--border);
+  border-radius: var(--r);
+  padding: 7px 10px;
+  font-family: var(--mono);
+  font-size: 11.5px;
+  color: var(--text);
+  outline: none;
+  transition: border-color .15s;
+  resize: vertical;
+}
+
+.card-input input[type="text"]:focus,
+.card-input input[type="password"]:focus,
+.card-input input[type="number"]:focus,
+.card-input textarea:focus,
+.card-input select:focus {
+  border-color: var(--amber);
+}
+
+.card-input textarea { min-height: 64px; }
+.card-input select {
+  cursor: pointer;
+  appearance: none;
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 12 12'%3E%3Cpath fill='%238d97ad' d='M6 8L1 3h10z'/%3E%3C/svg%3E");
+  background-repeat: no-repeat;
+  background-position: right 10px center;
+  padding-right: 28px;
+}
+
+.card-input optgroup { color: var(--text2); font-weight: 600; }
+.card-input option { color: var(--text); background: var(--bg3); }
+
+.toggle-shell { display: flex; align-items: center; gap: 8px; }
+.tog {
+  padding: 5px 14px;
+  border-radius: 20px;
+  border: 1px solid var(--border2);
+  background: var(--bg3);
+  color: var(--text3);
+  font-family: var(--mono);
+  font-size: 11px;
+  font-weight: 700;
+  cursor: pointer;
+  transition: all .18s;
+  letter-spacing: .5px;
+}
+.tog.on {
+  background: rgba(61,214,140,.15);
+  border-color: rgba(61,214,140,.4);
+  color: var(--green);
+}
+
+.picker-shell { display: flex; flex-direction: column; gap: 6px; }
+.picker-row { display: flex; gap: 6px; align-items: center; flex-wrap: wrap; }
+
+.picker-select {
+  flex: 1;
+  min-width: 0;
+  padding: 6px 28px 6px 8px !important;
+  font-size: 11px !important;
+}
+
+.mini-btn {
+  padding: 5px 9px;
+  border-radius: var(--r);
+  border: 1px solid var(--border2);
+  background: var(--bg3);
+  color: var(--text2);
+  font-family: var(--mono);
+  font-size: 10px;
+  font-weight: 600;
+  cursor: pointer;
+  transition: all .15s;
+  white-space: nowrap;
+}
+.mini-btn:hover { background: var(--bg4); color: var(--text); }
+
+.right-panel {
+  width: var(--panel-w);
+  flex-shrink: 0;
+  border-left: 1px solid var(--border);
+  background: var(--bg2);
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+.panel-scroll {
+  flex: 1;
+  overflow-y: auto;
+  padding: 16px;
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+
+.panel-scroll::-webkit-scrollbar { width: 4px; }
+.panel-scroll::-webkit-scrollbar-track { background: transparent; }
+.panel-scroll::-webkit-scrollbar-thumb { background: var(--border2); border-radius: 4px; }
+
+.pblock {
+  background: var(--bg3);
+  border: 1px solid var(--border);
+  border-radius: var(--r2);
+  overflow: hidden;
+}
+
+.pblock-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 10px 14px;
+  border-bottom: 1px solid var(--border);
+}
+
+.pblock-title {
+  font-size: 10.5px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 1px;
+  color: var(--text3);
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+
+.pblock-body { padding: 12px 14px; display: flex; flex-direction: column; gap: 8px; }
+
+.pblock-body textarea,
+.pblock-body input[type="text"] {
+  width: 100%;
+  background: var(--bg);
+  border: 1px solid var(--border);
+  border-radius: var(--r);
+  padding: 8px 10px;
+  font-family: var(--mono);
+  font-size: 10.5px;
+  color: var(--text2);
+  outline: none;
+  resize: vertical;
+  transition: border-color .15s;
+}
+
+.pblock-body textarea:focus,
+.pblock-body input[type="text"]:focus {
+  border-color: var(--amber);
+  color: var(--text);
+}
+
+#importText { min-height: 80px; }
+#bundleOut { min-height: 60px; color: var(--amber2); }
+#envLineOut { font-size: 10px; }
+
+.row-btns { display: flex; gap: 6px; flex-wrap: wrap; }
+
+#summary {
+  font-size: 11.5px;
+  color: var(--text2);
+  line-height: 1.6;
+}
+
+#summary strong {
+  font-size: 15px;
+  color: var(--amber);
+  font-family: var(--mono);
+}
+
+.sum-keys {
+  margin-top: 8px;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px;
+}
+
+.sum-key {
+  font-family: var(--mono);
+  font-size: 9.5px;
+  color: var(--text2);
+  background: var(--bg4);
+  border: 1px solid var(--border2);
+  border-radius: 4px;
+  padding: 2px 6px;
+}
+
+#customSec { margin-top: 8px; }
+
+.custom-row {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  margin-bottom: 8px;
+}
+
+.custom-row input {
+  flex: 1;
+  background: var(--bg3);
+  border: 1px solid var(--border);
+  border-radius: var(--r);
+  padding: 7px 10px;
+  font-family: var(--mono);
+  font-size: 11px;
+  color: var(--text);
+  outline: none;
+  transition: border-color .15s;
+  min-width: 0;
+}
+
+.custom-row input:focus { border-color: var(--amber); }
+.custom-row input:first-child { flex: 0 0 40%; }
+
+#toast {
+  position: fixed;
+  bottom: 24px;
+  left: 50%;
+  transform: translateX(-50%) translateY(20px);
+  background: var(--bg4);
+  border: 1px solid var(--border2);
+  color: var(--amber);
+  font-family: var(--mono);
+  font-size: 12px;
+  font-weight: 600;
+  padding: 9px 20px;
+  border-radius: 30px;
+  z-index: 9999;
+  opacity: 0;
+  transition: opacity .2s, transform .2s;
+  pointer-events: none;
+  box-shadow: 0 8px 32px rgba(0,0,0,.5);
+}
+
+#toast.show {
+  opacity: 1;
+  transform: translateX(-50%) translateY(0);
+}
+
+::-webkit-scrollbar { width: 6px; height: 6px; }
+::-webkit-scrollbar-track { background: transparent; }
+::-webkit-scrollbar-thumb { background: var(--border2); border-radius: 4px; }
+
+@media (max-width: 900px) {
+  :root { --panel-w: 280px; --sidebar-w: 180px; }
+}
+
+@media (max-width: 700px) {
+  .right-panel { display: none; }
+  :root { --sidebar-w: 160px; }
+}
+
+@media (max-width: 520px) {
+  .sidebar-wrap { display: none; }
+  .topbar-divider, .topbar-title { display: none; }
+}
+</style>
+</head>
+
+<body>
+
+<header class="topbar">
+  <div class="topbar-logo">
+    <span class="logo-emoji">🪽</span>
+    <span class="topbar-wordmark">Hugging<em>Mes</em></span>
+  </div>
+  <div class="topbar-divider"></div>
+  <span class="topbar-title">ENV Builder</span>
+  <div class="topbar-spacer"></div>
+  <span class="topbar-pill">v2025</span>
+</header>
+
+<div class="layout">
+
+  <aside class="sidebar-wrap">
+    <div class="sidebar-scroll">
+      <div id="sidebar"></div>
+    </div>
+  </aside>
+
+  <main class="main">
+
+    <div class="toolbar">
+      <span class="toolbar-hint">Tip: Start with <strong>⚡ Required</strong>, then fill keys and click <strong># Generate Bundle</strong>.</span>
+      <div class="search-wrap">
+        <span class="search-icon">⌕</span>
+        <input id="search" type="text" placeholder="Search variables…" autocomplete="off" spellcheck="false">
+      </div>
+
+      <div class="tb-sep"></div>
+
+      <button id="selectRequired" class="btn">⚡ Required</button>
+      <button id="selectCommon" class="btn">★ Common</button>
+      <button id="selectVisible" class="btn">☑ Visible</button>
+      <button id="clearAll" class="btn btn-ghost">✕ Clear</button>
+    </div>
+
+    <div class="content-wrap">
+
+      <div class="sections-scroll">
+
+        <details class="tag-legend">
+          <summary class="legend-summary">
+            <div class="legend-chips">
+              <span class="badge badge-critical">critical</span>
+              <span class="badge badge-credential">credential</span>
+              <span class="badge badge-feature">feature</span>
+              <span class="badge badge-optional">optional</span>
+              <span class="badge badge-advanced">advanced</span>
+              <span class="badge badge-build">build</span>
+            </div>
+            <span class="legend-hint">▸ Tag legend</span>
+          </summary>
+          <div class="legend-body">
+            <div class="legend-row"><span class="badge badge-critical">critical</span> Required for the space to function at all</div>
+            <div class="legend-row"><span class="badge badge-credential">credential</span> API keys, tokens, secrets — keep private</div>
+            <div class="legend-row"><span class="badge badge-feature">feature</span> Unlocks an optional feature or integration</div>
+            <div class="legend-row"><span class="badge badge-optional">optional</span> Useful but not required; has a default</div>
+            <div class="legend-row"><span class="badge badge-advanced">advanced</span> Fine-tuning for specific deployments</div>
+            <div class="legend-row"><span class="badge badge-build">build</span> Affects Docker build, not runtime</div>
+            <div class="legend-tip">Use <strong>⚡ Required</strong> to auto-select all critical fields, then fill in credential keys.</div>
+          </div>
+        </details>
+
+        <div id="sections"></div>
+
+        <div id="customSec" class="sec" data-section="Custom Env">
+          <div class="sec-header">
+            <span class="sec-icon">🔧</span>
+            <span class="sec-title">Custom Env</span>
+            <div class="sec-line"></div>
+          </div>
+          <div id="customRows"></div>
+          <button id="addCustom" class="btn" style="margin-top:6px;">+ Add variable</button>
+        </div>
+      </div>
+
+      <aside class="right-panel">
+        <div class="panel-scroll">
+
+          <div class="pblock">
+            <div class="pblock-head">
+              <span class="pblock-title">📊 Summary</span>
+            </div>
+            <div class="pblock-body">
+              <div id="summary">No variables selected yet.</div>
+            </div>
+          </div>
+
+          <div class="pblock">
+            <div class="pblock-head">
+              <span class="pblock-title">📦 Bundle Output</span>
+            </div>
+            <div class="pblock-body">
+              <textarea id="bundleOut" placeholder="Select variables and click # Generate Bundle…" readonly spellcheck="false"></textarea>
+              <input type="text" id="envLineOut" placeholder="HUGGINGMES_ENV_BUNDLE=…" readonly spellcheck="false">
+              <div class="row-btns">
+                <button id="generateBundle" class="btn btn-amber" style="width:100%;"># Generate Bundle</button>
+              </div>
+              <div class="row-btns">
+                <button id="copyBundle" class="btn btn-amber">⎘ Bundle</button>
+                <button id="copyEnvLine" class="btn">⎘ Env Line</button>
+                <button id="copyJson" class="btn">⎘ JSON</button>
+                <button id="applyBundle" class="btn btn-ghost">↺ Apply</button>
+              </div>
+            </div>
+          </div>
+
+          <div class="pblock">
+            <div class="pblock-head">
+              <span class="pblock-title">📥 Import</span>
+            </div>
+            <div class="pblock-body">
+              <textarea id="importText" placeholder="Paste .env, JSON, or HUGGINGMES_ENV_BUNDLE=… here" spellcheck="false"></textarea>
+              <button id="applyImport" class="btn btn-amber" style="width:100%;">↓ Import & Apply</button>
+            </div>
+          </div>
+
+        </div>
+      </aside>
+
+    </div>
+  </main>
+</div>
+
+<div id="toast">Copied ✓</div>
+
+<script src="env-builder.js"></script>
+
+</body>
+</html>

env-builder.js

@@ -0,0 +1,797 @@
+// ── Model Catalogs ──
+const MODEL_CATALOGS = {
+  "LLM_MODEL": {
+    "Anthropic": [
+      "anthropic/claude-opus-4-7",
+      "anthropic/claude-opus-4-6",
+      "anthropic/claude-sonnet-4-6",
+      "anthropic/claude-sonnet-4-5",
+      "anthropic/claude-haiku-4-5",
+      "anthropic/claude-haiku-3-5"
+    ],
+    "Gemini": [
+      "gemini/gemini-2.5-pro-preview-06-05",
+      "gemini/gemini-2.5-flash-preview-05-20",
+      "gemini/gemini-2.5-flash",
+      "gemini/gemini-2.0-flash",
+      "gemini/gemini-1.5-pro",
+      "gemini/gemini-1.5-flash",
+      "google/gemini-2.5-flash",
+      "google/gemini-2.0-flash"
+    ],
+    "OpenAI": [
+      "openai/gpt-4.1",
+      "openai/gpt-4.1-mini",
+      "openai/gpt-4o",
+      "openai/gpt-4o-mini",
+      "openai/o3",
+      "openai/o4-mini",
+      "openai/o3-mini"
+    ],
+    "OpenRouter": [
+      "openrouter/anthropic/claude-opus-4-7",
+      "openrouter/anthropic/claude-sonnet-4-6",
+      "openrouter/anthropic/claude-haiku-4-5",
+      "openrouter/openai/gpt-4o",
+      "openrouter/openai/o3",
+      "openrouter/google/gemini-2.5-flash",
+      "openrouter/google/gemini-2.5-pro",
+      "openrouter/meta-llama/llama-4-maverick",
+      "openrouter/deepseek/deepseek-r1",
+      "openrouter/deepseek/deepseek-chat-v3-5",
+      "openrouter/mistralai/mistral-large"
+    ],
+    "DeepSeek": [
+      "deepseek/deepseek-chat",
+      "deepseek/deepseek-reasoner"
+    ],
+    "xAI": [
+      "xai/grok-3",
+      "xai/grok-3-mini",
+      "xai/grok-2"
+    ],
+    "HuggingFace": [
+      "huggingface/meta-llama/Llama-3.3-70B-Instruct",
+      "huggingface/meta-llama/Llama-3.1-70B-Instruct",
+      "huggingface/Qwen/Qwen2.5-72B-Instruct",
+      "huggingface/mistralai/Mistral-7B-Instruct-v0.3",
+      "huggingface/google/gemma-2-27b-it"
+    ],
+    "Moonshot / Kimi": [
+      "moonshot/moonshot-v1-128k",
+      "kimi-coding/kimi-k2-0711-preview",
+      "kimi-coding-cn/kimi-k2-0711-preview"
+    ],
+    "Alibaba": [
+      "alibaba/qwen-max",
+      "alibaba/qwen-plus",
+      "alibaba/qwen-turbo"
+    ],
+    "Minimax": [
+      "minimax/minimax-01",
+      "minimax-cn/minimax-01"
+    ],
+    "NVIDIA": [
+      "nvidia/meta/llama-3.1-70b-instruct",
+      "nvidia/meta/llama-3.3-70b-instruct"
+    ],
+    "GLM / ZAI": [
+      "zai/glm-4-plus",
+      "glm/chatglm-turbo"
+    ],
+    "Vercel AI Gateway": [
+      "vercel-ai-gateway/anthropic/claude-sonnet-4-6",
+      "vercel-ai-gateway/openai/gpt-4o"
+    ],
+    "Custom / OpenAI-compatible": [
+      "custom"
+    ]
+  }
+};
+
+// ── Icons per group ──
+const ICONS = {
+  "All":       "🌐",
+  "Core":      "⚡",
+  "Telegram":  "📱",
+  "Terminal":  "💻",
+  "Providers": "🔑",
+  "Cloudflare":"☁️",
+  "Advanced":  "⚙️",
+  "Custom Env":"🔧"
+};
+
+// ── Field definitions ──
+// tag: "critical" | "credential" | "feature" | "optional" | "advanced" | "build"
+const FIELDS = [
+  // ── Core ──
+  {
+    "g": "Core", "icon": "⚡",
+    "k": "GATEWAY_TOKEN",
+    "lbl": "Gateway token — protects the Hermes web UI",
+    "type": "password", "secret": 1, "common": 1, "tag": "critical"
+  },
+  {
+    "g": "Core", "icon": "⚡",
+    "k": "LLM_MODEL",
+    "lbl": "Default model (provider/model-name format)",
+    "type": "model", "options_key": "LLM_MODEL",
+    "ph": "gemini/gemini-2.5-flash", "common": 1, "tag": "critical"
+  },
+  {
+    "g": "Core", "icon": "⚡",
+    "k": "LLM_API_KEY",
+    "lbl": "API key for the chosen provider",
+    "type": "password", "secret": 1, "common": 1, "tag": "credential"
+  },
+
+  // ── Telegram ──
+  {
+    "g": "Telegram", "icon": "📱",
+    "k": "TELEGRAM_BOT_TOKEN",
+    "lbl": "Telegram bot token from @BotFather",
+    "type": "password", "secret": 1, "common": 1, "tag": "credential"
+  },
+  {
+    "g": "Telegram", "icon": "📱",
+    "k": "TELEGRAM_ALLOWED_USERS",
+    "lbl": "Allowed Telegram user IDs (comma-separated)",
+    "type": "text", "ph": "123456789,987654321", "common": 1, "tag": "feature"
+  },
+  {
+    "g": "Telegram", "icon": "📱",
+    "k": "TELEGRAM_MODE",
+    "lbl": "Telegram update mode",
+    "type": "select",
+    "options": ["webhook", "polling"],
+    "ph": "webhook", "tag": "optional"
+  },
+  {
+    "g": "Telegram", "icon": "📱",
+    "k": "TELEGRAM_WEBHOOK_URL",
+    "lbl": "Override webhook URL (auto-detected from SPACE_HOST if blank)",
+    "type": "text", "ph": "https://your-space.hf.space/telegram", "tag": "optional"
+  },
+  {
+    "g": "Telegram", "icon": "📱",
+    "k": "TELEGRAM_BASE_URL",
+    "lbl": "Custom Telegram API base URL (for proxies)",
+    "type": "text", "ph": "https://proxy.example.com/bot", "tag": "optional"
+  },
+
+  // ── Terminal ──
+  {
+    "g": "Terminal", "icon": "💻",
+    "k": "DEV_MODE",
+    "lbl": "Enable JupyterLab terminal (on by default)",
+    "type": "toggle", "ph": "true", "common": 1, "tag": "feature"
+  },
+  {
+    "g": "Terminal", "icon": "💻",
+    "k": "JUPYTER_TOKEN",
+    "lbl": "Override terminal password (defaults to GATEWAY_TOKEN)",
+    "type": "password", "secret": 1, "tag": "credential"
+  },
+  {
+    "g": "Terminal", "icon": "💻",
+    "k": "JUPYTER_ROOT_DIR",
+    "lbl": "JupyterLab root directory",
+    "type": "text", "ph": "/opt/data/workspace", "tag": "optional"
+  },
+
+  // ── Providers ──
+  {
+    "g": "Providers", "icon": "🔑",
+    "k": "ANTHROPIC_API_KEY",
+    "lbl": "Anthropic API key",
+    "type": "password", "secret": 1, "tag": "credential"
+  },
+  {
+    "g": "Providers", "icon": "🔑",
+    "k": "OPENAI_API_KEY",
+    "lbl": "OpenAI API key",
+    "type": "password", "secret": 1, "tag": "credential"
+  },
+  {
+    "g": "Providers", "icon": "🔑",
+    "k": "GOOGLE_API_KEY",
+    "lbl": "Google / Gemini API key",
+    "type": "password", "secret": 1, "tag": "credential"
+  },
+  {
+    "g": "Providers", "icon": "🔑",
+    "k": "GEMINI_API_KEY",
+    "lbl": "Gemini API key (alias for GOOGLE_API_KEY)",
+    "type": "password", "secret": 1, "tag": "credential"
+  },
+  {
+    "g": "Providers", "icon": "🔑",
+    "k": "OPENROUTER_API_KEY",
+    "lbl": "OpenRouter API key",
+    "type": "password", "secret": 1, "tag": "credential"
+  },
+  {
+    "g": "Providers", "icon": "🔑",
+    "k": "DEEPSEEK_API_KEY",
+    "lbl": "DeepSeek API key",
+    "type": "password", "secret": 1, "tag": "credential"
+  },
+  {
+    "g": "Providers", "icon": "🔑",
+    "k": "XAI_API_KEY",
+    "lbl": "xAI (Grok) API key",
+    "type": "password", "secret": 1, "tag": "credential"
+  },
+  {
+    "g": "Providers", "icon": "🔑",
+    "k": "HERMES_INFERENCE_PROVIDER",
+    "lbl": "Force Hermes inference provider (overrides auto-detect)",
+    "type": "select",
+    "options": ["auto", "anthropic", "openai", "gemini", "openrouter", "huggingface", "custom", "deepseek", "xai"],
+    "ph": "auto", "tag": "advanced"
+  },
+  {
+    "g": "Providers", "icon": "🔑",
+    "k": "CUSTOM_BASE_URL",
+    "lbl": "Custom OpenAI-compatible base URL",
+    "type": "text", "ph": "https://your-api.example.com/v1", "tag": "feature"
+  },
+  {
+    "g": "Providers", "icon": "🔑",
+    "k": "CUSTOM_API_KEY",
+    "lbl": "API key for the custom provider",
+    "type": "password", "secret": 1, "tag": "credential"
+  },
+  {
+    "g": "Providers", "icon": "🔑",
+    "k": "CUSTOM_PROVIDER",
+    "lbl": "Provider name for custom endpoints",
+    "type": "text", "ph": "custom", "tag": "advanced"
+  },
+  {
+    "g": "Providers", "icon": "🔑",
+    "k": "CUSTOM_MODEL_CONTEXT_LENGTH",
+    "lbl": "Context length for custom model",
+    "type": "number", "ph": "131072", "tag": "advanced"
+  },
+  {
+    "g": "Providers", "icon": "🔑",
+    "k": "CUSTOM_MODEL_MAX_TOKENS",
+    "lbl": "Max output tokens for custom model",
+    "type": "number", "ph": "8192", "tag": "advanced"
+  },
+
+  // ── Cloudflare ──
+  {
+    "g": "Cloudflare", "icon": "☁️",
+    "k": "CLOUDFLARE_WORKERS_TOKEN",
+    "lbl": "Cloudflare Workers API token (for Telegram proxy setup)",
+    "type": "password", "secret": 1, "tag": "credential"
+  },
+  {
+    "g": "Cloudflare", "icon": "☁️",
+    "k": "CLOUDFLARE_PROXY_URL",
+    "lbl": "Cloudflare proxy URL for Telegram (if already deployed)",
+    "type": "text", "ph": "https://your-worker.your-subdomain.workers.dev", "tag": "feature"
+  },
+  {
+    "g": "Cloudflare", "icon": "☁️",
+    "k": "CLOUDFLARE_PROXY_DEBUG",
+    "lbl": "Enable Cloudflare proxy debug logging",
+    "type": "toggle", "ph": "false", "tag": "advanced"
+  },
+
+  // ── Advanced ──
+  {
+    "g": "Advanced", "icon": "⚙️",
+    "k": "WEBHOOK_URL",
+    "lbl": "URL to POST a JSON notification on gateway (re)start",
+    "type": "text", "ph": "https://...", "tag": "optional"
+  },
+  {
+    "g": "Advanced", "icon": "⚙️",
+    "k": "SPACE_PRIVACY",
+    "lbl": "Override Space privacy detection (public/private) — skips HF API call",
+    "type": "select", "options": ["public", "private"], "ph": "public", "tag": "advanced"
+  },
+  {
+    "g": "Advanced", "icon": "⚙️",
+    "k": "GATEWAY_READY_TIMEOUT",
+    "lbl": "Seconds to wait for gateway API port before failing",
+    "type": "number", "ph": "120", "tag": "advanced"
+  },
+  {
+    "g": "Advanced", "icon": "⚙️",
+    "k": "API_SERVER_PORT",
+    "lbl": "Hermes gateway internal API port",
+    "type": "number", "ph": "8642", "tag": "advanced"
+  },
+  {
+    "g": "Advanced", "icon": "⚙️",
+    "k": "DASHBOARD_PORT",
+    "lbl": "Hermes dashboard internal port",
+    "type": "number", "ph": "9119", "tag": "advanced"
+  },
+  {
+    "g": "Advanced", "icon": "⚙️",
+    "k": "HERMES_BACKGROUND_NOTIFICATIONS",
+    "lbl": "Background process notification level",
+    "type": "select",
+    "options": ["result", "progress", "none"],
+    "ph": "result", "tag": "optional"
+  },
+  {
+    "g": "Advanced", "icon": "⚙️",
+    "k": "TELEGRAM_WEBHOOK_SECRET",
+    "lbl": "Secret token for Telegram webhook validation (auto-generated if blank)",
+    "type": "password", "secret": 1, "tag": "credential"
+  }
+];
+
+// ── Runtime (shared with HuggingClaw env-builder) ──
+
+const BUNDLE_KEY = 'HUGGINGMES_ENV_BUNDLE';
+
+const $ = id => document.getElementById(id);
+const esc = s => String(s ?? '').replace(/[&<>"']/g, c => ({
+  '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;'
+}[c]));
+const safeKey = k => /^[A-Z_][A-Z0-9_]*$/.test(k) && ![BUNDLE_KEY, 'ENV_BUNDLE'].includes(k);
+
+function encodeBundle(obj) {
+  const j = JSON.stringify(obj);
+  let b = '';
+  for (const x of new TextEncoder().encode(j)) b += String.fromCharCode(x);
+  return btoa(b).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
+}
+
+function decodeBundle(raw) {
+  try {
+    raw = String(raw || '').trim();
+    if (!raw) return {};
+    if (raw.includes(BUNDLE_KEY + '=')) raw = raw.split(BUNDLE_KEY + '=').pop().trim();
+    if ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'"))) raw = raw.slice(1, -1);
+    if (raw.startsWith('{')) return JSON.parse(raw);
+    const p = raw + '='.repeat((4 - raw.length % 4) % 4);
+    const b = atob(p.replace(/-/g, '+').replace(/_/g, '/'));
+    const bytes = Uint8Array.from(b, c => c.charCodeAt(0));
+    return JSON.parse(new TextDecoder().decode(bytes));
+  } catch { return {}; }
+}
+
+function parseEnv(text) {
+  text = String(text || '').trim();
+  if (!text) return {};
+  if (text.startsWith('{') || /^[A-Za-z0-9_-]{20,}$/.test(text) || text.includes(BUNDLE_KEY + '=')) {
+    return decodeBundle(text);
+  }
+  const out = {};
+  for (let line of text.split(/\r?\n/)) {
+    line = line.trim();
+    if (!line || line.startsWith('#')) continue;
+    if (line.startsWith('export ')) line = line.slice(7).trim();
+    const i = line.indexOf('=');
+    if (i < 1) continue;
+    const key = line.slice(0, i).trim();
+    let val = line.slice(i + 1).trim();
+    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) val = val.slice(1, -1);
+    if (safeKey(key)) out[key] = val;
+  }
+  return out;
+}
+
+function showToast(msg = 'Copied!') {
+  const t = $('toast');
+  t.textContent = msg;
+  t.classList.add('show');
+  setTimeout(() => t.classList.remove('show'), 1500);
+}
+
+let activeGroup = 'All';
+let customCount = 0;
+const GROUPS = ['All', ...[...new Set(FIELDS.map(f => f.g))], 'Custom Env'];
+
+function renderSidebar() {
+  const sb = $('sidebar');
+  sb.innerHTML = '<div class="sb-label">Groups</div>';
+  GROUPS.forEach(g => {
+    const btn = document.createElement('button');
+    btn.className = 'nav-btn' + (activeGroup === g ? ' active' : '');
+    btn.dataset.group = g;
+    const id = 'nc_' + g.replace(/\W/g, '_');
+    btn.innerHTML = `<span class="nav-icon">${ICONS[g] || '📁'}</span><span class="nav-label">${esc(g)}</span><span class="nav-count" id="${id}">0</span>`;
+    btn.onclick = () => { activeGroup = g; renderSidebar(); filter(); };
+    sb.appendChild(btn);
+  });
+}
+
+function renderOptionsHTML(field) {
+  if (field.options_key === 'LLM_MODEL') {
+    const groups = MODEL_CATALOGS.LLM_MODEL || {};
+    return Object.entries(groups).map(([group, items]) => {
+      const options = items.map(v => `<option value="${esc(v)}">${esc(v)}</option>`).join('');
+      return `<optgroup label="${esc(group)}">${options}</optgroup>`;
+    }).join('');
+  }
+  const src = field.options || MODEL_CATALOGS[field.options_key] || [];
+  if (Array.isArray(src)) return src.map(v => `<option value="${esc(v)}">${esc(v)}</option>`).join('');
+  return '';
+}
+
+function defaultValueFor(field) {
+  if (field.type === 'toggle') {
+    const on = String(field.ph ?? '').toLowerCase();
+    return ['1', 'true', 'yes', 'on', 'enabled'].includes(on) ? 'true' : 'false';
+  }
+  if (field.type === 'select') return String(field.ph ?? '');
+  return '';
+}
+
+function valueControlHTML(field) {
+  const key = esc(field.k);
+  const placeholder = esc(field.ph || field.lbl || '');
+  const isSecret = !!field.secret;
+  const isTextarea = field.type === 'textarea';
+  const hasPicker = !!field.options_key || Array.isArray(field.options);
+  const inputType = isSecret ? 'password' : (field.type === 'number' ? 'number' : 'text');
+
+  let control = '';
+  if (field.type === 'toggle') {
+    const initial = defaultValueFor(field);
+    control = `<div class="toggle-shell" data-toggle-row="1" data-field="${key}">
+      <input type="hidden" data-key="${key}" value="${initial}">
+      <button type="button" class="tog ${initial === 'true' ? 'on' : ''}" data-toggle="${key}">${initial === 'true' ? 'On' : 'Off'}</button>
+    </div>`;
+  } else if (isTextarea) {
+    control = `<textarea data-key="${key}" placeholder="${placeholder}" spellcheck="false"></textarea>`;
+  } else {
+    control = `<input type="${inputType}" data-key="${key}" placeholder="${placeholder}" spellcheck="false"/>`;
+  }
+
+  if (!hasPicker) return control;
+
+  return `<div class="picker-shell" data-picker-shell="${key}" data-picker-mode="single">
+    <div class="picker-row">
+      <select class="picker-select" data-pick-for="${key}" aria-label="${esc(field.lbl || field.k)} presets">
+        <option value="">Choose preset…</option>
+        ${renderOptionsHTML(field)}
+        <option value="__custom__">Custom…</option>
+      </select>
+      <button type="button" class="mini-btn" data-custom-for="${key}">+ Custom</button>
+      <button type="button" class="mini-btn" data-clear-for="${key}">Clear</button>
+    </div>
+    ${control}
+  </div>`;
+}
+
+function tagBadgeHTML(f) {
+  const t = f.tag || (f.secret ? 'credential' : 'optional');
+  return `<span class="badge badge-${t}">${t}</span>`;
+}
+
+function cardHTML(f) {
+  const tagStr = (f.tag || '') + ' ' + (f.secret ? 'credential' : '') + ' ' + (f.g + ' ' + f.k + ' ' + (f.lbl || '')).toLowerCase();
+  return `<div class="env-card" data-row data-group="${esc(f.g)}" data-tag="${esc(f.tag || '')}" data-search="${esc(tagStr.toLowerCase())}">
+    <div class="card-top">
+      <input type="checkbox" class="card-check" data-check="${esc(f.k)}" ${f.common ? 'data-common="1"' : ''} ${f.tag === 'critical' ? 'data-critical="1"' : ''}>
+      <div class="card-info">
+        <div class="card-key">${esc(f.k)}</div>
+        <div class="card-lbl">${esc(f.lbl || '')}</div>
+      </div>
+      ${tagBadgeHTML(f)}
+    </div>
+    <div class="card-input">${valueControlHTML(f)}</div>
+  </div>`;
+}
+
+function addCustomRow(key = '', val = '', enabled = false) {
+  const id = customCount++;
+  const row = document.createElement('div');
+  row.className = 'custom-row';
+  row.dataset.customRow = id;
+  row.dataset.enabled = enabled ? '1' : '0';
+  row.innerHTML = `
+    <input data-ck="${id}" placeholder="CUSTOM_ENV_NAME" value="${esc(key)}">
+    <input data-cv="${id}" placeholder="value" value="${esc(val)}">
+    <button class="tog${enabled ? ' on' : ''}">${enabled ? 'On' : 'Off'}</button>`;
+  $('customRows').appendChild(row);
+  row.querySelectorAll('input').forEach(el => el.addEventListener('input', refresh));
+  row.querySelector('button').onclick = () => {
+    const on = row.dataset.enabled !== '1';
+    row.dataset.enabled = on ? '1' : '0';
+    row.querySelector('button').textContent = on ? 'On' : 'Off';
+    row.querySelector('button').classList.toggle('on', on);
+    refresh();
+  };
+}
+
+function getFieldValueInput(key) { return document.querySelector(`[data-key="${CSS.escape(key)}"]`); }
+
+function setFieldValue(key, value) {
+  const el = getFieldValueInput(key);
+  if (el) el.value = value ?? '';
+}
+
+function appendCsvValue(existing, next) {
+  const parts = String(existing || '').split(',').map(s => s.trim()).filter(Boolean);
+  const val = String(next || '').trim();
+  if (!val) return parts.join(', ');
+  if (!parts.includes(val)) parts.push(val);
+  return parts.join(', ');
+}
+
+function collect() {
+  const obj = {};
+  document.querySelectorAll('[data-key]').forEach(el => {
+    const key = el.dataset.key;
+    if (!key || !safeKey(key)) return;
+    const chk = document.querySelector(`[data-check="${CSS.escape(key)}"]`);
+    if (!chk || !chk.checked) return;
+    const val = String(el.value ?? '').trim();
+    if (val) obj[key] = val;
+  });
+  document.querySelectorAll('[data-custom-row]').forEach(row => {
+    const id = row.dataset.customRow;
+    const key = (row.querySelector(`[data-ck="${id}"]`)?.value || '').trim();
+    const val = (row.querySelector(`[data-cv="${id}"]`)?.value || '').trim();
+    if (row.dataset.enabled === '1' && safeKey(key) && val) obj[key] = val;
+  });
+  return obj;
+}
+
+function generateBundle() {
+  const obj = collect();
+  const keys = Object.keys(obj).sort();
+  const bundle = keys.length ? encodeBundle(Object.fromEntries(keys.map(k => [k, obj[k]]))) : '';
+  $('bundleOut').value = bundle;
+  $('envLineOut').value = bundle ? `${BUNDLE_KEY}=${bundle}` : '';
+}
+
+function refresh() {
+  // Refresh summary + counts — does NOT auto-regenerate bundle (requires explicit button click)
+  const obj = collect();
+  const keys = Object.keys(obj).sort();
+  const s = $('summary');
+  if (keys.length) {
+    s.innerHTML = `<strong>${keys.length}</strong> variable${keys.length > 1 ? 's' : ''} selected<div class="sum-keys">${keys.map(k => `<span class="sum-key">${esc(k)}</span>`).join('')}</div>`;
+  } else {
+    s.innerHTML = 'No variables selected yet.';
+  }
+  updateCounts();
+}
+
+function markSelected() {
+  document.querySelectorAll('[data-row]').forEach(r => r.classList.toggle('selected', !!r.querySelector('[data-check]')?.checked));
+}
+
+function updateCounts() {
+  document.querySelectorAll('[id^="nc_"]').forEach(el => el.textContent = '0');
+  const byGrp = {};
+  document.querySelectorAll('[data-check]:checked').forEach(ch => {
+    const g = ch.closest('[data-row]')?.dataset.group;
+    if (g) byGrp[g] = (byGrp[g] || 0) + 1;
+  });
+  const custOn = document.querySelectorAll('[data-custom-row][data-enabled="1"]').length;
+  const total = Object.values(byGrp).reduce((a, b) => a + b, 0) + custOn;
+  const allEl = document.getElementById('nc_All'); if (allEl) allEl.textContent = total;
+  Object.entries(byGrp).forEach(([g, c]) => {
+    const el = document.getElementById('nc_' + g.replace(/\W/g, '_'));
+    if (el) el.textContent = c;
+  });
+  const custEl = document.getElementById('nc_Custom_Env'); if (custEl) custEl.textContent = custOn;
+}
+
+function filter() {
+  const q = $('search').value.trim().toLowerCase();
+  document.querySelectorAll('.sec[data-section]').forEach(sec => {
+    const grp = sec.dataset.section;
+    const gMatch = activeGroup === 'All' || activeGroup === grp;
+    if (!gMatch) { sec.classList.add('sec-hidden'); return; }
+    let any = false;
+    sec.querySelectorAll('[data-row]').forEach(card => {
+      const m = !q || card.dataset.search.includes(q);
+      card.classList.toggle('hidden', !m);
+      if (m) any = true;
+    });
+    sec.classList.toggle('sec-hidden', !any);
+  });
+  const cs = $('customSec');
+  if (cs) cs.style.display = (activeGroup === 'All' || activeGroup === 'Custom Env') ? '' : 'none';
+  document.querySelectorAll('.nav-btn').forEach(b => b.classList.toggle('active', b.dataset.group === activeGroup));
+}
+
+function clearForm() {
+  document.querySelectorAll('[data-check]').forEach(c => c.checked = false);
+  document.querySelectorAll('[data-key]').forEach(el => {
+    if (el.closest('[data-toggle-row]')) {
+      el.value = 'false';
+      const btn = el.closest('.toggle-shell')?.querySelector('[data-toggle]');
+      if (btn) { btn.textContent = 'Off'; btn.classList.remove('on'); }
+      return;
+    }
+    el.value = '';
+  });
+  $('customRows').innerHTML = '';
+  customCount = 0;
+  addCustomRow();
+}
+
+function applyObj(obj, replace = false) {
+  if (replace) clearForm();
+  for (const [key, val] of Object.entries(obj || {})) {
+    if (!safeKey(key)) continue;
+    const inp = getFieldValueInput(key);
+    const chk = document.querySelector(`[data-check="${CSS.escape(key)}"]`);
+    if (inp && chk) {
+      inp.value = val;
+      chk.checked = true;
+      const btn = inp.closest('[data-toggle-row]')?.querySelector('[data-toggle]');
+      if (btn) {
+        const on = String(val).trim().toLowerCase() === 'true';
+        btn.textContent = on ? 'On' : 'Off';
+        btn.classList.toggle('on', on);
+        inp.value = on ? 'true' : 'false';
+      }
+    } else {
+      addCustomRow(key, val, true);
+    }
+  }
+  markSelected(); filter(); refresh();
+}
+
+function autoCheck(key) {
+  const chk = document.querySelector(`[data-check="${CSS.escape(key)}"]`);
+  if (chk && !chk.checked) { chk.checked = true; markSelected(); }
+}
+
+function handlePickerChange(sel) {
+  const key = sel.dataset.pickFor;
+  const value = sel.value;
+  if (!key || !value || value === '__custom__') { if (value === '__custom__') sel.value = ''; return; }
+  const inp = getFieldValueInput(key);
+  if (!inp) return;
+  inp.value = value;
+  sel.value = '';
+  autoCheck(key);
+  refresh();
+}
+
+function promptCustomModel(btn) {
+  const key = btn.dataset.customFor;
+  const inp = getFieldValueInput(key);
+  if (!inp) return;
+  const text = prompt('Enter a custom value', '');
+  if (text === null) return;
+  const val = String(text).trim();
+  if (!val) return;
+  inp.value = val;
+  autoCheck(key);
+  refresh();
+}
+
+function resetPickerField(btn) {
+  const key = btn.dataset.clearFor;
+  const inp = getFieldValueInput(key);
+  if (!inp) return;
+  if (inp.closest('[data-toggle-row]')) {
+    inp.value = 'false';
+    const toggleBtn = inp.closest('.toggle-shell')?.querySelector('[data-toggle]');
+    if (toggleBtn) { toggleBtn.textContent = 'Off'; toggleBtn.classList.remove('on'); }
+  } else {
+    inp.value = '';
+  }
+  refresh();
+}
+
+function toggleField(key) {
+  const inp = getFieldValueInput(key);
+  if (!inp) return;
+  const on = String(inp.value || '').trim().toLowerCase() !== 'true';
+  inp.value = on ? 'true' : 'false';
+  const btn = inp.closest('.toggle-shell')?.querySelector('[data-toggle]');
+  if (btn) { btn.textContent = on ? 'On' : 'Off'; btn.classList.toggle('on', on); }
+  const chk = document.querySelector(`[data-check="${CSS.escape(key)}"]`);
+  if (chk) { chk.checked = on; markSelected(); }
+  refresh();
+}
+
+function bindFieldEvents() {
+  document.querySelectorAll('[data-check]').forEach(el => el.addEventListener('change', () => { markSelected(); refresh(); }));
+  document.querySelectorAll('[data-key]').forEach(el => el.addEventListener('input', refresh));
+  document.querySelectorAll('[data-toggle]').forEach(btn => btn.addEventListener('click', () => toggleField(btn.dataset.toggle)));
+  document.querySelectorAll('[data-pick-for]').forEach(sel => sel.addEventListener('change', () => handlePickerChange(sel)));
+  document.querySelectorAll('[data-custom-for]').forEach(btn => btn.addEventListener('click', () => promptCustomModel(btn)));
+  document.querySelectorAll('[data-clear-for]').forEach(btn => btn.addEventListener('click', () => resetPickerField(btn)));
+}
+
+function renderSections() {
+  const grouped = {};
+  FIELDS.forEach(f => { (grouped[f.g] ||= []).push(f); });
+  const wrap = $('sections');
+  wrap.innerHTML = '';
+  Object.entries(grouped).forEach(([grp, items]) => {
+    const sec = document.createElement('div');
+    sec.className = 'sec';
+    sec.dataset.section = grp;
+    sec.innerHTML = `<div class="sec-header">
+      <span class="sec-icon">${ICONS[grp] || '📁'}</span>
+      <span class="sec-title">${esc(grp)}</span>
+      <div class="sec-line"></div>
+    </div>
+    <div class="cards">${items.map(cardHTML).join('')}</div>`;
+    wrap.appendChild(sec);
+  });
+  bindFieldEvents();
+}
+
+function copyText(text) {
+  return navigator.clipboard.writeText(text).then(
+    () => showToast('Copied ✓'),
+    () => {
+      const ta = document.createElement('textarea');
+      ta.value = text;
+      ta.style.position = 'fixed';
+      ta.style.left = '-9999px';
+      document.body.appendChild(ta);
+      ta.select();
+      document.execCommand('copy');
+      ta.remove();
+      showToast('Copied ✓');
+    }
+  );
+}
+
+// ── Init ──
+renderSidebar();
+renderSections();
+addCustomRow();
+filter();
+refresh();
+
+// ── Events ──
+$('search').oninput = filter;
+$('selectRequired').onclick = () => {
+  document.querySelectorAll('[data-critical="1"]').forEach(c => c.checked = true);
+  markSelected(); refresh();
+  showToast('Critical fields selected ✓');
+};
+$('selectCommon').onclick = () => {
+  document.querySelectorAll('[data-common="1"]').forEach(c => c.checked = true);
+  markSelected(); refresh();
+};
+$('selectVisible').onclick = () => {
+  document.querySelectorAll('.sec:not(.sec-hidden) [data-row]:not(.hidden) [data-check]').forEach(c => c.checked = true);
+  markSelected(); refresh();
+};
+$('clearAll').onclick = () => { clearForm(); markSelected(); filter(); refresh(); };
+$('generateBundle').onclick = () => { generateBundle(); showToast('Bundle generated ✓'); };
+$('applyImport').onclick = () => {
+  try { applyObj(parseEnv($('importText').value), true); showToast('Imported ✓'); }
+  catch (e) { showToast('Import failed'); alert(e.message); }
+};
+$('importText').addEventListener('paste', () => {
+  setTimeout(() => {
+    try {
+      const val = $('importText').value.trim();
+      if (!val) return;
+      applyObj(parseEnv(val), true);
+      showToast('Auto-imported ✓');
+    } catch (e) { showToast('Import failed'); }
+  }, 0);
+});
+$('importText').addEventListener('input', () => {
+  const val = $('importText').value.trim();
+  if (!val) return;
+  const looksLikeEnv = val.includes('=') || val.startsWith('{') || /^[A-Za-z0-9_\-]{20,}$/.test(val);
+  if (looksLikeEnv) {
+    try { applyObj(parseEnv(val), true); } catch (e) { /* silent */ }
+  }
+});
+$('addCustom').onclick = () => addCustomRow();
+$('applyBundle').onclick = () => {
+  try { applyObj(decodeBundle($('bundleOut').value), true); showToast('Bundle applied ✓'); }
+  catch (e) { showToast('Invalid bundle'); }
+};
+$('copyBundle').onclick = () => copyText($('bundleOut').value);
+$('copyEnvLine').onclick = () => copyText($('envLineOut').value);
+$('copyJson').onclick = () => copyText(JSON.stringify(collect(), null, 2));

health-server.js

@@ -0,0 +1,979 @@
+"use strict";
+
+const http = require("http");
+const https = require("https");
+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 JUPYTER_PORT = 8888;
+const GATEWAY_HOST = "127.0.0.1";
+const TERMINAL_BASE = "/terminal";
+const startTime = Date.now();
+const API_SERVER_KEY = process.env.API_SERVER_KEY || "";
+const APP_BASE = "/app";
+const LOGIN_PATH = "/login";
+const SESSION_COOKIE = "huggingmes_session";
+
+// ── Private Space redirect support ──
+const SPACE_ID = (process.env.SPACE_ID || "").trim();
+function deriveHfSpaceUrl() {
+  if (SPACE_ID) return `https://huggingface.co/spaces/${SPACE_ID}`;
+  const host = (process.env.SPACE_HOST || "").replace(/\.hf\.space$/i, "");
+  const author = (process.env.SPACE_AUTHOR_NAME || "").trim().toLowerCase();
+  if (author && host.toLowerCase().startsWith(author + "-")) {
+    const spaceName = host.slice(author.length + 1);
+    return `https://huggingface.co/spaces/${process.env.SPACE_AUTHOR_NAME}/${spaceName}`;
+  }
+  return "";
+}
+const HF_SPACE_URL = deriveHfSpaceUrl();
+
+// Privacy detection priority:
+//   1. SPACE_PRIVACY env var ("public"/"private") — explicit override, skip API call
+//   2. HF API auto-detect with retry
+//   3. Fail-secure: treat as private if SPACE_ID set
+const _spacPrivacyEnv = (process.env.SPACE_PRIVACY || "").trim().toLowerCase();
+let SPACE_IS_PRIVATE;
+let _privacyDetectionDone = false;
+let _privacyDetectionResolve;
+const privacyDetectionReady = new Promise((res) => { _privacyDetectionResolve = res; });
+
+if (_spacPrivacyEnv === "public") {
+  SPACE_IS_PRIVATE = false;
+  _privacyDetectionDone = true;
+  console.log("[health-server] Space privacy: public (SPACE_PRIVACY env override)");
+  _privacyDetectionResolve();
+} else if (_spacPrivacyEnv === "private") {
+  SPACE_IS_PRIVATE = true;
+  _privacyDetectionDone = true;
+  console.log("[health-server] Space privacy: private (SPACE_PRIVACY env override)");
+  _privacyDetectionResolve();
+} else {
+  // Fail-secure default until API call resolves
+  SPACE_IS_PRIVATE = !!SPACE_ID;
+}
+
+async function detectSpacePrivacy() {
+  if (_spacPrivacyEnv === "public" || _spacPrivacyEnv === "private") return;
+  if (!SPACE_ID) {
+    SPACE_IS_PRIVATE = false;
+    _privacyDetectionDone = true;
+    _privacyDetectionResolve();
+    return;
+  }
+  const token = (process.env.HF_TOKEN || "").trim();
+  const reqOptions = {
+    hostname: "huggingface.co",
+    path: `/api/spaces/${SPACE_ID}`,
+    method: "GET",
+    headers: Object.assign(
+      { "User-Agent": "HuggingMes/health-server" },
+      token ? { Authorization: `Bearer ${token}` } : {}
+    ),
+  };
+  const MAX_ATTEMPTS = 5;
+  let detected = false;
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    try {
+      const result = await new Promise((resolve) => {
+        const r = https.request(reqOptions, (apiRes) => {
+          let body = "";
+          apiRes.on("data", (chunk) => { body += chunk; });
+          apiRes.on("end", () => {
+            try {
+              if (apiRes.statusCode === 200) {
+                SPACE_IS_PRIVATE = JSON.parse(body).private === true;
+                resolve({ ok: true });
+              } else if (apiRes.statusCode === 401 || apiRes.statusCode === 403) {
+                SPACE_IS_PRIVATE = true;
+                resolve({ ok: true });
+              } else {
+                resolve({ ok: false });
+              }
+            } catch { resolve({ ok: false }); }
+          });
+        });
+        r.on("error", () => resolve({ ok: false }));
+        r.setTimeout(8000, () => { r.destroy(); resolve({ ok: false }); });
+        r.end();
+      });
+      console.log(`[health-server] Privacy detection attempt ${attempt}/${MAX_ATTEMPTS}: ok=${result.ok}`);
+      if (result.ok) { detected = true; break; }
+    } catch {}
+    const delay = Math.min(2000 * attempt, 10000);
+    if (attempt < MAX_ATTEMPTS) await new Promise((r) => setTimeout(r, delay));
+  }
+  if (!detected) {
+    console.warn(`[health-server] Privacy detection failed after ${MAX_ATTEMPTS} attempts — defaulting to ${SPACE_IS_PRIVATE ? "private" : "public"}. TIP: Set SPACE_PRIVACY=public in Space secrets to skip API detection.`);
+  } else {
+    console.log(`[health-server] Space privacy detected: ${SPACE_IS_PRIVATE ? "private" : "public"}`);
+  }
+  _privacyDetectionDone = true;
+  _privacyDetectionResolve();
+}
+
+if (_spacPrivacyEnv !== "public" && _spacPrivacyEnv !== "private") {
+  detectSpacePrivacy();
+  setInterval(detectSpacePrivacy, 5 * 60 * 1000);
+}
+
+const CLOUDFLARE_KEEPALIVE_STATUS_FILE =
+  "/tmp/huggingmes-cloudflare-keepalive-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 timingSafeEqualString(left, right) {
+  if (!left || !right) return false;
+  const leftBuffer = Buffer.from(left);
+  const rightBuffer = Buffer.from(right);
+  if (leftBuffer.length !== rightBuffer.length) return false;
+  return crypto.timingSafeEqual(leftBuffer, rightBuffer);
+}
+
+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 separator = item.indexOf("=");
+    if (separator < 0) continue;
+    const name = item.slice(0, separator).trim();
+    const value = item.slice(separator + 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) {
+  if (!value || typeof value !== "string") return `${APP_BASE}/`;
+  if (!value.startsWith("/") || value.startsWith("//")) return `${APP_BASE}/`;
+  return value;
+}
+
+function loginUrl(nextPath) {
+  return `${LOGIN_PATH}?next=${encodeURIComponent(sanitizeNext(nextPath))}`;
+}
+
+function renderLoginPage(nextPath, errorMessage = "") {
+  const safeNext = sanitizeNext(nextPath);
+  return `<!doctype html><html lang="en"><head>
+  <meta charset="utf-8"/><meta name="viewport" content="width=device-width,initial-scale=1"/>
+  <title>HuggingMes</title>
+  <style>
+    :root{color-scheme:dark;--bg:#08080f;--panel:#12111b;--line:#26243a;--text:#f6f4ff;--muted:#7f7a9e;--bad:#fb7185}
+    *{box-sizing:border-box}body{margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;font-family:Inter,ui-sans-serif,system-ui,-apple-system,sans-serif;background:var(--bg);color:var(--text);padding:24px}
+    .card{border:1px solid var(--line);background:var(--panel);border-radius:14px;padding:36px 32px;max-width:400px;width:100%;text-align:center}
+    h1{margin:0 0 8px;font-size:1.4rem}
+    .sub{color:var(--muted);font-size:.82rem;margin:0 0 24px}
+    .row{display:flex;gap:8px;margin-top:16px}
+    input{flex:1;background:#0d0c18;border:1px solid var(--line);border-radius:7px;padding:10px 12px;color:var(--text);font-size:.95rem;outline:none;transition:border-color .15s}
+    input:focus{border-color:#6366f1}
+    button{background:#fff;color:#000;border:none;border-radius:7px;padding:10px 20px;font-weight:700;font-size:.95rem;cursor:pointer;transition:opacity .15s;white-space:nowrap}
+    button:hover{opacity:.85}
+    .err{color:var(--bad);font-size:.82rem;margin-top:10px}
+    code{background:#232234;border:1px solid #34324c;border-radius:5px;padding:2px 6px;font-size:.88em}
+  </style></head><body>
+  <div class="card">
+    <h1>🪽 HuggingMes</h1>
+    <p class="sub">Enter your <code>GATEWAY_TOKEN</code> to continue</p>
+    <form method="post" action="${LOGIN_PATH}">
+      <input type="hidden" name="next" value="${escapeHtml(safeNext)}" />
+      <div class="row">
+        <input type="password" name="token" placeholder="GATEWAY_TOKEN" autofocus autocomplete="current-password" required>
+        <button type="submit">Unlock</button>
+      </div>
+      ${errorMessage ? `<p class="err">Invalid token — try again</p>` : ""}
+    </form>
+  </div>
+</body></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);
+  });
+}
+
+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;
+}
+
+function wantsHtml(req) {
+  const accept = String(req.headers.accept || "");
+  return accept.includes("text/html");
+}
+
+async function handleLogin(req, res, parsed) {
+  const nextPath = sanitizeNext(
+    parsed.searchParams.get("next") || `${APP_BASE}/`,
+  );
+
+  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 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();
+}
+
+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));
+  return {
+    ok: gateway,
+    uptime: formatUptime(Date.now() - startTime),
+    startedAt: new Date(startTime).toISOString(),
+    gateway,
+    dashboard,
+    authConfigured: !!API_SERVER_KEY,
+    ports: {
+      public: PORT,
+      gateway: GATEWAY_PORT,
+      dashboard: DASHBOARD_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",
+    keepalive: readJson(CLOUDFLARE_KEEPALIVE_STATUS_FILE, null),
+  };
+}
+
+function renderPrivateRedirect(targetUrl) {
+  const safeUrl = escapeHtml(targetUrl);
+  return `<!doctype html><html lang="en"><head>
+  <meta charset="utf-8"/><meta name="viewport" content="width=device-width,initial-scale=1"/>
+  <meta http-equiv="refresh" content="3;url=${safeUrl}"/>
+  <title>HuggingMes — Private Space</title>
+  <style>
+    :root{color-scheme:dark}
+    body{margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;
+         font-family:Inter,ui-sans-serif,system-ui,-apple-system,sans-serif;
+         background:#08080f;color:#f6f4ff;text-align:center;padding:24px}
+    .card{border:1px solid #26243a;background:#12111b;border-radius:14px;padding:36px 32px;max-width:440px}
+    h1{margin:0 0 12px;font-size:1.5rem}
+    p{color:#b8b3d7;line-height:1.6;margin:0 0 24px}
+    .btn{display:inline-flex;align-items:center;justify-content:center;
+         background:#fff;color:#000;font-weight:850;font-size:.95rem;
+         border-radius:8px;padding:12px 28px;text-decoration:none;transition:opacity .15s}
+    .btn:hover{opacity:.85}
+    .sub{color:#7f7a9e;font-size:.78rem;margin-top:16px}
+  </style></head><body>
+  <div class="card">
+    <h1>🔒 Private Space</h1>
+    <p>This HuggingFace Space is private. You need to be logged in to <strong>huggingface.co</strong> to access it.<br><br>Redirecting you now&hellip;</p>
+    <a class="btn" href="${safeUrl}">Open on Hugging Face →</a>
+    <div class="sub">Redirecting in 3 seconds&hellip;</div>
+  </div>
+  <script>
+    // Only auto-redirect when NOT inside an iframe — navigating an iframe to
+    // huggingface.co is blocked by X-Frame-Options and causes "refused to connect".
+    const _inFrame = (() => { try { return window.top !== window.self; } catch { return true; } })();
+    if (!_inFrame) {
+      setTimeout(() => { window.location.replace(${JSON.stringify(targetUrl)}); }, 100);
+    }
+  </script>
+</body></html>`;
+}
+
+function badge(label, state) {
+  return `<span class="badge ${state ? "ok" : "off"}">${escapeHtml(label)}</span>`;
+}
+
+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 renderDashboard(data) {
+  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 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 serviceOk = data.gateway && data.dashboard;
+
+  const tiles = [
+    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: "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</title>
+  <style>
+    :root { color-scheme: dark; --bg:#08080f; --panel:#12111b; --panel2:#151421; --line:#26243a; --text:#f6f4ff; --muted:#7f7a9e; --soft:#b8b3d7; --good:#22c55e; --warn:#f5c542; --bad:#fb7185; --accent:#6557df; --accent2:#7c6cf2; }
+    * { 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; line-height:1; letter-spacing:0; }
+    .subtitle { margin-top:12px; color:var(--muted); font-size:.72rem; text-transform:uppercase; letter-spacing:.14em; font-weight:800; }
+    .hero-buttons { display:flex; gap:10px; margin:24px 0 20px; }
+    .hero-action { display:flex; flex:1; min-height:46px; align-items:center; justify-content:center; border-radius:8px; background:#ffffff; color:#000000; text-decoration:none; font-weight:850; font-size:.98rem; transition:background 0.15s ease; }
+    .hero-action:hover { background:#e5e5e5; }
+    .hero-action.secondary { background:var(--panel); color:var(--text); border:1px solid var(--line); }
+    .hero-action.secondary:hover { background:var(--panel2); }
+    .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; }
+
+    code { background:#232234; border:1px solid #34324c; border-radius:6px; padding:2px 6px; color:var(--text); font-size:.9em; }
+    pre { margin:0; white-space:pre-wrap; overflow-wrap:anywhere; background:#0d0d0d; border:1px solid var(--line); border-radius:7px; padding:10px; color:var(--soft); font-size:.82rem; line-height:1.45; }
+    .row { display:flex; flex-wrap:wrap; gap:8px; align-items:center; }
+    .badge { display:inline-flex; align-items:center; width:max-content; 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); }
+    .button { display:inline-flex; align-items:center; justify-content:center; min-height:40px; padding:0 16px; border-radius:8px; color:#fff; background:var(--accent); text-decoration:none; font-weight:850; font-size:.9rem; }
+    .button.secondary { color:var(--text); background:#242424; border:1px solid var(--line); }
+    footer { color:var(--muted); text-align:center; font-size:.74rem; margin-top:18px; }
+    footer .live { color:var(--good); }
+    .warn-banner { background:rgba(245,197,66,.1); border:1px solid rgba(245,197,66,.35); border-radius:8px; padding:10px 14px; margin-bottom:16px; color:var(--warn); font-size:.82rem; line-height:1.5; }
+    .warn-banner strong { font-weight:700; }
+    @media (max-width: 700px) { .overview { grid-template-columns:1fr; } main { width:min(100% - 22px, 720px); padding-top:28px; } }
+  </style>
+</head>
+<body>
+  <main>
+    <header>
+      <h1>HuggingMes</h1>
+      <div class="subtitle">Self-hosted - Hermes Agent</div>
+    </header>
+    <div class="hero-buttons">
+      <a class="hero-action" data-space-link="app" href="${APP_BASE}/">Open Hermes Agent →</a>
+      <a class="hero-action secondary" data-space-link="terminal" href="/terminal/">💻 Open Terminal →</a>
+      <a class="hero-action secondary" data-space-link="env-builder" href="/env-builder">⚙️ ENV Builder →</a>
+    </div>
+    <section class="overview">
+      ${tiles}
+    </section>
+    <footer>Built by <a href="https://github.com/somratpro" target="_blank" rel="noopener noreferrer" style="color: var(--accent); text-decoration: none;">@somratpro</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();
+      }
+    });
+    const inEmbeddedApp = (() => { try { return window.top !== window.self; } catch { return true; } })();
+    const isDirectHfSpaceHost = /\.hf\.space$/i.test(window.location.hostname);
+    const HF_SPACE_URL = ${JSON.stringify(HF_SPACE_URL)};
+    // Server-side value may be stale if privacy detection raced — syncPrivacy() corrects it.
+    let SPACE_IS_PRIVATE = ${JSON.stringify(SPACE_IS_PRIVATE)};
+
+    function applyLinkTargets() {
+      const openInNewTab = !SPACE_IS_PRIVATE && (inEmbeddedApp || isDirectHfSpaceHost);
+      document.querySelectorAll('a[data-space-link]').forEach((a) => {
+        if (openInNewTab) {
+          a.setAttribute('target', '_blank');
+          a.setAttribute('rel', 'noopener noreferrer');
+        } else {
+          a.removeAttribute('target');
+          a.removeAttribute('rel');
+        }
+      });
+    }
+    applyLinkTargets();
+
+    function syncPrivacy() {
+      return fetch('/api/is-private', { cache: 'no-store' })
+        .then(r => r.json())
+        .then(d => {
+          if (d.isPrivate !== SPACE_IS_PRIVATE) {
+            SPACE_IS_PRIVATE = d.isPrivate;
+            applyLinkTargets();
+          }
+          return d.isPrivate;
+        })
+        .catch(() => SPACE_IS_PRIVATE);
+    }
+
+    if (isDirectHfSpaceHost) {
+      syncPrivacy().then(isPrivate => {
+        if (isPrivate) {
+          setTimeout(syncPrivacy, 8000);
+          setTimeout(syncPrivacy, 16000);
+        }
+      });
+    }
+
+    // Private redirect — only when NOT in iframe (huggingface.co has X-Frame-Options: DENY)
+    if (SPACE_IS_PRIVATE && isDirectHfSpaceHost && !inEmbeddedApp && HF_SPACE_URL) {
+      const notice = document.createElement('div');
+      notice.style.cssText = 'position:fixed;inset:0;display:flex;align-items:center;justify-content:center;background:#08080f;color:#f6f4ff;font-family:sans-serif;flex-direction:column;gap:16px;z-index:9999';
+      notice.innerHTML = '<span style="font-size:1.1rem">🔒 Private Space &mdash; Redirecting&hellip;</span><a href="' + HF_SPACE_URL + '" style="color:#a5b4fc;font-size:.85rem">Click here if not redirected</a>';
+      document.body.appendChild(notice);
+      setTimeout(() => { window.location.replace(HF_SPACE_URL); }, 300);
+    }
+  </script>
+</body>
+</html>`;
+}
+
+const server = http.createServer(async (req, res) => {
+  const parsed = new URL(req.url, "http://localhost");
+  const path = parsed.pathname;
+
+  // Lightweight endpoint for client-side privacy fallback.
+  // Called by dashboard JS to correct stale server-rendered SPACE_IS_PRIVATE value.
+  // No auth required — not sensitive.
+  if (path === "/api/is-private") {
+    if (!_privacyDetectionDone) await privacyDetectionReady;
+    res.writeHead(200, { "content-type": "application/json", "cache-control": "no-store" });
+    return res.end(JSON.stringify({ isPrivate: SPACE_IS_PRIVATE }));
+  }
+
+  if (path === LOGIN_PATH) {
+    await handleLogin(req, res, parsed);
+    return;
+  }
+
+  // ── Private Space Guard (server-side) ──
+  // Intercepts browser HTML requests from raw .hf.space hosts when the Space is private.
+  // /health and /status are always exempt so uptime monitors keep working.
+  const isHtmlReq = (req.headers.accept || "").includes("text/html");
+
+  // RACE CONDITION FIX: await privacy detection before computing redirect logic.
+  // Without this, the fail-secure default (SPACE_IS_PRIVATE=true when SPACE_ID is set)
+  // causes public spaces to redirect during the brief window before API detection completes.
+  if (isHtmlReq && !_privacyDetectionDone) {
+    await Promise.race([
+      privacyDetectionReady,
+      new Promise((r) => setTimeout(r, 1500)),
+    ]);
+  }
+
+  // In-app navigation from same origin or HF App iframe — skip private redirect.
+  const referer = req.headers.referer || req.headers.referrer || "";
+  const isSameOriginNav = !!(referer && typeof req.headers.host === "string" &&
+    referer.startsWith(`https://${req.headers.host}`));
+  const isFromHFApp = !!(referer && (
+    referer.startsWith("https://huggingface.co") ||
+    referer.startsWith("https://hf.co")
+  ));
+
+  const isDirectHfSpaceReq = SPACE_IS_PRIVATE &&
+    HF_SPACE_URL &&
+    isHtmlReq &&
+    !isSameOriginNav &&
+    !isFromHFApp &&
+    typeof req.headers.host === "string" &&
+    req.headers.host.endsWith(".hf.space");
+
+  if (path === "/hf-redirect" || path === "/hf-redirect/") {
+    if (HF_SPACE_URL) {
+      res.writeHead(302, { location: HF_SPACE_URL, "cache-control": "no-store" });
+      return res.end();
+    }
+    res.writeHead(404, { "content-type": "text/plain" });
+    return res.end("SPACE_ID not configured.");
+  }
+
+  if (path === "/health" || path === `${APP_BASE}/health`) {
+    const data = await statusPayload();
+    // Always 200 — health server up means the app is running.
+    // Gateway readiness is in the JSON body (gateway: true/false).
+    // Returning 503 here caused Docker HEALTHCHECK to fail during gateway
+    // startup, keeping HF Space stuck in RUNNING_APP_STARTING indefinitely.
+    res.writeHead(200, { "content-type": "application/json" });
+    res.end(
+      JSON.stringify({
+        ok: data.ok,
+        gateway: data.gateway,
+        uptime: data.uptime,
+      }),
+    );
+    return;
+  }
+
+  if (path === "/status" || path === `${APP_BASE}/status`) {
+    const data = await statusPayload();
+    res.writeHead(200, { "content-type": "application/json" });
+    res.end(JSON.stringify(data, null, 2));
+    return;
+  }
+
+  if (path === "/env-builder" || path === "/env-builder/") {
+    if (!requireAuth(req, res)) return;
+    try {
+      const html = fs.readFileSync(require("path").join(__dirname, "env-builder.html"), "utf8");
+      res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+      res.end(html);
+    } catch (e) {
+      res.writeHead(404, { "content-type": "text/plain" });
+      res.end("env-builder.html not found");
+    }
+    return;
+  }
+
+  if (path === "/env-builder.js") {
+    if (!requireAuth(req, res)) return;
+    try {
+      const js = fs.readFileSync(require("path").join(__dirname, "env-builder.js"), "utf8");
+      res.writeHead(200, { "content-type": "application/javascript; charset=utf-8" });
+      res.end(js);
+    } catch (e) {
+      res.writeHead(404, { "content-type": "text/plain" });
+      res.end("env-builder.js not found");
+    }
+    return;
+  }
+
+  if (path === "/") {
+    if (isDirectHfSpaceReq) {
+      res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+      return res.end(renderPrivateRedirect(HF_SPACE_URL));
+    }
+    const data = await statusPayload();
+    res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+    res.end(renderDashboard(data));
+    return;
+  }
+
+  if (path === "/dashboard" || path === "/dashboard/") {
+    redirect(res, `${APP_BASE}/${parsed.search}`);
+    return;
+  }
+
+  if (path === "/telegram" || path.startsWith("/telegram/")) {
+    proxyRequest(req, res, TELEGRAM_WEBHOOK_PORT);
+    return;
+  }
+
+  if (path === APP_BASE || path.startsWith(`${APP_BASE}/`)) {
+    if (!requireAuth(req, res)) return;
+    proxyRequest(
+      req,
+      res,
+      DASHBOARD_PORT,
+      (p) => p.replace(/^\/app/, "") || "/",
+    );
+    return;
+  }
+
+  if (
+    path === "/favicon.ico" ||
+    path.startsWith("/assets/") ||
+    path.startsWith("/api/") ||
+    path.startsWith("/dashboard-plugins/") ||
+    path.startsWith("/ds-assets/")
+  ) {
+    if (!requireAuth(req, res)) return;
+    proxyRequest(req, res, DASHBOARD_PORT);
+    return;
+  }
+
+  if (
+    [
+      "/analytics",
+      "/chat",
+      "/config",
+      "/cron",
+      "/docs",
+      "/env",
+      "/logs",
+      "/models",
+      "/plugins",
+      "/profiles",
+      "/sessions",
+      "/skills",
+    ].some((route) => path === route || path.startsWith(`${route}/`))
+  ) {
+    redirect(res, `${APP_BASE}${path}${parsed.search}`);
+    return;
+  }
+
+  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;
+  }
+
+  if (path === TERMINAL_BASE || path.startsWith(`${TERMINAL_BASE}/`)) {
+    if (!requireAuth(req, res)) return;
+    canConnect(JUPYTER_PORT).then((up) => {
+      if (!up) {
+        res.writeHead(503, { "content-type": "text/plain; charset=utf-8" });
+        res.end("JupyterLab is not running. GATEWAY_TOKEN must be set, and DEV_MODE must not be false.");
+        return;
+      }
+      // Inject the Jupyter token so JupyterLab skips its own login screen.
+      // User already authenticated via GATEWAY_TOKEN — no second prompt needed.
+      // JUPYTER_TOKEN env may be empty in this process (health-server starts before
+      // start_jupyter() exports it), so fall back to API_SERVER_KEY (== GATEWAY_TOKEN),
+      // which is what JupyterLab was actually started with.
+      const rawJToken = (process.env.JUPYTER_TOKEN || "").trim();
+      const jToken = rawJToken || API_SERVER_KEY;
+      // JupyterLab 4.x ignores the Authorization header for HTML page loads and
+      // shows its own login screen. The reliable fix is to inject ?token= into the
+      // URL for the initial HTML request — Jupyter reads it, sets the auth cookie,
+      // then redirects to the clean URL. All subsequent requests use the cookie.
+      if (jToken && isHtmlReq) {
+        const parsed2 = new URL(req.url, "http://localhost");
+        if (!parsed2.searchParams.has("token")) {
+          const sep = parsed2.search ? "&" : "?";
+          redirect(res, `${parsed2.pathname}${parsed2.search}${sep}token=${encodeURIComponent(jToken)}`);
+          return;
+        }
+      }
+      const overrides = jToken ? { authorization: `token ${jToken}` } : {};
+      proxyRequest(req, res, JUPYTER_PORT, (p) => p, overrides);
+    });
+    return;
+  }
+
+  res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+  res.end("Not found");
+});
+
+// ── WebSocket upgrade (JupyterLab terminals + kernels need this) ──
+server.on("upgrade", (req, socket, head) => {
+  const { pathname } = new URL(req.url, "http://localhost");
+  const isJupyter = pathname === TERMINAL_BASE || pathname.startsWith(`${TERMINAL_BASE}/`);
+  const targetPort = isJupyter ? JUPYTER_PORT : GATEWAY_PORT;
+  const ps = net.createConnection(targetPort, GATEWAY_HOST, () => {
+    ps.write(`${req.method} ${req.url} HTTP/${req.httpVersion}\r\n`);
+    ps.write(`Host: ${GATEWAY_HOST}:${targetPort}\r\n`);
+    ps.write(`X-Forwarded-Host: ${req.headers.host || ""}\r\n`);
+    ps.write("X-Forwarded-Proto: https\r\n");
+    for (let i = 0; i < req.rawHeaders.length; i += 2) {
+      const lower = req.rawHeaders[i].toLowerCase();
+      if (["host", "x-forwarded-host", "x-forwarded-proto"].includes(lower)) continue;
+      ps.write(`${req.rawHeaders[i]}: ${req.rawHeaders[i + 1]}\r\n`);
+    }
+    ps.write("\r\n");
+    if (head && head.length) ps.write(head);
+    ps.pipe(socket).pipe(ps);
+  });
+  ps.on("error", () => socket.destroy());
+  ps.on("close", () => socket.destroy());
+  socket.on("error", () => ps.destroy());
+  socket.on("close", () => ps.destroy());
+});
+
+server.timeout = 0;
+server.keepAliveTimeout = 65000;
+server.listen(PORT, "0.0.0.0", () => {
+  console.log(`HuggingMes dashboard listening on 0.0.0.0:${PORT}`);
+});

start.sh

@@ -0,0 +1,772 @@
+#!/bin/bash
+set -euo pipefail
+
+umask 0077
+
+# ════════════════════════════════════════════════════════════════
+# HuggingMes — Hermes Gateway for HF Spaces
+# ════════════════════════════════════════════════════════════════
+
+# ── Startup Banner ──
+APP_DIR="${HUGGINGMES_APP_DIR:-/opt/huggingmes}"
+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}"
+CF_PROXY_ENV_FILE="/tmp/huggingmes-cloudflare-proxy.env"
+STARTUP_FILE="$HERMES_HOME/workspace/startup.sh"
+
+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
+
+echo ""
+echo "  ╔══════════════════════════════════════════╗"
+echo "  ║        🪽 HuggingMes Hermes Gateway      ║"
+echo "  ╚══════════════════════════════════════════╝"
+echo ""
+
+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 API token for this boot."
+  fi
+fi
+
+# ── Setup directories ──
+mkdir -p "$HERMES_HOME"/{cron,sessions,logs,hooks,memories,skills,skins,plans,workspace,home,plugins}
+
+# Expose hermes CLI in ~/.local/bin so login shells (terminal backend) find it.
+# Base image PATH includes /opt/data/.local/bin but hermes lives in the venv.
+mkdir -p "$HERMES_HOME/.local/bin"
+ln -sfn /opt/hermes/.venv/bin/hermes "$HERMES_HOME/.local/bin/hermes"
+
+# Redirect Hermes plugin dir into volume so plugins survive container restarts
+if [ ! -L "${HOME}/.hermes/plugins" ]; then
+  mkdir -p "${HOME}/.hermes"
+  rm -rf "${HOME}/.hermes/plugins"
+  ln -sfn "$HERMES_HOME/plugins" "${HOME}/.hermes/plugins"
+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..."
+  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
+
+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
+    export TELEGRAM_WEBHOOK_SECRET
+    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"
+    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|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#*/}"   # strip "google/" or "gemini/" prefix — Hermes gemini provider needs bare model name
+    ;;
+  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)
+    [ -n "$LLM_API_KEY" ] && export DASHSCOPE_API_KEY="${DASHSCOPE_API_KEY:-$LLM_API_KEY}"
+    ;;
+  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
+
+# ── Pool key promotion ──
+# Mirror first key from comma-separated pool vars into the singular env var.
+# Hermes providers read singular vars; this lets users supply pool keys like
+# ANTHROPIC_API_KEYS=key1,key2 and have them picked up automatically.
+promote_first_pool_key() {
+  local singular_var="$1"
+  local pool_var="$2"
+  local singular_val="${!singular_var:-}"
+  local pool_val="${!pool_var:-}"
+  [ -n "$singular_val" ] && return 0
+  [ -n "$pool_val" ] || return 0
+  local first
+  first=$(printf '%s' "$pool_val" | tr ',' '\n' | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//' | awk 'NF{print; exit}')
+  [ -n "$first" ] || return 0
+  export "${singular_var}=$first"
+}
+
+promote_first_pool_key "OPENROUTER_API_KEY"   "OPENROUTER_API_KEYS"
+promote_first_pool_key "ANTHROPIC_API_KEY"    "ANTHROPIC_API_KEYS"
+promote_first_pool_key "OPENAI_API_KEY"       "OPENAI_API_KEYS"
+promote_first_pool_key "GOOGLE_API_KEY"       "GOOGLE_API_KEYS"
+promote_first_pool_key "GEMINI_API_KEY"       "GEMINI_API_KEYS"
+promote_first_pool_key "DEEPSEEK_API_KEY"     "DEEPSEEK_API_KEYS"
+promote_first_pool_key "KIMI_API_KEY"         "KIMI_API_KEYS"
+promote_first_pool_key "MINIMAX_API_KEY"      "MINIMAX_API_KEYS"
+promote_first_pool_key "NVIDIA_API_KEY"       "NVIDIA_API_KEYS"
+promote_first_pool_key "XAI_API_KEY"          "XAI_API_KEYS"
+promote_first_pool_key "KILOCODE_API_KEY"     "KILOCODE_API_KEYS"
+promote_first_pool_key "GLM_API_KEY"          "GLM_API_KEYS"
+promote_first_pool_key "ARCEEAI_API_KEY"      "ARCEEAI_API_KEYS"
+promote_first_pool_key "DASHSCOPE_API_KEY"    "DASHSCOPE_API_KEYS"
+promote_first_pool_key "GMI_API_KEY"          "GMI_API_KEYS"
+promote_first_pool_key "TOKENHUB_API_KEY"     "TOKENHUB_API_KEYS"
+
+# ── Build config ──
+python3 - <<'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_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                          # always from env — deploy-time setting
+    if provider_name and provider_name != "auto":
+        model["provider"] = provider_name                  # explicit provider (openrouter, huggingface, custom…)
+    else:
+        model.pop("provider", None)                        # let Hermes infer from model-name prefix
+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()
+        ])
+
+path.write_text(yaml.safe_dump(config, sort_keys=False), encoding="utf-8")
+path.chmod(0o600)
+PY
+
+# ── Startup Summary ──
+HERMES_RUNTIME_VERSION="$(/opt/hermes/.venv/bin/hermes --version 2>/dev/null | awk '{print $NF; exit}' || true)"
+echo ""
+if [ -n "${HERMES_RUNTIME_VERSION:-}" ]; then
+  echo "Version   : ${HERMES_RUNTIME_VERSION}"
+fi
+echo "Model     : ${MODEL_FOR_CONFIG:-unset}"
+echo "Provider  : ${PROVIDER_FOR_CONFIG:-unset}"
+if [ -n "${TELEGRAM_BOT_TOKEN:-}" ]; then
+  if [ -n "${TELEGRAM_WEBHOOK_URL:-}" ]; then
+    echo "Telegram  : webhook"
+  else
+    echo "Telegram  : polling"
+  fi
+else
+  echo "Telegram  : not configured"
+fi
+if [ -n "${CLOUDFLARE_PROXY_URL:-}" ]; then
+  echo "Proxy     : ${CLOUDFLARE_PROXY_URL}"
+fi
+echo "Routes    : /app/ (Hermes UI), /terminal/ (JupyterLab)"
+echo "Dashboard : http://127.0.0.1:${DASHBOARD_PORT}"
+echo "Gateway   : http://127.0.0.1:${GATEWAY_API_PORT}"
+echo ""
+
+# ── JupyterLab terminal (on by default when GATEWAY_TOKEN is set) ──
+JUPYTER_PID=""
+start_jupyter() {
+  if [ "${DEV_MODE:-true}" = "false" ]; then
+    echo "JupyterLab disabled (DEV_MODE=false)."
+    return 0
+  fi
+  # Guard: skip if already running
+  if [ -n "${JUPYTER_PID:-}" ] && kill -0 "$JUPYTER_PID" 2>/dev/null; then
+    return 0
+  fi
+  local token="${JUPYTER_TOKEN:-${API_SERVER_KEY:-}}"
+  if [ -z "$token" ]; then
+    echo "WARNING: No GATEWAY_TOKEN or JUPYTER_TOKEN set — JupyterLab skipped (terminal would be unauthenticated)." >&2
+    return 0
+  fi
+  export JUPYTER_TOKEN="$token"
+  local VENV_PYTHON="/opt/hermes/.venv/bin/python"
+  if ! "$VENV_PYTHON" -c "import jupyterlab" >/dev/null 2>&1; then
+    echo "WARNING: jupyterlab not installed in venv; skipping terminal." >&2
+    return 0
+  fi
+  local root_dir="${JUPYTER_ROOT_DIR:-$HERMES_HOME/workspace}"
+  mkdir -p "$root_dir"
+  ln -sfn "$HERMES_HOME" "$root_dir/HuggingMes" 2>/dev/null || true
+  echo "Starting JupyterLab terminal on port 8888 (root: $root_dir)"
+  "$VENV_PYTHON" -m jupyterlab \
+    --ip 127.0.0.1 \
+    --port 8888 \
+    --no-browser \
+    --IdentityProvider.token="$JUPYTER_TOKEN" \
+    --ServerApp.base_url=/terminal/ \
+    --ServerApp.terminals_enabled=True \
+    --ServerApp.terminado_settings='{"shell_command":["/bin/bash","-i"]}' \
+    --ServerApp.allow_origin='*' \
+    --ServerApp.allow_remote_access=True \
+    --ServerApp.trust_xheaders=True \
+    --ServerApp.tornado_settings="{'headers': {'Content-Security-Policy': 'frame-ancestors *'}}" \
+    --IdentityProvider.cookie_options="{'SameSite': 'None', 'Secure': True}" \
+    --ServerApp.disable_check_xsrf=True \
+    --LabApp.news_url=None \
+    --LabApp.check_for_updates_class=jupyterlab.NeverCheckForUpdate \
+    --ServerApp.log_level=WARN \
+    --ServerApp.root_dir="$root_dir" \
+    >> "$HERMES_HOME/logs/jupyter.log" 2>&1 &
+  JUPYTER_PID=$!
+  export JUPYTER_PID
+  echo "JupyterLab started (PID: $JUPYTER_PID)"
+}
+
+# ── Trap SIGTERM for graceful shutdown ──
+DASHBOARD_PID=""
+graceful_shutdown() {
+  echo "Shutting down HuggingMes..."
+  kill $(jobs -p) 2>/dev/null || true
+  exit 0
+}
+trap graceful_shutdown SIGTERM SIGINT
+
+# ── Shell capture wrappers ──
+# Written to ~/.bashrc so terminal installs are recorded in workspace/startup.sh
+# and replayed on next boot — packages survive Space restarts.
+if [ ! -f "$STARTUP_FILE" ]; then
+  touch "$STARTUP_FILE"
+  chmod +x "$STARTUP_FILE"
+  echo "Created workspace/startup.sh"
+fi
+cat > "$HOME/.bashrc" << 'BASHRC'
+export PATH="/opt/hermes/.venv/bin:/opt/data/.local/bin:$PATH"
+export DEBIAN_FRONTEND="${DEBIAN_FRONTEND:-noninteractive}"
+if [ -z "${PS1:-}" ] || [ "$PS1" = "$ " ]; then
+  export PS1="\u@\h:\w\$ "
+fi
+
+HERMES_HOME="${HERMES_HOME:-/opt/data}"
+STARTUP_FILE="$HERMES_HOME/workspace/startup.sh"
+
+_hm_append() {
+  [ "${HUGGINGMES_CAPTURE_DISABLE:-0}" = "1" ] && return 0
+  local line="$*"
+  mkdir -p "$(dirname "$STARTUP_FILE")"
+  touch "$STARTUP_FILE"
+  chmod +x "$STARTUP_FILE" 2>/dev/null || true
+  grep -qxF "$line" "$STARTUP_FILE" 2>/dev/null || echo "$line" >> "$STARTUP_FILE"
+}
+_hm_quote_args() {
+  local quoted=()
+  local arg
+  for arg in "$@"; do
+    printf -v arg '%q' "$arg"
+    quoted+=("$arg")
+  done
+  printf '%s' "${quoted[*]}"
+}
+_hm_append_cmd() {
+  local cmd="$1"
+  shift
+  local args
+  args=$(_hm_quote_args "$@")
+  if [ -n "$args" ]; then
+    _hm_append "$cmd $args"
+  else
+    _hm_append "$cmd"
+  fi
+}
+_hm_args_without_flags() {
+  local out=()
+  for arg in "$@"; do
+    case "$arg" in
+      ''|-|--*|-*) ;;
+      *) out+=("$arg") ;;
+    esac
+  done
+  printf '%s\n' "${out[@]}"
+}
+_hm_has_install_targets() {
+  local item
+  while IFS= read -r item; do
+    [ -n "$item" ] && return 0
+  done <<EOF
+$(_hm_args_without_flags "$@")
+EOF
+  return 1
+}
+_hm_has_arg() {
+  local needle="$1"
+  shift
+  for arg in "$@"; do
+    [ "$arg" = "$needle" ] && return 0
+  done
+  return 1
+}
+_hm_can_sudo_apt() {
+  command -v sudo >/dev/null 2>&1 && sudo -n apt-get --version >/dev/null 2>&1
+}
+_hm_apt_install() {
+  if [ "$(id -u)" -eq 0 ]; then
+    command apt-get update && command apt-get install -y "$@"
+  elif _hm_can_sudo_apt; then
+    sudo apt-get update && sudo apt-get install -y "$@"
+  else
+    echo "Error: apt install needs root." >&2
+    return 1
+  fi
+}
+apt-get() {
+  case "${1:-}" in
+    install)
+      shift
+      _hm_apt_install "$@"
+      local rc=$?
+      if [ $rc -eq 0 ]; then
+        _hm_has_install_targets "$@" && _hm_append_cmd "sudo apt-get update && sudo apt-get install -y" "$@"
+      fi
+      return $rc
+      ;;
+    update)
+      if [ "$(id -u)" -eq 0 ]; then command apt-get "$@"
+      elif _hm_can_sudo_apt; then sudo apt-get "$@"
+      else command apt-get "$@"; fi
+      return $?
+      ;;
+    *) command apt-get "$@"; return $? ;;
+  esac
+}
+apt() {
+  case "${1:-}" in
+    install)
+      shift
+      _hm_apt_install "$@"
+      local rc=$?
+      if [ $rc -eq 0 ]; then
+        _hm_has_install_targets "$@" && _hm_append_cmd "sudo apt-get update && sudo apt-get install -y" "$@"
+      fi
+      return $rc
+      ;;
+    update)
+      if [ "$(id -u)" -eq 0 ]; then command apt "$@"
+      elif _hm_can_sudo_apt; then sudo apt "$@"
+      else command apt "$@"; fi
+      return $?
+      ;;
+    *) command apt "$@"; return $? ;;
+  esac
+}
+pip() {
+  command pip "$@"
+  local rc=$?
+  if [ $rc -eq 0 ] && [ "${1:-}" = "install" ] \
+      && ! _hm_has_arg -r "${@:2}" && ! _hm_has_arg --requirement "${@:2}" \
+      && _hm_has_install_targets "${@:2}"; then
+    _hm_append_cmd "pip install" "${@:2}"
+  fi
+  return $rc
+}
+pip3() {
+  command pip3 "$@"
+  local rc=$?
+  if [ $rc -eq 0 ] && [ "${1:-}" = "install" ] \
+      && ! _hm_has_arg -r "${@:2}" && ! _hm_has_arg --requirement "${@:2}" \
+      && _hm_has_install_targets "${@:2}"; then
+    _hm_append_cmd "pip install" "${@:2}"
+  fi
+  return $rc
+}
+uv() {
+  command uv "$@"
+  local rc=$?
+  if [ $rc -eq 0 ] && [ "${1:-}" = "pip" ] && [ "${2:-}" = "install" ] \
+      && ! _hm_has_arg -r "${@:3}" && ! _hm_has_arg --requirements "${@:3}" \
+      && _hm_has_install_targets "${@:3}"; then
+    _hm_append_cmd "uv pip install" "${@:3}"
+  fi
+  return $rc
+}
+npm() {
+  command npm "$@"
+  local rc=$?
+  if [ $rc -eq 0 ] && { [ "${1:-}" = "install" ] || [ "${1:-}" = "i" ]; } && { [ "${2:-}" = "-g" ] || [ "${2:-}" = "--global" ]; } && _hm_has_install_targets "${@:3}"; then
+    _hm_append_cmd "npm install -g" "${@:3}"
+  fi
+  return $rc
+}
+hermes() {
+  command hermes "$@"
+  local rc=$?
+  if [ $rc -eq 0 ] && [ "${1:-}" = "plugins" ] && [ "${2:-}" = "install" ] && _hm_has_install_targets "${@:3}"; then
+    _hm_append_cmd "hermes plugins install" "${@:3}"
+  fi
+  return $rc
+}
+BASHRC
+cat > "$HOME/.profile" << 'PROFILE'
+[ -n "${BASH_VERSION:-}" ] && [ -f ~/.bashrc ] && . ~/.bashrc
+PROFILE
+echo "Shell capture wrappers ready."
+
+# ── Optional package installs from HF Variables/Secrets ──
+HM_STARTUP_FAILURES=0
+
+if [ -n "${HUGGINGMES_APT_PACKAGES:-}" ]; then
+  echo "Installing apt packages from HUGGINGMES_APT_PACKAGES..."
+  read -r -a HM_APT_PACKAGES <<< "$HUGGINGMES_APT_PACKAGES"
+  if command -v sudo >/dev/null 2>&1; then
+    if sudo apt-get update && sudo apt-get install -y "${HM_APT_PACKAGES[@]}"; then
+      echo "HUGGINGMES_APT_PACKAGES install complete."
+    else
+      HM_STARTUP_FAILURES=$((HM_STARTUP_FAILURES + 1))
+      echo "ERROR: HUGGINGMES_APT_PACKAGES install failed: ${HUGGINGMES_APT_PACKAGES}" >&2
+    fi
+  elif [ "$(id -u)" -eq 0 ]; then
+    if apt-get update && apt-get install -y "${HM_APT_PACKAGES[@]}"; then
+      echo "HUGGINGMES_APT_PACKAGES install complete."
+    else
+      HM_STARTUP_FAILURES=$((HM_STARTUP_FAILURES + 1))
+      echo "ERROR: HUGGINGMES_APT_PACKAGES install failed: ${HUGGINGMES_APT_PACKAGES}" >&2
+    fi
+  else
+    HM_STARTUP_FAILURES=$((HM_STARTUP_FAILURES + 1))
+    echo "ERROR: root/sudo unavailable; HUGGINGMES_APT_PACKAGES skipped" >&2
+  fi
+fi
+
+if [ -n "${HUGGINGMES_PIP_PACKAGES:-}" ]; then
+  echo "Installing Python packages from HUGGINGMES_PIP_PACKAGES..."
+  read -r -a HM_PIP_PACKAGES <<< "$HUGGINGMES_PIP_PACKAGES"
+  if /opt/hermes/.venv/bin/pip install "${HM_PIP_PACKAGES[@]}"; then
+    echo "HUGGINGMES_PIP_PACKAGES install complete."
+  else
+    HM_STARTUP_FAILURES=$((HM_STARTUP_FAILURES + 1))
+    echo "ERROR: HUGGINGMES_PIP_PACKAGES install failed: ${HUGGINGMES_PIP_PACKAGES}" >&2
+  fi
+fi
+
+if [ -n "${HUGGINGMES_NPM_PACKAGES:-}" ]; then
+  echo "Installing npm packages from HUGGINGMES_NPM_PACKAGES..."
+  read -r -a HM_NPM_PACKAGES <<< "$HUGGINGMES_NPM_PACKAGES"
+  if npm install -g "${HM_NPM_PACKAGES[@]}"; then
+    echo "HUGGINGMES_NPM_PACKAGES install complete."
+  else
+    HM_STARTUP_FAILURES=$((HM_STARTUP_FAILURES + 1))
+    echo "ERROR: HUGGINGMES_NPM_PACKAGES install failed: ${HUGGINGMES_NPM_PACKAGES}" >&2
+  fi
+fi
+
+# ── Arbitrary startup script (HUGGINGMES_RUN) ──
+# Supports plain bash or base64-encoded scripts (prefix with base64: or b64:).
+# Example: HUGGINGMES_RUN="pip install pandas && npm install -g typescript"
+# Example: HUGGINGMES_RUN="base64:$(base64 -w0 setup.sh)"
+hm_run_startup_auto() {
+  local payload="$1"
+  [ -n "$payload" ] || return 0
+  local script_file
+  script_file=$(mktemp "/tmp/huggingmes-startup.XXXXXX.sh")
+  {
+    echo 'export HUGGINGMES_CAPTURE_DISABLE=1'
+    echo '[ -f ~/.bashrc ] && . ~/.bashrc'
+    if [[ "$payload" == base64:* ]] || [[ "$payload" == b64:* ]]; then
+      printf '%s' "${payload#*:}" | base64 -d
+    else
+      printf '%s\n' "$payload"
+    fi
+  } > "$script_file"
+  chmod 700 "$script_file"
+  echo "[startup:HUGGINGMES_RUN] running script"
+  set +e
+  bash "$script_file"
+  local rc=$?
+  set -e
+  rm -f "$script_file"
+  if [ $rc -eq 0 ]; then
+    echo "[startup:HUGGINGMES_RUN] ok"
+  else
+    HM_STARTUP_FAILURES=$((HM_STARTUP_FAILURES + 1))
+    echo "ERROR: HUGGINGMES_RUN script failed (exit ${rc})" >&2
+  fi
+}
+
+if [ -n "${HUGGINGMES_RUN:-}" ]; then
+  hm_run_startup_auto "$HUGGINGMES_RUN"
+fi
+
+# ── Run workspace startup script ──
+# Replays install commands recorded by the shell wrappers from previous sessions.
+if [ -s "$STARTUP_FILE" ]; then
+  echo "Running workspace/startup.sh..."
+  set +e
+  HUGGINGMES_CAPTURE_DISABLE=1 bash -l "$STARTUP_FILE"
+  set -e
+  echo "Workspace startup script complete."
+fi
+
+if [ "$HM_STARTUP_FAILURES" -gt 0 ]; then
+  echo "Warning: ${HM_STARTUP_FAILURES} startup step(s) failed. Check logs above." >&2
+fi
+
+# ── Start background services ──
+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 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
+
+# ── Launch dashboard once (restarts if it dies) ──
+start_dashboard_once() {
+  if [ -n "${DASHBOARD_PID:-}" ] && kill -0 "$DASHBOARD_PID" 2>/dev/null; then
+    return 0
+  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=$!
+}
+
+start_dashboard_once
+start_jupyter
+
+# ── Gateway restart loop ──
+GATEWAY_RESTART_DELAY="${GATEWAY_RESTART_DELAY:-5}"
+GATEWAY_MAX_RESTARTS="${GATEWAY_MAX_RESTARTS:-0}"
+GATEWAY_RESTART_COUNT=0
+GATEWAY_READY_TIMEOUT="${GATEWAY_READY_TIMEOUT:-120}"
+
+while true; do
+  # Monitor health-server — restart if it died unexpectedly
+  if [ -n "${HEALTH_PID:-}" ] && ! kill -0 "$HEALTH_PID" 2>/dev/null; then
+    echo "Warning: health-server exited (PID $HEALTH_PID dead); restarting..."
+    node "$APP_DIR/health-server.js" &
+    HEALTH_PID=$!
+    echo "Health server restarted (PID: $HEALTH_PID)"
+  fi
+
+  # Monitor Hermes dashboard — restart if it died unexpectedly
+  if [ -n "${DASHBOARD_PID:-}" ] && ! kill -0 "$DASHBOARD_PID" 2>/dev/null; then
+    echo "Warning: Hermes dashboard exited; restarting..."
+    start_dashboard_once
+  fi
+
+  # Monitor JupyterLab — restart if it died unexpectedly
+  if [ "${DEV_MODE:-true}" != "false" ] && [ -n "${JUPYTER_PID:-}" ] && ! kill -0 "$JUPYTER_PID" 2>/dev/null; then
+    echo "Warning: JupyterLab exited (PID $JUPYTER_PID dead); restarting..."
+    unset JUPYTER_PID
+    start_jupyter
+  fi
+
+  echo "Launching Hermes gateway..."
+  (hermes gateway run 2>&1 | tee -a "$HERMES_HOME/logs/gateway.log") &
+  GATEWAY_PID=$!
+
+  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
+
+  set +e
+  wait "$GATEWAY_PID"
+  GATEWAY_EXIT_CODE=$?
+  set -e
+
+  GATEWAY_RESTART_COUNT=$((GATEWAY_RESTART_COUNT + 1))
+  if [ "$GATEWAY_MAX_RESTARTS" != "0" ] && [ "$GATEWAY_RESTART_COUNT" -ge "$GATEWAY_MAX_RESTARTS" ]; then
+    echo "Gateway exited (code ${GATEWAY_EXIT_CODE}); restart limit (${GATEWAY_MAX_RESTARTS}) reached."
+    exit "$GATEWAY_EXIT_CODE"
+  fi
+
+  echo "Gateway exited (code ${GATEWAY_EXIT_CODE}); restarting in ${GATEWAY_RESTART_DELAY}s..."
+  sleep "$GATEWAY_RESTART_DELAY"
+done