Disk

DiskVFS mounts a directory on the host filesystem. Reads and writes go through node:fs against the configured root.

Node only. The browser SDK has no kernel filesystem; use OPFS instead.

Install

pnpm add @struktoai/mirage-node

Config

import { DiskVFS, MountMode, Workspace } from '@struktoai/mirage-node'

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

await ws.shell('echo hello | tee /disk/note.txt')
await ws.shell('cat /disk/note.txt')

Field	Default	Notes
`root`	required	Absolute path on the host. Reads and writes are scoped to this directory. A second disk mount whose root resolves to a folder already mounted is refused; a folder inside one is fine.
`folderVersions`	`true`	Store each listing at its folder’s version (device, inode, change and modified time), so a `read: fresh` mount re-lists only folders that changed. Must be a boolean. Set `false` for a network or FUSE root (NFS, SMB, rclone, s3fs, mirage’s own FUSE), whose change time may not move with its entries. In YAML: `folder_versions`.

A folder changed in the last 2 seconds gets no version and is re-listed until it has been quiet that long.

Mount mode

read, write, exec. Use MountMode.EXEC if python3 or js should run scripts from the mount.

Snapshot behavior

A snapshot carries the mount’s files, and loading it restores them. For behavior shared with Python (filesystem layout, supported shell commands), see the Python Disk docs.

VFS.md

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

Rendered
Raw

Virtual Filesystem

Path	Description
`/<path>`	`disk`, write

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.

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

# Virtual Filesystem

| Path | Description |
| --- | --- |
| `/<path>` | `disk`, write |

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

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Install

Config

Mount mode

Snapshot behavior

VFS.md

Virtual Filesystem

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

​Install

​Config

​Mount mode

​Snapshot behavior

​VFS.md

​Virtual Filesystem

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

Install

Config

Mount mode

Snapshot behavior

VFS.md

Virtual Filesystem

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS