Disk

The Disk VFS mounts a local directory at some prefix such as /data/. All operations are backed by real files on disk. Path resolution validates against the root boundary to prevent directory traversal escapes.

Config

from mirage import MountMode, Workspace
from mirage.vfs.disk import DiskVFS

vfs = DiskVFS(root="/path/to/dir")
ws = Workspace({"/data": vfs}, mode=MountMode.READ)

DiskVFS(root=..., folder_versions=True) takes the root path of the directory to mount. Both READ and WRITE modes are supported.

Field	Default	Notes
`root`	required	The host directory the mount mirrors. A second disk mount whose root resolves to a folder already mounted is refused; a folder inside one is fine.
`folder_versions`	`True`	Store each listing at its folder’s version, so a `read: fresh` mount re-lists only folders that changed. Must be a boolean. Turn it off for a network or FUSE root.

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.

The Disk VFS mirrors the structure of the root directory. For example, if root="/srv/files" contains:

/srv/files/
  notes.txt
  config.json
  reports/
    q1.csv
    q2.csv

Then mounting at /data/ exposes:

/data/
  notes.txt
  config.json
  reports/
    q1.csv
    q2.csv

Paths like ../../etc/passwd are rejected - resolution is always confined to the root boundary.

Cache

The Disk VFS uses IndexCacheStore with index_ttl = 60 (1 minute). Directory listings are cached for up to 60 seconds before being refreshed from disk. A configured index: replaces this lifetime with its own ttl, and the mount’s ttl: caps it. Each listing is stored with its folder’s version: the folder’s device, inode, change time and modified time. Under read: fresh, a later command stats the folder and serves the cached listing while the version still matches, so it pays one local stat per listed folder instead of a scan. A folder changed in the last 2 seconds gets no version and is re-listed until it has been quiet that long, since two changes inside one timestamp tick could leave its times unmoved. This assumes a local POSIX filesystem, where adding, renaming or removing an entry moves the folder’s change time. A network or FUSE root (NFS, SMB, rclone, s3fs, mirage’s own FUSE) may not, so turn the versions off there:

vfs = DiskVFS(root="/mnt/nfs/share", folder_versions=False)

That mount then re-lists a cached folder once per command, as every unversioned backend does.

Example

import asyncio
import shutil
import tempfile
from pathlib import Path

from mirage import MountMode, Workspace
from mirage.vfs.disk import DiskVFS

DATA_DIR = Path("/path/to/files")

tmp = tempfile.mkdtemp()
shutil.copytree(DATA_DIR, Path(tmp) / "files", dirs_exist_ok=True)

vfs = DiskVFS(root=tmp + "/files")


async def main() -> None:
    ws = Workspace({"/data/": vfs}, mode=MountMode.READ)

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

    r = await ws.shell("cat /data/example.json")
    print(await r.stdout_str())

    r = await ws.shell("tree /data/")
    print(await r.stdout_str())

    r = await ws.shell("find /data/ -name '*.json'")
    print(await r.stdout_str())

    r = await ws.shell("grep example /data/example.json")
    print(await r.stdout_str())

    r = await ws.shell("stat /data/example.json")
    print(await r.stdout_str())


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

Shell Commands

The Disk VFS supports the full set of shell commands since it operates on real file content (text, binary, JSON, CSV, etc.):

Read Commands

Command	Notes
`cat`	Read file content
`head` / `tail`	First/last N lines
`grep` / `rg`	Pattern search (file or directory level)
`jq`	Query JSON fields
`wc`	Line/word/byte counts
`stat`	File metadata (name, size, type, modified)
`find`	Recursive search with `-name`, `-maxdepth`
`tree`	Directory tree view
`nl`	Number lines
`du`	Disk usage summary
`file`	Detect file type
`strings`	Extract printable strings from binary
`xxd`	Hex dump
`md5`	MD5 checksum
`sha256sum`	SHA-256 checksum

Text Processing

Command	Notes
`awk`	Pattern scanning and processing
`sed`	Stream editor
`tr`	Translate or delete characters
`sort`	Sort lines
`uniq`	Remove duplicate lines
`cut`	Extract fields/columns
`join`	Join lines on a common field
`paste`	Merge lines side by side
`column`	Columnate output
`fold`	Wrap lines to a specified width
`expand`	Convert tabs to spaces
`unexpand`	Convert spaces to tabs
`fmt`	Simple text formatter
`rev`	Reverse lines
`tac`	Concatenate and print in reverse
`look`	Display lines beginning with a given string
`shuf`	Shuffle lines
`tsort`	Topological sort
`comm`	Compare two sorted files
`cmp`	Compare two files byte by byte
`diff`	Compare files line by line
`patch`	Apply a diff patch
`iconv`	Character encoding conversion

File Operations

Command	Notes
`cp`	Copy files
`mv`	Move/rename files
`rm`	Remove files
`mkdir`	Create directories
`touch`	Create empty file or update timestamp
`ln`	Create symbolic links
`tee`	Write stdin to file and stdout
`mktemp`	Create temporary file
`split`	Split file into pieces
`csplit`	Split file by context

Path Utilities

Command	Notes
`basename`	Strip directory from path
`dirname`	Strip filename from path
`realpath`	Resolve path
`readlink`	Print symbolic link target
`ls`	List directory contents

Compression

Command	Notes
`gzip`	Compress files
`gunzip`	Decompress gzip files
`zip`	Create zip archives
`unzip`	Extract zip archives
`tar`	Archive files
`zcat`	Cat compressed files
`zgrep`	Grep compressed files

Encoding

Command	Notes
`base64`	Base64 encode/decode

Use Cases

Local directory access: Mount local directories for AI agents to read and process
Sandboxed file access: Restrict agent file operations to a specific directory tree
FUSE mounting: Expose disk files through a virtual FUSE mount for external tools
Data pipelines: Process local datasets with shell-like commands
Development: Test file operations against real data before deploying to cloud mounts

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Config

VFS.md

Virtual Filesystem

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Cache

Example

Shell Commands

Read Commands

Text Processing

File Operations

Path Utilities

Compression

Encoding

Use Cases

​Config

​VFS.md

​Virtual Filesystem

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Cache

​Example

​Shell Commands

​Read Commands

​Text Processing

​File Operations

​Path Utilities

​Compression

​Encoding

​Use Cases

Config

VFS.md

Virtual Filesystem

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Cache

Example

Shell Commands

Read Commands

Text Processing

File Operations

Path Utilities

Compression

Encoding

Use Cases