Upload 6 files

.gitignore

@@ -3,3 +3,5 @@
 *.db-shm
 *.db-wal
 .encryption-key
+__pycache__/
+*.py[cod]

DEPLOY_HF_SPACE.md

@@ -1,21 +1,24 @@
-# Deployment checklist (Hugging Face Spaces)
+# Deployment checklist
 
-1. Create a **Docker** Space and upload/push this folder.
-2. Add a Space secret `ENCRYPTION_KEY`. Generate locally:
-   `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`
-3. Attach a writable Storage Bucket at `/data` if database persistence is needed.
-4. Ensure the Space metadata retains `sdk: docker` and `app_port: 7860` in `README.md`.
-5. Open the Space URL and finish FreeLLMAPI's initial account setup.
-6. In the dashboard, add provider keys and copy the unified FreeLLMAPI API key.
-7. From the computer running Claude Code:
+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>"`
 
-## Expected URLs
+## Endpoints
 
 - UI: `https://<username>-<space-name>.hf.space/`
-- Claude Code base URL: `https://<username>-<space-name>.hf.space`
-- OpenAI-style API base: `https://<username>-<space-name>.hf.space/v1`
+- OpenAI-compatible API: `https://<username>-<space-name>.hf.space/v1`
+- Claude Code / Anthropic API base: `https://<username>-<space-name>.hf.space`
 
 ## Important
 
-Never commit an actual provider key, unified API key, or `ENCRYPTION_KEY` to the Space repository. FreeLLMAPI is intended as a single-user router; a public Space must not be treated as a community endpoint. Space default storage is ephemeral unless a persistent volume/bucket is attached.
+- 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.

Dockerfile

@@ -1,15 +1,30 @@
-# FreeLLMAPI upstream image includes the Node API server and React dashboard.
-# Pin to a release rather than tracking :latest for repeatable Space builds.
+# FreeLLMAPI's actual API and dashboard are Node.js/React; use the upstream
+# release image, with a small Python launcher to configure Hugging Face Spaces.
 FROM ghcr.io/tashfeenahmed/freellmapi:v0.16.7
 
 USER root
-COPY hf-entrypoint.sh /usr/local/bin/hf-entrypoint.sh
-RUN chmod 755 /usr/local/bin/hf-entrypoint.sh
 
-ENV NODE_ENV=production
-ENV PORT=7860
+# Python launcher + pip keep the Space package Python-friendly and install the
+# declared requirements.txt. No third-party Python dependencies are currently
+# needed by app.py.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends python3 python3-pip \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY requirements.txt /app/requirements.txt
+RUN if grep -qEv '^[[:space:]]*(#.*)?$' /app/requirements.txt; then \
+        python3 -m pip install --break-system-packages --no-cache-dir -r /app/requirements.txt; \
+    fi
+COPY app.py /app/app.py
+
+ENV NODE_ENV=production \
+    PORT=7860 \
+    FREELLMAPI_DATA_DIR=/data
+
 EXPOSE 7860
 
-# Keep the upstream image's CMD (node server/dist/index.js); our wrapper sets
-# the Hugging Face port/data path and then calls the official entrypoint.
-ENTRYPOINT ["/usr/local/bin/hf-entrypoint.sh"]
+# Explicit CMD is important: without a command, the inherited setpriv-based
+# upstream entrypoint can emit "setpriv: No program specified".
+ENTRYPOINT ["python3", "/app/app.py"]
+CMD ["node", "server/dist/index.js"]

README.md

@@ -10,70 +10,66 @@ pinned: false
 
 # FreeLLMAPI on Hugging Face Spaces
 
-A Hugging Face Spaces deployment wrapper for [FreeLLMAPI](https://github.com/tashfeenahmed/freellmapi). It uses the official upstream Docker image, including the **web dashboard/UI**, OpenAI-compatible API, and Anthropic Messages API used by Claude Code.
+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.
 
-## Deploy it
+**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.
 
-1. Create a new **Docker** Space on Hugging Face.
-2. Upload these files (`Dockerfile`, `hf-entrypoint.sh`, `README.md`, `DEPLOY_HF_SPACE.md`) to the Space repository, or push this folder with Git.
-3. In Space **Settings → Variables and secrets**, add a secret named `ENCRYPTION_KEY`. Generate a fresh 64-character hex key on your own computer with:
+## 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
-   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+   python -c "import secrets; print(secrets.token_hex(32))"
    ```
 
-   If you skip this secret, the entrypoint generates a fallback key file in `/data`.
-4. For data to survive a Space restart/rebuild, attach a writable Hugging Face Storage Bucket at the mount path `/data`. Without persistent storage, the database and fallback key can be lost on restart.
-5. Wait for the Docker build to complete, then open the Space URL. The upstream app dashboard should load. Complete the app's initial account setup, sign in, and add the API-provider keys you intend to use on the **Keys** page.
+   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 Space URL looks like `https://<your-username>-<space-name>.hf.space`.
+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.
 
-## Endpoints after deployment
+## URLs
 
-Replace the example URL with your actual Space URL.
+Replace the examples with your actual Space URL, usually `https://<username>-<space-name>.hf.space`.
 
-- Dashboard/UI: `https://<your-username>-<space-name>.hf.space/`
-- OpenAI-compatible API base: `https://<your-username>-<space-name>.hf.space/v1`
-- Anthropic Messages API base for Claude Code: `https://<your-username>-<space-name>.hf.space` (the client calls `/v1/messages`)
-- Models check: `https://<your-username>-<space-name>.hf.space/v1/models`
+- 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`
 
-The inference calls need the **unified API key** shown in the FreeLLMAPI dashboard. It is not the same as an upstream provider key or a Hugging Face access token.
+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://<your-username>-<space-name>.hf.space" --api-key "<your-freellmapi-unified-api-key>"
+npx freellmapi setup-claude \
+  --url "https://<username>-<space-name>.hf.space" \
+  --api-key "<your-freellmapi-unified-api-key>"
 ```
 
-The setup command reads the available model catalog from your running FreeLLMAPI instance and configures Claude Code. If you'd rather use environment variables manually, set:
+Or configure environment variables manually:
 
 ```bash
-export ANTHROPIC_BASE_URL="https://<your-username>-<space-name>.hf.space"
+export ANTHROPIC_BASE_URL="https://<username>-<space-name>.hf.space"
 export ANTHROPIC_AUTH_TOKEN="<your-freellmapi-unified-api-key>"
 claude
 ```
 
-Keep the key on your own computer or in a local secret manager. **Do not** commit it to this Space, put it in frontend JavaScript, or paste it into public issues/screenshots.
-
-## Other clients
-
-For an OpenAI-compatible client, use:
-
-```text
-Base URL: https://<your-username>-<space-name>.hf.space/v1
-API key:  <your-freellmapi-unified-api-key>
-```
+Keep the key private: do not commit it to the Space repository or put it in browser/frontend code.
 
-## Security and persistence notes
+## Notes
 
-- A publicly reachable Space URL is accessible from the internet. FreeLLMAPI is designed as a single-user router, not as a shared public API service. Use a strong dashboard password and keep the unified API key private; anyone who obtains that key may be able to use your configured provider quota.
-- Do not store upstream provider keys in this repository. Enter them through the dashboard after deployment. Keep the same `ENCRYPTION_KEY` when retaining an existing database; changing it without re-encrypting stored keys can make them unreadable.
-- A `Private` Space may require Hugging Face authentication in addition to FreeLLMAPI's own key and may not work directly with every external CLI. For a publicly reachable Space, rely on FreeLLMAPI's app/API authentication and keep credentials private.
-- A Hugging Face Space's default disk is ephemeral. Attach a writable Storage Bucket to `/data` to persist the SQLite database and generated fallback encryption key across restarts/rebuilds.
-- FreeLLMAPI and upstream free-provider quotas/terms remain applicable. See the upstream README and documentation for the current limits and terms.
+- 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 project
+## Upstream
 
-This wrapper does not fork or reimplement FreeLLMAPI; it adapts the official container's port and data path for Spaces. See the [upstream GitHub repository](https://github.com/tashfeenahmed/freellmapi) and [Hugging Face Docker Spaces documentation](https://huggingface.co/docs/hub/en/spaces-sdks-docker).
+- [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)

app.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+"""Hugging Face Spaces launcher for the upstream FreeLLMAPI container.
+
+FreeLLMAPI itself is a Node.js/React application. This small Python launcher
+prepares the Space environment and explicitly forwards the server command to
+the upstream privilege-dropping entrypoint.
+"""
+from __future__ import annotations
+
+import os
+import secrets
+import sys
+from pathlib import Path
+
+
+def prepare_environment() -> None:
+    data_dir = Path(os.environ.get("FREELLMAPI_DATA_DIR", "/data"))
+    data_dir.mkdir(parents=True, exist_ok=True)
+
+    os.environ.setdefault("NODE_ENV", "production")
+    os.environ.setdefault("PORT", os.environ.get("SPACE_PORT", "7860"))
+    os.environ.setdefault("FREEAPI_DB_PATH", str(data_dir / "freeapi.db"))
+
+    # Keep a stable generated key beside the DB if a Space Secret was not set.
+    # For a persistent deployment, mount a writable bucket at /data.
+    if not os.environ.get("ENCRYPTION_KEY"):
+        key_file = Path(
+            os.environ.get("ENCRYPTION_KEY_FILE", str(data_dir / ".encryption-key"))
+        )
+        if not key_file.is_file() or key_file.stat().st_size == 0:
+            key_file.parent.mkdir(parents=True, exist_ok=True)
+            try:
+                descriptor = os.open(
+                    key_file,
+                    os.O_WRONLY | os.O_CREAT | os.O_EXCL,
+                    0o600,
+                )
+            except FileExistsError:
+                # Another startup process created it first.
+                pass
+            else:
+                with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+                    handle.write(secrets.token_hex(32))
+                    handle.write("\n")
+        os.environ["ENCRYPTION_KEY"] = key_file.read_text(encoding="utf-8").strip()
+
+
+def main() -> None:
+    prepare_environment()
+
+    # Dockerfile supplies this CMD explicitly. Keep the fallback to avoid ever
+    # calling setpriv with an empty command (the error seen in the Space logs).
+    command = sys.argv[1:] or ["node", "server/dist/index.js"]
+    upstream_entrypoint = "/usr/local/bin/docker-entrypoint.sh"
+    if not os.path.isfile(upstream_entrypoint):
+        raise FileNotFoundError(
+            f"Expected upstream FreeLLMAPI entrypoint at {upstream_entrypoint}"
+        )
+
+    os.execv(upstream_entrypoint, [upstream_entrypoint, *command])
+
+
+if __name__ == "__main__":
+    main()

requirements.txt

@@ -1,13 +1,3 @@
-fastapi>=0.100.0
-uvicorn>=0.23.0
-huggingface_hub>=0.16.4
-rank_bm25>=0.2.2
-torch>=2.0.0
-tiktoken
-aiohttp>=3.8.5
-beautifulsoup4>=4.12.2
-transformers>=4.36.0
-accelerate>=0.25.0
-bitsandbytes>=0.41.0
-openai
-faiss-cpu
+# No third-party Python packages are required.
+# app.py uses only the Python standard library; the actual FreeLLMAPI server/UI
+# and its dependencies are shipped in the upstream container image.