Harden Chromium launch flags for headless HF container stability

Dockerfile

@@ -21,6 +21,7 @@ ENV DEV_MODE=${DEV_MODE}
 RUN apt-get update && apt-get install -y \
     git \
     sudo \
+    file \
     ca-certificates \
     jq \
     curl \

README.md

@@ -20,7 +20,7 @@ secrets:
   - name: GATEWAY_TOKEN
     description: "Strong token to secure your OpenClaw Control UI (generate: openssl rand -hex 32)."
   - name: JUPYTER_TOKEN
-    description: "Optional strong token for the JupyterLab terminal at /terminal/ (defaults to huggingface)."
+    description: "Optional token for the JupyterLab terminal at /terminal/. Defaults to GATEWAY_TOKEN when set — no extra secret needed."
   - name: CLOUDFLARE_WORKERS_TOKEN
     description: "Cloudflare API token — auto-creates a Worker proxy and KeepAlive monitor."
   - name: TELEGRAM_ALLOWED_USERS
@@ -57,7 +57,6 @@ secrets:
 - [💻 Local Development](#-local-development)
 - [🔗 CLI Access](#-cli-access)
 - [💻 JupyterLab Terminal](#-jupyterlab-terminal)
-- [🔍 Merge Comparison](#-merge-comparison)
 - [🏗️ Architecture](#-architecture)
 - [💓 Staying Alive](#-staying-alive)
 - [🐛 Troubleshooting](#-troubleshooting)
@@ -78,7 +77,7 @@ secrets:
 - 📊 **Visual Dashboard:** Beautiful Web UI to monitor uptime, sync status, and active models.
 - 🔔 **Webhooks:** Get notified on restarts or backup failures via standard webhooks.
 - 🔐 **Flexible Auth:** Secure the Control UI with either a gateway token or password.
-- 💻 **Optional Dev Terminal:** JupyterLab is available at `/terminal/` only when `DEV_MODE=true` (disabled by default).
+- 💻 **Terminal Out of the Box:** JupyterLab is available at `/terminal/` automatically when `GATEWAY_TOKEN` is set — no extra config needed. `GATEWAY_TOKEN` is reused as the terminal auth token. Set `DEV_MODE=false` explicitly to opt out.
 - 🏠 **100% HF-Native:** Runs entirely on HuggingFace’s free infrastructure (2 vCPU, 16GB RAM).
 
 ## 🎥 Video Tutorial
@@ -104,7 +103,9 @@ Navigate to your new Space's **Settings**, scroll down to the **Variables and se
 > [!TIP]
 > HuggingClaw is completely flexible! You only need these three secrets to get started. You can set other secrets later.
 
-Optional: set `DEV_MODE=true` (Variable) to enable JupyterLab support and install Jupyter dependencies at build time. You can also set `JUPYTER_TOKEN` as a Secret to set a strong terminal token (must not be `huggingface`). If you want to pin a specific OpenClaw release instead of `latest`, add `OPENCLAW_VERSION` under **Variables** in your Space settings. For Docker Spaces, HF passes Variables as build args during image build, so these should be Variables, not Secrets (except tokens).
+**Terminal auto-enables when `GATEWAY_TOKEN` is set** — no extra secrets needed. `GATEWAY_TOKEN` is reused as `JUPYTER_TOKEN`, so the terminal is protected by the same credential as the Control UI. To set a different token, add `JUPYTER_TOKEN` as a Secret. To disable the terminal entirely, set `DEV_MODE=false` as a Variable.
+
+If you want to pin a specific OpenClaw release instead of `latest`, add `OPENCLAW_VERSION` under **Variables** in your Space settings. For Docker Spaces, HF passes Variables as build args during image build, so these should be Variables, not Secrets (except tokens).
 
 ### Step 3: Deploy & Run
 
@@ -366,21 +367,12 @@ The merged Space includes the Hugging Face JupyterLab template behavior inside t
 | :--- | :--- | :--- | :--- |
 | `/` | HuggingClaw dashboard | `7861` | Public HF Spaces entrypoint |
 | `/app/` | OpenClaw Control UI | `7860` | Mounted behind the local reverse proxy |
-| `/terminal/` | JupyterLab terminal (DEV_MODE only) | `8888` | Available only when `DEV_MODE=true`; token login uses `JUPYTER_TOKEN` (set a strong value) |
+| `/terminal/` | JupyterLab terminal | `8888` | Auto-enabled when `GATEWAY_TOKEN` is set; uses `GATEWAY_TOKEN` as auth token unless `JUPYTER_TOKEN` is set separately. Set `DEV_MODE=false` to disable. |
 
 When enabled, the terminal notebook root is `/home/node`, so you can inspect HuggingClaw files, logs, workspace state, and runtime scripts from the browser.
 
 > [!IMPORTANT]
-> For real deployments, set a strong `JUPYTER_TOKEN` secret. Do not use `huggingface`; generate a strong token with `openssl rand -hex 32`.
-
-## 🔍 Merge Comparison
-
-This repository is a merge of two sources:
-
-- `anurag162008/HuggingClaw`: OpenClaw gateway, dashboard, Cloudflare proxy/keep-alive, Telegram/WhatsApp helpers, backup sync, key rotation, docs, and security metadata.
-- Hugging Face `SpacesExamples/jupyterlab` template: JupyterLab Docker behavior, token login UX, Hugging Face-branded login template, pinned Jupyter packages, and Git LFS defaults for large model/data artifacts.
-
-The main merge-specific change is the single-port router: HF Spaces exposes `7861`, while the router keeps OpenClaw at `/app/` and JupyterLab at `/terminal/` without leaking internal redirects such as `http://127.0.0.1:8888/...`.
+> No extra secret needed — `GATEWAY_TOKEN` is automatically reused as `JUPYTER_TOKEN`. Set a separate `JUPYTER_TOKEN` secret only if you want a different terminal credential.
 
 ## 🏗️ Architecture
 
@@ -402,7 +394,7 @@ HuggingClaw uses a multi-layered approach to ensure stability and persistence on
 2. Resolve backup namespace and restore workspace from HF Dataset.
 3. Generate `openclaw.json` configuration.
 4. Launch background tasks (auto-sync, channel helpers).
-5. Start the local dashboard/reverse proxy and OpenClaw gateway (JupyterLab starts only when `DEV_MODE=true`).
+5. Start the local dashboard/reverse proxy and OpenClaw gateway (JupyterLab starts when `GATEWAY_TOKEN` is set, `DEV_MODE=true`, or `HUGGINGCLAW_JUPYTER_ENABLED=true`).
 
 </details>
 

health-server.js

@@ -20,9 +20,12 @@ const GATEWAY_HOST = "127.0.0.1";
 const JUPYTER_PORT = Number.parseInt(process.env.JUPYTER_PORT || "8888", 10);
 const JUPYTER_HOST = "127.0.0.1";
 const JUPYTER_BASE = normalizeBase(process.env.JUPYTER_BASE, "/terminal");
+const GATEWAY_TOKEN = (process.env.GATEWAY_TOKEN || "").trim();
 const DEV_MODE_ENABLED = isTrue(process.env.DEV_MODE);
+// Auto-enable Jupyter when DEV_MODE=true, HUGGINGCLAW_JUPYTER_ENABLED=true, or GATEWAY_TOKEN is set.
+// GATEWAY_TOKEN doubles as JUPYTER_TOKEN in start.sh — no extra secret needed.
 const JUPYTER_ENABLED = /^(true|1|yes|on)$/i.test(
-  process.env.HUGGINGCLAW_JUPYTER_ENABLED || (DEV_MODE_ENABLED ? "true" : "false")
+  process.env.HUGGINGCLAW_JUPYTER_ENABLED || (DEV_MODE_ENABLED ? "true" : GATEWAY_TOKEN ? "true" : "false")
 );
 const startTime = Date.now();
 const LLM_MODEL = process.env.LLM_MODEL || "Not Set";
@@ -634,7 +637,7 @@ const server = http.createServer(async (req, res) => {
   if (pathname === JUPYTER_BASE || pathname.startsWith(JUPYTER_BASE + "/")) {
     if (!JUPYTER_ENABLED) {
       res.writeHead(404, { "Content-Type": "application/json" });
-      return res.end(JSON.stringify({ status: "disabled", message: "JupyterLab terminal is disabled. Set DEV_MODE=true to enable /terminal/." }));
+      return res.end(JSON.stringify({ status: "disabled", message: "JupyterLab terminal is disabled. Set GATEWAY_TOKEN or DEV_MODE=true to enable /terminal/ (or set HUGGINGCLAW_JUPYTER_ENABLED=true)." }));
     }
     if (isDirectHfSpaceRequest) {
       res.writeHead(200, { "Content-Type": "text/html" });

start.sh

@@ -93,6 +93,12 @@ DEV_MODE_ENABLED=false
 if hc_is_true "$DEV_MODE_NORMALIZED"; then
   DEV_MODE_ENABLED=true
 fi
+# Auto-enable DEV_MODE when GATEWAY_TOKEN is set and DEV_MODE was not explicitly configured.
+# GATEWAY_TOKEN doubles as JUPYTER_TOKEN (see start_jupyter_once) — no extra secret required.
+if [ "$DEV_MODE_ENABLED" != "true" ] && [ -z "${DEV_MODE:-}" ] && [ -n "${GATEWAY_TOKEN:-}" ]; then
+  DEV_MODE_ENABLED=true
+  echo "GATEWAY_TOKEN set and DEV_MODE not explicitly configured — auto-enabling terminal (set DEV_MODE=false to opt out)"
+fi
 SYNC_INTERVAL="$(trim_var "${SYNC_INTERVAL:-180}")"
 DEVDATA_DATASET_NAME="$(trim_var "${DEVDATA_DATASET_NAME:-huggingclaw-devdata}")"
 DEVDATA_SYNC_INTERVAL="$(trim_var "${DEVDATA_SYNC_INTERVAL:-180}")"
@@ -514,10 +520,44 @@ inject_provider_models_from_env "github-copilot" "GITHUB_COPILOT_MODELS" "COPILO
 
 # Browser configuration (managed local Chromium in HF/Docker)
 BROWSER_EXECUTABLE_PATH=""
-# On Debian/Ubuntu, /usr/bin/chromium is a shell wrapper; the real ELF binary
-# lives at /usr/lib/chromium/chromium. Check the real binary first, then fall
-# back to wrapper scripts (which are also valid executablePath values for
-# Playwright/OpenClaw — they re-exec the real binary internally).
+BROWSER_WRAPPER_PATH=""
+HAS_FILE_CMD=false
+if command -v file >/dev/null 2>&1; then
+  HAS_FILE_CMD=true
+fi
+
+ensure_chromium_for_browser_plugin() {
+  # Enforce Chromium availability when browser plugin is explicitly enabled.
+  [ "$BROWSER_PLUGIN_MODE" = "enabled" ] || return 0
+  for candidate in /usr/lib/chromium/chromium /usr/bin/chromium /usr/bin/chromium-browser; do
+    [ -x "$candidate" ] && return 0
+  done
+  if [ "$HAS_FILE_CMD" != "true" ]; then
+    echo "BROWSER_PLUGIN_MODE=enabled and 'file' command is missing; attempting runtime install..."
+    if _hc_apt_install file; then
+      HAS_FILE_CMD=true
+      echo "'file' command installed via apt-get."
+    else
+      echo "Warning: could not install 'file'; continuing with executable-path fallback checks."
+    fi
+  fi
+  echo "BROWSER_PLUGIN_MODE=enabled but Chromium is missing; attempting runtime install..."
+  if _hc_apt_install chromium; then
+    echo "Chromium installed via apt-get."
+    return 0
+  fi
+  if _hc_apt_install chromium-browser; then
+    echo "Chromium browser package installed via apt-get."
+    return 0
+  fi
+  echo "ERROR: Browser plugin is enabled, but Chromium install failed. Disable browser plugin or rebuild image with Chromium preinstalled." >&2
+  return 1
+}
+ensure_chromium_for_browser_plugin || HC_STARTUP_FAILURES=$((HC_STARTUP_FAILURES + 1))
+
+# On Debian/Ubuntu, /usr/bin/chromium is often a shell wrapper while the real
+# ELF binary lives under /usr/lib/chromium/*. Prefer a real ELF binary, then
+# fall back to wrapper launchers (Playwright/OpenClaw can execute those too).
 for candidate in \
     /usr/lib/chromium/chromium \
     /usr/lib/chromium-browser/chromium-browser \
@@ -525,14 +565,29 @@ for candidate in \
     /usr/bin/chromium-browser \
     /snap/bin/chromium; do
   if [ -x "$candidate" ]; then
-    if file "$candidate" 2>/dev/null | grep -q "ELF"; then
+    if [ "$HAS_FILE_CMD" = "true" ]; then
+      if file "$candidate" 2>/dev/null | grep -q "ELF"; then
+        BROWSER_EXECUTABLE_PATH="$candidate"
+        break
+      fi
+    else
+      # Minimal images may not ship `file`; accept the first executable path.
       BROWSER_EXECUTABLE_PATH="$candidate"
       break
     fi
+    if [ -z "$BROWSER_WRAPPER_PATH" ]; then
+      BROWSER_WRAPPER_PATH="$candidate"
+    fi
   fi
 done
+if [ -z "$BROWSER_EXECUTABLE_PATH" ] && [ -n "$BROWSER_WRAPPER_PATH" ]; then
+  BROWSER_EXECUTABLE_PATH="$BROWSER_WRAPPER_PATH"
+  echo "No ELF Chromium binary found; using launcher wrapper at $BROWSER_EXECUTABLE_PATH"
+elif [ -n "$BROWSER_EXECUTABLE_PATH" ] && [ "$HAS_FILE_CMD" != "true" ]; then
+  echo "Detected Chromium executable at $BROWSER_EXECUTABLE_PATH (ELF probe skipped: 'file' command not installed)"
+fi
 if [ -z "$BROWSER_EXECUTABLE_PATH" ]; then
-  echo "Warning: No real Chromium binary found. Browser plugin will be disabled."
+  echo "Warning: Chromium executable not found. Browser plugin will be disabled."
 fi
 
 BROWSER_SHOULD_ENABLE=false
@@ -585,21 +640,21 @@ CONFIG_JSON=$(jq \
 
 if [ "$BROWSER_SHOULD_ENABLE" = "true" ]; then
   CONFIG_JSON=$(jq \
-    --arg execPath "$BROWSER_EXECUTABLE_PATH" \
     '.browser = {
        "enabled": true,
        "defaultProfile": "openclaw",
        "headless": true,
        "noSandbox": true,
-       "executablePath": $execPath,
-       "localLaunchTimeoutMs": 45000,
-       "localCdpReadyTimeoutMs": 30000,
        "extraArgs": [
+         "--headless=new",
          "--no-sandbox",
          "--disable-setuid-sandbox",
          "--no-zygote",
          "--disable-dev-shm-usage",
          "--disable-gpu",
+         "--remote-debugging-address=127.0.0.1",
+         "--disable-features=UseDBus,MediaRouter",
+         "--password-store=basic",
          "--no-first-run",
          "--disable-background-networking",
          "--disable-sync",
@@ -925,6 +980,13 @@ start_jupyter_once() {
     return 0
   fi
 
+  # GATEWAY_TOKEN fallback: if JUPYTER_TOKEN is unset or still the insecure default,
+  # reuse GATEWAY_TOKEN. Both protect the same Space, so the credential is equivalent.
+  if { [ -z "${JUPYTER_TOKEN:-}" ] || [ "${JUPYTER_TOKEN}" = "huggingface" ]; } && [ -n "${GATEWAY_TOKEN:-}" ]; then
+    JUPYTER_TOKEN="$GATEWAY_TOKEN"
+    echo "JUPYTER_TOKEN not set — using GATEWAY_TOKEN as terminal auth token"
+  fi
+
   # Security guard: refuse to start JupyterLab with the insecure default token.
   # JupyterLab exposes a full shell — a weak token is equivalent to no auth.
   if [ -z "${JUPYTER_TOKEN:-}" ] || [ "${JUPYTER_TOKEN}" = "huggingface" ]; then