Spaces:
Running
Running
| 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](https://github.com/tashfeenahmed/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: | |
| ```bash | |
| 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: | |
| ```bash | |
| npx freellmapi setup-claude \ | |
| --url "https://<username>-<space-name>.hf.space" \ | |
| --api-key "<your-freellmapi-unified-api-key>" | |
| ``` | |
| Or configure environment variables manually: | |
| ```bash | |
| 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](https://github.com/tashfeenahmed/freellmapi) | |
| - [Hugging Face Docker Spaces documentation](https://huggingface.co/docs/hub/en/spaces-sdks-docker) | |
| - [Hugging Face Spaces storage documentation](https://huggingface.co/docs/hub/main/spaces-storage) | |