Initial NII Relay

README.md

@@ -1,13 +1,34 @@
 ---
-title: Remote Shell
-emoji: 🏆
-colorFrom: green
+title: NII Relay
+emoji: 🛰️
+colorFrom: blue
 colorTo: indigo
 sdk: gradio
-sdk_version: 6.15.2
-python_version: '3.13'
+sdk_version: 5.9.1
 app_file: app.py
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# NII Relay
+
+A private message relay between your browser and shell daemons running inside
+no-SSH containers (e.g. on the NII cluster). The Space holds a queue of
+commands; daemons poll it, run the commands in persistent bash sessions, and
+post the output back.
+
+## Deploy
+
+1. Create a **private** Space (SDK: Gradio). Upload `app.py` and
+   `requirements.txt`.
+2. In **Settings → Variables and secrets**, add a secret named `RELAY_SECRET`
+   with a long random value. The daemons must use the same value.
+3. Wait for the Space to build. The URL (`https://huggingface.co/spaces/<you>/<name>`)
+   and its repo id (`<you>/<name>`) are what the daemon connects to.
+
+## Use
+
+Open the Space, pick an online container (🟢), name a bash session, type a
+command, hit **Run**. Reuse a session name to keep its `cd`/env/venv; type a new
+name to open a fresh shell.
+
+The daemon lives in `../daemon/`.

app.py

@@ -0,0 +1,255 @@
+"""
+NII Relay — a tiny HF Space that acts as a message relay between you (in the
+browser) and shell daemons running inside no-SSH containers on the cluster.
+
+Flow
+----
+1. A daemon inside a container registers with a CLIENT_ID and polls this Space
+   every few seconds (via the `gradio_client` API endpoints below).
+2. You pick a container + bash session in the web UI and submit a shell command.
+3. The next poll hands the command to the daemon, which marks it ACKNOWLEDGED,
+   runs it in a persistent bash session, and posts stdout + exit code back.
+4. The UI shows the output.
+
+State is in-memory only. If the Space restarts, daemons simply re-register on
+their next poll — but any not-yet-delivered commands are lost. That is fine for
+interactive debugging.
+
+Security: every API call must carry the shared RELAY_SECRET (set as a Space
+secret). The Space being private is the first line of defense; the secret is the
+second so a leaked HF read-token alone can't drive your shells.
+"""
+
+import os
+import time
+import uuid
+import threading
+from collections import defaultdict
+
+import gradio as gr
+
+SECRET = os.environ.get("RELAY_SECRET", "")          # set this as a Space secret
+CLIENT_STALE_AFTER = 30                                # seconds w/o a poll => "offline"
+MAX_OUTPUT_CHARS = 200_000                             # cap stored output per command
+MAX_HISTORY_PER_CLIENT = 200                           # ring-buffer of commands
+
+LOCK = threading.Lock()
+CLIENTS: dict[str, dict] = {}                          # cid -> {last_seen, meta}
+COMMANDS: dict[str, dict] = {}                         # command_id -> record
+BY_CLIENT: dict[str, list[str]] = defaultdict(list)    # cid -> [command_id, ...]
+
+
+def _now() -> float:
+    return time.time()
+
+
+def _check(secret: str):
+    if SECRET and secret != SECRET:
+        raise gr.Error("bad secret")
+
+
+def _touch_client(cid: str, meta: str = ""):
+    c = CLIENTS.setdefault(cid, {"first_seen": _now(), "meta": meta})
+    c["last_seen"] = _now()
+    if meta:
+        c["meta"] = meta
+
+
+# --------------------------------------------------------------------------- #
+# Machine API (called by the daemon via gradio_client)                         #
+# --------------------------------------------------------------------------- #
+def api_register(client_id: str, secret: str, meta: str):
+    _check(secret)
+    client_id = (client_id or "").strip()
+    if not client_id:
+        raise gr.Error("empty client_id")
+    with LOCK:
+        _touch_client(client_id, meta or "")
+    return {"ok": True, "ts": _now()}
+
+
+def api_poll(client_id: str, secret: str):
+    """Return all pending commands for this client and flip them to acknowledged."""
+    _check(secret)
+    client_id = (client_id or "").strip()
+    out = []
+    with LOCK:
+        _touch_client(client_id)
+        for cmd_id in BY_CLIENT[client_id]:
+            rec = COMMANDS[cmd_id]
+            if rec["status"] == "pending":
+                rec["status"] = "acknowledged"
+                rec["acknowledged_at"] = _now()
+                out.append({
+                    "id": rec["id"],
+                    "session": rec["session"],
+                    "command": rec["command"],
+                    "timeout": rec["timeout"],
+                })
+    return {"commands": out, "ts": _now()}
+
+
+def api_result(command_id: str, client_id: str, secret: str,
+               exit_code: float, stdout: str, session: str):
+    _check(secret)
+    with LOCK:
+        rec = COMMANDS.get(command_id)
+        if rec is None:
+            # Space probably restarted; record it anyway so output isn't lost.
+            rec = COMMANDS[command_id] = {
+                "id": command_id, "client_id": client_id, "session": session,
+                "command": "(unknown — relay restarted)", "created": _now(),
+                "status": "pending",
+            }
+            BY_CLIENT[client_id].append(command_id)
+        rec["status"] = "done"
+        rec["finished_at"] = _now()
+        rec["exit_code"] = int(exit_code)
+        rec["stdout"] = (stdout or "")[:MAX_OUTPUT_CHARS]
+        _touch_client(client_id)
+    return {"ok": True}
+
+
+# --------------------------------------------------------------------------- #
+# Human UI helpers                                                             #
+# --------------------------------------------------------------------------- #
+def _client_choices() -> list[str]:
+    with LOCK:
+        items = sorted(CLIENTS.items(), key=lambda kv: kv[1].get("last_seen", 0), reverse=True)
+        labels = []
+        for cid, c in items:
+            age = _now() - c.get("last_seen", 0)
+            dot = "🟢" if age < CLIENT_STALE_AFTER else "🔴"
+            labels.append(f"{dot} {cid}")
+        return labels
+
+
+def _strip_dot(label: str) -> str:
+    return label.split(" ", 1)[1] if label and label[:1] in "🟢🔴" else (label or "")
+
+
+def ui_send(client_label: str, session: str, command: str, timeout: int):
+    cid = _strip_dot(client_label)
+    if not cid:
+        return "⚠️ pick a container first", command
+    if not command.strip():
+        return "⚠️ empty command", command
+    session = (session or "main").strip()
+    cmd_id = uuid.uuid4().hex
+    with LOCK:
+        COMMANDS[cmd_id] = {
+            "id": cmd_id, "client_id": cid, "session": session,
+            "command": command, "timeout": int(timeout),
+            "status": "pending", "created": _now(),
+        }
+        hist = BY_CLIENT[cid]
+        hist.append(cmd_id)
+        # trim ring buffer
+        while len(hist) > MAX_HISTORY_PER_CLIENT:
+            old = hist.pop(0)
+            COMMANDS.pop(old, None)
+    return f"➡️ sent to `{cid}` [{session}]", ""
+
+
+_STATUS_ICON = {"pending": "⏳", "acknowledged": "📨", "done": "✅"}
+
+
+def ui_history(client_label: str, n: int = 12) -> str:
+    cid = _strip_dot(client_label)
+    if not cid:
+        return "_Select a container to see its command history._"
+    with LOCK:
+        ids = list(BY_CLIENT.get(cid, []))[-int(n):][::-1]
+        recs = [dict(COMMANDS[i]) for i in ids if i in COMMANDS]
+    if not recs:
+        return f"_No commands for `{cid}` yet._"
+    blocks = []
+    for r in recs:
+        icon = _STATUS_ICON.get(r["status"], "•")
+        head = f"{icon} **[{r.get('session','main')}]** `{r['command']}`"
+        if r["status"] == "done":
+            ec = r.get("exit_code", "?")
+            out = r.get("stdout", "") or "(no output)"
+            head += f"  → exit {ec}"
+            blocks.append(head + f"\n```text\n{out}\n```")
+        else:
+            blocks.append(head + f"\n_{r['status']}…_")
+    return "\n\n".join(blocks)
+
+
+def ui_refresh(client_label: str):
+    choices = _client_choices()
+    # keep the current selection if its cid is still present
+    keep = None
+    cur = _strip_dot(client_label)
+    for ch in choices:
+        if _strip_dot(ch) == cur:
+            keep = ch
+            break
+    if keep is None and choices:
+        keep = choices[0]
+    return gr.update(choices=choices, value=keep), ui_history(keep or "")
+
+
+# --------------------------------------------------------------------------- #
+# Layout                                                                        #
+# --------------------------------------------------------------------------- #
+with gr.Blocks(title="NII Relay", theme=gr.themes.Soft()) as demo:
+    gr.Markdown(
+        "# 🛰️ NII Relay\n"
+        "Send shell commands to no-SSH containers via a polling daemon. "
+        "Pick a container, name a bash session (reuse a name to keep its `cd`/env, "
+        "or type a new name to open a fresh session), and run."
+    )
+
+    with gr.Row():
+        client_dd = gr.Dropdown(label="Container", choices=_client_choices(),
+                                interactive=True, scale=3)
+        refresh_btn = gr.Button("↻ Refresh", scale=1)
+
+    with gr.Row():
+        session_tb = gr.Textbox(label="bash session", value="main", scale=2)
+        timeout_nb = gr.Number(label="timeout (s)", value=120, precision=0, scale=1)
+
+    command_tb = gr.Textbox(label="command", lines=2,
+                            placeholder="nvidia-smi    |    cd /mnt/data && ls -la    |    tail -n 50 train.log")
+    with gr.Row():
+        send_btn = gr.Button("Run ▶", variant="primary")
+        send_status = gr.Markdown("")
+
+    history_md = gr.Markdown("_Select a container to see its command history._")
+
+    timer = gr.Timer(2.0)
+
+    # wiring
+    send_btn.click(ui_send, [client_dd, session_tb, command_tb, timeout_nb],
+                   [send_status, command_tb])
+    command_tb.submit(ui_send, [client_dd, session_tb, command_tb, timeout_nb],
+                      [send_status, command_tb])
+    refresh_btn.click(ui_refresh, [client_dd], [client_dd, history_md])
+    client_dd.change(ui_history, [client_dd], history_md)
+    timer.tick(ui_refresh, [client_dd], [client_dd, history_md])
+
+    # --- hidden machine API endpoints (called by the daemon) ---
+    with gr.Row(visible=False):
+        a_cid = gr.Textbox()
+        a_secret = gr.Textbox()
+        a_meta = gr.Textbox()
+        a_cmdid = gr.Textbox()
+        a_session = gr.Textbox()
+        a_exit = gr.Number()
+        a_stdout = gr.Textbox()
+        a_out = gr.JSON()
+        b_reg = gr.Button()
+        b_poll = gr.Button()
+        b_res = gr.Button()
+        b_reg.click(api_register, [a_cid, a_secret, a_meta], a_out, api_name="register")
+        b_poll.click(api_poll, [a_cid, a_secret], a_out, api_name="poll")
+        b_res.click(api_result, [a_cmdid, a_cid, a_secret, a_exit, a_stdout, a_session],
+                    a_out, api_name="result")
+
+
+if __name__ == "__main__":
+    demo.queue(default_concurrency_limit=16).launch(
+        server_name="0.0.0.0", server_port=int(os.environ.get("PORT", 7860))
+    )

requirements.txt

@@ -0,0 +1 @@
+gradio>=5.0,<6