RAM

The RAM VFS exposes an in-memory filesystem mounted at some prefix such as /data/. All data lives in process memory and is lost on exit. No setup or credentials required.

Config

from mirage import MountMode, Workspace
from mirage.vfs.ram import RAMVFS

vfs = RAMVFS()
ws = Workspace({"/data": vfs}, mode=MountMode.WRITE)

RAMVFS() needs no configuration object. RAMVFS(capacity="100MB") caps the bytes the store holds; a write past it fails with “Disk quota exceeded”. See capacity.

VFS.md

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

Rendered
Raw

Virtual Filesystem

Path	Description
`/<path>`	`ram`, 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>` | `ram`, 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 RAM filesystem starts empty. Files and directories are created on demand via commands like touch, mkdir, tee, cp, etc.

/data/
  notes.txt
  config.json
  reports/
    q1.csv
    q2.csv
  uploads/
    image.png

Paths are normalized with a leading /. The root directory / always exists.

Cache

The RAM VFS uses IndexCacheStore with index_ttl = 0, so its listings are not cached: the data is in memory, and every listing reads it. A workspace or mount index: block still applies its ttl to this mount.

Integration

What RAM answers through its own API, so fewer files are read. Integration explains each command.

Command	On RAM
`find`, `du`, `ls -R`, `tree`	One recursive listing

Example

import asyncio

from mirage import MountMode, Workspace
from mirage.vfs.ram import RAMVFS

vfs = RAMVFS()


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

    # Create files
    await ws.shell('echo "hello world" | tee /data/hello.txt')
    await ws.shell('echo \'{"name": "alice", "age": 30}\' | tee /data/user.json')
    await ws.shell("mkdir /data/reports")
    await ws.shell('echo "revenue,100" | tee /data/reports/q1.csv')

    # Read
    r = await ws.shell("cat /data/hello.txt")
    print(await r.stdout_str())

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

    # Query JSON
    r = await ws.shell('jq ".name" /data/user.json')
    print(await r.stdout_str())

    # Search
    r = await ws.shell("grep hello /data/hello.txt")
    print(await r.stdout_str())

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

    # File info
    r = await ws.shell("stat /data/hello.txt")
    print(await r.stdout_str())

    # Copy, move, remove
    await ws.shell("cp /data/hello.txt /data/hello_copy.txt")
    await ws.shell("mv /data/hello_copy.txt /data/renamed.txt")
    await ws.shell("rm /data/renamed.txt")
    await ws.close()


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

Shell Commands

The RAM VFS supports the full set of shell commands since it handles 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

Testing: Fast filesystem for unit tests without I/O
Staging: Temporary data area during pipelines
Prototyping: Develop against a filesystem before switching to S3/disk
Caching: In-process data exchange between commands
Ephemeral workspaces: Create, process, discard - no cleanup needed

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

Integration

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

​Integration

​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

Integration

Example

Shell Commands

Read Commands

Text Processing

File Operations

Path Utilities

Compression

Encoding

Use Cases