Installation

Quick Install

For Node applications, use Node 22.20+ on Node 22, 24.12+ on Node 24, or 25+. Install the Node package:

pnpm add @struktoai/mirage-node

This ships the base runtime (Workspace, RAM VFS, Disk VFS, the shell executor) and is enough to follow the TypeScript Quickstart. npm install and yarn add work identically; examples below use pnpm because the FUSE binding’s install script needs pnpm’s onlyBuiltDependencies allow-list.

Optional Peer Dependencies

Mirage keeps native and network-heavy dependencies as optional peers so consumers who don’t use those features don’t pay the download or build cost. Mirage imports each library lazily, so unused peers cost nothing at runtime either. Install a peer with pnpm add <package> when you use the feature that needs it:

Feature	Packages	Needed for
FUSE	`@zkochan/fuse-native@^0.1.0`	Mounting a workspace as an OS filesystem; see the FUSE setup.
Redis	`redis@^5.0.0`	`RedisVFS`, the Redis file and index cache stores, and the Redis session store.
Postgres	`pg@^8.13.0`	`PostgresVFS`.
MongoDB	`mongodb@^6.10.0`	`MongoDBVFS` and `GridFSVFS`.
LanceDB	`@lancedb/lancedb@^0.30.0`	`LanceDBVFS`.
Qdrant	`@qdrant/js-client-rest@^1.18.0`	`QdrantVFS`.
Chroma	`chromadb@^3.4.3`	`ChromaVFS`.
SSH	`ssh2@^1.16.0`	`SSHVFS`, the SSH sandbox runtime and the SFTP mount.
Email	`imapflow@^1.0.0`, `mailparser@^3.12.4`, `nodemailer@^10.1.4`	`EmailVFS` (IMAP read, MIME parsing) and sending mail with `himalaya` (SMTP).
OpenDAL	`opendal@^0.49.4`	`HfBucketsVFS` and `NextcloudVFS`.
Python runtimes	`pyodide@^0.29.0 \|\| ^314.0.0`, `@pydantic/monty@^1.4.0`	The Pyodide and Monty runtimes behind `python3`.
Sandboxes	`e2b@^2.62.0`, `@daytonaio/sdk@^0.227.0`	The E2B and Daytona sandbox runtimes.
1Password	`@1password/sdk@^0.5.0`	The `1password` secret source.

The FUSE binding also needs pnpm’s onlyBuiltDependencies allow-list and, on macOS, the macFUSE 4+ symlink workaround described in the TypeScript FUSE setup. For a browser application, install @struktoai/mirage-browser instead and follow the browser quickstart.

Install From Source

Contributing to Mirage or exploring the examples directly:

git clone https://github.com/strukto-ai/mirage.git
cd mirage/typescript
pnpm install
pnpm -r build

The examples in examples/typescript/ link to the workspace packages via pnpm’s workspace protocol, so changes in packages/core or packages/node are picked up on the next pnpm build.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Quick Install

Optional Peer Dependencies

Install From Source

​Quick Install

​Optional Peer Dependencies

​Install From Source

Quick Install

Optional Peer Dependencies

Install From Source