HFDesk

A focused local dashboard for finding, analyzing, and downloading Hugging Face models.

HFDesk runs as a small local web server and gives you a desktop-style browser UI for the full model workflow: search the Hub, inspect GGUF quantizations, pick files, download with resume support, browse local cache, and mirror model storage to another drive.

Screenshots

Models	Active Jobs

Local Cache	Mirror

Settings

Highlights

• Search models and datasets directly from the Hugging Face Hub.
• Analyze repositories before downloading, including GGUF quantizations, file groups, RAM estimates, and recommended picks.
• Correctly groups sharded GGUF files into one quantization option.
• Parallel resumable downloads with retries, progress events, and active job tracking.
• Standard Hugging Face cache layout or LM Studio-style local files under <folder>/<owner>/<model>.
• Optionally route downloads into per-type folders (LLM/GGUF, LLM/Safetensors, Audio, Diffusion, Embedding).
• Local cache browser for HF cache, friendly folders, and user-added LM Studio-style model directories.
• Mirror cache contents to a NAS, USB drive, or another machine.
• Download history, disk-free indicator, proxy support, and optional basic auth.
• Single static binary with embedded web assets.

Install

Download a prebuilt binary from Releases, or install from source:

go install github.com/bashrusakh/hfdesk/cmd/hfdesk@latest

Docker:

docker run --rm -p 8080:8080 \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  ghcr.io/bashrusakh/hfdesk:latest

Quick Start

hfdesk

HFDesk opens http://localhost:8080 automatically.

Useful options:

hfdesk --no-open
hfdesk --port 9090
hfdesk --token hf_xxx
hfdesk --cache-dir /mnt/ssd/huggingface
hfdesk --local-dir /mnt/models

Configuration

HFDesk reads hfdesk.json, hfdesk.yaml, or hfdesk.yml from the launch directory first, then from ~/.config. Settings saved from the UI are written back to the launch directory.

Ordinary settings updates preserve both the active Hugging Face token and any separately stored token. A runtime override such as --token is not copied to disk implicitly. In POST /api/settings, an explicitly authored nonempty token sets the active and stored credential; "token": "" clears both. Omitting token, sending null, or returning a redacted display value preserves it. Values beginning with ******** are reserved redaction markers, not credentials. Startup overrides still take precedence after a restart.

Saved configuration contains explicitly stored credentials in plaintext. New and existing files saved by HFDesk have owner-only permissions (0600) on Unix. A persistence warning means settings took effect in memory but were not saved; repair the file/path permissions or invalid configuration and save again before restarting.

{
  "token": "hf_xxx",
  "cache-dir": "/mnt/ssd/huggingface",
  "connections": 8,
  "max-active": 3,
  "multipart-threshold": "32MiB",
  "verify": "size",
  "retries": 4,
  "endpoint": "https://huggingface.co"
}

The Hugging Face token is resolved as the --token flag, then the HF_TOKEN environment variable, then the token field in the config file. Set it at startup with:

HF_TOKEN=hf_xxx hfdesk

Proxy example:

{
  "proxy": {
    "url": "socks5://proxy.internal:1080",
    "username": "user",
    "password": "pass",
    "no_proxy": "localhost,127.0.0.1"
  }
}

API

HFDesk's web UI is backed by a local JSON API. See docs/API.md for endpoints, request shapes, and response formats.

Build

git clone https://github.com/bashrusakh/hfdesk
cd hfdesk
go build -o hfdesk ./cmd/hfdesk
./hfdesk

Run tests:

go test ./...
go test ./... -race

Credits

HFDesk is a fork of bodaay/HuggingFaceModelDownloader. Original copyright and license notices are retained. Licensed under the Apache License 2.0.