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

# RAM

> Use an in-memory Mirage filesystem for temporary files, tests, examples, and writable agent scratch space.

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

```python theme={null}
from mirage import MountMode, Workspace
from mirage.vfs.ram import RAMVFS

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

No configuration object needed - `RAMVFS()` 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.

```text theme={null}
/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 `index:` block still applies its `ttl` to this mount; see
[index TTL](/home/cache#index-ttl).

## Example

```python theme={null}
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")


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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.