Skip to main content
Set backend: fuse on a mount and Mirage also shows it as a real folder on this computer, so editors, git and other programs can read and write it. The FUSE overview lists what each OS supports. FUSE runs on Linux and macOS from Node; a browser or a Worker cannot mount a folder.

Install

1

Install FUSE for the OS

Follow the Linux or macOS guide.
2

Add the binding

@zkochan/fuse-native is an optional peer that compiles native code on install. First allow pnpm to build it, in pnpm-workspace.yaml:
pnpm-workspace.yaml
Outside a pnpm workspace, put the same list under "pnpm" in package.json. Then add it:
3

On macOS with macFUSE 4, link the library

macFUSE 4 ships libfuse.2.dylib, and the binding links the older name. Link it once, then rebuild:

Mount a folder

  • Mounting is async: await ws.fuseReady() resolves once every folder is live, and rejects if one fails. ws.close() unmounts.
  • ws.fuseMountpoints maps each prefix to its folder, a fresh mirage-fuse-* directory under the OS temp folder unless the mount sets mountpoint.
  • The folder follows the mount’s mode: a read mount cannot be written.
The folder is served on the mounting process’s event loop. A synchronous call on it from that process, such as readFileSync, statSync or execFileSync('cat', ...), waits on a call only that loop can answer and hangs the mount. Use the async fs API and async child processes, or own the mount from a child process (examples/typescript/fuse/helper.ts). Other processes are unaffected.

Backends

Each mount picks its own backend:
macOS allows one FUSE mount per process: a second one fails. Put a kernel backend on one mount, or run the others in separate processes.

Behavior

  • Files of unknown size. API mounts (Slack, Trello, …) report 0 bytes until a file is opened. ls -l, du and find -size show 0, and tar and rsync copy such files empty. cat, grep, cp and wc -c read the full content through fuse, and read the file as empty through nfs and fskit, which Mirage warns about.
  • Symlinks. Links made with ln -s, in the shell or in the folder, show as real symlinks and resolve inside the folder.
  • Permissions. The mode bits chmod and chown set are for display. Mount modes and policy decide access, never the kernel.
  • Extended attributes. getfattr and setfattr in the folder read and write the same attributes as the shell, on every VFS.

FSKit on macOS

With macFUSE 5 on macOS 15.4+, backend: 'fskit' serves the folder through FSKit instead of the kernel extension:
  • The folder is a volume under /Volumes. macOS creates it and removes it on unmount, and Mirage refuses a mountpoint anywhere else.
  • Every VFS on an FSKit mount must know its files’ sizes: a file that stats 0 before it is opened reads as empty. Mirage warns at mount time about any VFS that cannot.
  • fskit throws on other OSes; there is no automatic choice between it and fuse.
From TypeScript, FSKit is read-mostly and experimental. New files can be written as NUL bytes, and create, mkdir and rename return ENOSYS, because the binding cannot install the macOS callbacks FSKit needs for new names. A hung FSKit volume can block the system’s mount table until the macFUSE FSKit process is killed. Use fuse for anything long-running or written to. examples/typescript/fuse/fskit.ts runs the end-to-end check.