LiteboxFS

⚠️ This project is currently in an experimental state. There may be bugs that corrupt your data, and the on-disk format is not yet finalized. Use at your own risk!

LiteboxFS is a modern POSIX filesystem in a SQLite database.

LiteboxFS is:

• 🦀 A Rust library
• 💲 A CLI tool
• 🔌 A FUSE filesystem

LiteboxFS supports:

• 🪪 File metadata (mode, atime, mtime, ctime, btime, uid, gid)
• 🗃️ Symbolic links
• 🔗 Hard links
• 🕳️ Sparse files
• 💿️ Special files (block devices, character devices, named pipes)
• ✅️ Access control lists (ACLs)
• 🏷️ Extended attributes (xattrs)
• 📋️ Copy-on-write semantics
• ⚛️ Atomic transactions
• 📷️ Snapshots
• 📦️ Block-level deduplication with content-defined chunking
• 🗜️ Transparent compression
• 🔒️ Transparent encryption via SQLCipher
• 🗄️ Multiple logical filesystems in one database

To learn more, read the API docs.

The Pitch

Why did I make this? Mostly for fun. But also, consider some real use-cases:

An archive file format

Imagine a format like .zip or .tar that's fully mutable; you don't need to unpack and repack the entire archive to add, remove, edit, or move files. You can even mount it read-write via FUSE.

A litebox compresses to a similar size as a .zip file—often much faster—and block-level deduplication can reduce the size further.

A backup format

You can securely back up your files to an encrypted litebox, preserving file permissions, metadata, special files, hard links, sparse files, extended attributes, and ACLs.

Because a litebox can contain multiple independent logical filesystems, you can store many backups in a single litebox, and data is deduplicated between them. You can also tag your backups with metadata.

Because a litebox is mutable, you can prune old backups easily. You can also mount a specific backup to view your files as they were at a particular point in time.

Because a litebox is a database, backups are atomic; you don't have to worry about corruption from an interrupted backup.

An application file format

Because a litebox is a SQLite database, there's nothing stopping you from using the underlying database directly. Treat a litebox as a SQLite database with greatly expanded support for large blobs and use it as your application file format. Native SQLite only supports blobs up to 1 GB, and they cannot grow or shrink. With a litebox, you also get deduplication and transparent compression for free.

All tables that LiteboxFS uses are prefixed with liteboxfs_ to avoid conflicts with your application schema.

CLI

The LiteboxFS CLI allows you to use LiteboxFS as an archive file format. The litebox command for liteboxes is like the tar command for tarballs.

The CLI also allows you to use some of the format's more advanced features, like managing multiple logical filesystems (called "roots") or mounting a litebox via FUSE.

Consider reading the crate-level documentation in the API docs to understand some of the basic concepts in LiteboxFS.

Boolean flags in the CLI follow a predictable pattern:

• Every boolean option has two flags: one to enable it and one to disable it (e.g. --compression / --no-compression).
• Whether a boolean option is enabled or disabled by default is documented in the help text.
• The flag which is not the default will have a short name as well (e.g. --follow / -l).
• If the "on" flag has the short name, it will be a lowercase letter. If the "off" flag has the short name, it will be an uppercase letter (e.g. --no-recursive / -R).

All CLI commands which produce output can optionally output JSON, to help with scripting.

To install the LiteboxFS CLI, install Rust and run:

cargo install liteboxfs-cli

Platform Support

Currently, features that interact with the host filesystem (such as moving files in and out of a litebox) are only supported on Unix-like operating systems, meaning you would need to implement this functionality yourself on other platforms. Windows support will hopefully be added in the future. Some features of the library, such as the FUSE implementation, are only supported on Linux. Platform-dependent features are disabled at compile time on unsupported platforms.

If you plan to use LiteboxFS on a non-Linux OS, consider the following caveats:

• LiteboxFS is a POSIX filesystem, which means that it does not map one-to-one with Windows/macOS filesystem metadata or semantics, and it may not have an equivalent for all Windows/macOS filesystem features.
• LiteboxFS is currently only tested on Linux. This project uses self-hosted runners for CI/CD, and the maintainer does not currently have access to a Windows or macOS machine to test on.

Performance

These bench tests were run on a mid-range laptop from 2022. They test reading and writing a 512 MiB file to a litebox on an NVMe drive with write-ahead logging disabled. Test results are provided both with and without content-defined chunking enabled.

Development

This repo provides common recipes for development via just. Run just to see a list of recipes.

To run tests (via just test), you'll need to install cargo-nextest. Nextest is not a hard dependency; you can also run the full test suite with the standard cargo test runner.

To run test coverage (via just coverage), you'll need to install cargo-llvm-cov.

Testing

In addition to unit tests, the FUSE implementation of this library is tested against:

• fstest, a filesystem testing suite for FreeBSD by Pawel Jakub Dawidek and ported to Linux by Jean-Pierre Andre and Szabolcs Szakacsits. You can run this test suite with just run-fstest.
• fsx, a file I/O testing tool from Apple. This tool tests random reads and writes to validate good behavior. Out of the box it runs forever, but we cap it at a finite number of operations. You can run this test with just run-fsx.

Note that because they require special privileges to run in Docker/Podman, fstest and fsx are not currently run in CI.

Copyright

Copyright © 2025-2026 Lark Aster

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.