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
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
"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.fuseMountpointsmaps each prefix to its folder, a freshmirage-fuse-*directory under the OS temp folder unless the mount setsmountpoint.- The folder follows the mount’s mode: a
readmount cannot be written.
Backends
Each mount picks its ownbackend:
Behavior
- Files of unknown size. API mounts (Slack, Trello, …) report
0 bytes until a file is opened.
ls -l,duandfind -sizeshow 0, andtarandrsynccopy such files empty.cat,grep,cpandwc -cread the full content throughfuse, and read the file as empty throughnfsandfskit, 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
chmodandchownset are for display. Mount modes and policy decide access, never the kernel. - Extended attributes.
getfattrandsetfattrin 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 amountpointanywhere 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.
fskitthrows on other OSes; there is no automatic choice between it andfuse.