Adding a New VFS

A VFS is a class that extends BaseVFS. Override readdir, read and stat, and ls, cat, grep, find, head, wc and the other read commands work on the service. Custom VFS lists every method, with examples for a writable VFS and for grep on the service’s own search.

Write one

import { Accessor, BaseVFS, FileStat, type PathSpec, Workspace } from '@struktoai/mirage-node'
import { parseConfigWithSchema, secretStr, z } from '@struktoai/mirage-core/vfs/secrets'

const JiraConfigSchema = z.object({ site: z.string(), token: secretStr() })

class JiraAccessor extends Accessor {
  constructor(readonly client: JiraClient) {
    super()
  }
}

class JiraVFS extends BaseVFS<JiraAccessor> {
  constructor(input: Record<string, unknown>) {
    const config = parseConfigWithSchema(JiraConfigSchema, input)
    super({
      name: 'jira',
      accessor: new JiraAccessor(makeClient(config)),
      vfsMd: 'Issues rendered as .json files.',
    })
  }

  override async readdir(path: PathSpec): Promise<FileStat[]> { ... }
  override async read(path: PathSpec): Promise<Uint8Array> { ... }
  override async stat(path: PathSpec): Promise<FileStat> { ... }

  override async close(): Promise<void> {
    if (this.isClosed) return
    try {
      await this.accessor.client.close()
    } finally {
      await super.close()
    }
  }
}

const ws = new Workspace({ '/jira/': new JiraVFS({ site: 'acme', token: '...' }) })
await ws.shell('grep -rl outage /jira/')

parseConfigWithSchema refuses an unknown key by name, and secretStr() keeps the token out of logs and snapshots. The subpath import needs npm install @struktoai/mirage-core. 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. Use path.vfsPath to address the service and path.virtual for the workspace path. Set FileStat.size to the length of the bytes read returns, or null when it is unknown.

Add functions as the service grows

Every other function is optional. Override one, and the commands that need it start working; leave it out, and those commands answer Operation not supported.

Functions	Enables
`write`, `append`, `create`, `truncate`	`>`, `>>`, `touch`, `truncate`, `sed -i`
`mkdir`, `rmdir`, `unlink`, `rmR`, `rename`, `copy`, `dirCopy`, `setattr`	`mkdir`, `rm`, `mv`, `cp`, `chmod`, `touch -d`
`filesContaining`, `linesContaining`	Search for `grep` and `rg` from the service’s own index
`firstLines`, `lastLines`, `lineCount`, `checksum`, `readTree`	Fast `head`, `tail`, `wc -l`, `md5sum`, `find` (Lines, Walks)
`deltaHook`	Notifications from the service’s change feed

The mount mode still decides whether a write may run. read may return an async iterable of bytes for a large file, and write receives one when a program’s output streams into the mount.

Plug in the service’s search

filesContaining and linesContaining 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. beforeFullWalk can refuse a command that would walk the whole tree. For example, an S3 bucket whose objects are indexed in Elasticsearch under their keys, by whatever indexes the bucket (such as a function on S3 events). Extend the built-in S3VFS and answer from the index:

import { Client } from '@elastic/elasticsearch'
import { MountMode, S3VFS, Workspace, type PathSpec, type S3Config } from '@struktoai/mirage-node'
import { mountedPath } from '@struktoai/mirage-core/utils/key_prefix'

class IndexedS3VFS extends S3VFS {
  override readonly wholeWordSearch = true

  constructor(
    config: S3Config,
    readonly es: Client,
  ) {
    super(config)
  }

  override async filesContaining(
    path: PathSpec,
    text: string,
    opts: { wholeWord: boolean; ignoreCase: boolean },
  ): Promise<PathSpec[] | null> {
    if (!opts.wholeWord) return null
    const found = await this.es.search({
      index: this.config.bucket,
      query: { match_phrase: { body: text } },
      size: 1000,
      track_total_hits: true,
    })
    const total = typeof found.hits.total === 'number' ? found.hits.total : (found.hits.total?.value ?? 0)
    if (total > found.hits.hits.length) return null
    return found.hits.hits.map((hit) => mountedPath(path, `/${hit._id}`))
  }

  override async close(): Promise<void> {
    if (this.isClosed) return
    try {
      await this.es.close()
    } finally {
      await super.close()
    }
  }
}

const vfs = new IndexedS3VFS({ bucket: 'docs' }, new Client({ node: 'http://localhost:9200' }))
const ws = new Workspace({ '/s3/': [vfs, MountMode.READ] })
await ws.shell('grep -rlw outage /s3/')

grep -rlw outage /s3/ reads only the objects Elasticsearch names. Elasticsearch ignores case, so it may name more than grep prints; grep checks each line and drops the rest. grep -rl outage without -w gets null and reads every object, so outages still matches. The mount is read-only because a write through Mirage would leave the index behind. The answer is only as complete as the index: grep skips an object written elsewhere that Elasticsearch has not indexed yet, so return null while the indexer lags.

Function	Asked by	Answers
`filesContaining(path, text, { wholeWord, ignoreCase })`	`grep -r`, `rg` on a folder	The files under `path` that may hold `text`, or `null` to read every file
`linesContaining(path, text, { ignoreCase })`	`grep`, `rg` on one file	The lines that may hold `text`, in file order, or `null` to read the file
`beforeFullWalk(path, files)`	`tar -c`, `cp -r`, `rm -r`, `chmod -R`, `diff -r`	Resolve to let the walk run; reject to refuse it

Answer more files than needed, never fewer: an extra file costs one read, a missing one is a wrong answer. Return null whenever the answer may be incomplete, such as a truncated result or an index that lags writes.
A search that matches only whole words, as Elasticsearch does, returns null unless opts.wholeWord is set, and sets wholeWordSearch = true so the mount’s VFS.md tells the agent to use grep -w.
Set searchable to the globs the search covers, such as ['*/*.json']; a file outside them is always read.
walkLimit caps how many files one command walks, 1000 by default.

Search lists which patterns and flags reach these functions, and which built-in VFSs answer them. A service action that is not a file, such as a JQL search or adding a comment to an issue, belongs in a CLI, next to the mount.

Use it in YAML

A workspace YAML mounts the class by its file and name:

mounts:
  /jira:
    vfs: ./jira.mjs:JiraVFS
    config:
      site: acme
      token: ${JIRA_TOKEN}

To write vfs: jira instead, register the class once:

import { registerVfs } from '@struktoai/mirage-node'

registerVfs('jira', (config) => Promise.resolve(new JiraVFS(config)))

Examples

Runnable, each with a Python twin:

Example	Shows
`custom_vfs.ts`	A complete backend in one file: grep on its search, a snapshot and a load
`basevfs_views.ts`	A read-only VFS beside a nested mount, a symlink and a CLI
`custom_command.ts`	A command of the VFS’s own
`filetype.ts`	A renderer for one file type

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Adding a New VFS

Write one

Add functions as the service grows

Plug in the service’s search

Use it in YAML

Examples

​Write one

​Add functions as the service grows

​Plug in the service’s search

​Use it in YAML

​Examples

Write one

Add functions as the service grows

Plug in the service’s search

Use it in YAML

Examples