Skip to main content
A Hugging Face model repo becomes a read-only folder of its files. Configs, tokenizers and cards read at once; weights stream only when a command reads them.

Setup

Public models need no token. A gated or private model needs a Hugging Face access token:
  1. For a gated model, open its page on the Hub, accept the conditions and wait for access to be granted.
  2. At huggingface.co/settings/tokens, click New token and create a read token, or a fine-grained token with read access to that model.
  3. Add token: ${HF_TOKEN} to the YAML config.

Connect

workspace.yaml

Layout

  • Files keep their repo paths. repo_id is namespace/name, or a bare name under the token’s owner.
  • revision pins a branch, tag or commit (default main); key_prefix mounts one folder of the repo.
  • ls and stat never download a file; sha256sum on an LFS file answers with the hash the Hub keeps.

Sample runs

The mount is read-only: a Hub write is a commit, so echo >, rm, cp and mv are refused. The hf CLI downloads a copy and uploads changes back as one commit.

SDK guides

Python

Every config field, the VFS.md and write support.

TypeScript

Every config field, the VFS.md and write support.