strukto-ai--mirage/docs/typescript/install.mdx

---
title: Installation
description: Install the Mirage TypeScript SDK and add the optional native peers only if you need them.
icon: download
---

## Quick Install

Install the Node package:

```bash
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](/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.

<Tabs>
  <Tab title="FUSE">
    Expose a workspace as a real OS filesystem.

    ```bash
    pnpm add @zkochan/fuse-native
    ```

    Then follow the [TypeScript FUSE setup](/typescript/setup/fuse) for the pnpm `onlyBuiltDependencies` allow-list and the macOS 4+ symlink workaround.
  </Tab>
  <Tab title="Redis">
    Required for `RedisResource`, `RedisFileCacheStore`, and `RedisIndexCacheStore`.

    ```bash
    pnpm add redis
    ```

    Any `redis@^5` client works.
  </Tab>
  <Tab title="Postgres">
    Required for `PostgresResource`.

    ```bash
    pnpm add pg
    ```
  </Tab>
  <Tab title="MongoDB">
    Required for `MongoDBResource`.

    ```bash
    pnpm add mongodb
    ```
  </Tab>
  <Tab title="LanceDB">
    Required for `LanceDBResource`.

    ```bash
    pnpm add @lancedb/lancedb
    ```
  </Tab>
  <Tab title="Qdrant">
    Required for `QdrantResource`.

    ```bash
    pnpm add @qdrant/js-client-rest
    ```
  </Tab>
  <Tab title="SSH">
    Required for `SSHResource`.

    ```bash
    pnpm add ssh2
    ```
  </Tab>
  <Tab title="Email">
    Required for `EmailResource` (IMAP read, SMTP send, MIME parsing).

    ```bash
    pnpm add imapflow mailparser nodemailer
    ```
  </Tab>
</Tabs>

## Verify

```ts
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:

```bash
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`.