feat: add JupyterLab terminal at /terminal/ (DEV_MODE=true)

Install JupyterLab in the venv. When DEV_MODE=true and JUPYTER_TOKEN
is set (strong token required — full shell access), start JupyterLab
on port 8888 with /terminal/ base URL. health-server proxies HTTP
and WebSocket (required for kernels/terminals) to JupyterLab.

Usage: set DEV_MODE=true and JUPYTER_TOKEN=<openssl rand -hex 32>
in HF Space secrets, then visit /terminal/.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Dockerfile

@@ -30,7 +30,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     fonts-liberation \
     fonts-noto-color-emoji \
     && rm -rf /var/lib/apt/lists/* \
-    && uv pip install --python /opt/hermes/.venv/bin/python --no-cache-dir huggingface_hub hf_transfer
+    && uv pip install --python /opt/hermes/.venv/bin/python --no-cache-dir huggingface_hub hf_transfer jupyterlab
 
 COPY --chown=hermes:hermes start.sh /opt/huggingmes/start.sh
 COPY --chown=hermes:hermes health-server.js /opt/huggingmes/health-server.js

health-server.js

@@ -9,7 +9,9 @@ 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";
@@ -662,10 +664,50 @@ const server = http.createServer(async (req, res) => {
     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. Set DEV_MODE=true and JUPYTER_TOKEN in Space secrets to enable /terminal/.");
+        return;
+      }
+      proxyRequest(req, res, JUPYTER_PORT);
+    });
+    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

@@ -308,6 +308,49 @@ echo "Dashboard : http://127.0.0.1:${DASHBOARD_PORT}"
 echo "Gateway   : http://127.0.0.1:${GATEWAY_API_PORT}"
 echo ""
 
+# ── JupyterLab terminal (DEV_MODE=true + JUPYTER_TOKEN required) ──
+start_jupyter() {
+  if [ "${DEV_MODE:-false}" != "true" ]; then
+    echo "JupyterLab disabled (set DEV_MODE=true to enable /terminal/)."
+    return 0
+  fi
+  if [ -z "${JUPYTER_TOKEN:-}" ] || [ "${JUPYTER_TOKEN}" = "huggingface" ]; then
+    echo "ERROR: JUPYTER_TOKEN unset or insecure default. JupyterLab grants full shell — set a strong token." >&2
+    echo "       Hint: openssl rand -hex 32" >&2
+    return 1
+  fi
+  if ! python3 -c "import jupyterlab" >/dev/null 2>&1; then
+    echo "WARNING: jupyterlab not installed; skipping terminal." >&2
+    return 1
+  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 (path: /terminal/) root: $root_dir"
+  python3 -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 ──
 graceful_shutdown() {
   echo "Shutting down HuggingMes..."
@@ -371,6 +414,8 @@ if [ -n "${HF_TOKEN:-}" ]; then
   python3 -u "$APP_DIR/hermes-sync.py" loop &
 fi
 
+start_jupyter
+
 wait "$GATEWAY_PID"
 
 # Gateway exited (e.g. user restarted from Hermes UI). Sync before container dies.