# Deploy PolyGuard on Hugging Face Spaces

## Security

Never commit or paste Hugging Face tokens into chat or the repo. If a token was exposed, revoke it under **Settings → Access Tokens** and create a new one. Use **Space → Settings → Secrets** to store `HF_TOKEN` if a private Hub asset is required.

## One-time setup

1. Create a new Space: **Docker** SDK, visibility as you prefer, hardware **CPU basic** (cheap). Note the repo id, e.g. `YourName/polyguard-openenv`.

2. From your machine (with Docker and Git):

   ```bash
   cd polyguard-rl
   docker build -f Dockerfile.space -t polyguard-space .
   ```

3. Push the Space repo (HF expects `Dockerfile` at root). Either:

   - **Option A:** In the Space repo on Hub, set **Build → Dockerfile path** to `Dockerfile.space` if the UI allows, **or** copy/rename: `cp Dockerfile.space Dockerfile` in the branch you push.

   - **Option B:** Make this `polyguard-rl` folder the Space git root and add a symlink or duplicate `Dockerfile` pointing to the same content as `Dockerfile.space`.

4. Commit and push to the Space repository. HF builds the image on their builders (you do not need to `docker push` to Docker Hub for standard Spaces).

## Runtime

- **Port:** Space sets `PORT` (default `7860`). Nginx listens on `PORT` and routes `/api/*` → API, `/ws` → OpenEnv WebSocket, `/` → built React app.
- **First boot:** If `checkpoints/active/grpo_adapter` is missing, `entrypoint.sh` runs `scripts/install_hf_active_bundle.py`. That pulls `TheJackBright/polyguard-openenv-training-full-artifacts` (slow, ~1.1 GB).
- **CORS:** Set via `POLYGUARD_ALLOW_HF_SPACE_CORS=true` (default in the Space Dockerfile).

## If logs show `401` / `RepositoryNotFoundError` on startup

The artifact **model repo is private, gated, or needs a license click** while anonymous downloads are blocked. The UI can still “work” using the **heuristic ranker** and public base models, but **your trained bundle is not installed**.

**Fix (pick one):**

1. **Space secret (recommended):** Space → **Settings** → **Secrets** → add **`HF_TOKEN`** = a [read token](https://huggingface.co/settings/tokens) that can access `polyguard-openenv-training-full-artifacts`. Restart the Space.
2. **Hub settings:** Make that model repo **public**, or ensure **gated** access allows the token you use in (1).
3. **Ignore:** Leave as-is if ranker-only behavior is enough for the demo.

## Secrets

| Name        | Use |
|------------|-----|
| `HF_TOKEN` | **Required** if the artifact repo is not anonymously readable; `huggingface_hub` reads it automatically. |

## Local smoke (same as Space)

```bash
docker run --rm -p 7860:7860 -e PORT=7860 polyguard-space
```

Open `http://127.0.0.1:7860`.