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
2
Add the extra
Mount a folder
- The constructor returns once every folder is live, so the folder is ready
inside the
withblock. Leaving the block unmounts it. ws.fuse_mountpointsmaps each prefix to its folder, a fresh/tmp/mirage-*directory unless the mount setsmountpoint.- The folder follows the mount’s mode: a
readmount cannot be written.
In async code, never block the workspace's loop on the folder
In async code, never block the workspace's loop on the folder
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 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. On Windows,fusealso 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
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
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 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. Byte stores (RAM, Disk, Redis, S3, GridFS) and Linear qualify; Mirage warns at mount time about any other.
fskitraises on other OSes; there is no automatic choice between it andfuse.
examples/python/fuse/fskit.py
runs an FSKit mount end to end: the size warning, reads, and each write with
its result.