XHFS (Extended Headless File System)

XHFS is a small, full-fledged file system that enables you to store files anywhere, on anything, across an arbitrary combination of arbitrary devices.

Concept

Fundamentally, any writable, readable, and seekable abstract block device can be used as a storage device, whether or not it was built for such an operation: be it a file on disk, a remote Key-Value store (Redis, Cloudflare KV), or heck, even a database.

XHFS makes no assumptions about what the underlying "device" actually is; in fact, it remains entirely agnostic as long as you provide a way to read/write to arbitrary locations.

While its core design is inspired by ext4, the primary architectural split is that its inode extents are organized as a linked list instead of a H Tree, which you may argue makes it slower for seek operations but still good enough.

Use-cases

• Basic: You can setup blob file replicas across drives on top of your local filesystem.
• As a storage layer on top of an existing one:
  • Split your XHFS storage into multiple files, then store them on a locally synchronized folder using null.fs, Syncthing, Google Drive, Mega, OneDrive or anything similar. You get an encrypted storage layer that can be shared publicly + automatic backups.
• Distributed: Out of the box, XHFS makes no assumptions about the underlying device as long as we can read/write/seek arbitrary data.
• As Yet Another Filesystem: The wiring is already there, you can hack your way into formatting a physical block device or write a driver for it.

Example

Consider the following configuration:

# xhfs.yaml
# Encrypt the drive
# or use the cli with --password helloworld if the config and bins are made public
password: helloworld
key_derivation:
  algorithm: argon2 # or sha256
devices:
  - type: file
    name: blob1
    path: ./part1.bin
  - type: file
    name: blob2
    path: ./part1-replica.bin
  - type: file
    name: blob3
    path: ./part2.bin
configuration:
  logical:
    - name: dev1
      # The data will be replicated accross these block devices.
      # The first block device will be the main block for reads
      # and we can swap the order if we suspect corruption
      include: [blob1, blob2]
      capacity: "50 MiB"
      max_concurrent: 2
    - name: dev2
      include: [blob3]
      capacity: "50 MiB"
      max_concurrent: 1
  # Final storage layout
  # [dev1: 0 - 50MB] [dev2: 50MiB - 100MiB]
  layout: [dev1, dev2]

All that is left to do is format the drive (if you haven't done so yet) and then start playing with it.

# Setup the File System if not formatted yet

xhfs format


echo "Hello World" > thething.txt

xhfs upload thething.txt /test.txt


xhfs x ls -v

# FILE     2026-06-07 12:58:47  2026-06-07 12:58:33        28 B test.txt


xhfs read test.txt | echo

# Hello World


# You can also import stored files like this..

xhfs download test.txt my_physical_copy.txt

Installation

Download the binary from the releases or install using cargo.

cargo install xhfs

Environment variables

# xhfs.yaml
password: helloworld # XHFS_PASSWORD
servers:
  webdav: # XHFS_WEBDAV_USERNAME + XHFS_WEBDAV_PASSWORD
    username: admin
    password: password

• Environment variables take precedence over the values in the config file.
• XHFS will automatically load from .env if detected.

Features

• File System
  • Encryption (ChaCha20 stream cipher + argon2 or sha256 key derivation)
  • No journaling, CoW based
  • xhfs core: fopen, fwrite, fseek, mkdir, fmove, fcopy, unlink
  • Native Symlink support: create_symlink
  • Native Hardlink support: create_hardlink
  • Extra: fappend
• RAID-like configuration
  • Logical grouping
  • Replication
  • Error correction
• No device assumption
  • File device
  • In memory device
  • Custom KV http endpoint
  • Cloudflare KV example
  • s3 device
• Explorer
  • CLI
  • Inspection utilities: xhfs inspect
  • Servers
    • WebDAV server: xhfs server webdav

Mount

WebDAV

Usually, most file explorers already have a built-in WebDAV client with varying degree of relayability.

• Using rclone (recommended)

Feel free to play with the cache parameters, this example is tunned for video players.

rclone config create test-xhfs webdav url=http://localhost:1122 vendor=other user=admin pass=admin


# Windows

rclone mount --vfs-cache-mode full --dir-cache-time 3s test-xhfs: X:

# Linux

rclone mount --vfs-cache-mode full --dir-cache-time 3s test-xhfs: ~/mnt/xhfs

• explorer.exe (Windows only, not recommended)

net use X: http://localhost:1122

Inspection tools

The command line provides a few sets of utilities you can use to inspect the formatted filesystem.

General state

xhfs info

The info command will show you the general layout of what constitutes your storage, this includes the remaining usable space and metadata layout.

Config loaded: xhfs.yaml
XHFS version: 1
Capacity:        104857600 B (100.0 MiB)
Remaining:        83886080 B (80.0 MiB)
Format Configuration:
  Block Size:            4096 B (4.0 KiB)
  Data Blocks per Group: 20480
  INode count per Group: 4096
  Total Groups:     1
Geometry Layout (relative):
  Group Stride:        84221025
  INodes per Group:    4096
  Usable Blocks/Group: 20480
  Header Region:       0x00000000 -- 0x00000050 (        81 B) (        81 B)
  Data Bitmap Region:  0x00000051 -- 0x00000a58 (      2568 B) (     2.5 KiB)
  INode Bitmap Region: 0x00000a59 -- 0x00000c60 (       520 B) (       520 B)
  INode Table Region:  0x00000c61 -- 0x00051c60 (    331776 B) (   324.0 KiB)
  Data Payload Region: 0x00051c61 -- 0x05051c60 (  83886080 B) (    80.0 MiB)

INode metadata

# Display metadata of an INode and its extent address

xhfs inspect inode /Pictures/cat.jpg

# INode #4

# - Number of Links: 1

# - Kind: File

# - Size: 1050318 B

# - Creation time: 2026-05-17 21:26:29 UTC

# - Modification time: 2026-05-17 21:26:29 UTC

# - Immediate Extent address: 404025 (0x00062a39)


# then the Extent chain up to a count

xhfs inspect extent 0x00062a39 -m 3 

# #1 :: 0x00062a39 -- 0x00062e39 (      1025 B)

# #2 :: 0x00164239 -- 0x00264639 (   1049601 B)

# #3 :: 0x00264639 -- 0x00264e39 (      2049 B)

Block view and dump

If you want to read from the filesystem directly, you can dump or view its content either raw or decrypted. This can be useful if you want to make custom a tool that reconstruct removed file extents, dump the entire filesystem content locally or inspect the state of the data.

# which you can view in hex (don't forget to decrypt for the data and INode regions)

xhfs inspect view 0x00062a39 0x00062a50 -c 16 --decrypt

# 00000000: 00 00 00 00 00 00 00 00 39 42 16 00 00 00 00 00 | ........9B......

# 00000010: 01 00 00 00 00 00 00                            | .......


# or even dump

xhfs inspect dump 0x00062a39 0x00062a50 stuff.bin --decrypt


# and many other things too...

Benchmarks

cargo bench -p xhfs-core --bench io -- --quick

# then open target/criterion/read_large_64k/report/index.html