Installation

Quick Install

Install the Node package:

pnpm add @struktoai/mirage-node

This ships the base runtime (Workspace, RAM resource, Disk resource, 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.

Expose a workspace as a real OS filesystem.

pnpm add @zkochan/fuse-native

Then follow the TypeScript FUSE setup for the pnpm onlyBuiltDependencies allow-list and the macOS 4+ symlink workaround.

Required for RedisResource, RedisFileCacheStore, and RedisIndexCacheStore.

pnpm add redis

Any redis@^5 client works.

Required for PostgresResource.

pnpm add pg

Required for MongoDBResource.

pnpm add mongodb

Required for LanceDBResource.

pnpm add @lancedb/lancedb

Required for QdrantResource.

pnpm add @qdrant/js-client-rest

Required for SSHResource.

pnpm add ssh2

Required for EmailResource (IMAP read, SMTP send, MIME parsing).

pnpm add imapflow mailparser nodemailer

Verify

import { MountMode, RAMResource, Workspace } from '@struktoai/mirage-node'

const ws = new Workspace(
  { '/data': new RAMResource() },
  { mode: MountMode.WRITE },
)
const res = await ws.execute('echo "hello" | tee /data/x.txt')
console.log(res.stdoutText) // hello
await ws.close()

If this prints hello, the base install is wired up correctly.

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

Agents

Resources

Runtimes

Quick Install

Optional Peer Dependencies

Verify

Install From Source

​Quick Install

​Optional Peer Dependencies

​Verify

​Install From Source

Quick Install

Optional Peer Dependencies

Verify

Install From Source