HF Spaces

The HF Spaces VFS mounts a Hugging Face Space repo (app code, README, config, requirements) at some prefix such as /s/. For credential setup, see HF Spaces Setup.

Install

# No extra needed: the Hub API is reached over aiohttp, a core dependency.
uv add mirage-ai

Config

import os

from mirage import MountMode, Workspace
from mirage.vfs.hf_spaces import HfSpacesConfig, HfSpacesVFS

config = HfSpacesConfig(
    repo_id=os.environ["HF_SPACE_REPO"],   # "namespace/space-name"
    token=os.environ.get("HF_TOKEN"),
    # Optional:
    # endpoint="https://huggingface.co",
    # revision="main",
)
vfs = HfSpacesVFS(config)
ws = Workspace({"/s": vfs}, mode=MountMode.READ)

Field	Description
`timeout` default `30`	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.
`repo_id` 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.
`key_prefix`	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`.
`expand_commits`	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 key_prefix, 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.

For example, HuggingFaceBio/carbon-demo mounted at /s/ might expose:

/s/
  README.md
  app.py
  requirements.txt
  Dockerfile

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

Example

import asyncio

from mirage import MountMode, Workspace
from mirage.vfs.hf_spaces import HfSpacesConfig, HfSpacesVFS


async def main() -> None:
    vfs = HfSpacesVFS(
        HfSpacesConfig(repo_id="HuggingFaceBio/carbon-demo"))
    ws = Workspace({"/s": vfs}, mode=MountMode.READ)

    r = await ws.shell("ls /s/")
    print(await r.stdout_str())

    r = await ws.shell("cat /s/README.md | head -n 20")
    print(await r.stdout_str())

    r = await ws.shell("grep -l import /s/*.py 2>/dev/null")
    print(await r.stdout_str())


if __name__ == "__main__":
    asyncio.run(main())

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.

Use Cases

Space introspection: Browse an app’s structure, requirements, and config before forking/cloning
App code review: grep / find across a Space’s Python without cloning the repo

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Install

Config

Reading, not writing

Listings under `fresh`

VFS.md

Virtual Filesystem

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Integration

Example

Shell Commands

Use Cases

​Install

​Config

​Reading, not writing

​Listings under fresh

​VFS.md

​Virtual Filesystem

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Integration

​Example

​Shell Commands

​Use Cases

Install

Config

Reading, not writing

Listings under `fresh`

VFS.md

Virtual Filesystem

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Integration

Example

Shell Commands

Use Cases