Verifiable offline-first storage

A filesystem that keeps working when the network does not

NexusFS represents every change as a signed operation rather than a state diff, so devices can write while disconnected and reconcile deterministically later. Content is addressed by hash, namespace state is a CRDT, and remote data is verified before it is trusted — not after.

Try It In Your Browser Read The Docs Quick Start

Current Baseline All eight milestones: encrypted, replicated, provable

Two nodes converge over QUIC with every operation and chunk verified before it is accepted, content is encrypted at rest without breaking that verification, replication adapts to the device's power and heat, and the state root is a Merkle commitment — so any single file can be proved present, or proved gone, to someone holding no filesystem at all. Content is sealed per recipient, so a replica can hold every byte of a file and still not be able to read it.

Binary shape Single executable

Replication model Oplog first

Verification Signatures + commitments

Target Edge + offline-first

Milestone 8 of 8 complete

Hashing BLAKE3, content-addressed

At rest XChaCha20-Poly1305, sealed per recipient

Test suite 237 tests, clippy clean

Licence Apache-2.0 OR MIT

Design decisions

Five choices that shape everything else

Operations, not diffs

A write records what the user meant — create this name in this directory — rather than the resulting bytes. Intent can be replayed in any order and still land in the same place; a diff cannot.

Inode ids derived from operations

A new inode's id is a hash of the operation that allocated it, so every replica names it identically without consulting a shared counter. Two offline devices creating the same path produce two distinct inodes, which is precisely the conflict the merge rules then resolve.

Conflicts are renamed, never dropped

Concurrent writes to one name both survive. The lower dot keeps the plain name, the other gains a suffix derived from its author and timestamp — a value every replica computes the same way, so no round trip is needed to agree.

Verify before trusting

Signatures are checked before an operation can touch state, and chunk hashes are checked before content is stored. A peer cannot hand you bytes that do not match the hash you asked for.

Under pressure, keep the map and drop the cargo

An operation is a few hundred bytes; the content it names can be megabytes. So a device short on power keeps taking operations and defers the bytes. It still knows what exists, where, and at what version — and fetches any particular file once power returns. Falling behind on content is recoverable; falling behind on the namespace is not.

System Shape

Layered for integrity, not ceremony

NexusFS separates immutable content, mutable namespace state, transport, and optional facades. That keeps the local state machine deterministic while letting the replication layer and future proof systems evolve independently.

Core: object formats, chunking, state transitions
Storage: blob and KV backends with clean traits
Protocol: shared operation and network message types
Net: oplog-first synchronization, blob fetch, push notification
Proofs: a Merkle commitment over the inode map, checkable offline
Facades: admin console and an S3-compatible API. A POSIX mount is new scope rather than a debt — M2 asked for one facade

See the architecture page

NexusFS architecture layers from clients and peers through core, storage, crypto, and proof systems.

Build Surface

Designed to ship as a project, not just a paper

Research Tracks

Grounded implementation, ambitious horizon

Quick start

Files in and out of a real repository

cargo build -p nexusfs
cp examples/nexusfs.toml ./nexusfs.toml

cargo run -p nexusfs -- mkdir --config ./nexusfs.toml /docs
echo "hello nexus" > /tmp/a.txt
cargo run -p nexusfs -- put --config ./nexusfs.toml /tmp/a.txt /docs/a.txt
cargo run -p nexusfs -- ls  --config ./nexusfs.toml /docs
cargo run -p nexusfs -- cat --config ./nexusfs.toml /docs/a.txt

Every mutating command builds a signed operation and applies it through the same pipeline replication will use, so the CLI is not a shortcut around the state machine — it is a client of it. Run nexusfs daemon for the admin console on 127.0.0.1:7070, which shows the head, state root, storage accounting and recent operations.

Documentation

Public docs and engineering specs, both included

The repo now includes a dedicated `documentation/` folder for clean onboarding and a deeper internal `docs/` set for protocol and research detail.

Browse Public Docs See The Roadmap