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
Repository id as
namespace/name, or a bare name that resolves against the token’s owner.Hugging Face access token; unset sends anonymous requests, which reach public repositories only.
Hub origin requests go to, for a mirror or a self-hosted Hub.
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.
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.
Authentication
A public Space needs no token: unsettoken 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,cpandmvare refused rather than making one commit per file. ThehfCLI is the write half:hf download --local-dirputs a copy on a RAM or disk mount, andhf uploadsends it back as one commit. - Fresh reads: under
read: fresh, each command checks the commitrevisionresolves to with one small request, also whenrevisionis 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>.
- Rendered
- Raw
Virtual Filesystem
Supported 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.