Skip to main content
HfModelsVFS mounts one Hugging Face model repository, read-only: every file in the repo becomes a file, read lazily, so configs, tokenizers and the model card open without downloading the weights. Set up the tokens for gated and private models as in HF Models setup.

Install

Configure

revision pins a branch, tag or commit (default main), and keyPrefix mounts one folder of the repo. endpoint points at a mirror or a self-hosted Hub.

Fields

string
required
Repository id as namespace/name, or a bare name that resolves against the token’s owner.
string
secret
Hugging Face access token; unset sends anonymous requests, which reach public repositories only.
string
default:"'https://huggingface.co'"
Hub origin requests go to, for a mirror or a self-hosted Hub.
number
default:"DEFAULT_TIMEOUT"
Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.
string
Path inside the repository that becomes the mount root; files outside it are not listed.
string
Branch, tag or commit the mount reads; unset reads main.
boolean
Fetch each file’s last commit so listings carry modification times, at 50 entries per request instead of 1000. Unset does so only when the whole repository fits in one page.
Fields marked secret are redacted in snapshots.

Authentication

A public model needs no token. A gated or private one needs token: a read token, or a fine-grained token with read access to that model; a gated model also needs its conditions accepted on the Hub. A repository or revision the token cannot see, or that does not exist, answers Permission denied.

Layout

Files keep their repo paths: /model/config.json is config.json in the repo. repoId is namespace/name, or a bare name under the token’s owner.

Behavior

  • Read-only: a Hub write is a commit, and a file write cannot say where a commit ends, so echo >, rm, cp and mv are refused rather than making one commit per file. The hf CLI is the write half: hf download --local-dir puts a copy on a writable mount, and hf upload sends it back as one commit.
  • Lazy reads: ls and stat never download a file, so the weights’ size shows without fetching them; they stream only when a command reads them.
  • Fresh reads: under read: fresh, each command checks once which commit revision points at, even when revision is a full commit sha, since a branch or tag can carry the same name.

Integration

The Hub answers this command through its own API, so fewer files are read. See Integration.
  • sha256sum: the LFS sha256 the Hub keeps; other files are read.

VFS.md

The VFS.md an agent reads with HF Models mounted at /<path>.
Virtual FilesystemSupported Unix Commands for VFSUnix commands work on each path as on a local filesystem, as far as the path supports them:Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:Run man <cmd> or <cmd> --help for one command’s usage.