deploy/hf-space/SETUP.md

# Deploying the MatrixCloud demo on Hugging Face

Two files in `deploy/hf-space/` (`Dockerfile`, `README.md`) are everything a
Hugging Face **Docker Space** needs.

## 1. Create the Space
- **Owner / name:** `ruslanmv / matrixcloud`
- **Short description:** "Self-hostable execution plane for AI — MCP sandboxes, models, MatrixShell."
- **License:** Apache-2.0
- **SDK:** **Docker** → template **Blank**
- **Hardware:** **Free** (CPU basic). No GPU needed — model *inspection* is
  metadata only, and LLM inference is bring-your-own (the user's HF token).
- **Storage bucket:** **not required** for the demo. Use Postgres (Neon) for
  durable accounts instead (see secrets below). Mounting a bucket at `/data` is
  only useful if you want the model cache to persist — if you do, also set
  `MATRIX_RUNTIME_DATA_DIR=/data`.
- **Visibility:** **Public** (so people can try it).
- **Dev mode / Protected:** not needed (PRO-only).

## 2. Add the files
Push `Dockerfile` and `README.md` from this folder to the new Space's git repo
(rename `deploy/hf-space/README.md` → `README.md` at the Space root; its YAML
front-matter sets `sdk: docker` and `app_port: 8080`).

## 3. Set Space secrets/variables
Secrets:
```
MATRIXCLOUD_DATABASE_URL = postgresql://…neon…?sslmode=require&channel_binding=require
MATRIXCLOUD_SECRET_KEY   = <openssl rand -hex 32>
RESEND_API_KEY           = re_…           # optional (emails)
```
Variables:
```
MATRIXCLOUD_DB_SCHEMA  = matrixcloud
MATRIXCLOUD_APP_URL    = https://ruslanmv-matrixcloud.hf.space
MATRIXCLOUD_EMAIL_FROM = MatrixCloud <noreply@matrixhub.io>   # if using Resend
```
Leave `MATRIX_RUNTIME_API_TOKEN` **unset** — the multitenant console
authenticates per-user with sessions; users just sign up. (Setting it would
gate operator-level API calls but isn't needed for the demo.)

Keep `MATRIX_SHELL_ENABLED=false` on a public Space (it runs sandboxed commands;
enable only if you want to demo it).

## 4. Test
Open `https://ruslanmv-matrixcloud.hf.space`, sign up, and try:
- **Models** → import + inspect `Qwen/Qwen2.5-7B-Instruct`
- **Settings** → plug in your Hugging Face token (BYO provider)
- **Catalog / Sandboxes** → launch a filesystem MCP sandbox
- `…/docs` and `…/v1/version` to confirm the API

> If you don't set `MATRIXCLOUD_DATABASE_URL`, the demo still works but accounts
> live in ephemeral `/tmp` and reset whenever the Space rebuilds/sleeps.