Mount Modes

Crab has two supported ways to run virtual filesystem mounts:

• Coordinator-style mounts: the default crab mount workflow. Use this when you want to mount a repository at a path now, with no repo registration step.
• DaemonService mode: the crab daemon workflow. Use this when you want a long-running service to manage a named set of repositories.

Both modes expose repositories through FUSE, fetch file content on demand, and use a local copy-on-write overlay for writes. The difference is ownership: coordinator-style mounts are mountpoint-oriented and ephemeral; DaemonService is repo-name-oriented and persistent.

Quick Recommendation

If you are unsure, start with coordinator-style mounts. Move to DaemonService when the mount set itself becomes something you want to manage.

Architecture at a Glance

Coordinator-Style Mounts

Coordinator-style mounts are the default behavior for crab mount on Unix when you do not pass --foreground.

crab mount --repo crab://bucket/ml-models --mountpoint /mnt/models

The CLI validates the request, creates the mountpoint if needed, then sends the mount request to a local coordinator process. If the coordinator is not running, Crab starts it automatically. The coordinator owns active FUSE sessions, shared chunk cache access, hydration workers, and runtime mount state.

State and Paths

The hash is derived from the source, so repeated mounts of the same remote or local path can reuse local state.

Lifecycle

1. User runs crab mount.
2. The CLI sends an IPC request to the coordinator.
3. The coordinator runs the mount pipeline: clone or open git metadata, build a snapshot, open the overlay, create the resolver, start hydration workers, and mount FUSE.
4. The CLI returns after the mount is ready.
5. crab unmount --mountpoint <path> removes the mount.
6. When the last mount is removed, the coordinator shuts down.

Use --foreground when you want the CLI process itself to own the mount:

crab mount --repo crab://bucket/repo --mountpoint /mnt/view --foreground

Foreground mode is useful for debugging, but it does not share runtime resources with other coordinator mounts.

Operations

Pros

• No registration step.
• Best default path for one-off and interactive use.
• Easy to switch a mount between branches.
• Multiple active mounts share one coordinator, cache, and hydration pool.
• One active mount is allowed per repo cache, so each cached checkout and snapshot database has a single owner.
• Overlay inspection is mountpoint-oriented and direct: diff, export, commit, and reset.
• Minimal persistent configuration.

Cons

• Active intent is tied to mountpoints, not stable repo names.
• Less convenient for "these repos should always be mounted" environments.
• Less suitable for boot-time or supervisor-managed workflows.
• If the coordinator exits unexpectedly, active mounts must be cleaned up and recreated.

DaemonService Mode

DaemonService mode is the crab daemon command family. It is not legacy code. It is a different operating model for persistent multi-repo mounts.

Register repos by name:

crab daemon add-repo \
  --name ml-models \
  --remote crab://bucket/ml-models \
  --branch main \
  --mount-root /mnt/repos

Start the service:

crab daemon

The repo is mounted at:

/mnt/repos/ml-models

The daemon stores a registry, periodically reconciles it, and mounts every enabled repo. If you add or remove repos while the daemon is running, the service loop picks up the registry change on its next sync.

State and Paths

Use --root <path> when you want the daemon state somewhere else:

crab daemon --root /srv/crab-daemon
crab daemon --root /srv/crab-daemon list

Lifecycle

1. User registers repos with crab daemon add-repo.
2. crab daemon starts the service and reads the registry.
3. The service reconciles registered repos every few seconds.
4. Enabled repos are mounted at <mount-root>/<name>.
5. Removed or disabled repos are unmounted.
6. On shutdown, the daemon tears down all managed mounts.

This is a service model. In production or shared environments, run it under a supervisor such as systemd, launchd, or the process manager used by your desktop or agent runtime.

Operations

Pros

• Repos are named and persistent.
• Better fit for machines that should keep a stable set of repos mounted.
• Easier to integrate with desktop apps, agents, and supervised services.
• Registry-backed list, status, enable, disable, fetch, and remount commands are easier to automate than mountpoint discovery.
• Stable per-repo state paths make operational debugging predictable.

Cons

• Requires repo registration before use.
• More persistent state to manage.
• Less convenient for quick branch views or one-off browsing.
• Overlay inspection is currently less rich than coordinator-style mounts: status reports dirty counts, and commit/remount workflows are repo-name based.
• Service lifecycle matters. If the daemon is not running, registered repos are not actively mounted.

Copy-on-Write and Commit-Back

Both modes use the same write model:

1. Reads check the overlay first.
2. If a path is not in the overlay, reads fall back to the mounted snapshot and on-demand hydration.
3. The first write to a base file promotes that file into the overlay.
4. New files, deletions, renames, symlinks, and directory changes are recorded in overlay state.
5. Nothing is pushed automatically.

To publish coordinator-style overlay changes:

crab mount diff --mountpoint /mnt/models
crab mount commit --mountpoint /mnt/models -m "Update generated artifacts"
crab mount commit --mountpoint /mnt/models -m "Update generated artifacts" --push

To publish DaemonService overlay changes:

crab daemon status --name ml-models
crab daemon commit --name ml-models -m "Update generated artifacts"
crab daemon commit --name ml-models -m "Update generated artifacts" --push

During commit, Crab freezes overlay writes, checks that the tracked base ref has not moved, creates a Git commit from the overlay contents, refreshes the snapshot, and clears the overlay after a successful local commit. If the push step fails, the local commit is recorded and the overlay remains available for recovery.

Use read-only mode when applications must not write:

crab mount --repo crab://bucket/repo --mountpoint /mnt/browse --read-only

Unmount or run crab mount switch before opening another view of the same repo. Crab intentionally keeps each repo cache owned by one active mountpoint at a time.

Choosing a Mode

Common Patterns

Temporary multi-repo workspace

crab mount --repo crab://bucket/repo-a --mountpoint /mnt/a
crab mount --repo crab://bucket/repo-b --mountpoint /mnt/b
crab mount --repo . --mountpoint /mnt/current-main --ref main

Use this when the set of repos changes often or is specific to one task.

Persistent workstation setup

crab daemon add-repo --name repo-a --remote crab://bucket/repo-a --branch main --mount-root /mnt/repos
crab daemon add-repo --name repo-b --remote crab://bucket/repo-b --branch main --mount-root /mnt/repos
crab daemon

Use this when users or tools expect the same mount paths to exist every day.

Agent or desktop integration

Use DaemonService when a higher-level app needs stable repo names, status polling, and service lifecycle control. Use coordinator-style mounts when the app is simply invoking crab mount for a user-selected path.

Troubleshooting by Mode

Related Reference

• crab mount - coordinator-style mount command.
• crab daemon - DaemonService command family.
• Mount Management - day-to-day coordinator mount operations.