Adding a New VFS

A VFS maps an external system to Mirage’s filesystem operations and shell commands. There are two paths:

Ship your own backend: a single TypeScript file in your own project or package, built on GenericVFS. No Mirage fork, no edits to Mirage source.
Contribute a builtin: the four-layer layout inside the Mirage repo, mirrored in Python.

Ship Your Own Backend

Write the core functions over your data source, put them on a CommandIO table, and GenericVFS wires the full generic command set (ls, cat, grep, find, head, wc, …) plus glob resolution and the VFS/FUSE ops:

import {
  Accessor,
  type CommandIO,
  FileStat,
  GenericVFS,
  MountMode,
  type PathSpec,
  streamFromBytes,
  Workspace,
} from '@struktoai/mirage-node'

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

declare function readdir(accessor: JiraAccessor, path: PathSpec): Promise<string[]>
declare function readBytes(accessor: JiraAccessor, path: PathSpec): Promise<Uint8Array>
declare function stat(accessor: JiraAccessor, path: PathSpec): Promise<FileStat>

class JiraVFS extends GenericVFS<JiraAccessor> {
  constructor(config: JiraConfig) {
    super({
      name: 'jira',
      accessor: new JiraAccessor(makeClient(config)),
      io: {
        readdir,
        readBytes,
        readStream: (a, p, i) => streamFromBytes(readBytes, a, p, i),
        stat,
        isMounted: () => true,
        local: false,
      },
      prompt: 'Issues rendered as .json files.',
    })
  }
}

const ws = new Workspace({ '/jira/': new JiraVFS(cfg) }, { mode: MountMode.READ })

The accessor is a type parameter, so the table is checked against the accessor your core functions actually take: wiring readdir where stat belongs, or an accessor from another backend, is a compile error rather than a runtime one. Only four table fields are required. The optional ones unlock more surface: write enables the byte-mutation family, find and du become native fast paths, and a command whose requirements the table cannot meet is never registered rather than registered and broken. The escape hatches are the ones the builtins use, because GenericVFS assembles exactly what they assemble by hand:

overrides drops a generic command you replace, and commands supplies the replacement (or any bespoke verb) from command({...}).
ops layers an irregular VFS/FUSE handler over the derived set; one carrying no filetype shadows the derived op of the same name. autoOps: false opts out of deriving any.
sizesAlwaysKnown declares that stat sizes every file without fetching it, which is also what makes the mount legal on FSKit. supportsSnapshot declares that stat fills FileStat.fingerprint; setting it without that is not drift detection.

To make the backend constructible by name (workspace config, snapshots, the daemon), register a factory:

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

registerVfsFactory('jira', (config) => Promise.resolve(new JiraVFS(config as JiraConfig)))

The registry takes a factory rather than a class because a browser backend is often reached through a dynamic import; buildVfs('jira', config) then works exactly as it does for a builtin. Registering is not needed to mount from config. A vfs value carrying a colon names the class directly, the same way a clis entry’s cli value names a spec tree, so a deployment can point at a file next to the config or at a class inside an installed package:

mounts:
  /jira:
    vfs: ./jira.mjs:JiraVFS
  /wiki:
    vfs: my-backends:WikiVFS

A relative path resolves against the config file’s directory, not the server’s working directory; a bare specifier is Node’s to resolve, so a package name is left alone. A registry name always wins over a reference, so a name can never be reread as code. A static async create is honored ahead of the constructor, which is how a backend whose setup needs I/O is spelled here. Snapshots and versions reach the registry too: Workspace.load rebuilds a saved mount through the registered name (or the ./jira.mjs:JiraVFS reference config named), the same way Python’s loader does. What comes back depends on what the VFS owns. Content the VFS holds itself (an in-memory store) is mirage-owned state: override getState and loadState to carry it, and a snapshot or a version restores the mount with that content and no override. Content that lives in a remote service is only observed: keep the default state, which says needs_override, set supportsSnapshot and fill FileStat.fingerprint, and a snapshot pins what it read while Workspace.load asks for the live VFS back through its overrides (Workspace.load(state, {}, { '/jira/': new JiraVFS(cfg) })). A forgotten override is a refusal to load, never a mount that comes back empty. Workspace.copy needs nothing, since it passes the live VFS through. examples/typescript/other/custom_vfs.ts shows both halves: a wiki page is written, the workspace is snapshotted, the page is changed, and the loaded workspace serves the page as it was, while a feed mount that keeps the default state is refused until the load hands it back through its overrides. See examples/typescript/other/custom_vfs.ts for a complete runnable backend in one file, and examples/python/other/custom_vfs.py for its Python twin. Both are asserted against the same truth file, so the two SDKs cannot drift.

Contribute a Builtin VFS

Builtins live inside the Mirage repo with the four-layer layout below. Keep the core I/O layer independent from command parsing, and check whether the same VFS or behavior should also be added to Python. Pick the package by runtime, not by preference: packages/core for a backend that works in both the browser and Node, packages/node for one that needs Node APIs, packages/browser for one that needs a browser transport. Use a recent VFS such as Qdrant or LanceDB as the structural reference. Paths are always PathSpec values inside the VFS; do not pass filesystem paths as raw strings.

File Structure

typescript/packages/<core|node|browser>/src/
  vfs/<name>/
    config.ts
    prompt.ts
    <name>.ts
  accessor/<name>.ts
  core/<name>/
    read.ts
    readdir.ts
    stat.ts
  ops/<name>/
    index.ts
  commands/builtin/<name>/
    index.ts
    io.ts
    <vfs-specific commands>.ts

Tests are colocated: <name>.test.ts beside the source it covers.

1. Config, Accessor, and Registry

Define the config as an interface plus a resolve<Name>Config that fills every default, and keep secrets out of anything that gets serialized. Create an Accessor subclass that owns the client or transport. Add the VFS name to VFSName, and add a factory to the runtime package’s vfs/registry.ts; that entry is what workspace config, snapshots, and the daemon construct through. Config keys arrive snake_case from YAML shared with Python and are mapped by normalizeFields, which already sends every unlisted key through snakeToCamel. Add a rename entry only for a key that mapping gets wrong. Keep every import at module scope. If that would create a cycle, change the dependency direction instead of adding a lazy import inside a function.

2. Core VFS Operations

Implement only the operations the backend supports. A read-only API-backed VFS usually starts with:

readdir(accessor, path, index?) returning child paths.
read(accessor, path, index?) returning bytes.
stat(accessor, path, index?) returning a FileStat.

FileStat.size must be the rendered content’s byte length or null, never a storage-side number: a confidently wrong size makes wc -c and ls -l lie over FUSE, while null rides the unknown-size machinery. Put the storage number in extra if it is worth reporting. Glob resolution is not a per-backend file: bind it from readdir with makeResolveGlob(readdir, cap), or let GenericVFS derive it from the table.

3. Ops Layer

Ops are the workspace dispatcher’s typed adapters onto the core functions, and they are generated, not hand-written:

import { QDRANT_IO } from '../../commands/builtin/qdrant/io.ts'
import { VFSName } from '../../types.ts'
import { makeGenericOps } from '../generic/factory.ts'
import type { RegisteredOp } from '../registry.ts'

export const QDRANT_OPS: readonly RegisteredOp[] = makeGenericOps(VFSName.QDRANT, QDRANT_IO)

Write an op by hand only for an irregular handler, and pass its name through overrides so the derived set skips it. Mark every mutation write: true.

4. Commands

Build the standard command set with makeGenericCommands over the same table; the generic command owns flag interpretation, so a backend wrapper is wiring only. Export the result as <NAME>_COMMANDS from commands/builtin/<name>/index.ts. For a VFS-specific command:

Use the shared command spec (specOf), or a new CommandSpec({...}) for a verb with its own grammar.
Mark every mutation write: true so MountMode.READ stays a real boundary.
Read a flag through new FlagView(flags, specOf('<name>')), never flags.get(...).
Add a provision estimator when a useful estimate is possible; otherwise the planner reports precision: unknown.

5. VFS Class

Import the command and op arrays at module scope and return them from commands() and ops():

export class MyVFS extends BaseVFS implements VFS {
  readonly kind: string = VFSName.MY_VFS
  readonly cachesReads: boolean = true
  readonly prompt: string = MY_PROMPT
  readonly accessor: MyAccessor

  constructor(config: MyConfig) {
    super()
    this.config = resolveMyConfig(config)
    this.accessor = new MyAccessor(this.config)
  }

  open(): Promise<void> {
    return Promise.resolve()
  }

  ops(): readonly RegisteredOp[] {
    return MY_VFS_OPS
  }

  commands(): readonly RegisteredCommand[] {
    return MY_VFS_COMMANDS
  }
}

Set cachesReads true only for stable, read-mostly content. Override getState() to carry the (redacted) config, and close() to release any client handles, calling super.close(), which closes the index store. A config-backed backend also sets needs_override: true in that state. TypeScript’s loader consults no registry, so a mount it was not handed comes back as an empty RAMVFS; the flag makes it refuse instead. Python does not need it, which is why the flag is written on only a handful of mounts there and read on none.

6. Snapshot Support

Leave supportsSnapshot unset unless the complete drift contract is implemented:

stat() returns a stable FileStat.fingerprint.
Every read record includes the fingerprint that produced those bytes.
If the backend supports immutable revisions, reads consult the resolved revision and record it.

Setting the flag without recording fingerprints does not provide drift detection.

7. Verification

Add tests for config resolution, path layout, every VFS op, command behavior, read-only enforcement, state redaction, and cleanup. For major features, add or update integration coverage under integ/, and check Python/TypeScript parity before opening the PR.

Getting Started

AI Agents

VFS

CLIs

Watch

Runtimes

Adding a New VFS

Ship Your Own Backend

Contribute a Builtin VFS

File Structure

1. Config, Accessor, and Registry

2. Core VFS Operations

3. Ops Layer

4. Commands

5. VFS Class

6. Snapshot Support

7. Verification

​Ship Your Own Backend

​Contribute a Builtin VFS

​File Structure

​1. Config, Accessor, and Registry

​2. Core VFS Operations

​3. Ops Layer

​4. Commands

​5. VFS Class

​6. Snapshot Support

​7. Verification

Ship Your Own Backend

Contribute a Builtin VFS

File Structure

1. Config, Accessor, and Registry

2. Core VFS Operations

3. Ops Layer

4. Commands

5. VFS Class

6. Snapshot Support

7. Verification