crab daemon

Run and manage DaemonService mode, Crab's persistent multi-repo virtual filesystem service.

DaemonService mode is separate from the default coordinator-style crab mount workflow. Use it when you want to register repositories by name and have a long-running service mount and reconcile them.

For a conceptual comparison, see Mount Modes.

Synopsis

crab daemon [OPTIONS]
crab daemon [OPTIONS] add-repo --name <NAME> --remote <URL> [--branch <BRANCH>] --mount-root <PATH> [--backend <BACKEND>]
crab daemon [OPTIONS] remove-repo --name <NAME>
crab daemon [OPTIONS] list [--json]
crab daemon [OPTIONS] status --name <NAME> [--json]
crab daemon [OPTIONS] set-refresh --name <NAME> --interval <SECONDS>
crab daemon [OPTIONS] remount --name <NAME> [--clean-overlay]
crab daemon [OPTIONS] fetch --name <NAME>
crab daemon [OPTIONS] enable --name <NAME>
crab daemon [OPTIONS] disable --name <NAME>
crab daemon [OPTIONS] commit --name <NAME> -m <MESSAGE> [--push] [--json]

Top-Level Options

Description

With no subcommand, crab daemon starts the service in the foreground. The service reads the repo registry, mounts enabled repos, and continues reconciling the registry until it receives SIGINT or SIGTERM.

crab daemon

For a persistent workstation, shared host, desktop integration, or agent environment, run this process under your normal service supervisor.

Registry Model

DaemonService repos are registered before they are mounted. A repo registration contains:

Daemon state lives under ~/.crab/daemon unless --root is provided.

The NFS control endpoint is private, exists only while the mount is live, and lets daemon commands drain pending writes and update the live snapshot safely. Registrations created before backend selection was introduced remain on FUSE.

Subcommands

add-repo

Register a repository for the daemon to manage.

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

The mount path will be /mnt/repos/ml-models.

Re-running add-repo with an existing name updates its registration. The running daemon detects backend and other configuration changes and remounts the repository.

remove-repo

Deregister a repository and unmount it if the service is running.

crab daemon remove-repo --name ml-models

list

List registered repositories.

crab daemon list
crab daemon list --json

Text output includes the repo name, redacted remote, branch, refresh interval, enabled state, backend, and mode.

status

Show status for one registered repo.

crab daemon status --name ml-models
crab daemon status --name ml-models --json

Status includes repo configuration, HEAD state when available, mount state, and overlay dirty count.

set-refresh

Update the refresh interval stored for a repo.

crab daemon set-refresh --name ml-models --interval 60

remount

Unmount and remount a repo with a fresh snapshot.

crab daemon remount --name ml-models

Discard local overlay changes before remounting:

crab daemon remount --name ml-models --clean-overlay

Use --clean-overlay only when you intentionally want to discard local writes that have not been committed.

fetch

Trigger an immediate fetch for a registered repo.

crab daemon fetch --name ml-models

enable and disable

Disable a repo without deleting its registration:

crab daemon disable --name ml-models

Enable it again:

crab daemon enable --name ml-models

The running daemon reconciles enabled and disabled repos from the registry.

commit

Commit copy-on-write overlay changes for a daemon-managed repo.

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

During commit, Crab freezes overlay writes, checks that the tracked branch has not moved since the mounted snapshot, creates a Git commit from the overlay, refreshes the live snapshot, and clears the overlay after a successful local commit. NFS commits first drain unstable writes through the mount's private control endpoint. If --push fails, the local commit is recorded and the overlay remains available for recovery.

Backend Prerequisites

Check the selected backend against the final mountpoint before registration:

crab mount doctor --backend nfs --mountpoint /mnt/repos/ml-models
crab mount doctor --backend fuse --mountpoint /mnt/repos/ml-models

NFS starts one loopback NFSv3 server per registered repository and mounts it through the operating system's native NFS client. FUSE uses an in-process FUSE session. Both use the same daemon-owned clone, snapshot, overlay, hydration, refresh, and publish pipeline.

Common Workflow

Register repos:

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

Start the service:

crab daemon

Inspect state:

crab daemon list
crab daemon status --name repo-a

Publish local overlay changes:

crab daemon commit --name repo-a -m "Update generated artifacts" --push

Stop the foreground service with Ctrl+C, or stop it through your supervisor.

When to Use crab daemon

Use DaemonService mode when:

• The same repos should be mounted repeatedly.
• Scripts or applications should address repos by stable names.
• A desktop app, agent runtime, or service supervisor owns the lifecycle.
• You need a persistent registry with enable, disable, fetch, status, and remount operations.

Use crab mount instead when you want a quick one-off mount by path.

Related Commands

• crab mount - default coordinator-style mount workflow.
• Mount Modes - compare coordinator-style mounts and DaemonService mode.
• Mount Management - day-to-day mountpoint operations.