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.

Install

1

Install FUSE for the OS

Follow the Linux, macOS or Windows guide. Windows is experimental.
2

Add the extra

Mount a folder

  • The constructor returns once every folder is live, so the folder is ready inside the with block. Leaving the block unmounts it.
  • ws.fuse_mountpoints maps each prefix to its folder, a fresh /tmp/mirage-* directory unless the mount sets mountpoint.
  • The folder follows the mount’s mode: a read mount cannot be written.
The folder is served on the workspace’s event loop. A synchronous open() on that loop, or a subprocess started with cwd inside the folder, waits on a call only that loop can answer. Use asyncio.to_thread, or pass the folder’s paths as arguments. A workspace first used in a with block, or run by a WorkspaceRunner or the server, has a loop of its own, so blocking calls are fine there.

Backends

Each mount picks its own backend:
macOS allows one FUSE mount per process: a second one fails with fuse: cannot register signal source. 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. On Windows, fuse also shows the size at once.
  • 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

On Apple Silicon the macFUSE kernel extension needs a reduced-security boot. With macFUSE 5 on macOS 15.4+, backend: fskit serves the same folder through FSKit instead, with no kext:
  • The folder is a volume under /Volumes. macOS creates it and removes it on unmount, and 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. Byte stores (RAM, Disk, Redis, S3, GridFS) and Linear qualify; Mirage warns at mount time about any other.
  • fskit raises on other OSes; there is no automatic choice between it and fuse.
Treat FSKit mounts as read-mostly. The macFUSE FSKit layer can write new files as NUL bytes with no error, so Mirage warns on a writable FSKit mount; use fuse for writes. Two more open macFUSE issues: a binary on the volume runs only after it has been read once (#1181), and new entries in the volume root may not appear in a live mount (#1165).
examples/python/fuse/fskit.py runs an FSKit mount end to end: the size warning, reads, and each write with its result.