Spaces:
Paused
Paused
|
Download SPEC.md from 2Btainment/repospace: direct link, hf CLI and curl.
- Browser
- Download file 3.59 kB
-
https://huggingface.co/spaces/2Btainment/repospace/resolve/main/SPEC.md
- Command line
-
hf download hf://spaces/2Btainment/repospace/SPEC.md
-
curl -L -o SPEC.md https://huggingface.co/spaces/2Btainment/repospace/resolve/main/SPEC.md
3.59 kB
| # 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/ | |
| ``` | |