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