HF Models

HfModelsResource mounts a Hugging Face Model repo at a prefix such as /m/. You can inspect configs, tokenizers, and READMEs without downloading the weights, weights stream only when you actually cat them. The TypeScript backend mirrors the Python one and returns identical results. For credential setup, see HF Models Setup.

Node only: the resource ships in @struktoai/mirage-node. It needs no native binding, though, because it speaks the Hub API over the runtime’s own fetch. The opendal binding belongs to HF Buckets, which is a different product.

Node

pnpm add @struktoai/mirage-node

import { HfModelsResource, MountMode, Workspace } from '@struktoai/mirage-node'

const model = new HfModelsResource({
  repoId: 'sapientinc/HRM-Text-1B', // "namespace/model-name"
  token: process.env.HF_TOKEN, // optional for public repos
  // Optional:
  // endpoint: 'https://huggingface.co',
  // revision: 'main',
})

const ws = new Workspace({ '/m/': model }, { mode: MountMode.READ })

// ls is cheap: one HTTP list call
console.log((await ws.execute('ls -lh /m/')).stdoutText)

// Read the config (small, fast)
console.log((await ws.execute('cat /m/config.json')).stdoutText)

// Stat the weights without downloading them
console.log((await ws.execute('stat /m/model.safetensors')).stdoutText)

Reading, not writing

This mount is read-only, the way a 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 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:

/m/
  README.md
  config.json
  tokenizer.json
  tokenizer_config.json
  model.safetensors        ← never downloaded unless you cat it

Shell Commands

Every read command in HF Buckets’ set works here, as do the text processing and path utilities, which only read. What does not is the File Operations group: this mount is read-only, so rm and touch are refused, as is any command asked to write into it.

Getting Started

AI Agents

Resources

CLIs

Watch

Runtimes

Node

Reading, not writing

Filesystem Layout

Shell Commands

​Node

​Reading, not writing

​Filesystem Layout

​Shell Commands

Node

Reading, not writing

Filesystem Layout

Shell Commands