Repository navigation
modalfs 0.1.0
The first release of modalfs: mount Modal Volumes as local folders on macOS and Linux. Files stream on demand, edits upload in the background, and mounting never starts any Modal compute.
modalfs is an independent project, not affiliated with or endorsed by Modal Labs. It uses the same API as Modal's SDKs, parts of which are undocumented. Read Limitations and the known issues before relying on it for data you care about. (简体中文说明)
What's in it
- Mount any Volume v2 as a folder. macOS uses its built-in NFS client (no macFUSE or kernel extension), Linux uses FUSE. Reads fetch only the 8 MiB blocks they touch, and sequential reads prefetch ahead.
- Small edits upload small. Changing 4 KiB of a 100 GiB file uploads one 8 MiB block. Renames copy the block list on Modal's side and move no data. Large copies upload while they're still being written.
- Your writes aren't lost. Every write is journaled on disk until Modal has it, survives crashes and power loss, and is replayed at the next mount. If a file changed on Modal while you were editing it, both versions are kept.
- A mount never moves. Each mount is pinned to its account and volume ID, so switching Modal CLI profiles, or renaming or recreating a volume, never points it at different data.
- Encrypted volumes (optional). File contents, names and labels are encrypted on your machine before they reach Modal.
- Remote downloads (off by default). Paste a link and a Modal Function downloads it straight into a volume, with live speed and cost. It's the only feature that runs compute on Modal.
- A desktop app and a complete CLI. Both drive the same background daemon. Closing the window never unmounts anything. The UI is in English, 繁體中文 and 简体中文.
Downloads
| File | For |
|---|---|
modalfs-0.1.0-macos.zip |
The Mac app, macOS 13 or later, Apple Silicon and Intel. The CLI is inside it, in modalfs.app/Contents/Resources/bin/modalfs. |
modalfs-gui-0.1.0-linux-amd64.tar.gz |
The desktop app for Linux on x86-64: Ubuntu 24.04 or newer, WebKitGTK 4.1 (libwebkit2gtk-4.1-0) and FUSE 3 (fuse3). |
modalfs-0.1.0-{darwin,linux}-{arm64,amd64}.tar.gz |
The CLI alone, for servers, ARM64 Linux or older distributions. modalfs ui serves the same interface in a browser. Linux needs FUSE 3. |
SHA256SUMS |
Checksums: shasum -a 256 -c SHA256SUMS --ignore-missing |
First launch on macOS: the app is signed ad hoc, not notarized, so macOS asks before opening it the first time. On macOS 15 and later, try to open it once, then click Open Anyway in System Settings → Privacy & Security. On macOS 13 and 14, right-click modalfs.app in Finder and choose Open.
Good to know
- Modal has no file locks or compare-and-swap. modalfs looks for a change on Modal before each commit and keeps a conflict copy, but avoid having a Modal container and your machine write the same file at the same time.
- Modal ignores file modes: files saved through modalfs are
0666inside containers, so runchmod +xthere for scripts. Symlinks can't be read or created through Modal's API. - On macOS, a copy larger than the cache size pauses in long stretches; keep the cache size above your largest copy for now.
- BitTorrent downloads upload to peers, which Modal's terms (§1.5) forbid. Everything you do through modalfs falls under Modal's Terms of Service.
Found a problem? Open an issue.