SQL

The SQL VFS keeps a filesystem in a database’s tables. It supports full read and write operations and needs no extra for a SQLite file: it uses Python’s own sqlite3.

Config

from mirage import MountMode, Workspace
from mirage.vfs.sql import SqlVFS

vfs = SqlVFS("./workspace.db")
ws = Workspace({"/sql": vfs}, mode=MountMode.WRITE)

Parameter	Required	Default	Description
`path`	no	in memory	The SQLite file, opened and closed with the mount
`capacity`	no	none	The most bytes the files may hold, like `100MB`
`driver`	no	none	A `SqlDriver` to borrow instead of a file; you close it

The tables are laid out as AgentFS’s:

fs_inode: one row per file and directory, with its size and mtime
fs_dentry: each entry’s name under its parent directory
fs_data: a file’s bytes, in rows of the database’s chunk size (4 KiB unless the database says otherwise)
fs_config: the chunk size

One database holds one filesystem. The TypeScript mount reads and writes the same tables, so a Python and a Node process on one file serve one filesystem.

VFS.md

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

Rendered
Raw

Virtual Filesystem

Path	Description
`/<path>`	`sql`, 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 1000 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>` | `sql`, 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 1000 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.

Cache

Index TTL is 0, so listings are read from the database every time. A workspace index: block still applies its ttl to this mount.

Example

import asyncio

from mirage import MountMode, Workspace
from mirage.vfs.sql import SqlVFS


async def main():
    ws = Workspace({"/sql": SqlVFS("./workspace.db")}, mode=MountMode.WRITE)
    try:
        await ws.shell("mkdir -p /sql/data/")
        await ws.shell('echo "hello world" | tee /sql/data/hello.txt')
        r = await ws.shell("cat /sql/data/hello.txt")
        print(await r.stdout_str())
    finally:
        await ws.close()


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

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

​Config

​VFS.md

​Virtual Filesystem

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Cache

​Example

Config

VFS.md

Virtual Filesystem

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Cache

Example