feat(sync): warn when keys live in ephemeral .env on a Space

The Hermes dashboard's Env tab writes to $HERMES_HOME/.env which is
intentionally excluded from backup. On HF Spaces the filesystem is
ephemeral, so anything saved there silently disappears on the next
restart and the gateway 500s with 'Provider X is set in config.yaml
but no API key was found'.

* hermes-sync.py: env_warning_payload() detects populated .env on a
Space when SYNC_INCLUDE_ENV is off, surfaces it via write_status() so
every status snapshot carries a structured warning, and prints once
at loop start so it's grep-able in Space logs.
* health-server.js: Backup tile on the HuggingMes status page renders
the warning as a yellow callout when present, and flips the tile
tone to warn so it's visible at a glance.
* README + .env.example: explicit guidance to put provider keys in HF
Space Secrets, with SYNC_INCLUDE_ENV=1 documented as the opt-in
weaker-security alternative. Also fixed stale '10 minute' backup
copy left over from the fixed-interval era.

False-positive guard: returns None when SPACE_ID/SPACE_HOST is unset,
so local dev installs and Docker hosts that legitimately use .env
stay quiet.

.env.example

@@ -20,6 +20,11 @@ LLM_MODEL=openrouter/anthropic/claude-sonnet-4
 # SYNC_POLL_INTERVAL=2
 # SYNC_DEBOUNCE_SECONDS=3
 # SYNC_INTERVAL=60
+# Back up $HERMES_HOME/.env (provider keys typed via the dashboard's Env tab)
+# into the private dataset. OFF by default — see README "Configure LLM
+# Provider via Config Editor" for the security tradeoff. Prefer adding keys
+# as HF Space Secrets, which never touch disk.
+# SYNC_INCLUDE_ENV=1
 
 # ── Optional: Cloudflare proxy + keep-alive ───────────────────────────
 # CLOUDFLARE_WORKERS_TOKEN=cf_xxx

README.md

@@ -82,7 +82,7 @@ Open Hermes Dashboard from here (`https://f4b404-hermes.hf.space/hm/app`)
 ## Your Data Is Safe
 
 When `HF_TOKEN` is set:
-- All your chats, files, settings, and agent memory are backed up to a **private** Hugging Face Dataset every 10 minutes
+- All your chats, files, settings, and agent memory are backed up to a **private** Hugging Face Dataset within seconds of each change (change-driven, capped at 60 s)
 - If the Space restarts, everything comes back exactly as you left it
 
 ---
@@ -122,6 +122,28 @@ Use the same (`https://your-name.hf.space`) url in android and then you can inst
 
 ## Configure LLM Provider via Config Editor
 
+> ### ⚠️ Provider keys go in HF Space Secrets, not the dashboard's Env tab
+>
+> The Hermes dashboard exposes an "Env" editor that writes to `/opt/data/.env`
+> inside the container. **That file is *not* backed up to your HF Dataset.**
+> On every Space sleep / rebuild the container's filesystem is wiped, the
+> `.env` is gone, and your `OLLAMA_API_KEY` / `OPENROUTER_API_KEY` /
+> `ANTHROPIC_API_KEY` / etc. disappear with it. The Space then 500s on the
+> first chat with `Provider 'X' is set in config.yaml but no API key was
+> found`.
+>
+> **Always add provider keys as HF Space Secrets** (Settings → Variables and
+> secrets → New secret). HF injects them as env vars at boot, never writes
+> them to disk on the Space, and they survive every restart.
+>
+> Use the dashboard's Env tab only for non-secret tweaks. The status page's
+> Backup tile will show a yellow warning whenever it detects keys sitting in
+> the ephemeral `.env` so you don't have to remember this on your own.
+>
+> If you accept the security tradeoff and want `.env` backed up anyway, set
+> `SYNC_INCLUDE_ENV=1` as a Space Variable. The dataset is private, but a
+> leak of that dataset URL is then a leak of every key in `.env`.
+
 If you prefer not to add API keys as HF Secrets, you can configure providers directly in Hermes after the Space starts:
 
 1. Open `/hm/app/config` in your Space

health-server.js

@@ -554,6 +554,11 @@ function renderStatusPage(data) {
   const backupDetail = data.backup?.message
     ? escapeHtml(data.backup.message)
     : "No status yet";
+  // Extra one-line warning row for known-loud failure modes (currently:
+  // ephemeral .env on a Space). hermes-sync.py emits this via warning.message.
+  const backupWarning = data.backup?.warning?.message
+    ? `<div class="tile-warning">${escapeHtml(data.backup.warning.message)}</div>`
+    : "";
   const keepAliveDetail = keepaliveConfigured
     ? `Pinging <code>${escapeHtml(data.keepalive.targetUrl || "/health")}</code>`
     : keepaliveStatus === "error" && data.keepalive?.message
@@ -596,9 +601,9 @@ function renderStatusPage(data) {
     }),
     renderTile({
       title: "Backup",
-      value: toneBadge(syncStatus.toUpperCase(), syncTone),
-      detail: backupDetail,
-      tone: syncTone,
+      value: toneBadge(syncStatus.toUpperCase(), data.backup?.warning ? "warn" : syncTone),
+      detail: backupDetail + backupWarning,
+      tone: data.backup?.warning ? "warn" : syncTone,
       meta: data.backup?.timestamp
         ? `<span class="local-time" data-iso="${data.backup.timestamp}"></span>`
         : "",
@@ -646,6 +651,7 @@ function renderStatusPage(data) {
     .tile-value { font-size:1.12rem; font-weight:850; overflow-wrap:anywhere; }
     .tile-detail { color:var(--soft); line-height:1.45; font-size:.83rem; }
     .tile-meta { color:var(--muted); line-height:1.4; font-size:.75rem; margin-top:auto; overflow-wrap:anywhere; }
+    .tile-warning { color:#fde68a; background:rgba(245,158,11,.08); border:1px solid rgba(245,158,11,.32); border-radius:6px; padding:6px 8px; margin-top:6px; font-size:.78rem; line-height:1.4; }
     code { background:#232234; border:1px solid #34324c; border-radius:6px; padding:2px 6px; color:var(--text); font-size:.9em; }
     .badge { display:inline-flex; align-items:center; border:1px solid var(--line); border-radius:999px; padding:5px 10px; font-size:.72rem; font-weight:850; line-height:1; text-transform:uppercase; }
     .badge.ok { color:var(--good); border-color:rgba(34,197,94,.34); background:rgba(34,197,94,.11); }

hermes-sync.py

@@ -71,10 +71,64 @@ HF_API = HfApi(token=HF_TOKEN) if HF_TOKEN else None
 STOP_EVENT = threading.Event()
 _REPO_ID_CACHE: str | None = None
 
+# `.env` warning: on HF Spaces, the dashboard's "Env" tab writes to
+# $HERMES_HOME/.env which is *not* backed up by default (see EXCLUDED_TOP_LEVEL
+# above). That means provider keys typed into the dashboard silently disappear
+# on every restart. We can't safely fix that by default — uploading plaintext
+# secrets to a dataset is the wrong tradeoff — but we can make the failure
+# loud. The status surface on the HuggingMes status page reads the JSON below,
+# so an `env_warning` field renders as a banner without any extra plumbing.
+ENV_FILE = HERMES_HOME / ".env"
+ON_HF_SPACE = bool(os.environ.get("SPACE_ID") or os.environ.get("SPACE_HOST"))
+
+
+def env_warning_payload() -> dict | None:
+    """Detect plaintext-secret-loss risk and return a warning blob, or None.
+
+    Fires when:
+      * we're on an HF Space (ephemeral filesystem), AND
+      * `.env` exists with non-trivial content, AND
+      * SYNC_INCLUDE_ENV is off (so .env is NOT being backed up).
+
+    The warning is informational. We never refuse to start sync, and we never
+    auto-flip SYNC_INCLUDE_ENV — the user must opt in to backing up plaintext.
+    """
+    if not ON_HF_SPACE or INCLUDE_ENV:
+        return None
+    try:
+        if not ENV_FILE.is_file():
+            return None
+        # Count non-empty, non-comment lines as a proxy for "user-set keys".
+        keys = 0
+        for raw in ENV_FILE.read_text(encoding="utf-8", errors="replace").splitlines():
+            line = raw.strip()
+            if not line or line.startswith("#"):
+                continue
+            if "=" in line:
+                keys += 1
+        if keys <= 0:
+            return None
+        return {
+            "kind": "ephemeral_env",
+            "keys": keys,
+            "message": (
+                f"{keys} entr{'y' if keys == 1 else 'ies'} in $HERMES_HOME/.env "
+                "will be wiped on the next Space restart. Move secrets to "
+                "Space Secrets (Settings -> Variables and secrets), or set "
+                "SYNC_INCLUDE_ENV=1 to back up .env to the private dataset "
+                "(plaintext; weaker security)."
+            ),
+        }
+    except OSError:
+        return None
+
 
 def write_status(status: str, message: str, fingerprint: str | None = None, marker: tuple[int, int, int] | None = None) -> None:
     timestamp = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
-    payload = {"status": status, "message": message, "timestamp": timestamp}
+    payload: dict = {"status": status, "message": message, "timestamp": timestamp}
+    warning = env_warning_payload()
+    if warning is not None:
+        payload["warning"] = warning
 
     tmp_path = STATUS_FILE.with_suffix(".tmp")
     try:
@@ -311,6 +365,11 @@ def loop() -> int:
         print(f"Hermes sync error: {exc}")
         return 1
 
+    warning = env_warning_payload()
+    if warning is not None:
+        # Loud, single-line, easy to grep in HF Space logs.
+        print(f"Hermes sync WARNING: {warning['message']}")
+
     # Seed from any prior run so we don't re-upload an identical tree.
     last_fingerprint: str | None = None
     last_marker: tuple[int, int, int] | None = None