docs/DEPLOY-huggingface.md

# Deploying the PROTEUS arena to HuggingFace Spaces

This puts the interactive web arena on a **public URL** anyone can open, with
**no API keys** — so it can never spend LLM tokens for a visitor.

## What runs publicly (and what doesn't)

| Mode | Works on the public Space? | Why |
|------|----------------------------|-----|
| Human play (`/session` → `/act`) | ✅ Yes | No model needed — you control the agent |
| `fake:demo` spectate | ✅ Yes | Offline canned agent |
| persona / policy memory | ✅ Yes | Offline reference policies, no model |
| Real-model spectate (`anthropic:…`, `openai:…`) | ❌ Returns a clean 400 | No API key + provider SDK not installed |

The "no LLM cost" guarantee comes from two layers: the Dockerfile installs
**base deps only** (no `openai`/`anthropic` SDK), and we set **no secrets**.

## Files involved

- `Dockerfile` — Python 3.12, base deps, runs `python -m proteus.web.local` on port 7860
- `.dockerignore` — keeps `.env`, `.venv/`, `runs/`, `.git/` etc. out of the image
- `README.md` — the YAML frontmatter at the top configures the Space (`sdk: docker`, `app_port: 7860`)

## One-time setup

1. Create a Space at <https://huggingface.co/new-space>
   - **SDK**: Docker → "Blank"
   - **Hardware**: CPU basic (free) is enough
   - Name it e.g. `proteus-arena`

2. Add the Space as a git remote and push this repo:

   ```bash
   # from the repo root
   git remote add space https://huggingface.co/spaces/<your-username>/proteus-arena
   git push space master:main      # Spaces deploy from the `main` branch
   ```

   > HuggingFace asks for a username + an **access token** as the password.
   > Create one at <https://huggingface.co/settings/tokens> (role: `write`).

3. The Space builds the Dockerfile automatically. When the log shows the server
   line, open the Space URL — the arena loads.

## Do NOT add secrets

Leave the Space **Settings → Variables and secrets** empty. Adding
`ANTHROPIC_API_KEY` / `OPENAI_API_KEY` would re-enable real-model spectate and
expose you to token cost / abuse from anonymous visitors. Keeping them unset is
the intended public posture.

## Updating the deployment

```bash
git push space master:main
```

Every push triggers a rebuild. Sessions are in-memory and not persisted, so a
rebuild simply resets all live games (fine for a demo).

## Local smoke test before pushing

```bash
docker build -t proteus-arena .
docker run --rm -p 7860:7860 proteus-arena
# open http://localhost:7860/
```