> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# HF Models

> Mount a Hugging Face model repository as a filesystem and inspect weights, configs, and cards with shell commands.

The HF Models VFS mounts a [Hugging Face Model](https://huggingface.co/models)
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](/home/setup/hf_models).

## Install

```bash theme={null}
# No extra needed: the Hub API is reached over aiohttp, a core dependency.
uv add mirage-ai
```

## Config

```python theme={null}
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`](/python/vfs/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](/python/cli/hf) 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.

## Filesystem Layout

Maps model repo files (config, tokenizer, weights, etc.) to virtual paths.

For example, `sapientinc/HRM-Text-1B` mounted at `/m/` exposes:

```text theme={null}
/m/
  README.md
  config.json
  tokenizer.json
  tokenizer_config.json
  model.safetensors        ← never downloaded unless you cat it
```

## Example

```python theme={null}
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.execute("ls -lh /m/")
    print(await r.stdout_str())

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

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


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

## Shell Commands

Every read command in [HF Buckets'](/python/vfs/hf_buckets#read-commands) set works here, as
do the text processing and path utilities, which only read. What does not is
the [File Operations](/python/vfs/hf_buckets#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