FUSE

Prerequisites

Node.js 20+
pnpm (recommended, npm and yarn also work, but the FUSE binding’s install script needs extra configuration with pnpm).

System FUSE

Install the OS-level FUSE kernel support first:

macOS FUSE Setup, macFUSE + kernel extension + Apple Silicon recovery mode steps.
Linux FUSE Setup, fuse3 install and /etc/fuse.conf.

Install the Node Binding

The Node package (@struktoai/mirage-node) ships FUSE support via an optional peer dependency on @zkochan/fuse-native, the pnpm author’s actively-maintained fork that works on Node 20+ and supports both macOS and Linux (thanks to @zkochan).

pnpm add @struktoai/mirage-node @zkochan/fuse-native

Non-FUSE users don’t need @zkochan/fuse-native, the base @struktoai/mirage-node package works without it. Only install the binding when you want a real mountpoint.

Allow pnpm to run the install script

@zkochan/fuse-native compiles native code on install. pnpm blocks install scripts by default, allow this one explicitly in pnpm-workspace.yaml:

onlyBuiltDependencies:
  - '@zkochan/fuse-native'

Or, if you’re not using a pnpm workspace, in package.json:

{
  "pnpm": {
    "onlyBuiltDependencies": ["@zkochan/fuse-native"]
  }
}

macOS 4+ Symlink Workaround

macOS
Linux

macFUSE 4 ships libfuse.2.dylib instead of the legacy libosxfuse.2.dylib that @zkochan/fuse-native was built against. Create a one-time symlink:

sudo ln -sf /usr/local/lib/libfuse.2.dylib /usr/local/lib/libosxfuse.2.dylib
pnpm rebuild @zkochan/fuse-native

No workaround needed on Linux, @zkochan/fuse-native links against libfuse3 directly.

Verify

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

const ws = new Workspace(
  { '/data/': new RAMResource() },
  { mode: MountMode.WRITE, fuse: true },
)

await ws.execute('echo hello | tee /data/x.txt')
console.log('mountpoint:', ws.fuseMountpoint)

// Any tool (ls, cat, external subprocess) can now see /data/x.txt under the mountpoint.
await ws.close() // auto-unmounts

If ws.fuseMountpoint prints a /tmp/mirage-fuse-XXXXXX path and no error is thrown, the binding is wired up correctly.

FUSE on Node has two important runtime constraints, a same-process deadlock when nativeExec runs against a mount the current process owns, and that fs-monkey can’t patch ESM node:fs imports. See TypeScript Limitations for details and workarounds.

Getting Started

Agents

Resources

Prerequisites

System FUSE

Install the Node Binding

Allow pnpm to run the install script

macOS 4+ Symlink Workaround

Verify

​Prerequisites

​System FUSE

​Install the Node Binding

​Allow pnpm to run the install script

​macOS 4+ Symlink Workaround

​Verify

Prerequisites

System FUSE

Install the Node Binding

Allow pnpm to run the install script

macOS 4+ Symlink Workaround

Verify