> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# HF Spaces

> Virtualize a Hugging Face Space repository from Node.

`HfSpacesVFS` mounts one [Hugging Face Space](https://huggingface.co/spaces)
repository as read-only files: its app code, README, config and requirements.
Set up a token for a private Space as in [HF Spaces setup](https://docs.mirage.strukto.ai/home/setup/hf_spaces.md).

## Install

```bash theme={null}
npm install @struktoai/mirage-node
```

## Configure

```ts theme={null}
import { HfSpacesVFS, MountMode, Workspace } from '@struktoai/mirage-node'

const space = new HfSpacesVFS({
  repoId: process.env.HF_SPACE_REPO!,
  token: process.env.HF_TOKEN,
})
const ws = new Workspace({ '/space': space }, { mode: MountMode.READ })

const result = await ws.shell("ls /space && find /space -name '*.py'")
console.log(result.stdoutText)
await ws.close()
```

`revision` picks a branch, tag or commit (`main` when unset), `keyPrefix`
mounts one folder of the repository, and `endpoint` points at a mirror or a
self-hosted Hub. The class ships in `@struktoai/mirage-node` only.

### Fields

**repoId** `string` *required*

Repository id as `namespace/name`, or a bare `name` that resolves against the token's owner.

**token** `string`

Hugging Face access token; unset sends anonymous requests, which reach public repositories only.

**endpoint** `string` (default: '[https://huggingface.co](https://huggingface.co)')

Hub origin requests go to, for a mirror or a self-hosted Hub.

**timeout** `number` (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** `string`

Path inside the repository that becomes the mount root; files outside it are not listed.

**revision** `string`

Branch, tag or commit the mount reads; unset reads `main`.

**expandCommits** `boolean`

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.

## Authentication

A public Space needs no token: unset `token` sends anonymous requests, which
reach public repositories only. A private Space needs a **Read** token, or a
**Fine-grained** one with read access to that Space's repository.

## Layout

```text theme={null}
/space/
  Dockerfile
  README.md
  app.py
  requirements.txt
  scripts/
    precompute.py
```

`repoId` is `namespace/space-name`, set at mount time, and the tree mirrors
the repository at `revision`: `/space/app.py` is `app.py`.

## Behavior

* **Read only:** a Hub write is a commit, and a POSIX write cannot say where a
  commit ends, so `echo >`, `rm`, `cp` and `mv` are refused rather than making
  one commit per file. The [`hf` CLI](https://docs.mirage.strukto.ai/typescript/cli/hf) is the write half:
  `hf download --local-dir` puts a copy on a RAM or disk mount, and
  `hf upload` sends it back as one commit.
* **Fresh reads:** under `read: fresh`, each command checks the commit
  `revision` resolves to with one small request, also when `revision` is a
  full commit SHA, since a branch or tag could carry the same name.

## Integration

The Hub answers this command through its own API, so fewer files are read.
See [Integration](https://docs.mirage.strukto.ai/home/integration/overview.md).

* `sha256sum`: the LFS sha256 the Hub keeps; other files are read.

## VFS.md

The [VFS.md](https://docs.mirage.strukto.ai/home/setup/vfs-md.md) an agent reads with HF Spaces mounted at `/<path>`.

> [tab] Rendered
>
> **Virtual Filesystem**
>
> | Path | Description |
> | - | - |
> | `/<path>` | 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.

> [tab] Raw
>
> ```markdown theme={null}
> ---
> name: workspace-filesystem
> description: The virtual filesystem layout of this workspace.
> ---
>
> # Virtual Filesystem
>
> | Path | Description |
> | --- | --- |
> | `/<path>` | 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.
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.