miniface

Local-first model registry

Your models,
close at hand.

A writable, Hugging Face-compatible registry for the models and adapters you train and keep. Import, inspect, version, and reuse them with the tools already in your workflow.

Install Miniface See it in action

One self-contained binary · Linux & macOS

terminal 
$ curl -fsSL https://miniface.co/install.sh | sh
Installed Miniface to ~/.local/bin/miniface
$ miniface
Registry listening at http://127.0.0.1:8080
Miniface model library showing locally stored model repositories, architectures, revisions, and sizes

Your private model workshop. Everything you need to find, inspect, and use a model. Nothing you don’t.

Runs on your machine

Use the tools already in your workflow

  • HF CLI
  • huggingface_hub
  • Transformers
  • PEFT
  • Unsloth

Where Miniface fits

Train and run elsewhere.
Keep models here.

Unsloth and PEFT fine-tune models. Ollama and vLLM run them. Unlike a download cache, Miniface is a writable local registry for versioned model repositories, adapters, and provenance.

Small on purpose

A model registry for the local loop.

Miniface keeps the useful slice of a model hub close: repositories, immutable revisions, storage, and client compatibility.

01

Local by default

One binary serves the registry, API, Xet storage, and web UI. It binds to loopback and keeps your workshop private.

02

Every revision pinned

Imports and uploads become immutable snapshots. Copy an exact revision into CLI, Transformers, PEFT, or Unsloth.

03

Xet under the hood

Large model files use chunked, deduplicated storage. Shared weights take less physical space without changing logical files.

The whole loop

From Hub to fine-tune
to your registry.

Keep training where it belongs. Miniface gives the artifacts around it a dependable home.

  1. 01

    Bring it in

    Import a local folder or mirror a pinned model directly from Hugging Face.

  2. 02

    Train your way

    Fine-tune with Unsloth, TRL, PEFT, or the training code you already use.

  3. 03

    Publish locally

    Upload adapters or merged weights with the familiar Hugging Face client API.

  4. 04

    Reload exactly

    Pin both adapter and base-model revisions for a reproducible local workflow.

Import

Start from here
or Hugging Face.

Point Miniface at a local directory, or search and mirror a public, private, or gated repository at an immutable source revision.

  • ✓ Streams directly into managed storage
  • ✓ Keeps private access tokens in memory only
  • ✓ Tracks every import in Activity
Miniface import form with local folder and Hugging Face source options

Inspect & use

Know what you have.
Use exactly that.

See architecture, quantization, files, provenance, and revision history. Then copy a pinned snippet for the tool you need.

  • ✓ Browse files without unpacking snapshots
  • ✓ Pin adapter and base revisions independently
  • ✓ Copy ready-to-run client examples
Miniface model overview with architecture, immutable revision, and model details

Familiar clients

Change the endpoint.
Keep the workflow.

Miniface implements the model APIs your existing tools expect. Set two environment variables, then work with local repositories by ID and revision.

DownloadsUploadsRange readsNative XetLFS fallback
ShellPython 
# Point Hugging Face clients at Miniface
export HF_ENDPOINT=http://127.0.0.1:8080
export HF_TOKEN=mf_pat_your_token

# Download one immutable snapshot
hf download local/ember-3b \
  --revision 4e7c2b9d…

Focused by design

Built for a private workshop.

Miniface is a single-administrator registry designed to run locally. It does not try to be a hosted social hub, training scheduler, or Internet-facing multi-user service.

Profile
Local filesystem + SQLite
Access
Loopback by default
Today
Linux & macOS

Ready when you are

Give your models
a place at home.

Install the binary, run miniface, and open your private registry.

$ curl -fsSL https://miniface.co/install.sh | sh

Downloads a checksum-verified release from GitHub. Review the install script first if you prefer.

Copied to clipboard