NomadFS

Zig & Oriel · Linux desktop · Android

Your devices,
one filesystem.

NomadFS shares folders across your laptop, phone and home server. Every device sees every shared folder at once; a file only travels when someone opens it. Add a swarm folder that all of them write to, and mount it all on Linux like any other folder.

Download Get started View on GitHub
transport
Noise XXpsk3 · Yamux · TCP
NomadFS on the Linux desktop: browsing a phone's Camera folder from the desktop, with name, size and modified columns
NomadFS on an Android phone: the Browse section lists the desktop with one shared folder

01 · what it does

Everything you share, from every device

Not a cloud and not a full mirror. Your devices keep their own files and lend them to each other on request.

Shared folders, on demand

Share a folder and every device can browse it right away. Only the listing travels; a file's bytes move when someone opens it, and only the blocks of the part being read.

A swarm folder

One folder every device reads and writes. Add, rename and delete from anywhere; edits merge without a server, and two edits at once keep both, the other as a conflict copy.

A Linux mount

Every device's shares appear under <mount>/<device>/<share>, read-only, and the swarm folder under <mount>/Swarm, writable from any app or file manager.

One-time invites

Join a device with a code or by scanning its QR code with the phone camera. The invite works once, for ten minutes, and the swarm key travels encrypted: it is never shown.

Encrypted, device to device

Devices talk over Noise XXpsk3 sessions keyed by your swarm, with Ed25519 device identities you can list and revoke. Every block is checked against its hash when it arrives.

An app for desktop and phone

Browse devices, preview images, video, audio, PDF and text, manage the swarm folder, mount from a tab or the tray, connect devices, and drop notes between them. Built with Oriel.

02 · the app

Night-caravan cartography

The same app on the Linux desktop and on Android phones: a drawer on wide windows, a navigation bar on phones.

The swarm folder on the desktop: a folder, three files, who added each one, and a conflict copy kept beside notes.md
Swarm folder · who added what, synced with the other device, a conflict kept as a copy
Connect devices on the desktop: create an invite, join with an invite code or scan a QR code, and rename this device
Connect devices · create a one-time invite, or join with a code or a QR scan
The swarm folder on a phone-sized window, with New folder and Add file
Swarm · on a phone
Browse on an Android phone, showing the desktop and its shared folder
Browse · a Xiaomi phone sees the desktop

on the phone

The same app, in your pocket

  • One section at a time, picked from a navigation bar: Browse, Shared, Connect, Swarm, Settings.
  • Share the camera roll, Pictures, Documents or Download through the system folder picker.
  • Scan an invite with the rear camera to join a swarm in one step.
  • Full-screen previews of photos, video, audio, PDF and text from any device.

03 · how it works

The route a file takes

Metadata goes everywhere. Bytes go only where they are asked for.

  1. 01

    A folder becomes a tree

    A shared folder is scanned into a Merkle tree: files are split with FastCDC into content-addressed blocks. The bytes stay in your files; NomadFS records where each block lives and stores only the directory blocks. Shares are rescanned every 30 seconds.

  2. 02

    Devices swap listings

    Each device asks the others for their share roots and reads one directory block at a time as you browse. Nothing is copied ahead of time.

  3. 03

    Opening a file fetches its blocks

    A read loads only the blocks that cover the requested range, from the device that has them, and checks each against its hash. Fetched blocks are cached, so what you opened once still opens offline.

  4. 04

    The swarm folder merges itself

    Its listing is a replicated manifest, a state-based CRDT, kept on every device and merged with each reachable peer every 10 seconds. Concurrent edits keep both versions under the same conflict name on every device.

Each step uses a technology you may want to look into: content-defined chunking, Merkle DAGs, the Noise handshake, a CRDT. Learn how NomadFS works, one diagram-led page each.

04 · get started

Build it with Zig & Oriel

NomadFS is early: built from source with Zig 0.16, tested on Linux and Android. The command line node and the app share one core; the app is made with Oriel by foreachdeveloper.

the node and CLI
# build zig-out/bin/nomadfs, run the tests
zig build
zig build test

# share a folder, then invite another device
./zig-out/bin/nomadfs --share Photos:$HOME/Pictures
./zig-out/bin/nomadfs --invite

# mount every device's shares (Linux)
./zig-out/bin/nomadfs --mount ~/NomadFS
the app (Oriel)
# fetches Oriel v0.20.0
cd nomadfs-gui
zig build run        # the desktop app
zig build package    # deb, rpm, AppImage

# Android: an APK with arm64-v8a and x86_64
oriel android build

Every command reads nomadfs.conf from the current folder, ~/.nomadfs/ or /etc/nomadfs/. The getting started guide walks through a first swarm.

05 · set out

Two devices, one invite, ten minutes

Build the node, share a folder, and scan the invite from your phone.

Read the guide Browse the docs