Align terminal enablement messaging with runtime behavior

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
@@ -78,7 +78,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 +104,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,12 +368,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`.
+> 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.
 
 ## 🔍 Merge Comparison
 
@@ -402,7 +404,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,10 @@ 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=""
+# 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 \
@@ -529,10 +535,17 @@ for candidate in \
       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"
+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
@@ -925,6 +938,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