HF Models

The HF Models VFS mounts a Hugging Face Model repo at some prefix such as /m/. You can inspect configs, tokenizers, and READMEs without downloading the weights, weights stream only when you actually cat them. For credential setup, see HF Models Setup.

Install

# No extra needed: the Hub API is reached over aiohttp, a core dependency.
uv add mirage-ai

Config

import os

from mirage import MountMode, Workspace
from mirage.vfs.hf_models import HfModelsConfig, HfModelsVFS

config = HfModelsConfig(
    repo_id=os.environ["HF_MODEL_REPO"],   # "namespace/model-name"
    token=os.environ.get("HF_TOKEN"),
    # Optional:
    # endpoint="https://huggingface.co",
    # revision="main",
)
vfs = HfModelsVFS(config)
ws = Workspace({"/m": vfs}, mode=MountMode.READ)

Reading, not writing

This mount is read-only, the way a github mount is. A Hub write is a commit, and a POSIX write cannot say where a commit ends, so echo >, rm, cp and mv are refused here rather than silently making one commit per file. The hf CLI is the write half: hf download --local-dir puts a copy on a ram or disk mount, which is an ordinary writable filesystem, and hf upload sends it back as a single commit.

Listings under `fresh`

Under read: fresh, a cached listing is checked against the commit the revision resolves to: one small check per command (revision/{rev}?expand[]=sha), after which every cached listing of the mount at that commit is served. A mount whose revision is a full 40- or 64-hex commit sha is checked the same way, with that one small request per command: a branch or tag named like the sha could take the name, and mirage does not assume which one the Hub resolves. With a key_prefix, the stored version is that commit joined with the prefix, so mounts of different subtrees sharing an index never share a version. See listings under fresh.

Filesystem Layout

Maps model repo files (config, tokenizer, weights, etc.) to virtual paths. For example, sapientinc/HRM-Text-1B mounted at /m/ exposes:

/m/
  README.md
  config.json
  tokenizer.json
  tokenizer_config.json
  model.safetensors        ← never downloaded unless you cat it

Example

import asyncio

from mirage import MountMode, Workspace
from mirage.vfs.hf_models import HfModelsConfig, HfModelsVFS

config = HfModelsConfig(repo_id="sapientinc/HRM-Text-1B")
vfs = HfModelsVFS(config)


async def main() -> None:
    ws = Workspace({"/m": vfs}, mode=MountMode.READ)

    # ls is cheap: one HTTP list call
    r = await ws.shell("ls -lh /m/")
    print(await r.stdout_str())

    # Read the config (small, fast)
    r = await ws.shell("cat /m/config.json")
    print(await r.stdout_str())

    # Stat the weights without downloading them
    r = await ws.shell("stat /m/model.safetensors")
    print(await r.stdout_str())


if __name__ == "__main__":
    asyncio.run(main())

Shell Commands

Every read command in HF Buckets’ set works here, as do the text processing and path utilities, which only read. What does not is the File Operations group: this mount is read-only, so rm and touch are refused, as is any command asked to write into it.

Use Cases

Model card inspection: Read configs, tokenizers, READMEs without pulling multi-GB weight files
Compatibility checks: jq over config.json to verify architecture before committing to a download
Pinned revisions: Mount a specific commit/tag for reproducibility

Getting Started

Access

AI Agents

VFS

CLIs

Watch

Runtimes

Install

Config

Reading, not writing

Listings under `fresh`

Filesystem Layout

Example

Shell Commands

Use Cases

​Install

​Config

​Reading, not writing

​Listings under fresh

​Filesystem Layout

​Example

​Shell Commands

​Use Cases

Install

Config

Reading, not writing

Listings under `fresh`

Filesystem Layout

Example

Shell Commands

Use Cases