DEPLOY_HF_SPACE.md

Deployment checklist

1. Create/select a Hugging Face Space with Docker SDK.
2. Upload README.md, Dockerfile, app.py, requirements.txt, and .gitignore to the repository root.
3. Add the ENCRYPTION_KEY secret in Space Settings → Variables and secrets. Generate it locally with: python -c "import secrets; print(secrets.token_hex(32))"
4. For persistence, attach a writable Storage Bucket volume to /data. Without a mounted persistent volume, the database and fallback key may be lost on restart.
5. Wait for the build. The runtime should start with node server/dist/index.js; the Python launcher ensures this command is passed to the upstream entrypoint.
6. Open the Space, complete the dashboard's initial account setup, then configure upstream provider keys.
7. Copy the unified API key from the dashboard and configure Claude Code: npx freellmapi setup-claude --url "https://<username>-<space-name>.hf.space" --api-key "<unified-api-key>"

Endpoints

• UI: https://<username>-<space-name>.hf.space/
• OpenAI-compatible API: https://<username>-<space-name>.hf.space/v1
• Claude Code / Anthropic API base: https://<username>-<space-name>.hf.space

Important

• FreeLLMAPI is a Node.js/React application. app.py is the Python startup wrapper, not a Python rewrite of the entire product.
• Never commit provider keys, unified API keys, or encryption secrets to Git.
• A private Space may require Hugging Face authentication in addition to FreeLLMAPI authentication. Test external CLI access for your visibility settings.
• Keep the same encryption secret when retaining an existing database.