Skip to main content

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.

The RAM resource 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.resource.ram import RAMResource

resource = RAMResource()
ws = Workspace({"/data": resource}, mode=MountMode.WRITE)
No configuration object needed - RAMResource() takes no arguments.

​
Filesystem Layout

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 resource uses IndexCacheStore with _index_ttl = 0 (no expiry). Since all data is in-memory, the index is always fresh, no network calls or stale cache concerns.

​
Example

import asyncio

from mirage import MountMode, Workspace
from mirage.resource.ram import RAMResource

resource = RAMResource()


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

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

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

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

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

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

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

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

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


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

​
Shell Commands

The RAM resource supports the full set of shell commands since it handles real file content (text, binary, JSON, CSV, etc.):

​
Read Commands

CommandNotes
catRead file content
head / tailFirst/last N lines
grep / rgPattern search (file or directory level)
jqQuery JSON fields
wcLine/word/byte counts
statFile metadata (name, size, type, modified)
findRecursive search with -name, -maxdepth
treeDirectory tree view
nlNumber lines
duDisk usage summary
fileDetect file type
stringsExtract printable strings from binary
xxdHex dump
md5MD5 checksum
sha256sumSHA-256 checksum

​
Text Processing

CommandNotes
awkPattern scanning and processing
sedStream editor
trTranslate or delete characters
sortSort lines
uniqRemove duplicate lines
cutExtract fields/columns
joinJoin lines on a common field
pasteMerge lines side by side
columnColumnate output
foldWrap lines to a specified width
expandConvert tabs to spaces
unexpandConvert spaces to tabs
fmtSimple text formatter
revReverse lines
tacConcatenate and print in reverse
lookDisplay lines beginning with a given string
shufShuffle lines
tsortTopological sort
commCompare two sorted files
cmpCompare two files byte by byte
diffCompare files line by line
patchApply a diff patch
iconvCharacter encoding conversion

​
File Operations

CommandNotes
cpCopy files
mvMove/rename files
rmRemove files
mkdirCreate directories
touchCreate empty file or update timestamp
lnCreate symbolic links
teeWrite stdin to file and stdout
mktempCreate temporary file
splitSplit file into pieces
csplitSplit file by context

​
Path Utilities

CommandNotes
basenameStrip directory from path
dirnameStrip filename from path
realpathResolve path
readlinkPrint symbolic link target
lsList directory contents

​
Compression

CommandNotes
gzipCompress files
gunzipDecompress gzip files
zipCreate zip archives
unzipExtract zip archives
tarArchive files
zcatCat compressed files
zgrepGrep compressed files

​
Encoding

CommandNotes
base64Base64 encode/decode

​
Data Format Support

Commands with format-specific variants for structured data files:
FormatExtensionVariants
Parquet.parquetcat, head, tail, wc, stat, cut, grep, ls, file
Feather.feathercat, head, tail, wc, stat, cut, grep, ls, file
ORC.orccat, head, tail, wc, stat, cut, grep, ls, file
HDF5.hdf5cat, head, tail, wc, stat, cut, grep, ls, file
These variants auto-detect the format by extension and convert to tabular text (CSV) for processing.

​
Audio Support (Optional)

Audio commands are opt-in and require sherpa-onnx with a Whisper model. They transcribe audio to text, enabling cat, head, tail, grep, and stat on audio files.
FormatExtensionCommands
WAV.wavcat, head, tail, grep, stat
MP3.mp3cat, head, tail, grep, stat
OGG.oggcat, head, tail, grep, stat
To enable, register audio commands manually: 
from mirage.commands.audio import AUDIO_COMMANDS
from mirage.commands.audio.utils import configure

configure(model_dir="path/to/sherpa-onnx-whisper-base")

for cmd in AUDIO_COMMANDS:
    ws.register(cmd)

​
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