HF Spaces

HfSpacesResource mounts a Hugging Face Space repo (app code, README, config, requirements) at a prefix such as /s/. The TypeScript backend mirrors the Python one and returns identical results. For credential setup, see HF Spaces 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 { HfSpacesResource, MountMode, Workspace } from '@struktoai/mirage-node'

const space = new HfSpacesResource({
  repoId: 'HuggingFaceBio/carbon-demo', // "namespace/space-name"
  token: process.env.HF_TOKEN, // optional for public spaces
  // Optional:
  // endpoint: 'https://huggingface.co',
  // revision: 'main',
})

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

console.log((await ws.execute('ls /s/')).stdoutText)
console.log((await ws.execute("find /s/ -name '*.py'")).stdoutText)
console.log((await ws.execute('cat /s/README.md | head -n 15')).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.

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

Shell Commands

​Node

​Reading, not writing

​Shell Commands

Node

Reading, not writing

Shell Commands