README.md

metadata

title: FreeLLMAPI on Hugging Face Spaces
emoji: 🚀
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 7860
pinned: false

FreeLLMAPI on Hugging Face Spaces

A Hugging Face Spaces deployment for FreeLLMAPI. It preserves the upstream web dashboard/UI, OpenAI-compatible API, and Anthropic Messages API used by Claude Code.

Why Docker plus Python? Hugging Face supports Python Spaces and Docker Spaces. The original FreeLLMAPI project itself is Node.js/React, so requirements.txt alone cannot run the whole product. This package includes a small Python launcher (app.py) and requirements.txt, while Docker runs the official upstream application image so its real UI and API remain intact.

Deploy

1. Create a new Space with Docker as its SDK, or replace the files in the root of your existing Docker Space with this package.

2. Upload these files to the Space repository root: README.md, Dockerfile, app.py, requirements.txt, and .gitignore.

3. In Settings → Variables and secrets, add a secret named ENCRYPTION_KEY. Generate a 64-character hex key on your own computer:

   python -c "import secrets; print(secrets.token_hex(32))"
   

   Paste the output as the secret value. The launcher can generate a fallback key at /data/.encryption-key, but a stable secret is preferable for production use.

4. To retain the database and fallback key after restarts, create/attach a writable Hugging Face Storage Bucket volume mounted at /data. Without a persistent mounted volume, Space files may be lost on restarts.

5. Wait for the Docker build, then open the Space URL. Finish the initial account setup and add provider keys on the dashboard's Keys page.

The setpriv: No program specified error is addressed by launching the upstream entrypoint with an explicit default command (node server/dist/index.js) and a Python fallback when no command is provided.

URLs

Replace the examples with your actual Space URL, usually https://<username>-<space-name>.hf.space.

• Dashboard/UI: https://<username>-<space-name>.hf.space/
• OpenAI-compatible API: https://<username>-<space-name>.hf.space/v1
• Anthropic Messages API / Claude Code: https://<username>-<space-name>.hf.space (the client calls /v1/messages)
• Model list check: https://<username>-<space-name>.hf.space/v1/models

Use the unified FreeLLMAPI API key shown in the dashboard. It is not your provider's key or a Hugging Face token.

Claude Code

On the computer where Claude Code is installed, run:

npx freellmapi setup-claude \
  --url "https://<username>-<space-name>.hf.space" \
  --api-key "<your-freellmapi-unified-api-key>"

Or configure environment variables manually:

export ANTHROPIC_BASE_URL="https://<username>-<space-name>.hf.space"
export ANTHROPIC_AUTH_TOKEN="<your-freellmapi-unified-api-key>"
claude

Keep the key private: do not commit it to the Space repository or put it in browser/frontend code.

Notes

• A Space configured as Private can require Hugging Face authentication as well; external CLI compatibility depends on whether the client can authenticate to the private Space. Make the Space public only if appropriate and protect the app/API credentials.
• FreeLLMAPI is intended as a single-user router, not a public shared API service. Never share your unified API key.
• Keep ENCRYPTION_KEY stable if keeping an existing database. Changing it can make stored provider keys unreadable.
• The Python launcher uses only the standard library; requirements.txt is present for packaging consistency and currently has no third-party packages.

Upstream

• FreeLLMAPI source and docs
• Hugging Face Docker Spaces documentation
• Hugging Face Spaces storage documentation