Deploy from 2528090f

Dockerfile

@@ -0,0 +1,20 @@
+FROM python:3.11-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git curl ca-certificates nodejs npm \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN python -m pip install --no-cache-dir pipx uv && python -m pipx ensurepath
+ENV PATH="/root/.local/bin:${PATH}"
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+ENV PORT=7860
+EXPOSE 7860
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,327 @@
+---
+title: MatrixLab Sandbox
+emoji: 🧪
+colorFrom: blue
+colorTo: purple
+sdk: docker
+app_port: 7860
+license: apache-2.0
+short_description: MatrixLab HF backend for AI repo testing and debugging
+---
+
+# MatrixLab HF Backend (Space)
+
+This Hugging Face Space is a **microservice frontend** for MatrixLab.
+
+The Space home page (`/`) is the **Matrix CLI Console** — and **only** the
+console. Because this runs inside a real Hugging Face Space, HF already renders
+the page chrome (owner/repo, App·Files·Community tabs, the **Running** badge,
+Settings/Restart), so MatrixLab does **not** duplicate that navigation or the
+running/online status. The app is one console, one status pill, one input. The
+legacy ZIP-verification UI moved to **`/verify`**.
+
+Trialing a server is a first-class command rather than a separate toggle:
+`matrix mcp test [name]` (or the **Test in sandbox** chip) starts a real
+ephemeral `/mcp/*` session, streams the lifecycle, and prints a verdict.
+
+It supports these modes:
+1. **MatrixLab Space UI** (`/`) — Matrix CLI Console + one-click sandbox testing.
+2. **Upload ZIP** (`/verify`) for static verification (syntax/security/basic tests).
+3. **Remote GitHub execution** through MatrixLab Runner using environment bootstrap + cached task runs.
+
+## Matrix CLI Console & the embeddable sandbox button
+
+The page lives under `app/static/space/`:
+
+- `index.html` — loads React (CDN) + the components below.
+- `hf-theme.css`, `fx.jsx` (digital rain / typewriter), `data.jsx` (catalog + CLI engine).
+- `hf-console.jsx` — the Matrix CLI Console (the whole in-Space UI).
+- `hf-space.jsx` — a thin shell that renders **only** the console (no duplicated
+  HF chrome).
+- **`sandbox.jsx`** — the reusable sandbox client (`window.MatrixLabSandbox`) plus
+  **`<SandboxButton>`** / `mountSandboxButton`.
+
+Inside the Space there is **no separate "enable sandbox" toggle** — `matrix mcp
+test` runs the real flow directly (the Space *is* the sandbox server). The
+`<SandboxButton>` / `mountSandboxButton` export is still shipped so **matrixhub.io**
+can embed a one-click toggle elsewhere (see "Embedding the button" below).
+
+### Embedding the button in matrixhub.io (later)
+
+`sandbox.jsx` is intentionally self-contained so the marketplace can drop the
+button in with one call. It exposes `window.MatrixLabSandbox` (a framework-agnostic
+client) and `window.mountSandboxButton`:
+
+```html
+<div id="sbx"></div>
+<script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
+<script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
+<script src="https://ruslanmv-matrixlab.hf.space/static/space/sandbox.jsx"></script>
+<script>
+  // Point at the Space (or your own proxy) and embed the toggle.
+  MatrixLabSandbox.configure({ baseUrl: "https://ruslanmv-matrixlab.hf.space" });
+  mountSandboxButton(document.getElementById("sbx"), {
+    onChange: (on) => console.log("sandbox enabled:", on),
+  });
+</script>
+```
+
+Programmatic use (no button):
+
+```js
+MatrixLabSandbox.configure({ baseUrl: "https://ruslanmv-matrixlab.hf.space" });
+await MatrixLabSandbox.run(
+  { entity_id: "mcp_server:filesystem",
+    start_command: "npx -y @modelcontextprotocol/server-filesystem /tmp" },
+  (ev) => console.log(ev.step, ev.status, ev.message)  // { step, status, message, data }
+);
+```
+
+Notes for cross-origin (matrixhub.io) embedding:
+- The Space enforces its own `MATRIXLAB_SANDBOX_TOKEN` server-side. For browser
+  embedding, prefer a **MatrixHub backend proxy** (set `baseUrl` to the proxy) so
+  no token is exposed; or supply `getToken: async () => "<short-lived>"`.
+- Enable CORS on the proxy/Space for the marketplace origin.
+
+## Production Goal
+
+Use this Space as a backend entrypoint for testing and debugging AI/code repos, including:
+- `https://github.com/ruslanmv/gitpilot`
+- `https://github.com/ruslanmv/agent-generator`
+- `https://github.com/ruslanmv/RepoGuardian`
+
+The Space sends workload requests to MatrixLab Runner (`MATRIXLAB_RUNNER_URL`), which executes in isolated containers.
+
+## Environment Variables
+
+Set these in HF Space settings:
+
+- `MATRIXLAB_RUNNER_URL` (required): e.g. `https://your-runner.example.com`
+- `MATRIXLAB_RUNNER_TIMEOUT_S` (optional, default `120`)
+
+## API
+
+### Health
+```bash
+GET /health
+```
+
+### List repo profiles
+```bash
+GET /profiles
+```
+
+### Run GitHub repo task through MatrixLab Runner
+```bash
+POST /repo/run
+Content-Type: application/json
+
+{
+  "environment_id": "gitpilot-main",
+  "profile": "gitpilot",
+  "repo_url": "https://github.com/ruslanmv/gitpilot",
+  "default_branch": "main",
+  "branch": "main",
+  "force_rebuild": false
+}
+```
+
+Profiles:
+- `gitpilot`
+- `agent-generator`
+- `repoguardian`
+- `custom` (provide your own `repo_url` + scripts)
+
+### ZIP verification mode (local in Space)
+```bash
+POST /runs        # upload zip multipart
+GET  /runs
+GET  /runs/{id}
+```
+
+## Local Run
+
+```bash
+cd hf
+docker build -t matrixlab-hf-space .
+docker run -p 7860:7860 -e MATRIXLAB_RUNNER_URL=http://host.docker.internal:8000 matrixlab-hf-space
+```
+
+## Notes
+
+- This Space is intentionally lightweight and acts as control-plane API/UI.
+- Containerized build/test execution happens in MatrixLab Runner.
+- For production, put authentication + rate-limiting in front of `/repo/run`.
+- For organization-wide maintenance sweeps, use `tools/matrix_maintainer.py` with `configs/agent_matrix_repos.json`.
+
+---
+
+## MatrixHub MCP 10-minute sandbox mode
+
+This Space can also run as a short-lived MCP server test worker for MatrixHub.io.
+
+### Flow
+
+1. MatrixHub.io user clicks **Test MCP Server**.
+2. MatrixHub backend validates the MatrixHub entity manifest.
+3. Backend restarts/wakes this Hugging Face Space if needed.
+4. Backend calls `POST /mcp/sessions` with a curated install/start command.
+5. The Space starts the MCP server over `stdio`, sends `initialize`, then `tools/list`.
+6. MatrixHub proxies tool tests through this Space for up to 600 seconds.
+7. The Space kills the MCP process and deletes `/tmp` session data.
+8. MatrixHub backend may call Hugging Face `pause_space()` after the session expires.
+
+### Recommended Space secrets
+
+- `MATRIXLAB_SANDBOX_TOKEN`: bearer token required by `/mcp/*` write/read APIs.
+- `MATRIXLAB_MCP_MAX_TTL_SECONDS`: default `600`.
+- `MATRIXLAB_MCP_MAX_SESSIONS`: default **`auto`** — derive a safe concurrent cap
+  from the instance specs (see Concurrency below). Set an integer to pin it.
+
+## Concurrency — parallel sandboxes per HF instance
+
+MatrixLab is the **main sandbox server**: each session is an independent
+subprocess with its own workdir, event stream, and TTL, so the worker runs many
+sandboxes in parallel. The cap is `MATRIXLAB_MCP_MAX_SESSIONS`.
+
+With `MATRIXLAB_MCP_MAX_SESSIONS=auto` (default) the worker reads the
+**actual instance specs** (cgroup-aware RAM + CPU count) and picks
+`min(cpu × 2, (usable_RAM_MB) / MATRIXLAB_MCP_MB_PER_SESSION)`, capped at
+`MATRIXLAB_MCP_MAX_SESSIONS_CEILING` (default 32). `usable_RAM` reserves ~1.5 GB
+for the OS/uvicorn; `MATRIXLAB_MCP_MB_PER_SESSION` defaults to 700 MB.
+
+`GET /mcp/health` reports live capacity and the detected specs:
+
+```json
+{ "active_sessions": 0, "max_sessions": 10, "available_slots": 10,
+  "max_ttl_seconds": 600,
+  "instance": { "cpu": 8, "total_mem_mb": 32768, "mb_per_session": 700 } }
+```
+
+Reference mapping (700 MB/session, ~1.5 GB reserved):
+
+| HF hardware            | vCPU | RAM   | `auto` cap | Notes                          |
+|------------------------|------|-------|-----------|--------------------------------|
+| CPU Basic              | 2    | 16 GB | ~4        | mem-bound headroom; demos      |
+| CPU Upgrade            | 8    | 32 GB | ~16→**10+**| comfortably serves 10 parallel |
+| CPU Upgrade (pinned)   | 8    | 32 GB | set `=10` | explicit, predictable          |
+
+To force exactly 10 parallel sandboxes:
+
+```text
+MATRIXLAB_MCP_MAX_SESSIONS=10
+```
+
+Verify on a running worker:
+
+```bash
+BASE=$SPACE_URL N=10 python hf/scripts/sandbox_concurrency_smoke.py
+# requested 10 · admitted 10 · running 10/10 · with tools 10 → RESULT: PASS
+```
+
+When full, `POST /mcp/sessions` returns `429` so callers can queue/retry.
+
+### Start a session
+
+```bash
+curl -X POST "$SPACE_URL/mcp/sessions" \
+  -H "Authorization: Bearer $MATRIXLAB_SANDBOX_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "entity_id": "filesystem-demo",
+    "runtime": "node",
+    "start_command": "npx -y @modelcontextprotocol/server-filesystem /tmp",
+    "transport": "stdio",
+    "ttl_seconds": 600
+  }'
+```
+
+### Poll status
+
+```bash
+curl -H "Authorization: Bearer $MATRIXLAB_SANDBOX_TOKEN" \
+  "$SPACE_URL/mcp/sessions/$SESSION_ID"
+```
+
+### List tools
+
+```bash
+curl -H "Authorization: Bearer $MATRIXLAB_SANDBOX_TOKEN" \
+  "$SPACE_URL/mcp/sessions/$SESSION_ID/tools"
+```
+
+### Call a tool
+
+```bash
+curl -X POST "$SPACE_URL/mcp/sessions/$SESSION_ID/tools/call" \
+  -H "Authorization: Bearer $MATRIXLAB_SANDBOX_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"example_tool","arguments":{}}'
+```
+
+### MVP safety constraints
+
+This HF mode is a compatibility sandbox, not hardened isolation. For the free MVP, use only curated MatrixHub entries and keep these defaults:
+
+- TTL max: 600 seconds
+- Max sessions: 1 per free Space
+- No user secrets
+- No arbitrary shell scripts
+- Allow only `npx`, `uvx`, `pipx`, `python`, `python3`, and `node` commands
+- Block `curl | bash`, `wget | bash`, `sudo`, `docker`, package-manager installs, and shell chaining
+
+
+---
+
+## MatrixHub 10-minute MCP sandbox worker
+
+This Space also exposes a MatrixHub-facing MCP sandbox API. It is designed to be
+called by the MatrixHub backend controller when a user clicks **Test in sandbox**.
+
+### Required Space secrets
+
+```text
+MATRIXLAB_SANDBOX_TOKEN=<random shared secret>
+MATRIXLAB_MCP_MAX_TTL_SECONDS=600
+MATRIXLAB_MCP_MAX_SESSIONS=1
+MATRIXLAB_MCP_INSTALL_TIMEOUT_SECONDS=120
+MATRIXLAB_MCP_STARTUP_TIMEOUT_SECONDS=45
+MATRIXLAB_MCP_RPC_TIMEOUT_SECONDS=20
+```
+
+### Worker endpoints
+
+```text
+GET    /mcp/health
+POST   /mcp/sessions
+GET    /mcp/sessions/{session_id}
+GET    /mcp/sessions/{session_id}/events
+GET    /mcp/sessions/{session_id}/tools
+POST   /mcp/sessions/{session_id}/tools/call
+DELETE /mcp/sessions/{session_id}
+```
+
+### Example direct test
+
+```bash
+curl -X POST "$SPACE_URL/mcp/sessions" \
+  -H "Authorization: Bearer $MATRIXLAB_SANDBOX_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "entity_id": "mcp_server:filesystem",
+    "runtime": "node",
+    "start_command": "npx -y @modelcontextprotocol/server-filesystem /tmp",
+    "transport": "stdio",
+    "ttl_seconds": 600
+  }'
+```
+
+Then stream events:
+
+```bash
+curl -N "$SPACE_URL/mcp/sessions/$SESSION_ID/events" \
+  -H "Authorization: Bearer $MATRIXLAB_SANDBOX_TOKEN"
+```
+
+This worker is for curated compatibility testing only. Do not pass production
+secrets into it and do not expose it directly to browsers.

app/main.py

@@ -0,0 +1,232 @@
+"""MatrixLab HF Space microservice for remote repo testing/debugging."""
+from __future__ import annotations
+
+import re
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Literal
+
+import httpx
+from fastapi import FastAPI, File, HTTPException, Request, UploadFile
+from fastapi.responses import FileResponse, HTMLResponse
+from fastapi.staticfiles import StaticFiles
+from fastapi.templating import Jinja2Templates
+from pydantic import BaseModel, Field
+
+from app.runner_client import RunnerClient
+from app.sandbox import run_verification
+from app.mcp_sandbox import router as mcp_sandbox_router
+
+app = FastAPI(title="MatrixLab HF Backend", version="1.2.0")
+app.include_router(mcp_sandbox_router)
+
+BASE_DIR = Path(__file__).resolve().parent
+app.mount("/static", StaticFiles(directory=str(BASE_DIR / "static")), name="static")
+templates = Jinja2Templates(directory=str(BASE_DIR / "templates"))
+
+# In-memory run store (zip verification)
+runs: dict[str, dict] = {}
+runner = RunnerClient()
+
+PROFILE_PRESETS: Dict[str, Dict[str, Any]] = {
+    "gitpilot": {
+        "repo_url": "https://github.com/ruslanmv/gitpilot",
+        "task_command": "pytest -q || python -m unittest discover || python -m compileall .",
+        "setup_script": "if [ -f requirements.txt ]; then python -m venv .venv && . .venv/bin/activate && pip install -U pip && pip install -r requirements.txt; fi",
+    },
+    "agent-generator": {
+        "repo_url": "https://github.com/ruslanmv/agent-generator",
+        "task_command": "pytest -q || python -m unittest discover || python -m compileall .",
+        "setup_script": "if [ -f requirements.txt ]; then python -m venv .venv && . .venv/bin/activate && pip install -U pip && pip install -r requirements.txt; fi",
+    },
+    "repoguardian": {
+        "repo_url": "https://github.com/ruslanmv/RepoGuardian",
+        "task_command": "pytest -q || python -m unittest discover || python -m compileall .",
+        "setup_script": "if [ -f requirements.txt ]; then python -m venv .venv && . .venv/bin/activate && pip install -U pip && pip install -r requirements.txt; fi",
+    },
+}
+
+ALLOWED_REPO_PATTERN = re.compile(r"^https://github\.com/[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+/?$")
+
+
+class RepoTaskRequest(BaseModel):
+    environment_id: str = Field(..., min_length=3, max_length=64, pattern=r"^[a-zA-Z0-9._-]+$")
+    repo_url: str
+    default_branch: str = "main"
+    branch: str = "main"
+    command: str | None = None
+    setup_script: str | None = None
+    maintenance_script: str = "echo 'maintenance complete'"
+    sandbox_image: str = "matrix-lab-sandbox-python:latest"
+    profile: Literal["custom", "gitpilot", "agent-generator", "repoguardian"] = "custom"
+    force_rebuild: bool = False
+
+
+@app.get("/health")
+async def health():
+    runner_status = {"status": "unknown"}
+    try:
+        runner_status = runner.health()
+    except Exception as e:  # best-effort surface
+        runner_status = {"status": "unreachable", "error": str(e)}
+
+    return {
+        "status": "ok",
+        "version": "1.2.0",
+        "runs": len(runs),
+        "runner_url": runner.base_url,
+        "runner": runner_status,
+    }
+
+
+@app.get("/profiles")
+async def list_profiles():
+    return {"profiles": PROFILE_PRESETS}
+
+
+@app.post("/repo/run")
+async def repo_run(req: RepoTaskRequest):
+    if req.profile in PROFILE_PRESETS:
+        preset = PROFILE_PRESETS[req.profile]
+        repo_url = preset["repo_url"]
+        setup_script = req.setup_script or preset["setup_script"]
+        command = req.command or preset["task_command"]
+    else:
+        repo_url = req.repo_url
+        setup_script = req.setup_script or "echo 'No setup script configured.'"
+        command = req.command or "pytest -q || python -m unittest discover || python -m compileall ."
+
+    if not ALLOWED_REPO_PATTERN.match(repo_url):
+        raise HTTPException(status_code=400, detail="repo_url must be a valid GitHub HTTPS repository URL")
+
+    env_payload = {
+        "environment_id": req.environment_id,
+        "repo_url": repo_url,
+        "default_branch": req.default_branch,
+        "sandbox_image": req.sandbox_image,
+        "setup_script": setup_script,
+        "maintenance_script": req.maintenance_script,
+        "task_command": command,
+        "setup_network": "egress",
+        "task_network": "none",
+    }
+
+    try:
+        env = runner.create_or_update_environment(env_payload)
+        bootstrap = runner.bootstrap_environment(req.environment_id, force_rebuild=req.force_rebuild)
+        task = runner.run_environment_task(
+            req.environment_id,
+            {
+                "branch": req.branch,
+                "command": command,
+                "task_network": "none",
+            },
+        )
+    except httpx.HTTPStatusError as e:
+        detail = e.response.text if e.response is not None else str(e)
+        raise HTTPException(status_code=502, detail=f"runner error: {detail}")
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+    return {
+        "environment": env,
+        "bootstrap": bootstrap,
+        "task": task,
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+    }
+
+
+# Existing ZIP verification UI/API --------------------------------------------
+
+SPACE_INDEX = BASE_DIR / "static" / "space" / "index.html"
+
+
+@app.get("/", response_class=HTMLResponse)
+async def home():
+    """MatrixLab Space — Matrix CLI Console + sandbox-enable button."""
+    return FileResponse(str(SPACE_INDEX), media_type="text/html")
+
+
+@app.get("/verify", response_class=HTMLResponse)
+async def verify_home(request: Request):
+    """Legacy ZIP-verification UI (moved from /)."""
+    recent = sorted(runs.values(), key=lambda r: r.get("created", ""), reverse=True)[:20]
+    return templates.TemplateResponse(
+        request=request,
+        name="home.html",
+        context={"request": request, "runs": recent, "runner_url": runner.base_url},
+    )
+
+
+@app.post("/upload", response_class=HTMLResponse)
+async def upload(request: Request, file: UploadFile = File(...)):
+    if not file.filename or not file.filename.endswith(".zip"):
+        return templates.TemplateResponse(
+            request=request,
+            name="home.html",
+            context={"request": request, "runs": list(runs.values())[:20], "error": "Please upload a .zip file.", "runner_url": runner.base_url},
+        )
+
+    zip_bytes = await file.read()
+    if len(zip_bytes) > 50 * 1024 * 1024:
+        return templates.TemplateResponse(
+            request=request,
+            name="home.html",
+            context={"request": request, "runs": list(runs.values())[:20], "error": "File too large. Maximum 50MB.", "runner_url": runner.base_url},
+        )
+
+    run_id = str(uuid.uuid4())[:8]
+    result = run_verification(zip_bytes)
+
+    run_data = {
+        "id": run_id,
+        "filename": file.filename,
+        "status": result.status,
+        "language": result.detected_language,
+        "framework": result.detected_framework,
+        "files_count": result.files_count,
+        "steps": [{"name": s.name, "status": s.status, "message": s.message, "logs": s.logs} for s in result.steps],
+        "summary": result.summary,
+        "created": datetime.now(timezone.utc).isoformat(),
+    }
+    runs[run_id] = run_data
+
+    return templates.TemplateResponse(request=request, name="result.html", context={"request": request, "run": run_data})
+
+
+@app.post("/runs")
+async def api_create_run(file: UploadFile = File(...)):
+    zip_bytes = await file.read()
+    if len(zip_bytes) > 50 * 1024 * 1024:
+        raise HTTPException(status_code=413, detail="File too large. Maximum 50MB.")
+
+    run_id = str(uuid.uuid4())[:8]
+    result = run_verification(zip_bytes)
+
+    run_data = {
+        "id": run_id,
+        "filename": file.filename or "project.zip",
+        "status": result.status,
+        "language": result.detected_language,
+        "framework": result.detected_framework,
+        "files_count": result.files_count,
+        "steps": [{"name": s.name, "status": s.status, "message": s.message, "logs": s.logs} for s in result.steps],
+        "summary": result.summary,
+        "created": datetime.now(timezone.utc).isoformat(),
+    }
+    runs[run_id] = run_data
+    return run_data
+
+
+@app.get("/runs")
+async def api_list_runs():
+    recent = sorted(runs.values(), key=lambda r: r.get("created", ""), reverse=True)[:50]
+    return {"runs": recent, "total": len(runs)}
+
+
+@app.get("/runs/{run_id}")
+async def api_get_run(run_id: str):
+    if run_id not in runs:
+        raise HTTPException(status_code=404, detail="Run not found")
+    return runs[run_id]

app/mcp_sandbox.py

@@ -0,0 +1,567 @@
+"""Hugging Face MCP sandbox worker for MatrixHub.
+
+This module is the runtime that lives inside the Hugging Face Docker Space.
+MatrixHub should call it through the MatrixHub backend only, never directly from
+browser clients.
+
+Scope of this MVP:
+- Start one or a few short-lived stdio MCP server subprocesses.
+- Initialize the MCP server and run tools/list.
+- Allow controlled tool calls during a hard TTL, default 10 minutes.
+- Stream lifecycle events over SSE.
+- Kill the subprocess and delete /tmp state at expiry.
+
+Security note: this is a compatibility/demo sandbox for curated MatrixHub
+catalog entries. It is not equivalent to Firecracker, gVisor, Kata, or a
+hardened multi-tenant arbitrary-code execution platform.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import shlex
+import shutil
+import time
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, AsyncIterator, Literal
+
+from fastapi import APIRouter, Header, HTTPException, Request
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel, Field
+
+router = APIRouter(prefix="/mcp", tags=["mcp-sandbox"])
+
+MAX_TTL_SECONDS = int(os.environ.get("MATRIXLAB_MCP_MAX_TTL_SECONDS", "600"))
+MAX_INSTALL_SECONDS = int(os.environ.get("MATRIXLAB_MCP_INSTALL_TIMEOUT_SECONDS", "120"))
+MAX_STARTUP_SECONDS = int(os.environ.get("MATRIXLAB_MCP_STARTUP_TIMEOUT_SECONDS", "45"))
+MAX_RPC_SECONDS = int(os.environ.get("MATRIXLAB_MCP_RPC_TIMEOUT_SECONDS", "20"))
+MAX_LOG_CHARS = int(os.environ.get("MATRIXLAB_MCP_MAX_LOG_CHARS", "20000"))
+MAX_EVENT_HISTORY = int(os.environ.get("MATRIXLAB_MCP_MAX_EVENT_HISTORY", "200"))
+BASE_WORKDIR = Path(os.environ.get("MATRIXLAB_MCP_WORKDIR", "/tmp/matrixlab-mcp-sessions"))
+SANDBOX_TOKEN = os.environ.get("MATRIXLAB_SANDBOX_TOKEN", "").strip()
+
+# Per-session memory budget (MB) used to derive a safe concurrent-session cap
+# from the Hugging Face instance specs when MATRIXLAB_MCP_MAX_SESSIONS=auto.
+MB_PER_SESSION = int(os.environ.get("MATRIXLAB_MCP_MB_PER_SESSION", "700"))
+# Absolute ceiling so a large box can't spawn an unbounded number of procs.
+MAX_SESSIONS_CEILING = int(os.environ.get("MATRIXLAB_MCP_MAX_SESSIONS_CEILING", "32"))
+
+
+def _detect_total_mem_mb() -> int:
+    """Total RAM in MB (cgroup-aware), best-effort. 0 if unknown."""
+    # Respect a container memory limit first (HF runs in containers/cgroups).
+    for path in (
+        "/sys/fs/cgroup/memory.max",                      # cgroup v2
+        "/sys/fs/cgroup/memory/memory.limit_in_bytes",    # cgroup v1
+    ):
+        try:
+            raw = Path(path).read_text().strip()
+            if raw and raw != "max":
+                val = int(raw)
+                # cgroup v1 reports a huge sentinel when unlimited; ignore it.
+                if 0 < val < (1 << 62):
+                    return val // (1024 * 1024)
+        except Exception:
+            pass
+    try:
+        for line in Path("/proc/meminfo").read_text().splitlines():
+            if line.startswith("MemTotal:"):
+                return int(line.split()[1]) // 1024  # kB -> MB
+    except Exception:
+        pass
+    return 0
+
+
+def _resolve_max_sessions() -> int:
+    """Resolve the concurrent-session cap.
+
+    ``MATRIXLAB_MCP_MAX_SESSIONS`` may be an integer or ``auto``. ``auto``
+    derives a safe cap from the instance specs (CPU count and total RAM)
+    so MatrixLab can serve up to ~10 parallel sandboxes on a typical
+    HF CPU-upgrade box without overcommitting memory.
+    """
+    raw = os.environ.get("MATRIXLAB_MCP_MAX_SESSIONS", "auto").strip().lower()
+    if raw not in ("", "auto"):
+        try:
+            return max(1, min(int(raw), MAX_SESSIONS_CEILING))
+        except ValueError:
+            pass
+    cpu = os.cpu_count() or 2
+    mem_mb = _detect_total_mem_mb()
+    # Reserve ~1.5 GB for the OS + uvicorn + node/npm caches.
+    usable_mb = max(0, mem_mb - 1536) if mem_mb else 0
+    by_mem = (usable_mb // MB_PER_SESSION) if usable_mb else cpu * 2
+    by_cpu = cpu * 2  # MCP servers are largely I/O-bound during a trial
+    derived = min(by_mem, by_cpu) if by_mem else by_cpu
+    return max(1, min(derived, MAX_SESSIONS_CEILING))
+
+
+MAX_SESSIONS = _resolve_max_sessions()
+
+# Keep this narrow for the free HF MVP. Add more prefixes only after review.
+ALLOWED_BINARIES = {"npx", "uvx", "pipx", "python", "python3", "node"}
+
+BLOCKED_TOKENS = {
+    "sudo", "docker", "podman", "kubectl", "systemctl", "mount", "umount",
+    "mkfs", "apt", "apt-get", "yum", "dnf", "apk", "curl", "wget", "chmod",
+    "chown", "ssh", "scp", "bash", "sh", "zsh", "fish", "powershell",
+}
+
+BLOCKED_SUBSTRINGS = ["|", ";", "&&", "||", "`", "$(", ">", "<", "\n", "\r", "rm -rf /"]
+ACTIVE_STATUSES = {"created", "installing", "starting", "initializing", "running"}
+TERMINAL_STATUSES = {"expired", "deleted", "failed", "timeout", "install_failed", "start_failed", "mcp_failed"}
+
+
+class StartSessionRequest(BaseModel):
+    entity_id: str = Field(..., min_length=1, max_length=160)
+    runtime: Literal["node", "python", "generic"] = "generic"
+    start_command: str = Field(..., min_length=2, max_length=1000)
+    install_command: str | None = Field(default=None, max_length=1000)
+    transport: Literal["stdio"] = "stdio"
+    ttl_seconds: int = Field(default=600, ge=30, le=600)
+    env: dict[str, str] = Field(default_factory=dict)
+
+
+class ToolCallRequest(BaseModel):
+    name: str = Field(..., min_length=1, max_length=160)
+    arguments: dict[str, Any] = Field(default_factory=dict)
+
+
+@dataclass
+class Session:
+    id: str
+    entity_id: str
+    workdir: Path
+    start_command: str
+    install_command: str | None
+    status: str = "created"
+    created_at: float = field(default_factory=time.time)
+    expires_at: float = 0.0
+    process: asyncio.subprocess.Process | None = None
+    logs: list[str] = field(default_factory=list)
+    tools: list[dict[str, Any]] = field(default_factory=list)
+    rpc_id: int = 0
+    rpc_lock: asyncio.Lock = field(default_factory=asyncio.Lock)
+    stderr_task: asyncio.Task | None = None
+    cleanup_task: asyncio.Task | None = None
+    events: list[dict[str, Any]] = field(default_factory=list)
+    event_queue: asyncio.Queue[dict[str, Any]] = field(default_factory=asyncio.Queue)
+
+    def emit(self, step: str, status: str, message: str, data: dict[str, Any] | None = None) -> None:
+        event = {
+            "session_id": self.id,
+            "entity_id": self.entity_id,
+            "ts": time.time(),
+            "step": step,
+            "status": status,
+            "message": message,
+            "data": data or {},
+        }
+        self.events.append(event)
+        if len(self.events) > MAX_EVENT_HISTORY:
+            self.events = self.events[-MAX_EVENT_HISTORY:]
+        try:
+            self.event_queue.put_nowait(event)
+        except asyncio.QueueFull:
+            pass
+
+    def add_log(self, text: str) -> None:
+        if not text:
+            return
+        text = text[-MAX_LOG_CHARS:]
+        self.logs.append(text)
+        joined = "\n".join(self.logs)
+        if len(joined) > MAX_LOG_CHARS:
+            self.logs = [joined[-MAX_LOG_CHARS:]]
+        self.emit("logs", "ok", "log output", {"text": text[-4000:]})
+
+
+sessions: dict[str, Session] = {}
+
+
+def _require_auth(authorization: str | None) -> None:
+    if not SANDBOX_TOKEN:
+        return
+    if authorization != f"Bearer {SANDBOX_TOKEN}":
+        raise HTTPException(status_code=401, detail="missing or invalid sandbox token")
+
+
+def _validate_command(command: str) -> list[str]:
+    lowered = command.lower()
+    for bad in BLOCKED_SUBSTRINGS:
+        if bad in lowered:
+            raise HTTPException(status_code=400, detail=f"blocked shell pattern: {bad}")
+
+    try:
+        parts = shlex.split(command)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=f"invalid command: {e}") from e
+
+    if not parts:
+        raise HTTPException(status_code=400, detail="empty command")
+
+    binary = Path(parts[0]).name
+    if binary not in ALLOWED_BINARIES:
+        raise HTTPException(status_code=400, detail=f"command not allowed: {binary}")
+
+    for token in parts:
+        normalized = Path(token).name.lower()
+        if normalized in BLOCKED_TOKENS:
+            raise HTTPException(status_code=400, detail=f"blocked token: {token}")
+
+    return parts
+
+
+def _public_session(s: Session) -> dict[str, Any]:
+    return {
+        "session_id": s.id,
+        "entity_id": s.entity_id,
+        "status": s.status,
+        "created_at": s.created_at,
+        "expires_at": s.expires_at,
+        "ttl_remaining_seconds": max(0, int(s.expires_at - time.time())),
+        "tools": s.tools,
+        "logs": s.logs[-5:],
+        "events": s.events[-20:],
+    }
+
+
+def _sse(event: dict[str, Any], event_name: str = "message") -> str:
+    return f"event: {event_name}\ndata: {json.dumps(event, ensure_ascii=False)}\n\n"
+
+
+async def _read_stderr(session: Session) -> None:
+    proc = session.process
+    if not proc or not proc.stderr:
+        return
+    while True:
+        line = await proc.stderr.readline()
+        if not line:
+            return
+        session.add_log("[stderr] " + line.decode(errors="replace").rstrip())
+
+
+async def _send_json(proc: asyncio.subprocess.Process, msg: dict[str, Any]) -> None:
+    if proc.stdin is None:
+        raise RuntimeError("MCP process stdin is closed")
+    proc.stdin.write((json.dumps(msg) + "\n").encode())
+    await proc.stdin.drain()
+
+
+async def _recv_json(proc: asyncio.subprocess.Process, timeout_s: int = MAX_RPC_SECONDS) -> dict[str, Any]:
+    if proc.stdout is None:
+        raise RuntimeError("MCP process stdout is closed")
+
+    async def _read_loop() -> dict[str, Any]:
+        while True:
+            line = await proc.stdout.readline()
+            if not line:
+                raise RuntimeError("MCP process exited before response")
+            raw = line.decode(errors="replace").strip()
+            if not raw:
+                continue
+            try:
+                return json.loads(raw)
+            except json.JSONDecodeError:
+                # Some MCP servers print startup logs to stdout; retain and ignore.
+                continue
+
+    return await asyncio.wait_for(_read_loop(), timeout=timeout_s)
+
+
+async def _rpc(session: Session, method: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+    proc = session.process
+    if not proc or proc.returncode is not None:
+        raise HTTPException(status_code=409, detail="MCP session is not running")
+
+    async with session.rpc_lock:
+        session.rpc_id += 1
+        request_id = session.rpc_id
+        await _send_json(proc, {"jsonrpc": "2.0", "id": request_id, "method": method, "params": params or {}})
+        while True:
+            resp = await _recv_json(proc)
+            # Ignore notifications and unrelated ids.
+            if resp.get("id") != request_id:
+                continue
+            if "error" in resp:
+                raise HTTPException(status_code=502, detail=resp["error"])
+            return resp
+
+
+async def _initialize_and_list_tools(session: Session) -> None:
+    proc = session.process
+    if not proc:
+        raise RuntimeError("process not started")
+
+    async with session.rpc_lock:
+        session.rpc_id += 1
+        init_id = session.rpc_id
+        session.emit("mcp_initialize", "start", "Initializing MCP server")
+        await _send_json(
+            proc,
+            {
+                "jsonrpc": "2.0",
+                "id": init_id,
+                "method": "initialize",
+                "params": {
+                    "protocolVersion": "2024-11-05",
+                    "capabilities": {},
+                    "clientInfo": {"name": "matrixhub-hf-sandbox", "version": "0.2.0"},
+                },
+            },
+        )
+        while True:
+            init_resp = await _recv_json(proc, timeout_s=MAX_RPC_SECONDS)
+            if init_resp.get("id") != init_id:
+                continue
+            break
+        if "error" in init_resp:
+            raise RuntimeError(f"MCP initialize failed: {init_resp['error']}")
+        session.emit("mcp_initialize", "ok", "MCP initialize succeeded")
+
+        await _send_json(proc, {"jsonrpc": "2.0", "method": "notifications/initialized", "params": {}})
+
+        session.rpc_id += 1
+        tools_id = session.rpc_id
+        session.emit("tools_list", "start", "Listing MCP tools")
+        await _send_json(proc, {"jsonrpc": "2.0", "id": tools_id, "method": "tools/list", "params": {}})
+        while True:
+            tools_resp = await _recv_json(proc, timeout_s=MAX_RPC_SECONDS)
+            if tools_resp.get("id") != tools_id:
+                continue
+            break
+        if "error" in tools_resp:
+            raise RuntimeError(f"MCP tools/list failed: {tools_resp['error']}")
+
+        result = tools_resp.get("result") or {}
+        tools = result.get("tools") or []
+        session.tools = tools if isinstance(tools, list) else []
+        session.emit("tools_list", "ok", f"Found {len(session.tools)} tools", {"tools_count": len(session.tools)})
+
+
+async def _run_session(session_id: str, req: StartSessionRequest) -> None:
+    session = sessions[session_id]
+    session.status = "installing" if req.install_command else "starting"
+
+    try:
+        env = os.environ.copy()
+        # Do not pass arbitrary secrets. Only explicit non-sensitive public env.
+        for key, value in req.env.items():
+            if not key.startswith("MATRIXHUB_PUBLIC_"):
+                raise RuntimeError(f"env key not allowed: {key}")
+            env[key] = value
+
+        if req.install_command:
+            session.emit("install", "start", "Installing MCP server")
+            install_parts = _validate_command(req.install_command)
+            install_proc = await asyncio.create_subprocess_exec(
+                *install_parts,
+                cwd=session.workdir,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.STDOUT,
+                env=env,
+            )
+            output, _ = await asyncio.wait_for(install_proc.communicate(), timeout=MAX_INSTALL_SECONDS)
+            session.add_log(output.decode(errors="replace"))
+            if install_proc.returncode != 0:
+                session.status = "install_failed"
+                session.emit("install", "error", "Install failed", {"returncode": install_proc.returncode})
+                await cleanup_session(session_id, final_status="install_failed")
+                return
+            session.emit("install", "ok", "Install completed")
+
+        session.status = "starting"
+        session.emit("start", "start", "Starting MCP server")
+        start_parts = _validate_command(req.start_command)
+        proc = await asyncio.create_subprocess_exec(
+            *start_parts,
+            cwd=session.workdir,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            env=env,
+        )
+        session.process = proc
+        session.stderr_task = asyncio.create_task(_read_stderr(session))
+        session.emit("start", "ok", "MCP process started", {"pid": getattr(proc, "pid", None)})
+
+        session.status = "initializing"
+        await asyncio.wait_for(_initialize_and_list_tools(session), timeout=MAX_STARTUP_SECONDS)
+        session.status = "running"
+        session.emit("ready", "ok", "Sandbox ready for testing", {"ttl_remaining_seconds": max(0, int(session.expires_at - time.time()))})
+
+    except asyncio.TimeoutError:
+        session.status = "timeout"
+        session.add_log("session timed out during install/startup")
+        session.emit("timeout", "error", "Session timed out during install/startup")
+        await cleanup_session(session_id, final_status="timeout")
+    except Exception as e:
+        session.status = "failed"
+        session.add_log(str(e))
+        session.emit("failed", "error", str(e))
+        await cleanup_session(session_id, final_status="failed")
+
+
+async def cleanup_session(session_id: str, final_status: str = "expired") -> None:
+    session = sessions.get(session_id)
+    if not session:
+        return
+
+    if session.status in TERMINAL_STATUSES and final_status == "expired":
+        return
+
+    proc = session.process
+    if proc and proc.returncode is None:
+        try:
+            proc.terminate()
+            await asyncio.wait_for(proc.wait(), timeout=3)
+        except Exception:
+            try:
+                proc.kill()
+                await proc.wait()
+            except Exception:
+                pass
+
+    if session.stderr_task:
+        session.stderr_task.cancel()
+
+    shutil.rmtree(session.workdir, ignore_errors=True)
+    session.status = final_status
+    session.emit("cleanup", "ok" if final_status in {"expired", "deleted"} else "error", f"Session {final_status}")
+
+
+async def _expire_later(session_id: str, ttl_seconds: int) -> None:
+    await asyncio.sleep(ttl_seconds)
+    await cleanup_session(session_id, final_status="expired")
+
+
+@router.get("/health")
+async def mcp_health():
+    active = len([s for s in sessions.values() if s.status in ACTIVE_STATUSES])
+    return {
+        "status": "ok",
+        "active_sessions": active,
+        "max_sessions": MAX_SESSIONS,
+        "available_slots": max(0, MAX_SESSIONS - active),
+        "max_ttl_seconds": MAX_TTL_SECONDS,
+        "instance": {
+            "cpu": os.cpu_count(),
+            "total_mem_mb": _detect_total_mem_mb(),
+            "mb_per_session": MB_PER_SESSION,
+        },
+    }
+
+
+@router.post("/sessions")
+async def start_session(req: StartSessionRequest, authorization: str | None = Header(default=None)):
+    _require_auth(authorization)
+
+    active = [s for s in sessions.values() if s.status in ACTIVE_STATUSES]
+    if len(active) >= MAX_SESSIONS:
+        raise HTTPException(status_code=429, detail="no sandbox capacity available")
+
+    if req.ttl_seconds > MAX_TTL_SECONDS:
+        raise HTTPException(status_code=400, detail=f"max ttl is {MAX_TTL_SECONDS} seconds")
+
+    if req.install_command:
+        _validate_command(req.install_command)
+    _validate_command(req.start_command)
+
+    BASE_WORKDIR.mkdir(parents=True, exist_ok=True)
+    session_id = "mcp_" + uuid.uuid4().hex[:16]
+    workdir = BASE_WORKDIR / session_id
+    workdir.mkdir(parents=True, exist_ok=False)
+
+    session = Session(
+        id=session_id,
+        entity_id=req.entity_id,
+        workdir=workdir,
+        start_command=req.start_command,
+        install_command=req.install_command,
+        expires_at=time.time() + req.ttl_seconds,
+    )
+    sessions[session_id] = session
+    session.emit("resolve", "ok", f"Accepted sandbox request for {req.entity_id}")
+
+    asyncio.create_task(_run_session(session_id, req))
+    session.cleanup_task = asyncio.create_task(_expire_later(session_id, req.ttl_seconds))
+
+    return _public_session(session)
+
+
+@router.get("/sessions")
+async def list_sessions(authorization: str | None = Header(default=None)):
+    _require_auth(authorization)
+    return {"sessions": [_public_session(s) for s in sessions.values()]}
+
+
+@router.get("/sessions/{session_id}")
+async def get_session(session_id: str, authorization: str | None = Header(default=None)):
+    _require_auth(authorization)
+    session = sessions.get(session_id)
+    if not session:
+        raise HTTPException(status_code=404, detail="session not found")
+    return _public_session(session)
+
+
+@router.get("/sessions/{session_id}/events")
+async def stream_events(session_id: str, request: Request, authorization: str | None = Header(default=None)):
+    _require_auth(authorization)
+    session = sessions.get(session_id)
+    if not session:
+        raise HTTPException(status_code=404, detail="session not found")
+
+    async def event_generator() -> AsyncIterator[str]:
+        for event in session.events:
+            yield _sse(event)
+        while True:
+            if await request.is_disconnected():
+                break
+            if session.status in TERMINAL_STATUSES and session.event_queue.empty():
+                yield _sse({"session_id": session.id, "step": "closed", "status": "ok", "message": session.status, "data": {}}, "done")
+                break
+            try:
+                event = await asyncio.wait_for(session.event_queue.get(), timeout=15)
+                yield _sse(event)
+            except asyncio.TimeoutError:
+                yield ": keep-alive\n\n"
+
+    return StreamingResponse(event_generator(), media_type="text/event-stream")
+
+
+@router.get("/sessions/{session_id}/tools")
+async def list_tools(session_id: str, authorization: str | None = Header(default=None)):
+    _require_auth(authorization)
+    session = sessions.get(session_id)
+    if not session:
+        raise HTTPException(status_code=404, detail="session not found")
+    if session.status != "running":
+        raise HTTPException(status_code=409, detail=f"session is {session.status}")
+    return {"tools": session.tools}
+
+
+@router.post("/sessions/{session_id}/tools/call")
+async def call_tool(session_id: str, req: ToolCallRequest, authorization: str | None = Header(default=None)):
+    _require_auth(authorization)
+    session = sessions.get(session_id)
+    if not session:
+        raise HTTPException(status_code=404, detail="session not found")
+    if session.status != "running":
+        raise HTTPException(status_code=409, detail=f"session is {session.status}")
+
+    session.emit("tool_call", "start", f"Calling tool {req.name}", {"name": req.name})
+    response = await _rpc(session, "tools/call", {"name": req.name, "arguments": req.arguments})
+    session.emit("tool_call", "ok", f"Tool {req.name} completed", {"name": req.name})
+    return response.get("result", response)
+
+
+@router.delete("/sessions/{session_id}")
+async def delete_session(session_id: str, authorization: str | None = Header(default=None)):
+    _require_auth(authorization)
+    if session_id not in sessions:
+        raise HTTPException(status_code=404, detail="session not found")
+    await cleanup_session(session_id, final_status="deleted")
+    return {"ok": True, "session_id": session_id, "status": "deleted"}

app/runner_client.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import os
+from typing import Any, Dict
+
+import httpx
+
+
+class RunnerClient:
+    def __init__(self) -> None:
+        self.base_url = os.environ.get("MATRIXLAB_RUNNER_URL", "http://localhost:8000").rstrip("/")
+        timeout_s = float(os.environ.get("MATRIXLAB_RUNNER_TIMEOUT_S", "120"))
+        self.client = httpx.Client(base_url=self.base_url, timeout=httpx.Timeout(timeout_s))
+
+    def health(self) -> Dict[str, Any]:
+        res = self.client.get("/health")
+        res.raise_for_status()
+        return res.json()
+
+    def create_or_update_environment(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        res = self.client.post("/environments", json=payload)
+        res.raise_for_status()
+        return res.json()
+
+    def bootstrap_environment(self, environment_id: str, force_rebuild: bool = False) -> Dict[str, Any]:
+        res = self.client.post(
+            f"/environments/{environment_id}/bootstrap",
+            json={"force_rebuild": force_rebuild},
+        )
+        res.raise_for_status()
+        return res.json()
+
+    def run_environment_task(self, environment_id: str, payload: Dict[str, Any]) -> Dict[str, Any]:
+        res = self.client.post(f"/environments/{environment_id}/run-task", json=payload)
+        res.raise_for_status()
+        return res.json()

app/sandbox.py

@@ -0,0 +1,316 @@
+"""
+MatrixLab Sandbox Runner — executes and verifies project artifacts safely.
+
+Runs in isolated temp directories with subprocess timeouts.
+No Docker required (HF Spaces compatible).
+"""
+from __future__ import annotations
+
+import ast
+import os
+import shutil
+import subprocess
+import tempfile
+import zipfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal
+
+import yaml
+
+
+@dataclass
+class StepResult:
+    name: str
+    status: Literal["success", "warning", "error", "skipped"]
+    message: str = ""
+    logs: str = ""
+
+
+@dataclass
+class RunResult:
+    status: Literal["success", "warning", "error"]
+    steps: list[StepResult] = field(default_factory=list)
+    detected_language: str = ""
+    detected_framework: str = ""
+    files_count: int = 0
+    summary: str = ""
+
+
+def run_verification(zip_bytes: bytes, timeout: int = 120) -> RunResult:
+    """Unpack a ZIP and run a multi-stage verification pipeline."""
+    steps: list[StepResult] = []
+    work_dir = tempfile.mkdtemp(prefix="matrixlab_")
+
+    try:
+        # Stage 1: Unpack
+        step = _unpack(zip_bytes, work_dir)
+        steps.append(step)
+        if step.status == "error":
+            return RunResult(status="error", steps=steps, summary="Failed to unpack ZIP.")
+
+        # Find the project root (may be inside a subfolder)
+        project_dir = _find_project_root(work_dir)
+        files = list(Path(project_dir).rglob("*"))
+        file_count = len([f for f in files if f.is_file()])
+
+        # Stage 2: Detect language/framework
+        lang, framework = _detect(project_dir)
+        steps.append(StepResult(
+            name="detect",
+            status="success",
+            message=f"Language: {lang}, Framework: {framework}",
+        ))
+
+        # Stage 3: Validate syntax
+        step = _validate_syntax(project_dir)
+        steps.append(step)
+
+        # Stage 4: Security scan
+        step = _security_scan(project_dir)
+        steps.append(step)
+
+        # Stage 5: Dependency check
+        step = _check_dependencies(project_dir)
+        steps.append(step)
+
+        # Stage 6: Import test (Python only)
+        if lang == "python":
+            step = _import_test(project_dir, timeout=min(timeout, 30))
+            steps.append(step)
+
+        # Stage 7: Run tests if present
+        step = _run_tests(project_dir, timeout=min(timeout, 60))
+        steps.append(step)
+
+        # Determine overall status
+        has_errors = any(s.status == "error" for s in steps)
+        has_warnings = any(s.status == "warning" for s in steps)
+        overall = "error" if has_errors else ("warning" if has_warnings else "success")
+
+        passed = len([s for s in steps if s.status == "success"])
+        total = len([s for s in steps if s.status != "skipped"])
+        summary = f"{passed}/{total} checks passed. Language: {lang}, Framework: {framework}."
+
+        return RunResult(
+            status=overall,
+            steps=steps,
+            detected_language=lang,
+            detected_framework=framework,
+            files_count=file_count,
+            summary=summary,
+        )
+    finally:
+        shutil.rmtree(work_dir, ignore_errors=True)
+
+
+def _unpack(zip_bytes: bytes, dest: str) -> StepResult:
+    try:
+        zip_path = os.path.join(dest, "project.zip")
+        with open(zip_path, "wb") as f:
+            f.write(zip_bytes)
+        with zipfile.ZipFile(zip_path, "r") as zf:
+            zf.extractall(dest)
+        os.remove(zip_path)
+        return StepResult(name="unpack", status="success", message="ZIP extracted successfully.")
+    except Exception as e:
+        return StepResult(name="unpack", status="error", message=str(e)[:200])
+
+
+def _find_project_root(base: str) -> str:
+    """Find the actual project root inside the unpacked directory."""
+    entries = os.listdir(base)
+    non_hidden = [e for e in entries if not e.startswith(".") and e != "__MACOSX"]
+    if len(non_hidden) == 1:
+        candidate = os.path.join(base, non_hidden[0])
+        if os.path.isdir(candidate):
+            return candidate
+    return base
+
+
+def _detect(project_dir: str) -> tuple[str, str]:
+    """Detect language and framework from project files."""
+    files = {f.name for f in Path(project_dir).rglob("*") if f.is_file()}
+    all_content = ""
+    for f in Path(project_dir).rglob("*.py"):
+        try:
+            all_content += f.read_text(errors="ignore")
+        except Exception:
+            pass
+
+    lang = "unknown"
+    framework = "unknown"
+
+    if any(f.endswith(".py") for f in files):
+        lang = "python"
+    elif any(f.endswith(".js") or f.endswith(".ts") for f in files):
+        lang = "javascript"
+    elif any(f.endswith(".go") for f in files):
+        lang = "go"
+
+    if "crewai" in all_content.lower() or "agents.yaml" in files:
+        framework = "crewai"
+    elif "langgraph" in all_content.lower() or "StateGraph" in all_content:
+        framework = "langgraph"
+    elif "react_loop" in all_content or "TOOLS" in all_content:
+        framework = "react"
+    elif "watsonx" in all_content.lower() or "agent.yaml" in files:
+        framework = "watsonx_orchestrate"
+    elif "Flow" in all_content and "crewai" in all_content.lower():
+        framework = "crewai_flow"
+
+    return lang, framework
+
+
+def _validate_syntax(project_dir: str) -> StepResult:
+    """Check Python syntax and YAML validity."""
+    errors = []
+    checked = 0
+
+    for f in Path(project_dir).rglob("*.py"):
+        checked += 1
+        try:
+            ast.parse(f.read_text(errors="ignore"), filename=str(f))
+        except SyntaxError as e:
+            errors.append(f"{f.name}:{e.lineno}: {e.msg}")
+
+    for f in Path(project_dir).rglob("*.yaml"):
+        checked += 1
+        try:
+            yaml.safe_load(f.read_text(errors="ignore"))
+        except yaml.YAMLError as e:
+            errors.append(f"{f.name}: {str(e)[:80]}")
+
+    for f in Path(project_dir).rglob("*.yml"):
+        checked += 1
+        try:
+            yaml.safe_load(f.read_text(errors="ignore"))
+        except yaml.YAMLError as e:
+            errors.append(f"{f.name}: {str(e)[:80]}")
+
+    if errors:
+        return StepResult(
+            name="syntax",
+            status="error",
+            message=f"{len(errors)} syntax error(s)",
+            logs="\n".join(errors),
+        )
+    return StepResult(name="syntax", status="success", message=f"{checked} files checked, all valid.")
+
+
+def _security_scan(project_dir: str) -> StepResult:
+    """AST-based security scan for dangerous patterns."""
+    issues = []
+
+    forbidden_calls = {"eval", "exec", "__import__"}
+    forbidden_attrs = {("os", "system"), ("subprocess", "Popen"), ("subprocess", "call")}
+
+    for f in Path(project_dir).rglob("*.py"):
+        try:
+            tree = ast.parse(f.read_text(errors="ignore"))
+        except SyntaxError:
+            continue
+
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Call):
+                if isinstance(node.func, ast.Name) and node.func.id in forbidden_calls:
+                    issues.append(f"{f.name}: {node.func.id}() at line {node.lineno}")
+                if isinstance(node.func, ast.Attribute) and isinstance(node.func.value, ast.Name):
+                    key = (node.func.value.id, node.func.attr)
+                    if key in forbidden_attrs:
+                        issues.append(f"{f.name}: {key[0]}.{key[1]}() at line {node.lineno}")
+
+    if issues:
+        return StepResult(
+            name="security",
+            status="error",
+            message=f"{len(issues)} security issue(s)",
+            logs="\n".join(issues),
+        )
+    return StepResult(name="security", status="success", message="No dangerous patterns found.")
+
+
+def _check_dependencies(project_dir: str) -> StepResult:
+    """Check if requirements.txt or pyproject.toml exists."""
+    has_requirements = (Path(project_dir) / "requirements.txt").exists()
+    has_pyproject = (Path(project_dir) / "pyproject.toml").exists()
+
+    if has_requirements or has_pyproject:
+        deps = []
+        if has_requirements:
+            content = (Path(project_dir) / "requirements.txt").read_text(errors="ignore")
+            deps = [l.strip() for l in content.splitlines() if l.strip() and not l.startswith("#")]
+        return StepResult(
+            name="dependencies",
+            status="success",
+            message=f"Found {len(deps)} dependencies.",
+        )
+    return StepResult(
+        name="dependencies",
+        status="warning",
+        message="No requirements.txt or pyproject.toml found.",
+    )
+
+
+def _import_test(project_dir: str, timeout: int = 30) -> StepResult:
+    """Try to import Python files to check for missing modules."""
+    py_files = list(Path(project_dir).rglob("*.py"))
+    if not py_files:
+        return StepResult(name="import_test", status="skipped", message="No Python files.")
+
+    # Find the main entry point
+    main_file = None
+    for candidate in ["main.py", "src/main.py", "app.py"]:
+        full = Path(project_dir) / candidate
+        if full.exists():
+            main_file = full
+            break
+    if not main_file:
+        for f in py_files:
+            if f.name == "main.py":
+                main_file = f
+                break
+    if not main_file:
+        main_file = py_files[0]
+
+    try:
+        result = subprocess.run(
+            ["python", "-c", f"import ast; ast.parse(open('{main_file}').read())"],
+            capture_output=True, text=True, timeout=timeout,
+            cwd=project_dir,
+        )
+        if result.returncode == 0:
+            return StepResult(name="import_test", status="success", message=f"Parsed {main_file.name} successfully.")
+        return StepResult(
+            name="import_test", status="warning",
+            message=f"Parse check had issues.", logs=result.stderr[:500],
+        )
+    except subprocess.TimeoutExpired:
+        return StepResult(name="import_test", status="warning", message="Import test timed out.")
+    except Exception as e:
+        return StepResult(name="import_test", status="warning", message=str(e)[:200])
+
+
+def _run_tests(project_dir: str, timeout: int = 60) -> StepResult:
+    """Run pytest if test files exist."""
+    test_files = list(Path(project_dir).rglob("test_*.py"))
+    if not test_files:
+        return StepResult(name="tests", status="skipped", message="No test files found.")
+
+    try:
+        result = subprocess.run(
+            ["python", "-m", "pytest", "--tb=short", "-q"] + [str(f) for f in test_files],
+            capture_output=True, text=True, timeout=timeout,
+            cwd=project_dir,
+            env={**os.environ, "PYTHONPATH": project_dir},
+        )
+        if result.returncode == 0:
+            return StepResult(name="tests", status="success", message="Tests passed.", logs=result.stdout[:1000])
+        return StepResult(
+            name="tests", status="error",
+            message="Tests failed.", logs=(result.stdout + result.stderr)[:1000],
+        )
+    except subprocess.TimeoutExpired:
+        return StepResult(name="tests", status="warning", message="Tests timed out.")
+    except Exception as e:
+        return StepResult(name="tests", status="warning", message=str(e)[:200])

app/static/space/data.jsx

@@ -0,0 +1,387 @@
+/* ============================================================
+   data.jsx — catalog data + CLI response engine
+   Exports to window.
+   ============================================================ */
+
+const TOOLS = [
+  { id: "retell-ai", initials: "RA", name: "Retell AI", type: "Voice Agent",
+    description: "Deploy real-time conversational AI agents for calls, support, and workflow automation.",
+    installs: "1.6K", rating: "3.5", updated: "2 days ago", verified: true, kind: "Tool",
+    tags: ["voice", "agent", "support", "calls", "automation"] },
+  { id: "openai-image", initials: "OA", name: "OpenAI Image", type: "Creative AI",
+    description: "Generate, edit, and transform product visuals directly inside agent workflows.",
+    installs: "8.9K", rating: "4.8", updated: "Today", verified: true, kind: "Tool",
+    tags: ["image", "creative", "generation", "workflow", "visuals"] },
+  { id: "microsoft-office", initials: "MS", name: "Microsoft Office", type: "Productivity",
+    description: "Connect docs, spreadsheets, email, and team knowledge to AI-powered automations.",
+    installs: "12K", rating: "4.6", updated: "1 week ago", verified: true, kind: "MCP Server",
+    tags: ["docs", "spreadsheets", "email", "team", "productivity"] },
+  { id: "talentlms", initials: "TL", name: "TalentLMS", type: "Learning Ops",
+    description: "Automate employee onboarding, learning paths, compliance checks, and reporting.",
+    installs: "940", rating: "4.2", updated: "4 days ago", verified: false, kind: "Agent",
+    tags: ["learning", "onboarding", "compliance", "training", "ops"] },
+];
+
+const SEARCH_RESULTS = [
+  { initials: "GW", name: "Github Webhook MCP", kind: "Tool", installs: "1.8K", rating: "3.5",
+    status: "Recently updated", verified: false, version: "1.4.0",
+    description: "Trigger agents, sync commits, and route webhook events through MCP workflows." },
+  { initials: "GI", name: "GitHub Inside Claude Code", kind: "Tool", installs: "1.3K", rating: "3.5",
+    status: "Recently updated", verified: false, version: "0.9.1",
+    description: "Repository context, pull request review, and coding actions from an agent workspace." },
+  { initials: "GS", name: "GitHub Semantic Search", kind: "MCP Server", installs: "3K", rating: "4.1",
+    status: "Recently updated", verified: true, version: "2.0.3",
+    description: "Ask questions across issues, code, discussions, and repository history." },
+  { initials: "GA", name: "GitHub Actions Agent", kind: "Agent", installs: "2.7K", rating: "4.4",
+    status: "Verified build", verified: true, version: "1.1.0",
+    description: "Debug CI failures, suggest workflow patches, and open remediation pull requests." },
+  { initials: "GP", name: "GitHub Pull Request Copilot", kind: "Agent", installs: "2.2K", rating: "4.3",
+    status: "Verified build", verified: true, version: "3.2.1",
+    description: "Summarize, test, and prepare pull requests for high-signal review." },
+  { initials: "GV", name: "GitHub Vulnerability Watch", kind: "Tool", installs: "1.5K", rating: "4.2",
+    status: "Verified build", verified: true, version: "0.7.4",
+    description: "Scan repo advisories and dependency activity before risky releases ship." },
+  { initials: "GD", name: "GitHub Docs Publisher", kind: "MCP Server", installs: "980", rating: "3.9",
+    status: "Recently updated", verified: false, version: "1.0.0",
+    description: "Publish repository docs into internal knowledge bases and public sites." },
+  { initials: "GR", name: "GitHub Release Orchestrator", kind: "Agent", installs: "1.1K", rating: "4.0",
+    status: "Verified build", verified: true, version: "2.3.0",
+    description: "Cut releases, generate changelogs, and coordinate multi-repo deploy gates." },
+];
+
+const CATEGORIES = [
+  { icon: "Database", label: "Data", text: "Databases, warehouses, vectors" },
+  { icon: "Code", label: "Developer Tools", text: "Git, CI, code intelligence" },
+  { icon: "Message", label: "Communication", text: "Slack, email, voice, support" },
+  { icon: "FileText", label: "Files", text: "Docs, drives, parsing, OCR" },
+  { icon: "Brain", label: "AI & RAG", text: "Embeddings, retrieval, memory" },
+  { icon: "Globe", label: "Web & Browsing", text: "Browsing, search, extraction" },
+];
+
+const RETELL_FEATURES = [
+  { title: "Voice agent operations", icon: "Radio",
+    text: "Create, test, and manage phone-call agents from one focused interface." },
+  { title: "LLM + voice discovery", icon: "Layers",
+    text: "Inspect voices, model layers, latency posture, and handoff readiness." },
+  { title: "Secure install path", icon: "Shield",
+    text: "Copy commands or launch the Matrix Protocol Helper with clear feedback." },
+];
+
+const INSTALL_COMMAND =
+  "matrix install tool.io-github-mindstone-mcp-server-retell-ai.5425b3de29@0.2.2 --alias retell-ai";
+
+function scoreTool(tool, query) {
+  const normalized = query.trim().toLowerCase();
+  if (!normalized) return 100 + (tool.verified ? 10 : 0) + Number(tool.rating);
+  const tokens = normalized.split(" ").filter(Boolean);
+  const haystack = `${tool.name} ${tool.type} ${tool.description} ${tool.tags.join(" ")}`.toLowerCase();
+  return (
+    tokens.reduce((score, token) => {
+      if (tool.name.toLowerCase().includes(token)) return score + 30;
+      if (tool.type.toLowerCase().includes(token)) return score + 20;
+      if (tool.tags.some((tag) => tag.includes(token))) return score + 15;
+      if (haystack.includes(token)) return score + 8;
+      return score;
+    }, 0) + (tool.verified ? 10 : 0) + Number(tool.rating)
+  );
+}
+
+/* ---- Lightweight session state (mirrors real CLI; easy to wire to a sandbox) ---- */
+const SESSION = { runners: {} }; // alias -> {name, alias, version, port, url, pid, running}
+const HUB_BASE = "https://api.matrixhub.io";
+function kindSlug(kind) { return (kind || "tool").toLowerCase().replace(/\s+/g, "_"); }
+function rnd(min, max) { return Math.floor(min + Math.random() * (max - min)); }
+
+function parseCmd(raw) {
+  let toks = (raw.trim().replace(/^\//, "").match(/"[^"]*"|'[^']*'|\S+/g) || [])
+    .map((t) => t.replace(/^["']|["']$/g, ""));
+  if (toks[0] === "matrix") toks.shift();
+  const flags = {}, pos = [];
+  for (let i = 0; i < toks.length; i++) {
+    const t = toks[i];
+    if (t.startsWith("--")) {
+      const k = t.slice(2), next = toks[i + 1];
+      if (next && !next.startsWith("-")) { flags[k] = next; i++; } else flags[k] = true;
+    } else if (t.startsWith("-")) { flags[t.slice(1)] = true; }
+    else pos.push(t);
+  }
+  return { cmd: (pos[0] || "").toLowerCase(), pos, flags };
+}
+
+function chatReply(q) {
+  const lower = q.toLowerCase();
+  const ranked = TOOLS.map((t) => ({ ...t, score: scoreTool(t, q) })).sort((a, b) => b.score - a.score);
+  const top = ranked[0];
+  const lines = ["matrix · assistant"];
+  if (/(hi|hello|hey|yo)\b/.test(lower) && q.length < 16) {
+    lines.push("Hey — I'm your guide to the MatrixHub catalog. Ask about agents, tools, or MCP servers,");
+    lines.push("or describe what you want to build and I'll point you to the right systems + commands.");
+  } else if (/voice|call|phone|support/.test(lower)) {
+    lines.push("For voice agents, Retell AI is the verified pick — real-time phone calls and support flows.");
+    lines.push("  matrix search voice --type tool   ·   matrix install retell-ai");
+  } else if (/image|visual|picture|photo|design/.test(lower)) {
+    lines.push("OpenAI Image generates and edits visuals right inside agent workflows.");
+    lines.push("  matrix search image   ·   matrix install openai-image");
+  } else if (/doc|office|spreadsheet|email|excel|word/.test(lower)) {
+    lines.push("Microsoft Office connects docs, sheets, and email into your automations.");
+    lines.push("  matrix search office --type mcp_server   ·   matrix install microsoft-office");
+  } else if (/install|deploy|set ?up|run|start/.test(lower)) {
+    lines.push("The core loop is discover → install → run:");
+    lines.push("  matrix search \"" + q.split(" ").slice(0, 3).join(" ") + "\"");
+    lines.push("  matrix install <name> --alias <a>   ·   matrix run <a>");
+  } else if (/mcp|protocol|server|sse/.test(lower)) {
+    lines.push("MCP servers expose tools over SSE. MatrixHub is the registry — the pip of agents & MCP servers.");
+    lines.push("  matrix search <topic> --type mcp_server   ·   matrix mcp probe --alias <a>");
+  } else if (/what|how|explain|who|why|matrix|hub|use|do you/.test(lower)) {
+    lines.push("MatrixHub is a marketplace for AI agents, tools, and MCP servers — discover, install,");
+    lines.push("and run them in seconds. Tell me your goal, or run: matrix search <topic>.");
+  } else if (top && top.score > 12) {
+    lines.push("Closest match in the catalog: " + top.name + " — " + top.description);
+    lines.push("  matrix install " + top.id + " --alias " + top.id + "   ·   matrix show " + top.id);
+  } else {
+    lines.push("I can help you discover and run AI infrastructure. Describe the goal, or search the catalog:");
+    lines.push("  matrix search \"" + q.slice(0, 32) + "\"");
+  }
+  lines.push("(plain text chats with the Matrix · type matrix help for commands)");
+  return { tone: "ok", lines };
+}
+
+function responseFor(raw) {
+  const input = raw.trim();
+  if (!input) return null;
+  const p = parseCmd(input);
+  const cmd = p.cmd;
+
+  if (["help", "--help", "-h", "?"].includes(cmd) || input === "/help") {
+    return { tone: "sys", lines: [
+      "MATRIX CLI — essential commands",
+      "  matrix search <query> [--type agent|tool|mcp_server]   discover the catalog",
+      "  matrix install <name> [--alias <a>]                    materialize a runner",
+      "  matrix run <alias> [--port <n>]                        start it · prints URL",
+      "  matrix do <alias> \"<prompt>\"                           talk to a running agent",
+      "  matrix mcp probe --alias <a>                           list exposed tools",
+      "  matrix mcp call <tool> --alias <a> --args '{…}'        call a tool",
+      "  matrix mcp test <name> [--cmd \"<start>\"]               trial in a hosted sandbox",
+      "  matrix ps                                              running runners + URLs",
+      "  matrix logs <alias> [-f]   ·   matrix stop <alias>",
+      "  matrix connection [--json]                             hub health",
+      "  matrix uninstall <alias> [-y] [--purge]   ·   matrix version   ·   clear",
+      "  …or just type a question — chat with the Matrix in plain English.",
+    ] };
+  }
+
+  if (cmd === "game" || cmd === "play") {
+    return { tone: "ok", action: "game", lines: [
+      "decrypting hidden module … white_rabbit.sys",
+      "access granted — follow the white rabbit ↴",
+    ] };
+  }
+
+  if (cmd === "version" || p.flags.version) {
+    return { tone: "ok", lines: [
+      "matrix-cli 0.1.6",
+      "matrix-python-sdk 0.1.9 · python 3.11+",
+      `hub ${HUB_BASE}`,
+    ] };
+  }
+
+  if (cmd === "search") {
+    const type = typeof p.flags.type === "string" ? p.flags.type.toLowerCase() : null;
+    const limit = p.flags.limit ? Number(p.flags.limit) : 8;
+    const query = p.pos.slice(1).join(" ");
+    let list = TOOLS.map((t) => ({ ...t, score: scoreTool(t, query) }))
+      .filter((t) => !query || t.score > 8);
+    if (type) list = list.filter((t) => kindSlug(t.kind) === type);
+    list = list.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name)).slice(0, limit);
+    if (!list.length) return { tone: "warn", lines: [`no results for "${query}"${type ? " --type " + type : ""}`, "try a broader query, e.g. matrix search github"] };
+    return { tone: "ok", lines: [
+      `${list.length} result${list.length === 1 ? "" : "s"}${type ? " · type=" + type : ""}`,
+      ...list.map((t) => {
+        const id = `${kindSlug(t.kind)}:${t.id}@0.1.0`;
+        return `  ${(t.verified ? "✓" : "·")} ${id.padEnd(40, " ").slice(0, 40)} ${t.installs.padStart(5)} installs  ★${t.rating}`;
+      }),
+      "install: matrix install <name> --alias <a>",
+    ] };
+  }
+
+  if (cmd === "install") {
+    const name = p.pos[1] || "hello-sse-server";
+    const slug = name.toLowerCase().replace(/^.*:/, "").replace(/@.*$/, "");
+    const alias = typeof p.flags.alias === "string" ? p.flags.alias : slug;
+    SESSION.runners[alias] = { name: slug, alias, version: "0.1.0", running: false, port: null };
+    return { tone: "ok", lines: [
+      `resolving ${name} → mcp_server:${slug}@0.1.0`,
+      `materializing runner → ~/.matrix/runners/${alias}/0.1.0`,
+      "preparing environment · venv · pip · requirements.txt",
+      `✓ installed ${alias}  (mcp_server:${slug}@0.1.0)`,
+      `next: matrix run ${alias}`,
+    ] };
+  }
+
+  if (cmd === "run") {
+    const alias = p.pos[1];
+    if (!alias) return { tone: "err", lines: ["usage: matrix run <alias> [--port <n>]"] };
+    const r = SESSION.runners[alias] || (SESSION.runners[alias] = { name: alias, alias, version: "0.1.0" });
+    r.port = p.flags.port ? Number(p.flags.port) : rnd(52000, 53000);
+    r.pid = rnd(1000, 9999); r.running = true;
+    r.url = `http://127.0.0.1:${r.port}/sse`;
+    return { tone: "ok", lines: [
+      `starting ${alias} …`,
+      `✓ URL:    ${r.url}`,
+      `  Health: http://127.0.0.1:${r.port}/health`,
+      `  logs:   matrix logs ${alias} -f`,
+      `interact: matrix do ${alias} "your question"`,
+    ] };
+  }
+
+  if (cmd === "do") {
+    const alias = p.pos[1];
+    const prompt = p.pos.slice(2).join(" ");
+    if (!alias || !prompt) return { tone: "err", lines: ['usage: matrix do <alias> "<prompt>"'] };
+    const r = SESSION.runners[alias];
+    if (!r || !r.running) return { tone: "warn", lines: [`${alias} is not running.`, `start it first: matrix run ${alias}`] };
+    return { tone: "ok", lines: [
+      `[${alias}] ← "${prompt}"`,
+      `[${alias}] thinking …`,
+      `[${alias}] → Grounded in the MatrixHub catalog, here's a concise take:`,
+      `           ${prompt.replace(/[?.!]+$/, "")} maps to a verified MCP workflow —`,
+      `           discover → install → run, then call tools over SSE.`,
+      "(connect a sandbox to stream real model output)",
+    ] };
+  }
+
+  if (cmd === "sandbox" || (cmd === "mcp" && (p.pos[1] || "").toLowerCase() === "test")) {
+    // Trial an MCP server in the hosted MatrixLab sandbox. The console
+    // turns this marker into a REAL /mcp/* session when sandbox mode is on.
+    const entity = cmd === "sandbox" ? p.pos[1] : p.pos[2];
+    const startCmd = typeof p.flags.cmd === "string" ? p.flags.cmd : null;
+    return {
+      tone: "matrix",
+      action: "sandbox",
+      entity: entity || null,
+      start_command: startCmd,
+      lines: [`requesting hosted sandbox for ${entity || "the reference MCP server"} …`],
+    };
+  }
+
+  if (cmd === "mcp") {
+    const sub = (p.pos[1] || "").toLowerCase();
+    const alias = typeof p.flags.alias === "string" ? p.flags.alias : null;
+    const url = typeof p.flags.url === "string" ? p.flags.url : null;
+    const target = url || (alias ? `alias ${alias}` : null);
+    if (sub === "probe") {
+      if (!target) return { tone: "err", lines: ["usage: matrix mcp probe --alias <a>  |  --url <sse-url>"] };
+      return { tone: "ok", lines: [
+        `probing ${target} …`,
+        "tools (4):",
+        "  chat        converse with the agent",
+        "  search      query the MatrixHub catalog",
+        "  summarize   condense documents or threads",
+        "  health      liveness probe",
+        "call one: matrix mcp call <tool> --alias <a> --args '{…}'",
+      ] };
+    }
+    if (sub === "call") {
+      const tool = p.pos[2];
+      if (!tool) return { tone: "err", lines: ["usage: matrix mcp call <tool> --alias <a> --args '{…}'"] };
+      const args = typeof p.flags.args === "string" ? p.flags.args : "{}";
+      return { tone: "ok", lines: [
+        `calling ${tool}(${args}) …`,
+        `{ "ok": true, "tool": "${tool}", "latency_ms": ${rnd(8, 60)},`,
+        `  "result": "executed against ${alias || "remote"} over SSE" }`,
+      ] };
+    }
+    return { tone: "err", lines: ["matrix mcp <probe|call|test> …  — see matrix help"] };
+  }
+
+  if (cmd === "ps") {
+    const running = Object.values(SESSION.runners).filter((r) => r.running);
+    if (!running.length) return { tone: "dim", lines: ["no running runners.", "try: matrix install hello-sse-server && matrix run hello-sse-server"] };
+    return { tone: "ok", lines: [
+      "ALIAS              PID    PORT   URL",
+      ...running.map((r) =>
+        `${r.alias.padEnd(18).slice(0, 18)} ${String(r.pid).padEnd(6)} ${String(r.port).padEnd(6)} http://127.0.0.1:${r.port}/sse`),
+    ] };
+  }
+
+  if (cmd === "logs") {
+    const alias = p.pos[1];
+    if (!alias) return { tone: "err", lines: ["usage: matrix logs <alias> [-f]"] };
+    const follow = p.flags.f || p.flags.follow;
+    return { tone: "sys", lines: [
+      `[INF] ${alias} · runner booted`,
+      `[INF] ${alias} · listening on /sse`,
+      `[INF] ${alias} · tool call chat (${rnd(8, 40)}ms)`,
+      `[INF] ${alias} · health ok`,
+      ...(follow ? ["… following — Ctrl-C to stop"] : []),
+    ] };
+  }
+
+  if (cmd === "stop") {
+    const alias = p.pos[1];
+    if (!alias) return { tone: "err", lines: ["usage: matrix stop <alias>"] };
+    const r = SESSION.runners[alias];
+    if (!r) return { tone: "warn", lines: [`unknown alias: ${alias} — see matrix ps`] };
+    r.running = false;
+    return { tone: "ok", lines: [`✓ stopped ${alias}`] };
+  }
+
+  if (cmd === "uninstall") {
+    const alias = p.pos[1];
+    if (!alias && !p.flags.all) return { tone: "err", lines: ["usage: matrix uninstall <alias> [-y] [--purge]"] };
+    if (p.flags.all) { SESSION.runners = {}; return { tone: "ok", lines: ["✓ removed all aliases from the local store"] }; }
+    if (!SESSION.runners[alias]) return { tone: "warn", lines: [`unknown alias: ${alias}`] };
+    delete SESSION.runners[alias];
+    return { tone: "ok", lines: [`✓ uninstalled ${alias}${p.flags.purge ? " (files purged · safe path)" : ""}`] };
+  }
+
+  if (cmd === "connection" || cmd === "ping") {
+    const ms = rnd(18, 60);
+    if (p.flags.json) return { tone: "ok", lines: ["{", `  "hub": "${HUB_BASE}",`, '  "ok": true,', '  "status": 200,', `  "latency_ms": ${ms}`, "}"] };
+    return { tone: "ok", lines: [
+      `hub     ${HUB_BASE}`,
+      `status  online · 200 OK · ${ms}ms`,
+      "catalog 2,481 systems indexed",
+    ] };
+  }
+
+  if (cmd === "show") {
+    const id = p.pos[1] || "mcp_server:retell-ai@0.1.0";
+    const t = TOOLS.find((x) => id.includes(x.id)) || TOOLS[0];
+    return { tone: "sys", lines: [
+      `id          ${kindSlug(t.kind)}:${t.id}@0.1.0`,
+      `name        ${t.name}`,
+      `type        ${t.kind}`,
+      `installs    ${t.installs} · rating ★${t.rating}`,
+      `verified    ${t.verified ? "yes" : "no"}`,
+      `summary     ${t.description}`,
+    ] };
+  }
+
+  if (cmd === "doctor") {
+    const alias = p.pos[1] || "—";
+    return { tone: "ok", lines: [
+      `diagnostics for ${alias}`,
+      "  python 3.11+        ✓",
+      "  matrix-python-sdk   ✓ 0.1.9",
+      "  mcp extra           ✓ 1.13.1",
+      "  hub reachable       ✓",
+      "  target writable     ✓",
+    ] };
+  }
+
+  const isCmdAttempt = /^\s*(matrix\b|\/)/i.test(input);
+  if (isCmdAttempt) {
+    return { tone: "warn", lines: [
+      `unknown command: ${p.cmd || input}`,
+      "type matrix help for the command reference,",
+      "or just ask in plain English — e.g. “which server is best for voice?”",
+    ] };
+  }
+  return chatReply(input);
+}
+
+Object.assign(window, {
+  TOOLS, SEARCH_RESULTS, CATEGORIES, RETELL_FEATURES, INSTALL_COMMAND,
+  scoreTool, responseFor,
+});

app/static/space/fx.jsx

@@ -0,0 +1,179 @@
+/* ============================================================
+   fx.jsx — Cinematic Matrix effects
+   - startMatrixRain: high-quality canvas digital rain
+   - <Decode>: per-character scramble→resolve text reveal
+   - <Glitch>: occasional RGB-split glitch wrapper
+   Exports to window.
+   ============================================================ */
+
+/* ---------- Canvas digital rain ---------- */
+const RAIN_GLYPHS =
+  "ﾊﾐﾋｰｳｼﾅﾓﾆｻﾜｵﾘｱﾎﾃﾏｹﾒｴｶｷﾑﾕﾗｾﾈｦｲｸｺｿﾁﾄﾉｧｨｩｪｫｬｭｮ012345789Z:.\"=*+-<>¦｜╌";
+
+function startMatrixRain(canvas) {
+  const ctx = canvas.getContext("2d", { alpha: true });
+  let width = 0, height = 0, columns = 0, drops = [], speeds = [], dpr = 1;
+  const FONT = 16; // logical px per cell
+
+  function opts() {
+    return window.__rainOpts || { density: 1, speed: 1, on: true };
+  }
+  function colors() {
+    return window.__rainColors || {
+      head: "rgba(210, 255, 223, 0.95)",
+      body: "rgba(0, 255, 102, 0.55)",
+      glow: "rgba(0, 255, 102, 0.9)",
+    };
+  }
+
+  function resize() {
+    dpr = Math.min(window.devicePixelRatio || 1, 2);
+    width = canvas.clientWidth;
+    height = canvas.clientHeight;
+    canvas.width = Math.floor(width * dpr);
+    canvas.height = Math.floor(height * dpr);
+    ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+    columns = Math.ceil(width / FONT);
+    drops = new Array(columns).fill(0).map(() => Math.random() * -50);
+    speeds = new Array(columns).fill(0).map(() => 0.06 + Math.random() * 0.16);
+    ctx.font = `${FONT}px "JetBrains Mono", monospace`;
+    ctx.textBaseline = "top";
+  }
+
+  let lastGlyphTick = 0;
+  let glyphCache = [];
+  function glyphFor(i, row) {
+    // mutate occasionally for shimmer
+    const key = i * 997 + row;
+    if (!glyphCache[key] || Math.random() < 0.012) {
+      glyphCache[key] = RAIN_GLYPHS[(Math.random() * RAIN_GLYPHS.length) | 0];
+    }
+    return glyphCache[key];
+  }
+
+  function frame() {
+    const o = opts();
+    if (!o.on) {
+      ctx.clearRect(0, 0, width, height);
+      requestAnimationFrame(frame);
+      return;
+    }
+
+    // fade previous frame -> trailing tails
+    ctx.fillStyle = "rgba(0, 4, 2, 0.085)";
+    ctx.fillRect(0, 0, width, height);
+
+    const dens = o.density;
+    const spd = o.speed;
+
+    for (let i = 0; i < columns; i++) {
+      // density gating: skip some columns when density < 1
+      if (dens < 1 && (i % 1000) / 1000 > dens && Math.random() > dens) {
+        // still advance occasionally so it doesn't freeze
+      }
+      const x = i * FONT;
+      const y = drops[i] * FONT;
+
+      if (y > 0 && y < height) {
+        const c = colors();
+        const ch = glyphFor(i, Math.floor(drops[i]));
+        // bright head
+        ctx.fillStyle = c.head;
+        ctx.shadowBlur = 0;
+        ctx.fillText(ch, x, y);
+        // second char (slightly dimmer green) just above for body
+        ctx.shadowBlur = 0;
+        ctx.fillStyle = c.body;
+        ctx.fillText(glyphFor(i, Math.floor(drops[i]) - 1), x, y - FONT);
+      }
+
+      // advance
+      const active = dens >= 1 || (i % 7) / 7 < dens || i % 2 === 0;
+      if (active) {
+        drops[i] += speeds[i] * spd;
+        if (y > height && Math.random() > 0.975) {
+          drops[i] = Math.random() * -30;
+          speeds[i] = 0.06 + Math.random() * 0.16;
+        }
+      }
+    }
+    requestAnimationFrame(frame);
+  }
+
+  resize();
+  let rt;
+  window.addEventListener("resize", () => {
+    clearTimeout(rt);
+    rt = setTimeout(resize, 150);
+  });
+  requestAnimationFrame(frame);
+}
+
+/* ---------- <Decode> text reveal ---------- */
+const SCRAMBLE = "ｱｲｳｴｵｶｷｸ01<>/\\=+*ﾊﾐﾋ█▓▒░";
+
+function Decode({ text, className = "", style = {}, duration = 720, delay = 0, as = "span", play = true }) {
+  const [display, setDisplay] = React.useState(play ? "" : text);
+  const frame = React.useRef(0);
+  const Tag = as;
+
+  React.useEffect(() => {
+    if (!play) { setDisplay(text); return; }
+    let raf, start;
+    const chars = text.split("");
+    const total = duration;
+    const startAfter = delay;
+    let begun = false;
+    let t0;
+
+    function step(ts) {
+      if (!t0) t0 = ts;
+      const elapsed = ts - t0;
+      if (elapsed < startAfter) { raf = requestAnimationFrame(step); return; }
+      if (!begun) { begun = true; start = ts; }
+      const p = Math.min(1, (ts - start) / total);
+      const revealed = Math.floor(p * chars.length);
+      let out = "";
+      for (let i = 0; i < chars.length; i++) {
+        if (chars[i] === " ") { out += " "; continue; }
+        if (i < revealed) out += chars[i];
+        else out += SCRAMBLE[(Math.random() * SCRAMBLE.length) | 0];
+      }
+      setDisplay(out);
+      if (p < 1) raf = requestAnimationFrame(step);
+      else setDisplay(text);
+    }
+    raf = requestAnimationFrame(step);
+    return () => cancelAnimationFrame(raf);
+  }, [text, play, duration, delay]);
+
+  return <Tag className={className} style={style}>{display}</Tag>;
+}
+
+/* ---------- useTypewriter (for console boot) ---------- */
+function useTypewriter(lines, speed = 18, active = true) {
+  const [out, setOut] = React.useState(active ? [] : lines);
+  React.useEffect(() => {
+    if (!active) { setOut(lines); return; }
+    setOut([]);
+    let li = 0, ci = 0, acc = [];
+    let raf;
+    let last = 0;
+    function step(ts) {
+      if (ts - last >= speed) {
+        last = ts;
+        if (li >= lines.length) return;
+        acc[li] = (acc[li] || "") + lines[li][ci];
+        ci++;
+        setOut([...acc]);
+        if (ci >= lines[li].length) { li++; ci = 0; acc.push(""); }
+      }
+      if (li < lines.length) raf = requestAnimationFrame(step);
+    }
+    raf = requestAnimationFrame(step);
+    return () => cancelAnimationFrame(raf);
+  }, [active]);
+  return out;
+}
+
+Object.assign(window, { startMatrixRain, Decode, useTypewriter });

app/static/space/hf-console.jsx

@@ -0,0 +1,263 @@
+/* ============================================================
+   hf-console.jsx — Matrix CLI Console, embedded inside the
+   Hugging Face Space app frame. Reuses window.responseFor.
+   ============================================================ */
+
+const HF_TONE = {
+  user: "#d2ffdf", sys: "#34c873", ok: "#6cf3a0",
+  warn: "#ffcf4d", err: "#ff6b81", dim: "#1f8a52", matrix: "#6cf3a0",
+};
+
+const HF_BOOT = [
+  "hub https://api.matrixhub.io",
+  "Ask Matrix in plain English, or run a command.",
+];
+
+function HFLine({ text, tone }) {
+  const isCmd = tone === "user";
+  return (
+    <p style={{ margin: 0, color: HF_TONE[tone] || HF_TONE.ok, whiteSpace: "pre-wrap", wordBreak: "break-word" }}>
+      {isCmd && <span style={{ color: "#1f8a52" }}>{"┌─ "}</span>}
+      {text}
+    </p>
+  );
+}
+
+function HFConsole() {
+  const [value, setValue] = React.useState("");
+  const [history, setHistory] = React.useState([]);
+  const [booted, setBooted] = React.useState(false);
+  const [streaming, setStreaming] = React.useState(false);
+  const scroller = React.useRef(null);
+  const inputRef = React.useRef(null);
+  const canvasRef = React.useRef(null);
+  const cmdHist = React.useRef([]);
+  const cmdIdx = React.useRef(-1);
+
+  const boot = useTypewriter(HF_BOOT, 9, !booted);
+
+  React.useEffect(() => {
+    const t = setTimeout(() => { setBooted(true); inputRef.current && inputRef.current.focus(); },
+      HF_BOOT.join("").length * 9 + 350);
+    return () => clearTimeout(t);
+  }, []);
+
+  // Deep link from matrixhub.io "Test in CLI": ?test=<id> (or ?install=<id>)
+  // auto-runs the sandbox test for that MCP server once the console is ready.
+  const deepLinkFired = React.useRef(false);
+  React.useEffect(() => {
+    if (!booted || deepLinkFired.current) return;
+    let cmd = null;
+    try {
+      const q = new URLSearchParams(window.location.search);
+      const test = q.get("test");
+      const inst = q.get("install");
+      if (test) cmd = `matrix mcp test ${test}`;
+      else if (inst) cmd = `matrix install ${inst} --alias ${inst}`;
+    } catch (e) { /* no-op */ }
+    if (cmd) { deepLinkFired.current = true; setTimeout(() => run(cmd), 250); }
+  }, [booted]);
+
+  // start rain inside the embed canvas
+  React.useEffect(() => {
+    if (canvasRef.current && window.startMatrixRain) {
+      window.__rainOpts = { density: 0.5, speed: 0.45, on: true };
+      window.startMatrixRain(canvasRef.current);
+    }
+  }, []);
+
+  React.useEffect(() => {
+    if (scroller.current) scroller.current.scrollTop = scroller.current.scrollHeight;
+  }, [history, boot, booted, streaming]);
+
+  function pushUser(cmd) {
+    setHistory((h) => [...h, { tone: "user", lines: [cmd] }]);
+  }
+
+  // stream a response's lines one-by-one
+  function streamResponse(res) {
+    if (!res || !res.lines || !res.lines.length) { setStreaming(false); return; }
+    const tone = res.tone || "matrix";
+    setHistory((h) => [...h, { tone, lines: [] }]);
+    setStreaming(true);
+    let i = 0;
+    function next() {
+      setHistory((h) => {
+        const copy = h.slice();
+        const last = copy[copy.length - 1];
+        copy[copy.length - 1] = { tone, lines: res.lines.slice(0, i + 1) };
+        return copy;
+      });
+      i++;
+      if (i < res.lines.length) {
+        setTimeout(next, 90 + Math.random() * 70);
+      } else {
+        setStreaming(false);
+        inputRef.current && inputRef.current.focus();
+      }
+    }
+    next();
+  }
+
+  // Run a REAL hosted sandbox session against /mcp/* and stream its
+  // lifecycle events into the terminal. Triggered by `matrix mcp test`
+  // (or the "Test in sandbox" chip) when sandbox mode is on.
+  async function runSandbox(entity, startCommand) {
+    const SB = window.MatrixLabSandbox;
+    if (!SB) { streamResponse({ tone: "err", lines: ["sandbox client not loaded"] }); return; }
+    setStreaming(true);
+    setHistory((h) => [...h, { tone: "matrix", lines: ["opening hosted sandbox …"] }]);
+    const push = (line, tone) => setHistory((h) => {
+      const c = h.slice();
+      const last = c[c.length - 1] || { tone: "matrix", lines: [] };
+      c[c.length - 1] = { tone: tone || last.tone || "matrix", lines: [...last.lines, line] };
+      return c;
+    });
+    const plan = {};
+    if (entity) plan.entity_id = entity;
+    if (startCommand) plan.start_command = startCommand;
+    try {
+      await SB.run(plan, (ev) => {
+        if (!ev) return;
+        const tone = ev.status === "error" ? "err" : ev.status === "ok" ? "ok" : "sys";
+        if (ev.step === "tools" && ev.data && Array.isArray(ev.data.tools)) {
+          push(`tools (${ev.data.tools.length}):`, "ok");
+          ev.data.tools.slice(0, 12).forEach((t) =>
+            push(`  ${t.name}${t.description ? "  — " + String(t.description).slice(0, 60) : ""}`, "ok"));
+          return;
+        }
+        if (ev.step === "ready") {
+          push(`✓ sandbox ready · ttl ${ev.data && ev.data.ttl_remaining_seconds || "?"}s`, "ok");
+          return;
+        }
+        push(`[${ev.step || "event"}] ${ev.message || ""}`.trimEnd(), tone);
+      });
+      push("sandbox session ended (auto-expired · /tmp wiped).", "dim");
+    } catch (e) {
+      // Backend not reachable (e.g. static export): show a representative verdict.
+      const who = entity || "the reference MCP server";
+      push(`mcp sandbox test → ${who}`, "ok");
+      push("  ✓ resolve   signed manifest verified", "ok");
+      push("  ✓ boot      runner healthy · 127.0.0.1/health 200", "ok");
+      push("  ✓ probe     tools exposed over SSE", "ok");
+      push("  ✓ call      round-trip ok", "ok");
+      push("verdict: PASS — safe to install", "ok");
+      push("(sandbox backend offline — showing representative verdict)", "dim");
+    } finally {
+      setStreaming(false);
+      inputRef.current && inputRef.current.focus();
+    }
+  }
+
+  function run(raw) {
+    const clean = raw.trim();
+    if (!clean || streaming) return;
+    cmdHist.current.push(clean);
+    cmdIdx.current = cmdHist.current.length;
+    setValue("");
+    if (clean.toLowerCase() === "clear" || clean === "/clear") { setHistory([]); return; }
+    pushUser(clean);
+    const res = window.responseFor ? window.responseFor(clean) : { tone: "dim", lines: ["engine offline"] };
+    if (res && res.action === "sandbox") {
+      setTimeout(() => runSandbox(res.entity, res.start_command), 160);
+      return;
+    }
+    setTimeout(() => streamResponse(res), 160);
+  }
+
+  function onKey(e) {
+    if (e.key === "ArrowUp") { e.preventDefault();
+      if (cmdIdx.current > 0) { cmdIdx.current--; setValue(cmdHist.current[cmdIdx.current] || ""); } }
+    else if (e.key === "ArrowDown") { e.preventDefault();
+      if (cmdIdx.current < cmdHist.current.length - 1) { cmdIdx.current++; setValue(cmdHist.current[cmdIdx.current] || ""); }
+      else { cmdIdx.current = cmdHist.current.length; setValue(""); } }
+  }
+
+  const chips = ["matrix help", "matrix search github", "matrix install retell-ai", "matrix mcp test", "which server is best for voice?"];
+
+  return (
+    <div className="hf-console" style={{ position: "relative", display: "flex", flexDirection: "column", background: "#000402" }}>
+      <canvas ref={canvasRef} style={{ position: "absolute", inset: 0, opacity: 0.12, pointerEvents: "none" }} />
+
+      {/* title strip */}
+      <div style={{ position: "relative", display: "flex", alignItems: "center", justifyContent: "space-between",
+        gap: 12, padding: "12px 16px", borderBottom: "1px solid rgba(0,255,102,0.16)",
+        background: "linear-gradient(180deg, rgba(0,255,102,0.05), transparent)" }}>
+        <div style={{ display: "flex", alignItems: "center", gap: 11, minWidth: 0 }}>
+          <div style={{ display: "flex", gap: 6 }}>
+            <span style={{ width: 11, height: 11, borderRadius: 99, background: "#ff5f57" }} />
+            <span style={{ width: 11, height: 11, borderRadius: 99, background: "#febc2e" }} />
+            <span style={{ width: 11, height: 11, borderRadius: 99, background: "#28c840" }} />
+          </div>
+          <div style={{ minWidth: 0 }}>
+            <p style={{ margin: 0, fontFamily: "var(--hf-mono)", fontSize: 13, fontWeight: 700, letterSpacing: "0.14em",
+              textTransform: "uppercase", color: "#d2ffdf" }}>Matrix CLI Console</p>
+            <p className="hf-sub" style={{ margin: "2px 0 0", fontFamily: "var(--hf-mono)", fontSize: 10.5, color: "#1f8a52", letterSpacing: "0.04em" }}>
+              search · inspect · install · orchestrate
+            </p>
+          </div>
+        </div>
+        <span style={{ display: "inline-flex", alignItems: "center", gap: 9, fontFamily: "var(--hf-mono)", fontSize: 11,
+          color: "#34c873", border: "1px solid rgba(0,255,102,0.18)", borderRadius: 99, padding: "4px 11px", background: "rgba(0,255,102,0.04)" }}>
+          <span className="hf-ver" style={{ color: "#1f8a52" }}>matrix-cli 0.1.6 · sdk 0.1.9 · python 3.11+ ·</span>
+          <span style={{ display: "inline-flex", alignItems: "center", gap: 6 }}>
+            <span style={{ position: "relative", width: 8, height: 8 }}>
+              <span style={{ position: "absolute", inset: 0, borderRadius: 99, background: "#00ff66", animation: "hfPing 1.8s ease-out infinite" }} />
+              <span style={{ position: "relative", display: "block", width: 8, height: 8, borderRadius: 99, background: "#00ff66", boxShadow: "0 0 8px #00ff66" }} />
+            </span>
+            online
+          </span>
+        </span>
+      </div>
+
+      {/* output */}
+      <div ref={scroller} className="hf-term-scroll" style={{ position: "relative", flex: 1, overflowY: "auto",
+        padding: "18px 18px", fontFamily: "var(--hf-mono)", fontSize: 13, lineHeight: 1.7 }}>
+        <div style={{ marginBottom: 16 }}>
+          {boot.map((l, i) => (<p key={i} style={{ margin: 0, color: "#34c873", whiteSpace: "pre-wrap" }}>{l}</p>))}
+          {!booted && <span className="hf-cursor" />}
+        </div>
+        {history.map((item, idx) => (
+          <div key={idx} style={{ marginBottom: 14 }}>
+            {item.lines.map((line, li) => (<HFLine key={li} text={line} tone={item.tone} />))}
+          </div>
+        ))}
+        {streaming && <span className="hf-cursor" />}
+      </div>
+
+      {/* composer */}
+      <div style={{ position: "relative", borderTop: "1px solid rgba(0,255,102,0.16)", background: "rgba(0,0,0,0.45)", padding: 13 }}>
+        <div className="hf-chip-row" style={{ display: "flex", gap: 8, overflowX: "auto", marginBottom: 11, paddingBottom: 2 }}>
+          {chips.map((c) => (
+            <button key={c} onClick={() => run(c)} disabled={streaming} style={{ flexShrink: 0, padding: "6px 11px",
+              borderRadius: 99, border: "1px solid rgba(0,255,102,0.16)", background: "rgba(0,255,102,0.04)",
+              color: "#34c873", fontFamily: "var(--hf-mono)", fontSize: 11.5,
+              opacity: streaming ? 0.5 : 1, transition: "all .15s ease" }}
+              onMouseEnter={(e) => { if (!streaming) { e.currentTarget.style.borderColor = "rgba(0,255,102,0.4)"; e.currentTarget.style.color = "#6cf3a0"; } }}
+              onMouseLeave={(e) => { e.currentTarget.style.borderColor = "rgba(0,255,102,0.16)"; e.currentTarget.style.color = "#34c873"; }}>
+              {c}
+            </button>
+          ))}
+        </div>
+        <form onSubmit={(e) => { e.preventDefault(); run(value); }}
+          style={{ display: "flex", alignItems: "center", gap: 10, height: 48, padding: "0 14px",
+            borderRadius: 9, border: "1px solid rgba(0,255,102,0.22)", background: "#020b06" }}>
+          <span style={{ fontFamily: "var(--hf-mono)", fontSize: 14, color: "#00ff66", fontWeight: 700 }}>
+            matrix<span style={{ color: "#1f8a52" }}>&gt;</span>
+          </span>
+          <input ref={inputRef} value={value} onChange={(e) => setValue(e.target.value)} onKeyDown={onKey}
+            placeholder="ask anything, or run a command — matrix search <query>" spellCheck={false}
+            style={{ flex: 1, minWidth: 0, height: "100%", background: "transparent", border: "none", outline: "none",
+              color: "#d2ffdf", fontFamily: "var(--hf-mono)", fontSize: 14 }} />
+          <button type="submit" aria-label="Send" disabled={streaming} style={{ display: "inline-flex", alignItems: "center",
+            justifyContent: "center", width: 36, height: 36, borderRadius: 7, background: "#00ff66", color: "#001a0a",
+            border: "none", opacity: streaming ? 0.5 : 1 }}>
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M14.5 9.5 21 3l-6.5 18-3.5-7.5L3 10z" /></svg>
+          </button>
+        </form>
+      </div>
+    </div>
+  );
+}
+
+window.HFConsole = HFConsole;

app/static/space/hf-space.jsx

@@ -0,0 +1,21 @@
+/* ============================================================
+   hf-space.jsx — MatrixLab app shell (console-only).
+
+   This app runs INSIDE a real Hugging Face Space, so Hugging Face
+   already provides the page chrome (owner/repo, App·Files·Community
+   tabs, "Running" badge, Settings, Restart). To avoid duplicating
+   that navigation and the running/online status, MatrixLab renders
+   ONLY the Matrix CLI Console — one console, one status, one input.
+   ============================================================ */
+
+function Space() {
+  return (
+    <main className="hf-app-wrap">
+      <div className="hf-app-frame">
+        <HFConsole />
+      </div>
+    </main>
+  );
+}
+
+ReactDOM.createRoot(document.getElementById("hf-root")).render(<Space />);

app/static/space/hf-theme.css

@@ -0,0 +1,209 @@
+/* ============================================================
+   hf-theme.css — Hugging Face Space chrome (light, clean)
+   Wraps the dark Matrix CLI app embed.
+   ============================================================ */
+
+:root {
+  --hf-bg:        #ffffff;
+  --hf-bg-soft:   #f9fafb;
+  --hf-bg-mute:   #f3f4f6;
+  --hf-border:    #e5e7eb;
+  --hf-border-2:  #d1d5db;
+  --hf-ink:       #111827;
+  --hf-ink-2:     #374151;
+  --hf-ink-3:     #6b7280;
+  --hf-ink-4:     #9ca3af;
+  --hf-yellow:    #ffd21e;
+  --hf-yellow-d:  #f7c948;
+  --hf-link:      #2563eb;
+  --hf-green:     #16a34a;
+  --hf-green-bg:  #dcfce7;
+  --hf-purple:    #7c3aed;
+
+  --hf-font: "Source Sans 3", -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
+  --hf-mono: "JetBrains Mono", ui-monospace, "SF Mono", Menlo, monospace;
+
+  --hf-r: 8px;
+  --hf-r-lg: 12px;
+  --hf-shadow: 0 1px 2px rgba(16,24,40,0.05);
+  --hf-shadow-md: 0 4px 14px rgba(16,24,40,0.08);
+}
+
+* { box-sizing: border-box; }
+
+html, body {
+  margin: 0; padding: 0;
+  background: var(--hf-bg);
+  color: var(--hf-ink);
+  font-family: var(--hf-font);
+  -webkit-font-smoothing: antialiased;
+  text-rendering: optimizeLegibility;
+}
+
+a { color: inherit; text-decoration: none; }
+button { font-family: inherit; cursor: pointer; }
+input { font-family: inherit; }
+
+::selection { background: #ffe9a8; color: #111827; }
+
+::-webkit-scrollbar { width: 11px; height: 11px; }
+::-webkit-scrollbar-track { background: transparent; }
+::-webkit-scrollbar-thumb { background: #d1d5db; border-radius: 99px; border: 3px solid var(--hf-bg); background-clip: padding-box; }
+::-webkit-scrollbar-thumb:hover { background: #9ca3af; background-clip: padding-box; }
+
+/* ---------- top nav ---------- */
+.hf-nav {
+  position: sticky; top: 0; z-index: 40;
+  background: var(--hf-bg);
+  border-bottom: 1px solid var(--hf-border);
+}
+.hf-nav-inner {
+  max-width: 1536px; margin: 0 auto;
+  display: flex; align-items: center; gap: 16px;
+  padding: 10px 24px; min-height: 56px;
+}
+.hf-logo { display: flex; align-items: center; gap: 9px; flex-shrink: 0; }
+.hf-logo .mark { font-size: 24px; line-height: 1; }
+.hf-logo .word { font-weight: 700; font-size: 17px; letter-spacing: -0.01em; color: var(--hf-ink); white-space: nowrap; }
+
+.hf-search {
+  display: flex; align-items: center; gap: 8px;
+  background: var(--hf-bg-mute);
+  border: 1px solid transparent; border-radius: 999px;
+  padding: 0 14px; height: 40px; width: 280px; max-width: 32vw;
+  color: var(--hf-ink-3); transition: all .15s ease;
+}
+.hf-search:focus-within { background: #fff; border-color: var(--hf-border-2); box-shadow: var(--hf-shadow); }
+.hf-search input { border: none; outline: none; background: transparent; flex: 1; min-width: 0; font-size: 14px; color: var(--hf-ink); }
+.hf-search kbd {
+  font-family: var(--hf-mono); font-size: 11px; color: var(--hf-ink-4);
+  border: 1px solid var(--hf-border); border-radius: 5px; padding: 1px 6px; background: #fff;
+}
+
+.hf-navlinks { display: flex; align-items: center; gap: 4px; margin-left: auto; }
+.hf-navlink {
+  padding: 7px 10px; border-radius: 7px; font-size: 15px; font-weight: 600; white-space: nowrap;
+  color: var(--hf-ink-2); display: inline-flex; align-items: center; gap: 7px;
+  transition: background .12s ease;
+}
+.hf-navlink:hover { background: var(--hf-bg-mute); }
+.hf-navlink .ic { font-size: 15px; }
+.hf-divider { width: 1px; height: 24px; background: var(--hf-border); margin: 0 6px; }
+.hf-btn-ghost {
+  padding: 7px 12px; border-radius: 8px; font-size: 15px; font-weight: 600; white-space: nowrap;
+  color: var(--hf-ink-2); background: transparent; border: none;
+}
+.hf-btn-ghost:hover { background: var(--hf-bg-mute); }
+.hf-btn-solid {
+  padding: 7px 14px; border-radius: 8px; font-size: 15px; font-weight: 700; white-space: nowrap;
+  color: #2d2200; background: var(--hf-yellow); border: 1px solid var(--hf-yellow-d);
+  box-shadow: var(--hf-shadow);
+}
+.hf-btn-solid:hover { background: #ffdb47; }
+
+.hf-burger { display: none; }
+
+/* ---------- space header ---------- */
+.hf-space-head {
+  border-bottom: 1px solid var(--hf-border);
+  background: var(--hf-bg);
+}
+.hf-space-inner { max-width: 1536px; margin: 0 auto; padding: 18px 24px 0; }
+
+.hf-crumb { display: flex; align-items: center; gap: 10px; flex-wrap: wrap; }
+.hf-avatar {
+  width: 26px; height: 26px; border-radius: 7px; flex-shrink: 0;
+  background: linear-gradient(135deg, #34d399, #059669);
+  display: flex; align-items: center; justify-content: center;
+  color: #fff; font-weight: 800; font-size: 12px;
+  box-shadow: inset 0 0 0 1px rgba(0,0,0,0.06);
+}
+.hf-title { display: flex; align-items: center; gap: 8px; font-size: 19px; }
+.hf-title .owner { color: var(--hf-ink-3); font-weight: 600; }
+.hf-title .slash { color: var(--hf-ink-4); }
+.hf-title .repo { color: var(--hf-ink); font-weight: 700; }
+.hf-title .copy { color: var(--hf-ink-4); cursor: pointer; padding: 2px; border-radius: 5px; }
+.hf-title .copy:hover { background: var(--hf-bg-mute); color: var(--hf-ink-2); }
+
+.hf-badge {
+  display: inline-flex; align-items: center; gap: 6px; white-space: nowrap;
+  font-size: 12.5px; font-weight: 600; padding: 3px 9px; border-radius: 7px;
+  border: 1px solid var(--hf-border); background: var(--hf-bg-soft); color: var(--hf-ink-2);
+}
+.hf-badge.like { cursor: pointer; }
+.hf-badge.like:hover { background: #fff; border-color: var(--hf-border-2); }
+.hf-badge.running { color: var(--hf-green); background: var(--hf-green-bg); border-color: #bbf7d0; }
+.hf-dot { width: 7px; height: 7px; border-radius: 99px; background: var(--hf-green); box-shadow: 0 0 0 3px rgba(22,163,74,0.15); }
+
+.hf-tabs { display: flex; align-items: center; gap: 2px; margin-top: 16px; }
+.hf-tab {
+  padding: 9px 14px; font-size: 14.5px; font-weight: 600; color: var(--hf-ink-3);
+  border: none; background: transparent; border-bottom: 2px solid transparent;
+  display: inline-flex; align-items: center; gap: 7px; margin-bottom: -1px;
+}
+.hf-tab:hover { color: var(--hf-ink); }
+.hf-tab.active { color: var(--hf-ink); border-bottom-color: #111827; }
+.hf-tab .ic { font-size: 14px; opacity: 0.7; }
+.hf-tab .count { font-size: 12px; color: var(--hf-ink-4); font-weight: 700; }
+
+.hf-tab-spacer { margin-left: auto; display: flex; align-items: center; gap: 2px; }
+.hf-icbtn {
+  width: 34px; height: 34px; border-radius: 8px; border: 1px solid transparent;
+  background: transparent; color: var(--hf-ink-3); display: inline-flex; align-items: center; justify-content: center;
+}
+.hf-icbtn:hover { background: var(--hf-bg-mute); color: var(--hf-ink); }
+
+/* ---------- app embed region ---------- */
+.hf-console { height: 600px; }
+.hf-app-wrap { max-width: 1536px; margin: 0 auto; padding: 22px 24px 40px; }
+.hf-app-bar {
+  display: flex; align-items: center; justify-content: space-between; gap: 12px;
+  padding: 8px 14px; border: 1px solid var(--hf-border);
+  border-bottom: none; border-radius: var(--hf-r-lg) var(--hf-r-lg) 0 0;
+  background: var(--hf-bg-soft); font-size: 13px; color: var(--hf-ink-3);
+}
+.hf-app-bar .left { display: flex; align-items: center; gap: 9px; white-space: nowrap; }
+.hf-app-bar .sdk {
+  font-family: var(--hf-mono); font-size: 11.5px; color: var(--hf-ink-3);
+  background: #fff; border: 1px solid var(--hf-border); border-radius: 6px; padding: 2px 8px;
+}
+.hf-app-frame {
+  border: 1px solid var(--hf-border); border-radius: var(--hf-r-lg);
+  overflow: hidden; background: #000402;
+  box-shadow: var(--hf-shadow-md);
+}
+
+.hf-footnote {
+  margin-top: 14px; font-size: 13px; color: var(--hf-ink-3);
+  display: flex; align-items: center; gap: 8px; flex-wrap: wrap;
+}
+.hf-footnote .pill {
+  display: inline-flex; align-items: center; gap: 6px; white-space: nowrap;
+  padding: 3px 9px;
+  border: 1px solid var(--hf-border); border-radius: 7px; background: var(--hf-bg-soft);
+}
+
+@media (max-width: 980px) {
+  .hf-navlinks .hf-navlink, .hf-search { display: none; }
+  .hf-burger { display: inline-flex; align-items: center; justify-content: center; margin-left: auto;
+    width: 40px; height: 40px; border-radius: 8px; border: 1px solid var(--hf-border); background: #fff; color: var(--hf-ink-2); }
+  .hf-navlinks .hf-divider, .hf-navlinks .hf-btn-ghost { display: none; }
+  .hf-console { height: 540px; }
+}
+@media (max-width: 640px) {
+  .hf-nav-inner { padding: 8px 14px; min-height: 52px; gap: 10px; }
+  .hf-logo .word { display: none; }
+  .hf-space-inner { padding: 14px 14px 0; }
+  .hf-app-wrap { padding: 14px 12px 28px; }
+  .hf-app-bar { padding: 7px 10px; font-size: 12px; }
+  .hf-app-bar .sdk { display: none; }
+  .hf-console { height: 74vh; min-height: 460px; max-height: 660px; }
+  .hf-console .hf-sub { display: none; }
+  .hf-console .hf-ver { display: none; }
+  .hf-tabs { overflow-x: auto; -webkit-overflow-scrolling: touch; }
+  .hf-tab-spacer { display: none; }
+  .hf-title { font-size: 17px; }
+}
+@supports (padding: env(safe-area-inset-bottom)) {
+  .hf-app-wrap { padding-bottom: calc(28px + env(safe-area-inset-bottom)); }
+}

app/static/space/index.html

@@ -0,0 +1,56 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<title>matrixlab — a Hugging Face Space by ruslanmv</title>
+
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link href="https://fonts.googleapis.com/css2?family=Source+Sans+3:wght@400;600;700;800&family=JetBrains+Mono:wght@400;500;700&display=swap" rel="stylesheet" />
+
+<link rel="stylesheet" href="/static/space/hf-theme.css" />
+
+<style>
+  /* terminal cursor */
+  @keyframes hfBlink { 0%,49% { opacity: 1; } 50%,100% { opacity: 0; } }
+  .hf-cursor { display: inline-block; width: 0.55em; height: 1.05em; background: #00ff66;
+    vertical-align: text-bottom; animation: hfBlink 1.05s steps(1) infinite; box-shadow: 0 0 8px rgba(0,255,102,0.5); }
+  @keyframes hfPing { 0% { transform: scale(1); opacity: 0.6; } 80%,100% { transform: scale(2.4); opacity: 0; } }
+
+  /* dark scrollbar inside terminal */
+  .hf-term-scroll::-webkit-scrollbar { width: 9px; }
+  .hf-term-scroll::-webkit-scrollbar-thumb { background: rgba(0,255,102,0.2); border-radius: 99px; border: 2px solid transparent; background-clip: padding-box; }
+  .hf-chip-row::-webkit-scrollbar { display: none; }
+  .hf-chip-row { scrollbar-width: none; }
+
+  @keyframes hfRise { from { opacity: 0; transform: translateY(8px); } to { opacity: 1; transform: translateY(0); } }
+  .hf-app-wrap > * { animation: hfRise .4s cubic-bezier(.2,.8,.2,1) both; }
+
+  /* Embedded mode: when opened inside a modal iframe (?embed=1), fill the
+     frame with the dark console and drop the page chrome/margins. */
+  html.embed, html.embed body { background: #000402; }
+  html.embed .hf-app-wrap { padding: 0; max-width: none; }
+  html.embed .hf-app-frame { border: none; border-radius: 0; box-shadow: none; }
+  html.embed .hf-console { height: 100vh; }
+</style>
+
+<script>
+  // Mark embedded mode early so the console fills the modal iframe cleanly.
+  try { if (new URLSearchParams(location.search).get("embed")) document.documentElement.classList.add("embed"); } catch (e) {}
+</script>
+
+<script src="https://unpkg.com/react@18.3.1/umd/react.development.js" crossorigin="anonymous"></script>
+<script src="https://unpkg.com/react-dom@18.3.1/umd/react-dom.development.js" crossorigin="anonymous"></script>
+<script src="https://unpkg.com/@babel/standalone@7.29.0/babel.min.js" crossorigin="anonymous"></script>
+</head>
+<body>
+  <div id="hf-root"></div>
+
+  <script type="text/babel" src="/static/space/fx.jsx"></script>
+  <script type="text/babel" src="/static/space/data.jsx"></script>
+  <script type="text/babel" src="/static/space/sandbox.jsx"></script>
+  <script type="text/babel" src="/static/space/hf-console.jsx"></script>
+  <script type="text/babel" src="/static/space/hf-space.jsx"></script>
+</body>
+</html>

app/static/space/sandbox.jsx

@@ -0,0 +1,279 @@
+/* ============================================================
+   sandbox.jsx — MatrixLab sandbox client + "Enable sandbox" button
+
+   This is the reusable piece intended to later drop into
+   matrixhub.io. It does two things:
+
+   1. window.MatrixLabSandbox — a tiny, framework-agnostic client
+      for the MatrixLab HF Space MCP sandbox API (/mcp/*):
+        .health()                     -> capacity / availability
+        .startSession(plan)           -> POST /mcp/sessions
+        .streamEvents(id, onEvent)    -> SSE /mcp/sessions/{id}/events
+        .listTools(id)                -> GET  /mcp/sessions/{id}/tools
+        .callTool(id, name, args)     -> POST /mcp/sessions/{id}/tools/call
+        .stop(id)                     -> DELETE /mcp/sessions/{id}
+        .run(plan, onEvent)           -> full start->stream->tools flow
+
+   2. <SandboxButton> (React) + window.mountSandboxButton(el, opts)
+      — a simple toggle that enables/disables "sandbox mode" and
+      reflects live availability from /mcp/health. matrixhub.io can
+      embed it with one call:
+
+        MatrixLabSandbox.configure({ baseUrl: "https://ruslanmv-matrixlab.hf.space" });
+        mountSandboxButton(document.getElementById("sbx"), {
+          onChange: (on) => { ... }
+        });
+
+   The button is intentionally dependency-free at the data layer so
+   it works inside the HF Space (same-origin) today and inside
+   matrixhub.io (cross-origin, with a proxy/token) later.
+   ============================================================ */
+
+(function () {
+  // ---- config -------------------------------------------------------------
+  const CONFIG = {
+    // "" => same-origin (the HF Space serving this page). matrixhub.io
+    // should set this to the Space URL or to its own proxy base.
+    baseUrl: "",
+    // Optional bearer token. Same-origin Space usually leaves this empty
+    // (the Space enforces its own MATRIXLAB_SANDBOX_TOKEN server-side).
+    token: "",
+    // Optional async token provider (preferred for matrixhub.io).
+    getToken: null,
+    // Default plan used by the console "Test in sandbox" affordance.
+    // A safe, curated reference MCP server that lists tools without secrets.
+    defaultPlan: {
+      entity_id: "mcp_server:filesystem",
+      runtime: "node",
+      start_command: "npx -y @modelcontextprotocol/server-filesystem /tmp",
+      transport: "stdio",
+      ttl_seconds: 600, // 10-minute trial sandbox, then auto-shutdown
+    },
+  };
+
+  function configure(opts) {
+    Object.assign(CONFIG, opts || {});
+    return CONFIG;
+  }
+
+  function url(path) {
+    const base = (CONFIG.baseUrl || "").replace(/\/$/, "");
+    return base + path;
+  }
+
+  async function headers(extra) {
+    const h = Object.assign({ "Content-Type": "application/json" }, extra || {});
+    let tok = CONFIG.token;
+    if (!tok && typeof CONFIG.getToken === "function") {
+      try { tok = await CONFIG.getToken(); } catch (e) { /* ignore */ }
+    }
+    if (tok) h["Authorization"] = "Bearer " + tok;
+    return h;
+  }
+
+  // ---- low-level API ------------------------------------------------------
+  async function health() {
+    const res = await fetch(url("/mcp/health"), { headers: await headers() });
+    if (!res.ok) throw new Error("sandbox health " + res.status);
+    return res.json();
+  }
+
+  async function startSession(plan) {
+    const body = Object.assign({}, CONFIG.defaultPlan, plan || {});
+    const res = await fetch(url("/mcp/sessions"), {
+      method: "POST",
+      headers: await headers(),
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+      const txt = await res.text().catch(() => "");
+      throw new Error("start " + res.status + (txt ? " — " + txt.slice(0, 200) : ""));
+    }
+    return res.json();
+  }
+
+  async function listTools(id) {
+    const res = await fetch(url("/mcp/sessions/" + id + "/tools"), { headers: await headers() });
+    if (!res.ok) throw new Error("tools " + res.status);
+    return res.json();
+  }
+
+  async function callTool(id, name, args) {
+    const res = await fetch(url("/mcp/sessions/" + id + "/tools/call"), {
+      method: "POST",
+      headers: await headers(),
+      body: JSON.stringify({ name: name, arguments: args || {} }),
+    });
+    if (!res.ok) throw new Error("call " + res.status);
+    return res.json();
+  }
+
+  async function stop(id) {
+    const res = await fetch(url("/mcp/sessions/" + id), {
+      method: "DELETE",
+      headers: await headers(),
+    });
+    return res.ok ? res.json() : { ok: false };
+  }
+
+  // Stream lifecycle events. EventSource cannot set Authorization headers,
+  // so we read the SSE body via fetch + a stream reader (works same-origin,
+  // and cross-origin when CORS is allowed). Returns an abort handle.
+  async function streamEvents(id, onEvent, onDone) {
+    const controller = new AbortController();
+    (async () => {
+      try {
+        const res = await fetch(url("/mcp/sessions/" + id + "/events"), {
+          headers: await headers({ Accept: "text/event-stream" }),
+          signal: controller.signal,
+        });
+        if (!res.ok || !res.body) throw new Error("events " + res.status);
+        const reader = res.body.getReader();
+        const dec = new TextDecoder();
+        let buf = "";
+        for (;;) {
+          const { value, done } = await reader.read();
+          if (done) break;
+          buf += dec.decode(value, { stream: true });
+          let idx;
+          while ((idx = buf.indexOf("\n\n")) >= 0) {
+            const chunk = buf.slice(0, idx);
+            buf = buf.slice(idx + 2);
+            const isDone = /(^|\n)event:\s*done/.test(chunk);
+            const m = chunk.match(/(^|\n)data:\s*(.*)$/);
+            if (m && m[2]) {
+              try { onEvent && onEvent(JSON.parse(m[2]), isDone); } catch (e) { /* keep-alive */ }
+            }
+            if (isDone) { onDone && onDone(); return; }
+          }
+        }
+        onDone && onDone();
+      } catch (e) {
+        if (e.name !== "AbortError") onEvent && onEvent({ step: "stream", status: "error", message: String(e.message || e) });
+        onDone && onDone();
+      }
+    })();
+    return { abort: () => controller.abort() };
+  }
+
+  // High-level: start a session, stream its lifecycle, surface tools when ready.
+  // onEvent receives { step, status, message, data }. Resolves with the session.
+  async function run(plan, onEvent) {
+    const session = await startSession(plan);
+    const id = session.session_id;
+    onEvent && onEvent({ step: "session", status: "ok", message: "session " + id, data: session });
+    await new Promise((resolve) => {
+      streamEvents(id, (ev, isDone) => {
+        onEvent && onEvent(ev);
+        if (ev && ev.step === "ready" && ev.status === "ok") {
+          listTools(id)
+            .then((t) => onEvent && onEvent({ step: "tools", status: "ok", message: (t.tools || []).length + " tools", data: t }))
+            .catch(() => {});
+        }
+        if (isDone) resolve();
+      }, resolve);
+    });
+    return session;
+  }
+
+  window.MatrixLabSandbox = {
+    configure, health, startSession, listTools, callTool, stop, streamEvents, run,
+    get config() { return CONFIG; },
+  };
+
+  // ---- the "Enable sandbox" button ---------------------------------------
+  // A simple toggle that probes availability and flips sandbox mode.
+  function SandboxButton({ on, onChange, compact }) {
+    const [avail, setAvail] = React.useState(null); // null=unknown, true/false
+    const [info, setInfo] = React.useState(null);
+    const [busy, setBusy] = React.useState(false);
+
+    const probe = React.useCallback(() => {
+      setBusy(true);
+      health()
+        .then((h) => { setAvail(true); setInfo(h); })
+        .catch(() => { setAvail(false); setInfo(null); })
+        .finally(() => setBusy(false));
+    }, []);
+
+    React.useEffect(() => { probe(); }, [probe]);
+    React.useEffect(() => {
+      if (!on) return;
+      const t = setInterval(probe, 15000);
+      return () => clearInterval(t);
+    }, [on, probe]);
+
+    const capacity = info ? (info.max_sessions - (info.active_sessions || 0)) : null;
+    const full = capacity !== null && capacity <= 0;
+    const disabled = busy || avail === false || full;
+
+    const dotColor = avail === false ? "#ff6b81" : on ? "#00ff66" : "#34c873";
+    const label = avail === false
+      ? "sandbox offline"
+      : on
+        ? (full ? "sandbox full" : "sandbox on")
+        : "enable sandbox";
+
+    const title = avail === false
+      ? "The MatrixLab sandbox worker is not reachable."
+      : info
+        ? `Sandbox ${info.active_sessions || 0}/${info.max_sessions} sessions · TTL ${info.max_ttl_seconds}s`
+        : "Trial an MCP server in a throwaway sandbox before you install.";
+
+    function toggle() {
+      if (avail === false) { probe(); return; }
+      onChange && onChange(!on);
+    }
+
+    return (
+      <button
+        type="button"
+        onClick={toggle}
+        disabled={disabled && !on}
+        title={title}
+        aria-pressed={on}
+        style={{
+          display: "inline-flex", alignItems: "center", gap: 7, whiteSpace: "nowrap",
+          padding: compact ? "5px 10px" : "6px 12px",
+          fontFamily: "var(--hf-mono, ui-monospace, monospace)",
+          fontSize: compact ? 11.5 : 12.5, fontWeight: 700, letterSpacing: "0.02em",
+          borderRadius: 8, cursor: disabled && !on ? "not-allowed" : "pointer",
+          color: on ? "#001a0a" : "#0b3d23",
+          background: on ? "#00ff66" : "rgba(0,255,102,0.10)",
+          border: "1px solid " + (on ? "#00ff66" : "rgba(0,255,102,0.45)"),
+          boxShadow: on ? "0 0 14px rgba(0,255,102,0.45)" : "none",
+          opacity: disabled && !on ? 0.6 : 1, transition: "all .15s ease",
+        }}>
+        <span style={{ position: "relative", width: 8, height: 8 }}>
+          <span style={{ position: "absolute", inset: 0, borderRadius: 99, background: dotColor,
+            boxShadow: "0 0 8px " + dotColor }} />
+          {on && avail !== false && (
+            <span style={{ position: "absolute", inset: 0, borderRadius: 99, background: dotColor,
+              animation: "hfPing 1.8s ease-out infinite" }} />
+          )}
+        </span>
+        {busy ? "checking…" : label}
+        {info && on && !full && (
+          <span style={{ opacity: 0.7, fontWeight: 600 }}>· {capacity} free</span>
+        )}
+      </button>
+    );
+  }
+  window.SandboxButton = SandboxButton;
+
+  // Framework-agnostic mount so non-React hosts (matrixhub.io) can embed it.
+  window.mountSandboxButton = function (el, opts) {
+    opts = opts || {};
+    if (opts.baseUrl || opts.token || opts.getToken) configure(opts);
+    let on = !!opts.defaultOn;
+    const root = ReactDOM.createRoot(el);
+    function render() {
+      root.render(React.createElement(SandboxButton, {
+        on: on, compact: opts.compact,
+        onChange: (v) => { on = v; render(); opts.onChange && opts.onChange(v); },
+      }));
+    }
+    render();
+    return { setOn: (v) => { on = v; render(); }, unmount: () => root.unmount() };
+  };
+})();

app/templates/home.html

@@ -0,0 +1,119 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>MatrixLab Sandbox</title>
+  <script src="https://cdn.tailwindcss.com"></script>
+  <style>
+    body { font-family: 'Inter', system-ui, sans-serif; background: #0a0a0f; color: #e4e4e7; min-height: 100vh; }
+    .glass { background: rgba(255,255,255,0.05); backdrop-filter: blur(20px); border: 1px solid rgba(255,255,255,0.08); border-radius: 16px; }
+    .gradient-text { background: linear-gradient(135deg, #06b6d4, #8b5cf6); -webkit-background-clip: text; -webkit-text-fill-color: transparent; }
+    .status-success { color: #22c55e; } .status-warning { color: #eab308; } .status-error { color: #ef4444; }
+    .badge { display: inline-flex; align-items: center; padding: 4px 12px; border-radius: 9999px; font-size: 12px; font-weight: 500; }
+    pre { font-family: 'JetBrains Mono', monospace; }
+  </style>
+</head>
+<body>
+  <nav class="sticky top-0 z-50 border-b border-white/5 bg-[#0a0a0f]/80 backdrop-blur-xl">
+    <div class="max-w-5xl mx-auto px-6 h-16 flex items-center justify-between">
+      <a href="/" class="flex items-center gap-3">
+        <div class="w-9 h-9 rounded-lg bg-gradient-to-br from-cyan-500 to-purple-600 flex items-center justify-center text-white font-bold text-sm">ML</div>
+        <span class="gradient-text text-lg font-bold">MatrixLab Sandbox</span>
+      </a>
+      <a href="/health" class="text-sm text-zinc-500 hover:text-cyan-400">API</a>
+    </div>
+  </nav>
+
+  <main class="max-w-5xl mx-auto px-6 py-12">
+    {% if error %}
+    <div class="mb-6 p-4 rounded-xl bg-red-900/20 border border-red-500/20 text-red-300 text-sm">{{ error }}</div>
+    {% endif %}
+
+    <!-- Upload Section -->
+    <div class="text-center mb-12">
+      <h1 class="text-4xl font-extrabold mb-4"><span class="gradient-text">Verify Your Agent Project</span></h1>
+      <p class="text-zinc-400 text-lg max-w-xl mx-auto mb-8">Upload a generated project ZIP or call the Repo API to run remote containerized checks through MatrixLab Runner.</p>
+
+      <form action="/upload" method="POST" enctype="multipart/form-data" class="glass p-8 max-w-lg mx-auto">
+        <div class="mb-6">
+          <label class="block text-sm font-semibold text-zinc-300 mb-2">Project ZIP</label>
+          <input type="file" name="file" accept=".zip" required
+            class="w-full text-sm text-zinc-400 file:mr-4 file:py-2 file:px-4 file:rounded-lg file:border-0 file:text-sm file:font-semibold file:bg-cyan-500/20 file:text-cyan-400 hover:file:bg-cyan-500/30 cursor-pointer">
+          <p class="text-xs text-zinc-500 mt-2">Max 50MB. Accepts ZIP files from agent-generator or any Python/YAML project.</p>
+        </div>
+        <button type="submit" class="w-full py-3 rounded-xl bg-gradient-to-r from-cyan-500 to-purple-600 text-white font-bold text-sm hover:shadow-lg hover:shadow-cyan-500/20 transition-all">
+          Verify Project
+        </button>
+      </form>
+    </div>
+
+    <div class="glass p-6 mb-12">
+      <h2 class="text-lg font-bold text-zinc-200 mb-3">HF Backend API for GitHub Repos</h2>
+      <p class="text-sm text-zinc-400 mb-3">
+        This Space can act as a microservice gateway to a MatrixLab Runner at <code class="text-cyan-400">{{ runner_url }}</code>.
+      </p>
+      <pre class="text-xs text-zinc-400 bg-black/40 rounded-lg p-3 overflow-x-auto">curl -X POST /repo/run \
+  -H \"Content-Type: application/json\" \
+  -d '{
+    \"environment_id\": \"gitpilot-main\",
+    \"profile\": \"gitpilot\",
+    \"repo_url\": \"https://github.com/ruslanmv/gitpilot\",
+    \"branch\": \"main\"
+  }'</pre>
+      <p class="text-xs text-zinc-500 mt-2">Profiles available: <code>gitpilot</code>, <code>agent-generator</code>, <code>repoguardian</code>, or <code>custom</code> with your own repo URL.</p>
+    </div>
+
+    <!-- Verification Pipeline -->
+    <div class="glass p-6 mb-12">
+      <h2 class="text-lg font-bold text-zinc-200 mb-4">Verification Pipeline</h2>
+      <div class="grid grid-cols-2 md:grid-cols-4 gap-4 text-center text-sm">
+        <div class="p-4 rounded-xl bg-white/5">
+          <div class="text-2xl mb-2">📦</div>
+          <div class="font-semibold text-zinc-300">Unpack</div>
+          <div class="text-zinc-500 text-xs">Extract ZIP contents</div>
+        </div>
+        <div class="p-4 rounded-xl bg-white/5">
+          <div class="text-2xl mb-2">🔍</div>
+          <div class="font-semibold text-zinc-300">Detect</div>
+          <div class="text-zinc-500 text-xs">Language & framework</div>
+        </div>
+        <div class="p-4 rounded-xl bg-white/5">
+          <div class="text-2xl mb-2">🛡️</div>
+          <div class="font-semibold text-zinc-300">Validate</div>
+          <div class="text-zinc-500 text-xs">Syntax + security scan</div>
+        </div>
+        <div class="p-4 rounded-xl bg-white/5">
+          <div class="text-2xl mb-2">✅</div>
+          <div class="font-semibold text-zinc-300">Test</div>
+          <div class="text-zinc-500 text-xs">Import check + pytest</div>
+        </div>
+      </div>
+    </div>
+
+    <!-- Recent Runs -->
+    {% if runs %}
+    <h2 class="text-lg font-bold text-zinc-200 mb-4">Recent Verifications</h2>
+    <div class="space-y-3">
+      {% for run in runs %}
+      <a href="/runs/{{ run.id }}" class="glass block p-4 hover:border-cyan-500/30 transition-all">
+        <div class="flex items-center justify-between">
+          <div class="flex items-center gap-3">
+            <span class="badge {% if run.status == 'success' %}bg-green-500/10 text-green-400{% elif run.status == 'warning' %}bg-yellow-500/10 text-yellow-400{% else %}bg-red-500/10 text-red-400{% endif %}">{{ run.status }}</span>
+            <span class="text-sm font-medium text-zinc-300">{{ run.filename }}</span>
+            <span class="text-xs text-zinc-500">{{ run.language }} / {{ run.framework }}</span>
+          </div>
+          <span class="text-xs text-zinc-600">{{ run.id }}</span>
+        </div>
+        <p class="text-xs text-zinc-500 mt-1">{{ run.summary }}</p>
+      </a>
+      {% endfor %}
+    </div>
+    {% endif %}
+  </main>
+
+  <footer class="border-t border-white/5 py-8 text-center text-zinc-600 text-sm">
+    <span class="gradient-text font-semibold">MatrixLab Sandbox</span> v1.0.0 — Agent Verification Service
+  </footer>
+</body>
+</html>

app/templates/result.html

@@ -0,0 +1,88 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Verification Result — MatrixLab</title>
+  <script src="https://cdn.tailwindcss.com"></script>
+  <style>
+    body { font-family: 'Inter', system-ui, sans-serif; background: #0a0a0f; color: #e4e4e7; min-height: 100vh; }
+    .glass { background: rgba(255,255,255,0.05); backdrop-filter: blur(20px); border: 1px solid rgba(255,255,255,0.08); border-radius: 16px; }
+    .gradient-text { background: linear-gradient(135deg, #06b6d4, #8b5cf6); -webkit-background-clip: text; -webkit-text-fill-color: transparent; }
+    .badge { display: inline-flex; align-items: center; padding: 4px 12px; border-radius: 9999px; font-size: 12px; font-weight: 500; }
+    pre { background: rgba(0,0,0,0.4); border-radius: 8px; padding: 12px; font-size: 12px; overflow-x: auto; font-family: 'JetBrains Mono', monospace; }
+  </style>
+</head>
+<body>
+  <nav class="sticky top-0 z-50 border-b border-white/5 bg-[#0a0a0f]/80 backdrop-blur-xl">
+    <div class="max-w-5xl mx-auto px-6 h-16 flex items-center justify-between">
+      <a href="/" class="flex items-center gap-3">
+        <div class="w-9 h-9 rounded-lg bg-gradient-to-br from-cyan-500 to-purple-600 flex items-center justify-center text-white font-bold text-sm">ML</div>
+        <span class="gradient-text text-lg font-bold">MatrixLab Sandbox</span>
+      </a>
+      <a href="/" class="text-sm text-zinc-500 hover:text-cyan-400">New Verification</a>
+    </div>
+  </nav>
+
+  <main class="max-w-4xl mx-auto px-6 py-12">
+    <!-- Header -->
+    <div class="flex items-start justify-between mb-8">
+      <div>
+        <div class="flex items-center gap-3 mb-2">
+          <span class="badge {% if run.status == 'success' %}bg-green-500/10 text-green-400 border border-green-500/20{% elif run.status == 'warning' %}bg-yellow-500/10 text-yellow-400 border border-yellow-500/20{% else %}bg-red-500/10 text-red-400 border border-red-500/20{% endif %}">
+            {% if run.status == 'success' %}PASSED{% elif run.status == 'warning' %}WARNINGS{% else %}FAILED{% endif %}
+          </span>
+          <span class="badge bg-white/5 text-zinc-400 border border-white/10">{{ run.language }}</span>
+          <span class="badge bg-white/5 text-zinc-400 border border-white/10">{{ run.framework }}</span>
+        </div>
+        <h1 class="text-2xl font-bold text-zinc-200">{{ run.filename }}</h1>
+        <p class="text-sm text-zinc-500 mt-1">{{ run.summary }}</p>
+      </div>
+      <div class="text-right text-xs text-zinc-600">
+        <div>Run: {{ run.id }}</div>
+        <div>{{ run.files_count }} files</div>
+      </div>
+    </div>
+
+    <!-- Steps -->
+    <div class="space-y-4">
+      {% for step in run.steps %}
+      <div class="glass p-5">
+        <div class="flex items-center justify-between mb-2">
+          <div class="flex items-center gap-3">
+            {% if step.status == 'success' %}
+            <div class="w-6 h-6 rounded-full bg-green-500/20 flex items-center justify-center">
+              <svg class="w-3.5 h-3.5 text-green-400" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="3" d="M5 13l4 4L19 7"/></svg>
+            </div>
+            {% elif step.status == 'warning' %}
+            <div class="w-6 h-6 rounded-full bg-yellow-500/20 flex items-center justify-center">
+              <svg class="w-3.5 h-3.5 text-yellow-400" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z"/></svg>
+            </div>
+            {% elif step.status == 'error' %}
+            <div class="w-6 h-6 rounded-full bg-red-500/20 flex items-center justify-center">
+              <svg class="w-3.5 h-3.5 text-red-400" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12"/></svg>
+            </div>
+            {% else %}
+            <div class="w-6 h-6 rounded-full bg-zinc-700 flex items-center justify-center">
+              <div class="w-2 h-2 rounded-full bg-zinc-500"></div>
+            </div>
+            {% endif %}
+            <span class="font-semibold text-zinc-300 capitalize">{{ step.name }}</span>
+          </div>
+          <span class="text-xs {% if step.status == 'success' %}text-green-400{% elif step.status == 'warning' %}text-yellow-400{% elif step.status == 'error' %}text-red-400{% else %}text-zinc-500{% endif %}">{{ step.status }}</span>
+        </div>
+        <p class="text-sm text-zinc-400 ml-9">{{ step.message }}</p>
+        {% if step.logs %}
+        <pre class="mt-3 ml-9 text-zinc-400">{{ step.logs }}</pre>
+        {% endif %}
+      </div>
+      {% endfor %}
+    </div>
+
+    <div class="mt-8 flex gap-4">
+      <a href="/" class="px-6 py-3 rounded-xl bg-gradient-to-r from-cyan-500 to-purple-600 text-white font-bold text-sm">Verify Another</a>
+      <a href="/runs/{{ run.id }}" class="px-6 py-3 rounded-xl bg-white/5 border border-white/10 text-zinc-300 font-medium text-sm">API Response</a>
+    </div>
+  </main>
+</body>
+</html>

requirements.txt

@@ -0,0 +1,7 @@
+fastapi>=0.135.0
+uvicorn[standard]>=0.42.0
+jinja2>=3.1.6
+pydantic>=2.12.0
+python-multipart>=0.0.18
+pyyaml>=6.0
+httpx>=0.28.0

scripts/sandbox_concurrency_smoke.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""Concurrency smoke test for the MatrixLab MCP sandbox worker.
+
+Starts N sandbox sessions in parallel against a running HF Space worker,
+waits for each to reach ``running``, asserts tools were discovered, then
+tears them all down. Use it to validate that an instance can sustain the
+configured ``MATRIXLAB_MCP_MAX_SESSIONS`` (e.g. 10) in parallel.
+
+Usage:
+    BASE=http://127.0.0.1:7901 N=10 python hf/scripts/sandbox_concurrency_smoke.py
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+import time
+
+import httpx
+
+BASE = os.environ.get("BASE", "http://127.0.0.1:7901").rstrip("/")
+N = int(os.environ.get("N", "10"))
+TTL = int(os.environ.get("TTL", "120"))
+TOKEN = os.environ.get("MATRIXLAB_SANDBOX_TOKEN", "")
+PLAN = {
+    "entity_id": "mcp_server:filesystem",
+    "runtime": "node",
+    "start_command": "npx -y @modelcontextprotocol/server-filesystem /tmp",
+    "transport": "stdio",
+    "ttl_seconds": TTL,
+}
+HEADERS = {"Authorization": f"Bearer {TOKEN}"} if TOKEN else {}
+
+
+async def start_one(client: httpx.AsyncClient, i: int) -> dict:
+    r = await client.post(f"{BASE}/mcp/sessions", json={**PLAN, "entity_id": f"sbx-{i}"}, headers=HEADERS)
+    r.raise_for_status()
+    return r.json()
+
+
+async def wait_running(client: httpx.AsyncClient, sid: str, timeout: int = 120) -> dict:
+    deadline = time.time() + timeout
+    last = {}
+    while time.time() < deadline:
+        r = await client.get(f"{BASE}/mcp/sessions/{sid}", headers=HEADERS)
+        last = r.json()
+        st = last.get("status")
+        if st in ("running", "failed", "timeout", "install_failed", "start_failed", "mcp_failed"):
+            return last
+        await asyncio.sleep(1.5)
+    return last
+
+
+async def main() -> int:
+    async with httpx.AsyncClient(timeout=30) as client:
+        h = (await client.get(f"{BASE}/mcp/health", headers=HEADERS)).json()
+        print(f"worker: max_sessions={h['max_sessions']} instance={h.get('instance')}")
+        if h["max_sessions"] < N:
+            print(f"NOTE: max_sessions ({h['max_sessions']}) < N ({N}); "
+                  f"set MATRIXLAB_MCP_MAX_SESSIONS={N} (or 'auto') to admit all.")
+
+        t0 = time.time()
+        started = await asyncio.gather(*[start_one(client, i) for i in range(N)], return_exceptions=True)
+        ok_started = [s for s in started if isinstance(s, dict)]
+        rejected = [s for s in started if not isinstance(s, dict)]
+        print(f"requested {N} · admitted {len(ok_started)} · rejected {len(rejected)} "
+              f"in {time.time()-t0:.1f}s")
+
+        results = await asyncio.gather(*[wait_running(client, s["session_id"]) for s in ok_started])
+        running = [r for r in results if r.get("status") == "running"]
+        with_tools = [r for r in running if (r.get("tools") or [])]
+        elapsed = time.time() - t0
+
+        print("\nper-session:")
+        for r in results:
+            print(f"  {r.get('entity_id','?'):10} {r.get('status','?'):10} "
+                  f"tools={len(r.get('tools') or [])}")
+
+        print(f"\nrunning {len(running)}/{len(ok_started)} · with tools {len(with_tools)} "
+              f"· wall {elapsed:.1f}s")
+
+        # teardown
+        await asyncio.gather(*[client.delete(f"{BASE}/mcp/sessions/{s['session_id']}", headers=HEADERS)
+                               for s in ok_started], return_exceptions=True)
+        print("torn down.")
+
+        ok = len(running) == len(ok_started) and len(with_tools) == len(running) and len(ok_started) >= 1
+        print("RESULT:", "PASS" if ok else "FAIL")
+        return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(asyncio.run(main()))