English | 中文

HFBridge is an all-in-one Hugging Face proxy service with a built-in web dashboard. It provides transparent request forwarding, Large File Storage (LFS) link rewriting, and real-time usage analytics so that teams working behind firewalls or inside restricted networks can keep using Hugging Face resources.

• Transparent proxying for Hugging Face repositories, models, and files with a configurable upstream origin
• Automatic injection of a Hugging Face access token for private resources
• LFS batch response rewriting so large files are fetched via the proxy's /lfs/content endpoint
• Usage and bandwidth tracking persisted in SQLite with a live dashboard
• Integrated web UI for monitoring usage, repository statistics, and traffic trends
• Single-container deployment with Docker or a self-contained binary build

The repo ships with a ready-to-run Compose stack that pulls the published gouryella/hfbridge:latest image.

• Docker Engine 20.10+ with the docker compose plugin (or Docker Desktop)

1. Clone this repository and adjust environment variables in docker-compose.yml if needed (for example DEFAULT_UPSTREAM, HF_TOKEN or PROXY_ORIGIN).

2. Start the service:

   docker compose up -d

3. Visit http://localhost:8080 to open the web dashboard.

4. Follow logs when troubleshooting:

   docker compose logs -f hfbridge

5. Stop the stack when you are done:

   docker compose down

By default, the container persists its SQLite database to ./data on the host. Adjust the volume section in docker-compose.yml if you need a different location.

If you prefer to build the image yourself:

docker build -t hfbridge .
docker run -p 8080:8080 -v $(pwd)/data:/data hfbridge

For local binary builds, see the Development section.

Open http://localhost:8080 to inspect live usage metrics, repository rankings, and traffic charts.

# Proxy a public repository
git clone http://localhost:8080/google/bert

# Large file downloads are also rewritten through the proxy
git clone http://localhost:8080/runwayml/stable-diffusion-v1.5

Once the service is running, the proxy is available at http://<host>:8080. Point your tooling to this base URL to route traffic through HFBridge:

• huggingface-hub / transformers (Python)
  Configure the endpoint before using huggingface-cli or loading models:

  export HF_ENDPOINT=http://localhost:8080
  export HF_TOKEN=hf_your_token_if_needed
  huggingface-cli whoami

  Your existing scripts that rely on huggingface_hub or transformers will now download models and datasets via the proxy.

• Git clients
  To transparently clone any repository through HFBridge, set a Git rewrite rule once:

  git config --global url."http://localhost:8080/".insteadOf "https://huggingface.co/"

  Afterwards, any command that targets https://huggingface.co/... will automatically use the proxy (including Git LFS).

• Direct HTTP calls
  Replace https://huggingface.co with http://localhost:8080 in automation scripts. For example:

  curl http://localhost:8080/api/models/gpt2

# Health check
curl http://localhost:8080/v1/healthz

# Current usage metrics (JSON)
curl http://localhost:8080/v1/usage

# Live usage stream (SSE)
curl http://localhost:8080/v1/usage/stream

All settings are available via environment variables.

HFBridge is delivered as a single binary that embeds both the backend proxy and the web UI.

• Frontend: Next.js dashboard compiled to static assets and embedded into the Go binary.
• Backend: Go reverse proxy server serving API endpoints and static files.
• Database: SQLite file containing request logs and aggregated usage data.

Routing overview:

• / serves the dashboard.
• /_next/*, /icons/*, /favicon.ico serve static assets.
• /v1/usage, /v1/usage/stream, /v1/healthz expose API endpoints.
• Any other path (e.g. /google/bert) is proxied to the configured upstream.

hfbridge/
├── frontend/          # Next.js UI
│   ├── app/           # App Router pages
│   ├── components/    # React components
│   └── out/           # Static build output
├── backend/           # Go backend
│   ├── cmd/hfbridge/  # Main entry point
│   └── internal/      # Internal packages
│       └── server/    # HTTP server and embedded assets
├── Dockerfile         # Multi-stage build
└── docker-compose.yml

# Frontend development (hot reload)
cd frontend
pnpm install
pnpm dev

# Backend development (requires a built frontend once)
cd backend
go run ./cmd/hfbridge/

To ship a self-contained binary:

1. Build the frontend (pnpm build) and copy the assets into backend/internal/server/static.
2. Compile the backend with go build -o hfbridge ./cmd/hfbridge/.
3. Run ./hfbridge and visit http://localhost:8080.

GNU GPLv3 (see LICENSE)