# RepoSpace — Architecture Spec (HF Space MVP) ## One-liner Temporary, instantly usable live environments for GitHub repos in the browser. ## MVP loop GitHub URL → validate → clone (tarball) → detect → build/run in constrained subprocess → reverse-proxy preview in iframe under `/s/{id}/` → auto-shutdown after **15 min inactivity** (hard cap 60 min). ## META-BLUEPRINT → HF reality (honest deltas) | Blueprint (ideal) | HF Space MVP | Notes | |-------------------|--------------|-------| | AWS EKS + Firecracker / MicroVMs | **Not available** inside a single HF Space | Documented; no fake K8s claims | | Go control plane | **Python FastAPI** | Prefer FastAPI for HF Docker reliability | | Per-VM network isolation | Best-effort subprocess + localhost ports | Shared Space network namespace | | Docker-in-Docker | **Disabled** | HF does not offer privileged DinD for this use | | Full node/Python/Docker workloads | Static / simple Node build+serve / simple Python web | Next.js full server, heavy Docker images → clear failure + log diagnosis | | Distributed session store | **SQLite** in `/data` (or `/tmp/repospace`) | TTL + inactivity cleaner | | Unlimited concurrent sessions | Soft cap `MAX_CONCURRENT_SESSIONS` (default 3) | cpu-basic constraints | ### Features F1–F4 (as far as HF allows) - **F1 Launch from GitHub URL** — ✅ public tarball; private with user-supplied token (never logged; docs use `[ERSATZ_KEY]`) - **F2 Live preview iframe** — ✅ `/s/{id}/` reverse proxy when runnable - **F3 Build logs** — ✅ poll + optional SSE (`?sse=1`) - **F4 Auto-teardown** — ✅ 15 min inactivity + 60 min hard TTL + DELETE API ## Stack - **Deploy**: Hugging Face Space, Docker SDK, `cpu-basic` (upgrade if needed) - **Backend**: Python 3.11 + FastAPI (API + static UI + proxy) - **Frontend**: React 18 + TypeScript + Vite (UI **English**, i18n-ready) - **Session store**: SQLite - **Sandbox**: isolated `asyncio` subprocesses with `setsid`, CPU/AS soft `resource` limits, timeouts, temp dirs under `/data/sessions/{id}` ## API - `POST /api/sessions` `{repo_url, github_token?, ref?}` - `GET /api/sessions/{id}` - `GET /api/sessions/{id}/logs?after=&sse=` - `DELETE /api/sessions/{id}` - Proxy: `/s/{id}/…` → `127.0.0.1:{port}/…` - `GET /api/health` ## Preview strategies 1. **static** — `index.html` in root / `dist` / `build` / `public` / `out` → `python -m http.server` 2. **node** — `npm install` (+ optional `build` → static) or `npm run preview|start` with `$PORT` 3. **python** — FastAPI/Flask/Streamlit heuristics with pip install from `requirements.txt` 4. **unsupported** — Dockerfile-only / Next.js heavy / unknown → honest error + hints (build log diagnosis) ## Security - Never execute untrusted code in the main API process - Temp dirs per session; path traversal blocked on URL, archive members, proxy paths, session ids - Rate limit by IP: create 8/min, delete 30/min, status GET + logs poll 600/min (preview UI polls ~1/s) - Credential-like env vars stripped from child processes - Tokens redacted in logs; placeholders `[ERSATZ_KEY]` - No host secret mounts into sandboxes - Public repos without token; private only with user-supplied token ## Status machine `pending` → `building` → `running` | `failed` → `terminated` ## File tree ``` repospace/ ├── SPEC.md ├── RESULT.md ├── README.md # HF Space card + YAML frontmatter ├── Dockerfile ├── requirements.txt ├── backend/app/… ├── backend/tests/… ├── frontend/… └── scripts/ ```