polyguard-rl/docker/space/README.md

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):

   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 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)

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

Open http://127.0.0.1:7860.