[](https://crates.io/crates/liteboxfs)
[](https://docs.rs/liteboxfs)
[](https://justlark.codeberg.page/liteboxfs/coverage/)
# 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](https://docs.rs/liteboxfs).
## 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](https://sqlite.org/appfileformat.html). 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](https://docs.rs/liteboxfs) 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](https://rust-lang.org/tools/install/) 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.
| No | 821 MiB/s | 1,871 MiB/s |
| Yes | 612 MiB/s | 1,969 MiB/s |
## Development
This repo provides common recipes for development via
[just](https://just.systems/man/en/packages.html). Run `just` to see a list of
recipes.
To run tests (via `just test`), you'll need to install
[cargo-nextest](https://nexte.st/docs/installation/pre-built-binaries/).
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](https://github.com/taiki-e/cargo-llvm-cov?tab=readme-ov-file#installation).
## 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.
## Docs
In addition to the API docs, there is [project glossary](/docs/glossary.md) and
[database schema diagram](./docs/schema-diagram.svg). Read these if you plan on
digging into the codebase.
## 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.