Mirage 0.0.3

We are excited to announce the release of Mirage 0.0.3 🎉🎉🎉

Mirage 0.0.3 is a large parity and platform release. It lands a GNU-aligned shell environment (history, cwd/env, subshell isolation), a unified command factory shared across every backend, cache read-through with warm serving, the Claude Agent SDK integration, and four new/upgraded backends (SharePoint, Qdrant, OneDrive parity, MongoDB on PyMongo Async). Python and TypeScript are kept mirrored throughout.

pip install mirage-ai==0.0.3 · npm install @struktoai/mirage-core@0.0.3 (and -node, -browser, -server, -cli, -agents)

Highlights

• GNU history subsystem (Python + TypeScript). A hidden Observer records every top-level command as timestamp-ordered events; /.bash_history is a read-only view in GNU histfile format and the history shell builtin (-c -d -a -n -r -w -s -p + count) routes through the same mount, so the file and the builtin never disagree. History is captured into snapshots and restored on load. (#313)
• Claude Agent SDK integration. MirageServer + build_options wire a Mirage workspace into the Claude Agent SDK as a tool surface, mirrored in both languages with Python and TypeScript all-tools examples. (#322, #216)
• GNU-aligned cwd/env and subshell isolation. HOME/PWD/OLDPWD mirrors, cd/tilde/CDPATH GNU semantics, relative-path display, and subshell isolation. (#331)
• Unified command factory. Backend shell commands are now generated from one shared factory instead of per-backend wrappers, across disk, redis, ram, s3, ssh, google/chat, the database and SaaS families, notion, dify, nextcloud, onedrive, hf, box, dropbox, and email. Flag interpretation lives in the generics; wrappers are wiring only.
• Cache read-through and warm serving. Warm reads are served in place through shared read-through consumers, with invalidation done at the write site via CacheManager; the file cache is now a store rather than a mount. (#329)
• New and upgraded backends: SharePoint multi-site discovery (#365), a Qdrant resource (#367), full OneDrive S3-parity, and MongoDB migrated to PyMongo Async with client metadata (#330).
• Virtual root is now a real mount. /_default is replaced by a real / mount that callers can override with their own / mount.

Breaking Changes

• /_default is removed. The default scratch space is now a real virtual root mounted at /, overridable by a user-provided / mount.
• File cache is no longer a mount. It is exposed as a store; the cache-mount read redirect is removed and warm reads are served in place.
• MongoDB driver migrated from Motor to PyMongo Async (#330).
• Workspace config: the removed history field is dropped from configs; foreign history formats are tolerated on cross-language snapshot load.
• Cache API: invalidate_index_dirs is deleted in favor of write-site invalidation (#329); the factory drops unsupported_commands and per-command requires tuples.

Features

• sed: GNU-aligned engine: ^/$ anchors, s/// numeric count and p flag, y (transliterate) and c (change), BRE by default with ERE under -E/-r, multiple -e expressions, -f script files, and address negation (addr!cmd) (#340, #326).
• diff: full GNU-style recursive diff -r (py + ts).
• find: aligned with GNU coreutils across all backends: GNU start-path emission, -empty, -not, and unknown-predicate errors (#393, #312).
• FUSE: per-mount Mount spec with FuseManager ownership across both languages, in-memory xattr support, and caller-owned mountpoint cleanup (#345).
• github: grep/rg narrowing via code search on subdirs and regex, with a -l short-circuit (#406).
• mongodb: tail -f follows the change stream and stops caching live reads.
• Wasmer and Microsandbox examples running over a Mirage FUSE mount.

Bugfixes

• Many Python/TypeScript divergence fixes: stat on slack/discord/gdrive, du walk fallback, and assorted GNU command semantics (#419).
• csplit -f cwd resolution, ssh write recording, and disk mkdir invalidation ordering (#419).
• sed: honor ^/$ line anchors in TS substitution and addresses; pattern space excludes the trailing newline (#326).
• onedrive: ls trailing newline (#354), index-cache metadata (#361), and S3-parity command suite (#357).
• databricks_volume: stat reads content_length/last_modified (#355); record mount-relative write keys in touch/mkdir (#356).
• s3/nextcloud: populate ls -l / stat mtime across object-store and API backends (#362).
• Cache invalidation completed at every mutation site for create/copy/rm/rmdir (#329).
• Multi-pattern grep -e / rg -e routed through the generic on search-pushdown backends.
• tar: load bzip2/xz codecs via createRequire for ESM compatibility; redis read enoent preserves the virtual path; fixed open()/os interception hijacking real paths under the virtual root.

Changes

• Cross-mount commands (cp/mv/diff/cmp + read family) reuse the generics through a dispatch-backed adapter, split into per-command modules.
• Shared epoch_to_iso/epochToIso util dedups mtime ISO formatting and enforces second precision; diff flags grouped into a frozen struct.
• Dead-code and dead-test sweep (#359, #348).
• Security: resolved CodeQL code-scanning alerts (path-injection, request-forgery, ReDoS), cleared Dependabot vulnerabilities, added server rate limiting, and confined snapshot/load paths (#323, #324, #325, #342, #358, #360).
• Dependencies: bumped joserfc, pyjwt, nodemailer, undici, js-yaml, pypdf, fast-xml-parser, langchain, aiohttp (<3.14 cap lifted), and several GitHub Actions; added an informational uv audit CI job (#346, #352).
• Expanded the cross-language integ harness (history/observer, cache coherence, cross-mount, sed/find/diff, notion database, onedrive).

Contributors

Thanks to everyone who contributed to this release: @zechengz, @sonhmai, @MarshuMax, @hieu650002, @alexbevi, @ki3nd, @Anush008, @C1-BA-B1-F3, and @dependabot.

New Contributors

• @MarshuMax made their first contribution: Notion database browsing support (#21)
• @alexbevi made their first contribution: MongoDB PyMongo Async migration + client metadata (#330)
• @hieu650002 made their first contribution: SharePoint multi-site discovery (#365) and OneDrive metadata (#361)
• @Anush008 made their first contribution: Qdrant resource (#367)
• @C1-BA-B1-F3 made their first contribution: GNU find alignment (#393) and compact JSON rendering (#391)

Full Changelog: v0.0.2...v0.0.3

v0.0.2

Release v0.0.2.

TypeScript (npm, @struktoai/*) at 0.0.2:

• mirage-core, mirage-node, mirage-browser, mirage-server, mirage-agents, mirage-cli

Python (PyPI, mirage-ai) at 0.0.3a0 (alpha).

Notable: the CLI now reports its real package version instead of a hardcoded 0.0.0.

v0.0.1 — first public release

The first public release of Mirage — a unified virtual filesystem for AI agents.

Mount S3, Google Drive, Slack, Gmail, GitHub, Linear, Notion, Postgres, MongoDB, SSH, and more behind one filesystem so agents read, write, and pipe across services with familiar shell commands.

What's included

• Python SDK — mirage-ai on PyPI
• TypeScript SDKs — @struktoai/mirage-{core,node,browser,agents,cli,server} (npm publish forthcoming)
• CLI + daemon — uvx mirage-ai or uv tool install mirage-ai
• FUSE mounts — expose any workspace as a real filesystem (macOS / Linux)
• Agent integrations — OpenAI Agents SDK, Vercel AI SDK, LangChain (deepagents), Pydantic AI, CAMEL, OpenHands, Mastra, Pi Coding Agent
• CLI agent integrations — Claude Code and Codex via FUSE
• Documentation — https://docs.mirage.strukto.ai

Install

# Python (library + CLI)
uv add mirage-ai

# Or run the CLI directly
uvx mirage-ai

Quickstart

from mirage import MountMode, Workspace
from mirage.resource.ram import RAMResource

ws = Workspace({"/data": RAMResource()}, mode=MountMode.WRITE)
await ws.execute('echo "hello mirage" | tee /data/hello.txt')

See docs.mirage.strukto.ai for the full guide.

License

Apache 2.0. See LICENSE.

Notes

This is an early release. Expect bugs and breaking changes through the 0.0.x line. Report issues at github.com/strukto-ai/mirage/issues or report security concerns per SECURITY.md.