Adding a New Resource

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

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

Ship Your Own Backend (SDK)

Everything an out-of-tree backend needs is exported from mirage.sdk — that module is the stable public contract. Write the core functions over your data source, put them on a CommandIO, and GenericResource wires the full generic command set (ls, cat, grep, find, head, wc, …) plus glob resolution:

from functools import partial

from mirage.sdk import (Accessor, CommandIO, FileStat, GenericResource,
                        stream_from_bytes)


class JiraAccessor(Accessor):
    def __init__(self, config):
        self.client = make_client(config)


async def readdir(accessor, path, index=None) -> list[str]: ...
async def read_bytes(accessor, path, index=None) -> bytes: ...
async def stat(accessor, path, index=None) -> FileStat: ...


def make_jira_resource(config) -> GenericResource:
    io = CommandIO(
        readdir=readdir,
        read_bytes=read_bytes,
        read_stream=partial(stream_from_bytes, read_bytes),
        stat=stat,
        is_mounted=lambda a: True,
        local=False,
    )
    return GenericResource(name="jira", accessor=JiraAccessor(config), io=io,
                           prompt="Issues rendered as .json files.")

Mount it like any builtin: Workspace({"/jira/": make_jira_resource(cfg)}). The escape hatches mirror what builtins use: optional CommandIO fields unlock more surface (write enables the byte-mutation family; find/du_total/du_all become native fast paths; is_dir_name hints virtual directories), overrides= suppresses a generic command you replace, and commands=[...] adds bespoke @command verbs. VFS/FUSE ops are derived from the same table automatically (make_generic_ops under the hood): read/readdir/stat plus whatever mutations the table carries. Pass ops=[...] only for irregular handlers (they shadow same-named derived ops), or auto_ops=False to opt out. To make the backend constructible by name (workspace YAML, snapshots, the daemon), register it:

from mirage.sdk import register_resource

register_resource("jira", JiraResource, JiraConfig)

or ship it as a normal package with an entry point — discovered automatically at registry-build time:

[project.entry-points."mirage.resources"]
jira = "mypackage.backends:JiraResource"

The entry point resolves to the resource class; declare a CONFIG_CLS class attribute when the constructor takes a typed config. See examples/python/other/custom_resource.py for a complete runnable backend in one file.

Contribute a Builtin Resource

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 resource or behavior should also be added to TypeScript. Use a recent resource such as Dify or Databricks Volume as the structural reference. Paths are always PathSpec values inside the VFS; do not pass filesystem paths as raw strings.

File Structure

python/mirage/
  resource/<name>/
    __init__.py
    config.py
    <name>.py
  accessor/<name>.py
  core/<name>/
    read.py
    readdir.py
    stat.py
  ops/<name>/
    __init__.py
    read.py
    readdir.py
    stat.py
  commands/builtin/<name>/
    __init__.py
    <resource-specific commands>.py

Add matching tests under python/tests/ without creating __init__.py files in the test tree.

1. Config, Accessor, and Registry

Define a typed Pydantic config and keep secrets in SecretStr fields.

from pydantic import BaseModel, SecretStr


class MyConfig(BaseModel):
    token: SecretStr

Create an Accessor that owns the client or transport. Add the resource name to ResourceName, export the config/resource from resource/<name>/__init__.py, and add a lazy ResourceEntry to mirage/resource/registry.py. The registry entry is required for YAML, snapshots, and the daemon to construct the resource. Keep every import at module scope. If that creates a cycle, change the dependency direction instead of adding a function-local import.

2. Core VFS Operations

Implement only the operations the backend supports. Read-only API resources usually start with:

readdir(accessor, path, index) returning child names.
read_bytes(accessor, path, index) returning bytes.
stat(accessor, path, index) returning FileStat.

Glob resolution is not a per-backend file: bind it from readdir with make_resolve_glob(readdir, cap) (mirage.utils.glob_walk), or use the CommandIO.resolve_glob property. Use explicit types:

from mirage.accessor.base import Accessor
from mirage.cache.index import IndexCacheStore
from mirage.types import FileStat, PathSpec


async def stat(
    accessor: Accessor,
    path: PathSpec,
    index: IndexCacheStore | None,
) -> FileStat:
    ...

Add write, append, create, unlink, rename, or directory operations only when the backend has matching semantics. I/O should remain async-native.

3. Ops Layer

Ops are thin typed adapters from the workspace dispatcher to core functions. Declare dispatcher-injected arguments explicitly and keep **flags: object opaque.

from mirage.accessor.base import Accessor
from mirage.cache.index import IndexCacheStore
from mirage.core.my_resource.read import read_bytes
from mirage.ops.registry import op
from mirage.types import PathSpec


@op("read", resource="my_resource")
async def read(
    accessor: Accessor,
    path: PathSpec,
    *,
    index: IndexCacheStore | None,
    **flags: object,
) -> bytes:
    return await read_bytes(accessor, path, index)

Mark mutation ops with write=True. Export the decorated functions as OPS from ops/<name>/__init__.py.

4. Commands

Build standard commands with CommandIO and make_generic_commands; the generic command owns flag interpretation. Backend wrappers should only connect glob resolution and I/O functions. For a resource-specific command:

Use the shared command spec.
Mark every mutation with write=True so MountMode.READ remains a real boundary.
Declare injected parameters such as stdin, index, and prefix explicitly.
Use FlagView(flags, spec=...) when the command itself must read a flag; never use flags.get(...).
Add a provision estimator when a useful estimate is possible. Otherwise the planner reports precision=unknown.

Export the final list as COMMANDS from commands/builtin/<name>/__init__.py.

5. Resource Class

Import commands and ops at module scope, then register them in the constructor:

from mirage.accessor.my_resource import MyAccessor
from mirage.commands.builtin.my_resource import COMMANDS
from mirage.ops.my_resource import OPS as MY_RESOURCE_OPS
from mirage.resource.base import BaseResource
from mirage.resource.my_resource.config import MyConfig
from mirage.types import ResourceName


class MyResource(BaseResource):
    name: str = ResourceName.MY_RESOURCE
    caches_reads: bool = True

    def __init__(self, config: MyConfig) -> None:
        super().__init__()
        self.config = config
        self.accessor = MyAccessor(config)
        for fn in COMMANDS:
            self.register(fn)
        for fn in MY_RESOURCE_OPS:
            self.register_op(fn)

Set caches_reads=True only for stable, read-mostly content. Implement get_state() with credentials redacted and close any network clients in close().

6. Snapshot Support

Leave SUPPORTS_SNAPSHOT=False 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 revision_for(path.virtual) and record the resolved revision.

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

7. Verification

Add tests for config validation, 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

Agents

Resources

CLIs

Watch

Runtimes

Adding a New Resource

Ship Your Own Backend (SDK)

Contribute a Builtin Resource

File Structure

1. Config, Accessor, and Registry

2. Core VFS Operations

3. Ops Layer

4. Commands

5. Resource Class

6. Snapshot Support

7. Verification

​Ship Your Own Backend (SDK)

​Contribute a Builtin Resource

​File Structure

​1. Config, Accessor, and Registry

​2. Core VFS Operations

​3. Ops Layer

​4. Commands

​5. Resource Class

​6. Snapshot Support

​7. Verification

Ship Your Own Backend (SDK)

Contribute a Builtin Resource

File Structure

1. Config, Accessor, and Registry

2. Core VFS Operations

3. Ops Layer

4. Commands

5. Resource Class

6. Snapshot Support

7. Verification