vaultfs

FUSE filesystem for git-backed vaults.

vaultfs mounts a directory of git-backed markdown files as a native Linux filesystem. Every file write through the mount produces a git commit — without requiring a daemon, HTTP API, or async runtime.

Designed for multi-container sandbox environments where multiple agents read and write the same shared vault directory concurrently.

Usage

vaultfs --root /data/kb --mountpoint /workspace

Flag	Default	Description
--root	(required)	Path to vault git repo
--mountpoint	(required)	Mount path
--log-file	~/.vaultfs/fuse.log	Log file path
--allow-other	false	Allow other UIDs (needs /etc/fuse.conf)

How it works

Agent shell (cat, echo, grep, sed, mv, rm)
       │
       ▼  FUSE protocol
┌──────────────────────┐
│      vaultfs         │  Rust binary (~1.8 MB)
├──────────────────────┤
│  open()  → read file │  Direct filesystem I/O
│  write() → buffer    │  Scratch file working copy
│  flush() → git commit│  SHA-256 dedup, git2 in-process
│  flock()             │  Multi-container coordination
└──────────┬───────────┘
           │
           ▼
┌──────────────────────────┐
│  /data/kb                │  Git repo of .md files
│  └── .vaultfs/git.lock   │  Exclusive file lock
└──────────────────────────┘

Open-to-close consistency

1. open(path) — reads file from vault into a scratch file, records SHA-256
2. write(fh, data) — accumulates bytes in the scratch file
3. flush(fh) — if dirty: SHA-256 dedup check → flock() → write to disk → git add → git commit → unlock
4. release(fh) — cleans up scratch file

Multi-container safety

Multiple vaultfs instances on the same shared volume serialize git commits via flock(LOCK_EX) on .vaultfs/git.lock. The lock is held only during the git add + git commit sequence (milliseconds). Reads never need a lock.

Content dedup

If flush() detects that the content hash matches the open-time hash, no write or git commit occurs. This avoids no-op commits from tools like touch or idempotent writes.

Build

cargo build --release
# Binary at target/release/vaultfs (~1.8 MB musl)

Dependencies

• fuser — Rust FUSE bindings (libfuse3)
• git2 — libgit2 bindings for in-process git operations
• clap — CLI argument parsing
• sha2 — SHA-256 content dedup
• fs2 — flock-based file locking
• tracing — structured logging

Out of Scope

• Semantic / vector search
• Ontology validation
• Base-hash conflict detection (last-write-wins)
• Extended attributes / POSIX file locking / symlinks