One canonical JSON file per document. Zero-payload prefix indexes. Git-like version control
for your data. If an index ever drifts, FYLO rebuilds it from the documents — files are
always the source of truth.
✓ Filesystem-first✓ Zero native addons✓ One self-contained binary✓ 13 language clients included
1
canonical file per document
0
native addons or external services
O(log n)
mmap'd prefix index lookups
13
language clients (shims + local-first)
Show me the code
From install to query in one minute
One binary, one JSON protocol, your language. The same engine speaks NoSQL collections
and plain SQL. Pick a language, rename the collection — every sample follows.
from fylo import Fylo
with Fylo("/mnt/fylo") as db:
db.users.create("document")
db.users.put({"name": "Ada", "role": "admin"})
db.users.latest("<id>")
Everything you need
Complexity traded for clarity.
Git-like version control, SQL query surfaces, field-level encryption, and
durable queues — in one standalone binary with drop-in clients for 13 languages.
Storage
Documents are truth
Each document is one canonical JSON file on disk, sharded by TTID prefix. Easy to inspect, debug, back up, and rebuild from.
Indexing
Zero-payload prefix indexes
S3-style key-only index entries in an mmap'd sorted catalog. Queries narrow by binary search, then hydrate only matching documents.
Query
SQL + NoSQL APIs
Query with a JSON operation protocol — put, find, patch, join — or plain SQL over the same engine. Exact, range, prefix, and trigram strategies.
Versioning
Git-like version control
Branch, commit, diff, merge, and restore your document store. Auto-commit on writes with content-addressed, deduplicated snapshots.
Distribution
One self-contained binary
Download a single executable — no runtime, no daemon, no native addons. Install once, then use drop-in clients for 13 languages — thin shims plus local-first browser and mobile.
Security
Encryption, POSIX access & WORM
AES-GCM field encryption with HMAC blind indexes, per-record POSIX UID/GID/mode enforcement, trusted group membership, and strict write-once WORM collections.
Replication
Whole-root S3 backup & sync hooks
Point sync.s3 at a dedicated bucket prefix to mirror the entire root to S3 (mirror-on-write plus on-demand reconcile), or wire your own onWrite / onDelete hooks in await-sync or fire-and-forget mode. Durable local queue included.
Architecture
No server, no protocol
Every client owns its database directly — the binary on desktop, OPFS on the web, or a user-selected folder through File System Access. Browser queries can run in a worker with Wasm acceleration. Nothing listens on a port.
Interop
One protocol, many languages
A compiled executable speaks a JSON machine protocol tested against Python, Ruby, PHP, Dart, Java, C#, C++, Swift, Kotlin, and Rust.
How it works
Rebuildable, not sacred.
A collection is a directory. Index keys look like S3 object keys — field path, kind,
value, doc ID — and carry no payload. If they ever drift, one rebuild reconstructs them
from the documents.
Nothing is lost. Documents are the source of truth and indexes are derived accelerators — the rebuild operation reconstructs every index entry by scanning the canonical document files.
Any language that can spawn a process. FYLO ships as a single binary that speaks a JSON machine protocol over stdin/stdout; drop-in shims are provided for Python, Ruby, Node/TypeScript, PHP, Go, Rust, C#, Java, and Dart, and the protocol is tested in CI against even more. For platforms that can't spawn the binary there are local-only clients that embed the engine on-device — the browser bundle, native iOS (Swift) and Android (Kotlin) clients, and a Flutter client.
Yes — Fylo Explorer is a browser UI over a real FYLO root on your disk, opened through the File System Access API. Pick the folder once and browse collections, inspect documents, and filter with SQL WHERE expressions (role = 'admin' AND age >= 30). It is read-only by default — the engine rebuilds indexes into a copy-on-write overlay, never touching the folder — with opt-in writes that go through the engine. Document queries run in a worker with Wasm acceleration and automatic JavaScript fallback. Chromium-only, since Firefox and Safari do not implement real-folder access.
FYLO owns local storage and querying — the index is always local, never in the query path. For a hands-off backup, point sync.s3 at a dedicated bucket prefix and FYLO mirrors the whole root (documents, buckets, index, catalog, vcs) to S3: touched files are mirrored on write and reconcile() makes that prefix match the root exactly. Prefer your own client? onWrite / onDelete sync hooks still notify it in await-sync or fire-and-forget mode.
Writes are serialized per collection with advisory file locks. There are no cross-collection atomic commits — declare related objects as their own collections and join them at query time with joinDocs.
Fields listed in a schema’s $encrypted array are stored with AES-GCM. Equality lookups use HMAC blind indexes, so queries work without decrypting — with the documented trade-off that value repetition counts are observable.
Yes. Write it with .as({ gid: editorsGid, mode: 0o660 }), then authenticated group members read, update, or delete with .as({ uid: memberUid }). FYLO resolves membership from the host POSIX group database or your trusted groupsForUid resolver; callers cannot claim their own groups. Group write permission is required — 0o600 remains owner-only.
Your documents. Your filesystem. Your call.
Start with one command — no daemons, no native addons, no monolithic caches.
FYLO is a single binary that speaks a JSON machine protocol over stdin/stdout. Pick
your language below — the same operations work from
every client. The full
reference — configuration, schema versioning, recovery, and limitations — lives in
the
README on GitHub.
Install & quick start
Install the fylo binary once, drop the single-file client for
your language into your project, then point it at a directory and write.
Every operation is a JSON request; the response carries ok and
either result or error.
# 1. Install the fylo binary (macOS/Linux)
curl -fsSL https://fylo.del.ma/install.sh | sh
# 2. Add clients/python/ (one file, no external deps) from the
# version-matched clients bundle attached to the latest release:
# github.com/d31ma/Fylo/releases/latest/download/fylo-clients.tar.gz
from fylo import Fylo
with Fylo("/mnt/fylo") as db:
# Create a collection, then write your first document.
db.users.create("document")
db.users.put({"name": "Ada", "role": "admin"})