Skip to main content
HfSpacesVFS mounts one Hugging Face Space repository as read-only files: its app code, README, config and requirements. Set up a token for a private Space as in HF Spaces setup.

Install

Configure

revision picks a branch, tag or commit (main when unset), keyPrefix mounts one folder of the repository, and endpoint points at a mirror or a self-hosted Hub. The class ships in @struktoai/mirage-node only.

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 Space needs no token: unset token sends anonymous requests, which reach public repositories only. A private Space needs a Read token, or a Fine-grained one with read access to that Space’s repository.

Layout

repoId is namespace/space-name, set at mount time, and the tree mirrors the repository at revision: /space/app.py is app.py.

Behavior

  • Read only: a Hub write is a commit, and a POSIX 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 RAM or disk mount, and hf upload sends it back as one commit.
  • Fresh reads: under read: fresh, each command checks the commit revision resolves to with one small request, also when revision is a full commit SHA, since a branch or tag could 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 Spaces 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.