Skip to main content
A VFS is a class that extends BaseVFS. Define readdir, read and stat, and ls, cat, grep, find, head, wc and the other read commands work on the service. TypeScript names every method in camelCase (rm_r is rmR).

Write one

This VFS serves pages from a dictionary, which stands in for the service:
notes.py
Mount it like any other VFS:
  • readdir returns each child’s FileStat with name set to the base name. The mount keeps the listing and answers a later stat from it, so ls -l costs one request.
  • path.vfs_path (vfsPath) addresses the service and path.virtual the workspace path.
  • Set FileStat.size to the length of the bytes read returns, or leave it unset when it is unknown.
  • Pass name and vfs_md (vfsMd) to the base constructor. vfs_md is the mount’s layout in its VFS.md: a text tree, then a few notes, with {prefix} for the mount’s folder.

Add functions as the service grows

Every other function is optional. Define one, and the commands that need it start working; leave it out, and those commands answer Operation not supported. Some commands fall back to simpler functions: >> without append reads the file and calls write, cp without copy reads and writes, rm -r without rm_r removes entry by entry, and chmod without setattr keeps the mode in Mirage. The mount mode still decides whether a write may run. For example, write and unlink make the notes writable:
On a writable mount, echo hi > /notes/new.txt, sed -i and rm now work, and >> reads the page and writes it back. mv still answers Operation not supported until rename is defined. files_containing and lines_containing hand Mirage the service’s own search. grep and rg ask them which files or lines can hold the text and read only those; they still match every line themselves, so the output is the same as a full read. Returning None (null) reads every file.
grep -rn mirage /notes now reads only the pages this returns. mounted_path (mountedPath) turns a name inside the mount into a path. grep -ri gets None here, so it reads every page.
  • Answer more files than needed, never fewer: an extra file costs one read, a missing one is a wrong answer. Return None whenever the answer may be incomplete, such as a truncated result or an index that lags writes.
  • A search that matches only whole words returns None unless whole_word is set, and sets whole_word_search so the mount’s VFS.md tells the agent to use grep -w.
Chroma is a real one: its files_containing asks Chroma for the chunks whose text contains the word and returns their pages. Search lists which patterns and flags reach these functions. A service action that is not a file, such as a search query or adding a comment, belongs in a CLI, next to the mount.

Use it in YAML

A workspace YAML mounts the class by its file and name, relative to the YAML file; config is what its constructor gets:
workspace.yaml
The TypeScript server takes ./notes.ts:NotesVFS. To write vfs: notes instead, register the class once:

SDK guides

Python

Accessors, config, an Elasticsearch-backed S3 and runnable examples.

TypeScript

Accessors, config, an Elasticsearch-backed S3 and runnable examples.