Get started

BrewFS is a Rust-native distributed filesystem built for multi-agent collaborative read/write workloads, RandRW-heavy access patterns, and object-storage-backed infrastructure.

Quick start

LocalFS + SQLite is the simplest way to run BrewFS and inspect its data layout.

1. Prerequisites. Rust, FUSE, a mount directory and data directory, on Linux (FUSE mounting currently supports Linux only).
2. Clone the repository and build with cargo build --release.
3. Mount with the LocalFS + SQLite backend.
4. Read, write, and inspect files through normal paths.

git clone https://github.com/brewfs/brewfs
cd brewfs
cargo build --release

mkdir -p /tmp/brewfs-mnt /tmp/brewfs-data

cargo run -p brewfs -- mount /tmp/brewfs-mnt \
  --data-backend local-fs \
  --data-dir     /tmp/brewfs-data \
  --meta-backend sqlx \
  --meta-url     sqlite:///tmp/brewfs-meta.db

echo "hello brewfs" > /tmp/brewfs-mnt/hello.txt
cat /tmp/brewfs-mnt/hello.txt
ls -lh /tmp/brewfs-mnt

From here, move to S3-compatible object storage and metadata backends such as Redis, etcd, TiKV, or PostgreSQL.

Where to go next

• Getting Started — installation, mounting, configuration, CLI.
• Architecture — FUSE, VFS, metadata, Chunk / Block / Slice, object backend.
• Benchmarks — RandRW, metadata-heavy, multi-agent scaling, reproducibility.
• Benchmark Methodology — Redis + RustFS setup, fio profiles, published results, and fair-comparison rules.
• POSIX Testing — xfstests, pjdfstest, LTP, stress-ng coverage, runners, and explicit limits.
• Performance Tuning — cache, FUSE, S3, writeback, and metadata profiles.
• Kubernetes Operator — deploy and consume BrewFS mounts in Kubernetes.
• Operations — observability, control plane, GC, testing, and deployment.
• Developers — SDK, examples, backend adapter guides, contributing.
• Design Notes — BrewFS vs JuiceFS, agent workload design, known limitations.