Virtual Filesystem (FUSE Mount)
The FUSE mount gives you instant access to every file in a Crab repository without downloading anything upfront. Files appear at their full size in directory listings, but content is fetched from cloud storage only when you actually read them. It's like having the entire repository on disk, but only paying for what you touch.
Why Use a Virtual Filesystem?
Hydration works well when you know which files you need ahead of time. But sometimes you want to:
- Browse a large repository without deciding what to hydrate first
- Run tools that scan directories (IDEs, search, build systems) without hydrating everything
- View another branch without switching your working tree
- Access a remote repository without cloning it at all
The FUSE mount handles all of these by presenting files on-demand.
How It Works
When you mount a repository:
- Directory structure is instant — Crab builds a snapshot from git's tree objects (lightweight metadata).
lsandfindwork immediately. - File reads are on-demand — The first read of a file triggers chunk downloads. Subsequent reads are served from cache.
- Writes go to an overlay — Modified files are stored locally in an overlay layer, not pushed back to the remote.
Quick Start
Mount a remote repository
No prior clone needed — mount directly from cloud storage:
crab mount --repo crab://bucket/ml-models --mountpoint /mnt/modelsFiles are immediately accessible:
ls /mnt/models/
cat /mnt/models/config.json
python -c "import torch; m = torch.load('/mnt/models/weights.bin')"Mount a local branch
View another branch without switching your working tree:
crab mount --repo . --mountpoint /tmp/feature-view --ref=feature-branchUnmount
crab unmount --mountpoint /mnt/modelsRuntime Behavior
Multiple mounts can share local cache resources, so reading a file through one mount can make the same content faster to read elsewhere. Crab also prioritizes interactive reads over background prefetching, which keeps browsing responsive while larger files are loading.
You do not need to manage a background service manually. crab mount starts
what it needs, and unmounting the last active mount releases those resources.
Multiple Mounts
You can have multiple mounts active simultaneously:
crab mount --repo crab://bucket/repo-a --mountpoint /mnt/a
crab mount --repo crab://bucket/repo-b --mountpoint /mnt/b
crab mount --repo . --mountpoint /tmp/main-view --ref=mainAll share the same coordinator, cache, and hydration pool.
Managing Mounts
List active mounts
crab mount listCheck mount health
crab mount status --mountpoint /mnt/modelsSwitch branch without unmounting
crab mount switch --mountpoint /mnt/models --ref=experiment-v3Force refresh from remote
crab mount refresh --mountpoint /mnt/modelsRead-Only vs. Read-Write
By default, mounts support writes through an overlay layer. Written files are stored locally — they're not pushed back to the remote. This is useful for tools that need to write temporary files.
For a strict read-only mount:
crab mount --repo crab://bucket/repo --mountpoint /mnt/view --read-onlyPerformance Characteristics
| Operation | Latency | Notes |
|---|---|---|
ls / directory listing | Instant | Served from in-memory snapshot |
| First read of a file | Network-dependent | Downloads chunks from cloud |
| Subsequent reads | Local disk speed | Served from chunk cache |
| Small files (< 1 MB) | ~50-200ms first read | Single chunk fetch |
| Large files (> 1 GB) | Streaming | Chunks fetched as read progresses |
Prerequisites
macOS
brew install macfuseA reboot is required after the first install.
Linux (Ubuntu/Debian)
sudo apt-get install fuse3 libfuse3-devLinux (Fedora/RHEL)
sudo dnf install fuse3 fuse3-develVerify FUSE is available
ls /dev/fuseLimitations
- Network required for uncached reads — First access to a file needs cloud connectivity. Cached files work offline.
- Writes are local-only — The overlay doesn't push back to the remote. Use a real working tree for commits.
- First-access latency — The first read of a large file has download latency. Use
crab fetchto pre-warm if needed. - macOS/Linux only — Windows is not yet supported (no FUSE equivalent).
Mount vs. Hydrate: When to Use Which
| Use Case | Recommendation |
|---|---|
| Working on specific files (editing, training) | Hydrate — full local copy, no latency |
| Browsing / exploring a large repo | Mount — instant access, no upfront download |
| CI pipeline with known file list | Hydrate with manifest — predictable, cacheable |
| Viewing another branch | Mount — no working tree changes |
| IDE / editor access | Mount for browsing, hydrate for editing |
Troubleshooting
Stale mount (Transport endpoint not connected)
If the coordinator crashed:
crab unmount --all
# If that fails, use OS tools:
# Linux: fusermount3 -u /mnt/stale-mount
# macOS: umount -f /mnt/stale-mountPermission denied on mountpoint
sudo mkdir -p /mnt/models && sudo chown $USER /mnt/modelsSlow first access
Pre-warm the cache for files you'll need:
crab fetch --include 'models/**'CLI Reference
For complete command syntax, all subcommands, and options, see the crab mount reference.