HF Spaces

HfSpacesVFS 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 VFS 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 { HfSpacesVFS, MountMode, Workspace } from '@struktoai/mirage-node'

const space = new HfSpacesVFS({
  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.shell('ls /s/')).stdoutText)
console.log((await ws.shell("find /s/ -name '*.py'")).stdoutText)
console.log((await ws.shell('cat /s/README.md | head -n 15')).stdoutText)

Config

Field	Description
`repoId` required	Repository id as `namespace/name`, or a bare `name` that resolves against the token’s owner.
`token` secret	Hugging Face access token; unset sends anonymous requests, which reach public repositories only.
`endpoint` default `'https://huggingface.co'`	Hub origin requests go to, for a mirror or a self-hosted Hub.
`timeout` 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.
`keyPrefix`	Path inside the repository that becomes the mount root; files outside it are not listed.
`revision`	Branch, tag or commit the mount reads; unset reads `main`.
`expandCommits`	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.

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.

Listings under `fresh`

Under read: fresh, a cached listing is checked against the commit the revision resolves to: one small check per command (revision/{rev}?expand[]=sha), after which every cached listing of the mount at that commit is served. A mount whose revision is a full 40- or 64-hex commit sha is checked the same way, with that one small request per command: a branch or tag named like the sha could take the name, and mirage does not assume which one the Hub resolves. With a keyPrefix, the stored version is that commit joined with the prefix, so mounts of different subtrees sharing an index never share a version.

VFS.md

The VFS.md an agent reads with HF Spaces mounted at /<path>.

Rendered
Raw

Virtual Filesystem

Path	Description
`/<path>`	`hf_spaces`, read

Supported Unix Commands for VFS

Unix commands work on each path as on a local filesystem, as far as the path supports them:

Path	Supported
`/<path>`	Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest).

Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

Path	Limitations
`/<path>`	Read only: no command changes files. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused.

Run man <cmd> or <cmd> --help for one command’s usage.

---
name: workspace-filesystem
description: The virtual filesystem layout of this workspace.
---

# Virtual Filesystem

| Path | Description |
| --- | --- |
| `/<path>` | `hf_spaces`, read |

## Supported Unix Commands for VFS

Unix commands work on each path as on a local filesystem, as far as the path supports them:

| Path | Supported |
| --- | --- |
| `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). |

## Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

| Path | Limitations |
| --- | --- |
| `/<path>` | Read only: no command changes files. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |

Run `man <cmd>` or `<cmd> --help` for one command's usage.

Integration

What Hugging Face Spaces answers through its own API, so fewer files are read. Integration explains each command.

Command	On Hugging Face Spaces
`sha256sum`	The LFS sha256 the Hub keeps; other files are read

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

Access

AI Agents

VFS

CLIs

Runtimes

Node

Config

Reading, not writing

Listings under `fresh`

VFS.md

Virtual Filesystem

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Integration

Shell Commands

​Node

​Config

​Reading, not writing

​Listings under fresh

​VFS.md

​Virtual Filesystem

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Integration

​Shell Commands

Node

Config

Reading, not writing

Listings under `fresh`

VFS.md

Virtual Filesystem

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Integration

Shell Commands