Disk - Mirage

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.
`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. See the cache.

Mount mode

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

Snapshot behavior

DiskVFS.toState() captures the file tree as bytes. Loading a snapshot back doesn’t re-create the directory; pass a config file with a fresh root if the original location changed. For behavior shared with Python (filesystem layout, supported shell commands), see the Python Disk docs.