> ## 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.

# Disk

> Virtualize a local directory from Node.

`DiskVFS` mounts a directory on the host: every file and folder under `root`
appears under the mount, and reads and writes go to the real files. It needs
no credentials; see the [Disk page](https://docs.mirage.strukto.ai/home/setup/disk.md).

> [!NOTE]
>
> Node only. A browser has no host filesystem; use
> [OPFS](https://docs.mirage.strukto.ai/typescript/vfs/opfs.md) instead.

## Install

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

## Configure

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

const disk = new DiskVFS({ root: '/srv/files' })
const ws = new Workspace({ '/data': disk }, { mode: MountMode.WRITE })

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

`capacity: '1GB'` caps the bytes the root may hold; see
[capacity](https://docs.mirage.strukto.ai/home/setup/vfs.md#mount-capacity). A mount takes `MountMode.READ`,
`WRITE` or `EXEC`; use `EXEC` when `python3` or `js` should run scripts from
the mount.

### Fields

| Field | Default | Notes |
| - | - | - |
| `root` | required | Path on the host. Reads and writes are scoped to this directory. |
| `folderVersions` | `true` | Store each listing at its folder's version, so a `read: fresh` mount re-lists only folders that changed. Must be a boolean. In YAML: `folder_versions`. |
| `capacity` | none | The most bytes the root may hold, a size like `100MB` or a count of bytes. |

## Layout

```text theme={null}
/data/
  notes.txt
  config.json
  reports/
    q1.csv
    q2.csv
```

The mount mirrors `root`: with `root: '/srv/files'`, `/data/reports/q1.csv` is
the file `/srv/files/reports/q1.csv`.

## Behavior

* **Root boundary:** a path such as `../../etc/passwd` is rejected; every path
  resolves inside `root`.
* **One mount per folder:** a second disk mount whose `root` resolves to a
  folder already mounted is refused; a folder inside one is fine.
* **Folder versions:** a version is the folder's device, inode, change and
  modified time. Set `folderVersions: false` for a network or FUSE root (NFS,
  SMB, rclone, s3fs, Mirage's own FUSE), whose change time may not move with
  its entries. A folder changed in the last 2 seconds gets no version and is
  re-listed until it has been quiet that long.
* **Snapshots:** a snapshot carries the mount's files, and loading it restores
  them.

## VFS.md

The [VFS.md](https://docs.mirage.strukto.ai/home/setup/vfs-md.md) an agent reads with Disk mounted at `/<path>`.
`<mode>` is the mount's mode: `read`, `write` or `exec`. The commands shown are
those of a `write` mount.

> [tab] Rendered
>
> **Virtual Filesystem**
>
> | Path | Description |
> | - | - |
> | `/<path>` | `<mode>` |
>
> **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>` | Almost all Unix commands. |
>
> **Limitations of Unix Commands for VFS**
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | - | - |
> | `/<path>` | `grep -r`, `find` and `du` stop after 10000 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>` | `<mode>` |
>
> ## 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>` | Almost all Unix commands. |
>
> ## Limitations of Unix Commands for VFS
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | --- | --- |
> | `/<path>` | `grep -r`, `find` and `du` stop after 10000 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.