HUGGINGFACE_SPACE.md

Hugging Face Spaces — MiroFish API (Docker)

Create the Space

1. huggingface.co/spaces → Create new Space
2. SDK: Docker
3. Hardware: CPU (free) — long simulations may OOM or time out; upgrade if needed.
4. Connect this repo and set the Docker app directory to backend (or copy only backend/ into a dedicated repo).

Visibility must be Public (important)

If the Space is Private, browsers and your static site get 401 with body unauthorized (plain text) before the request reaches Flask.
Open Space → Settings → Visibility and set Public so https://YOUR-SPACE.hf.space/api/... works without a Hugging Face login cookie.

Build context = folder that contains Dockerfile, requirements.txt, app/, wsgi.py.

Secrets (Space → Settings → Variables and secrets)

Variable	Notes
SECRET_KEY	Long random string (Flask).
LLM_API_KEY, LLM_BASE_URL, LLM_MODEL_NAME	Your LLM.
ZEP_API_KEY	Zep.
SUPABASE_URL	https://xxx.supabase.co
SUPABASE_SERVICE_ROLE_KEY	Service role (never expose to browser).
PIPELINE_CLIENT_SECRET	Same as website VITE_PIPELINE_CLIENT_SECRET.
SUPABASE_REPORTS_BUCKET	Default reports.
PIPELINE_MAX_ROUNDS	Optional integer cap.

Optional: SUPABASE_JWT_SECRET if you use Supabase Auth JWT on the pipeline.

Website (website/.env)

VITE_API_BASE_URLS=https://YOUR-SPACE.hf.space
VITE_PIPELINE_CLIENT_SECRET=same-as-PIPELINE_CLIENT_SECRET
VITE_SUPABASE_URL=https://xxx.supabase.co
VITE_SUPABASE_ANON_KEY=your_anon_key

Login/sign-up use Supabase on public."User" — run supabase/grants_public_user.sql in the SQL editor.

Free tier notes

• Space sleeps when idle; first request is a cold start.
• Proxies may time out on very long HTTP requests; heavy pipelines may need paid hardware or another host.

Health check

GET /health → {"status":"ok",...}