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
asynciosubprocesses withsetsid, CPU/AS softresourcelimits, 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
- static β
index.htmlin root /dist/build/public/outβpython -m http.server - node β
npm install(+ optionalbuildβ static) ornpm run preview|startwith$PORT - python β FastAPI/Flask/Streamlit heuristics with pip install from
requirements.txt - 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/