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:

   # 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

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

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