LayerFS

Ephemeral Workspaces. Durable Shared History.

v0.1.6 Developer Preview: release and downloads, every measured selection, and compatibility boundary. Live Workspace state now lives in the sandbox and the Store format is unchanged; one construction worker, a bounded sandbox spool and every measured regression, waiver and declared allowance stay explicit.

Source notice (2026-10-10): the v0.1.6 implementation described below is not on main any more. Its source under root crates/ was retired once the replacement in core/ reached its closing examination; the release tag v0.1.6 still carries it, and the sections below describe that release. core/ is under development and is not a release.

🚀 What is LayerFS?

Ephemeral Workspaces. Durable Shared History.

LayerFS is a SQLite-backed, content-addressed time machine for agent Workspaces. Give every filesystem-affecting tool call its own ephemeral Workspace; when retained, that call becomes one immutable Commit—the base unit of the filesystem timeline. CAS, CDC, and COW store one shared base plus unique deltas instead of cloning full environments. From any Layer or eligible Commit, agents can fork zero-copy Branches, run parallel rollouts, discard failures, roll back by forking an earlier state, and promote a winning Branch with Add. The filesystem remains load-bearing for recursive multi-agent exploration without multiplying storage.

[!WARNING] LayerFS 0.1.6 is a Developer Preview. It is intended for local evaluation, agent-runtime integration, and performance research—not production storage. It does not provide crash- or power-loss-durability guarantees. Keep an independent copy of important data.

🧱 LayerStack storage model

⚙️ Core storage mechanisms

CAS, CDC, and COW make LayerStack history storage-efficient by reusing unchanged objects, file regions, and filesystem structure.

The governing invariant is simple: every filesystem state is complete logically, but incremental physically. A new state should cost what changed, not the size of the Workspace it exposes. Read the CAS + CDC + COW foundations for the design rationale and step-by-step storage model.

🗃️ Check out an ephemeral filesystem from any layer

A LayerStack records complete filesystem checkpoints. Agent A can start from L1 while Agent B independently starts from L3. Each gets a private place to work while the selected history remains shared.

This is the conceptual checkout view; the public lifecycle is Layer or Commit → Branch → Workspace.

One LayerStack, many zero-copy Branches, and ephemeral COW Workspaces sharing immutable history.

📦 Measured deduplication

The primary storage signal is semantic content growth: the canonical bytes needed by a new state. SQLite page allocation is reported separately because existing database pages can absorb new objects without changing the logical content represented by the Store.

These measurements come from the final public-SDK, real-FUSE campaign. See the full benchmark report for physical allocation, equations, source identity, and raw evidence.

---

🧭 System boundaries

🧩 LayerFS components

The storage engine, SDK, CLI, and filesystem projection are implemented in the 0.1.6 Developer Preview. They remain separate public boundaries so callers do not depend on private CAS handles or storage formats.

The one-Store boundary is intentional: a Client binds one SQLite Store, one Monitor, and one Workspace manager. A second Store uses a separate Client.

Each workspace exec starts a fresh process. commit publishes the Workspace state to its Branch. end removes the ephemeral projection and never commits implicitly.

🛠️ Quickstart

Releases are built from source. You need macOS or Linux and Rust 1.85 or newer. Docker, /dev/fuse, and CAP_SYS_ADMIN are needed only for managed container-FUSE workspaces. No packages are published to crates.io for this release.

From the repository root, at the v0.1.6 release tag:

git clone https://github.com/Ephemeral-AI-Lab/layerfs.git
cd layerfs
git checkout v0.1.6

cargo build --release -p layerfs-cli
export LAYERFS_BIN="$PWD/target/release/layerfs"
export LAYERFS_CONTEXT="$PWD/.layerfs/context"
mkdir -p "$PWD/.layerfs"

"$LAYERFS_BIN" db create "$PWD/.layerfs/store.sqlite"
"$LAYERFS_BIN" context use --store "$PWD/.layerfs/store.sqlite"
"$LAYERFS_BIN" layerstack init --name demo --empty
"$LAYERFS_BIN" query layerstacks

This creates a SQLite Store and an empty LayerStack with a genesis Layer. Continue with the complete quickstart for Branch creation, Workspace execution, commits, cleanup, directory imports, managed containers, and real FUSE.

When importing an existing directory, keep the Store file outside the directory being imported or projected:

mkdir -p "$PWD/import-root"
printf 'hello\n' > "$PWD/import-root/hello.txt"
"$LAYERFS_BIN" layerstack init --name imported "$PWD/import-root"

🗂️ Repository layout

core/                          replacement implementation (in development)
├── crates/                    content, storage, history, persistence, project,
│                              telemetry, overlay, workspace, fuse, daemon,
│                              bridge, sandbox and the SDK
├── benchmark/                 core harnesses, registrations and proof tools
└── docs/                      architecture, design contracts and run records
benchmark/                     v0.1.6 harness, historical; not runnable on main
docs/versioned/0.1.6           v0.1.6 manual
docs/versioned/0.1.2           previous versioned product manual
release-notes/                 release records, evidence and limitations
tools/production_loc.py        pinned production source-line counter

The v0.1.6 crates, tools/layerfs-eval and containers/layerfs-fuse are in the v0.1.6 release tag.

⚠️ Current limitations

LayerFS is suitable for evaluation and integration work, but the preview boundary matters:

• 0.1.6 operates against one Store per Client; there is no cross-host synchronization;
• live-process transaction visibility does not imply crash or power-loss durability, and Workspace backing is not fsynced;
• a v0.1.6 sandbox owner and a v0.1.5 host do not share a live Workspace; match SDK, CLI, daemon and runtime components across a session;
• the sandbox owns live mutable state and a private payload backing for its mount; the host learns it only when a Commit transfers it, and that transfer pays a storage read (bounded sandbox spool residency ≤ 2.6 MiB) instead of page-cache service. Kernel-dirty shared mmap is still not captured by a Commit;
• canonical construction runs one worker (namespace init is the only exception), so six dedup/CDC construction cells are 1.50–1.65× slower than v0.1.5 and are owner-accepted, and the cold namespace-100000 Init target is owner-waived (4.986 s against 2.7 s). Read the release record, acceptance and waivers;
• explicit compaction stays removed; compacted Stores from earlier builds remain readable through the retained authenticated read path, and ordinary storage is the only supported route;
• the measured v0.1.6 set is 36 selections: 28 performance receipts and 36 independent verifications, three performance rows above the 15 s family target under declared allowances, one verification row under a declared 30 s ceiling and two verify-only rows under frozen 120 s / 300 s watchdogs. Endurance is not qualified;
• the retained SQLite Store still misses the 600 MB primary-control goal; storage-efficiency tradeoffs are accepted for v0.1.4 in #18, with optimization design still to be discussed;
• the detached CLI context owner does not forward an interactive PTY; and
• CLI JSON output is a preview text envelope, not a stable machine API.

Read the full limitations before using LayerFS with important data.

📚 Documentation

Start with the documentation index, or jump directly to a focused guide:

The first-principles learning site is educational material and may describe future work. The versioned repository manual defines the current product contract.

🗺️ Roadmap

See the roadmap checklist and roadmap architecture notes for acceptance gates, ownership boundaries, and sequencing. Use the Rust SDK reference to integrate the current public SDK.

🤝 Contributing

Bug reports, reproducible performance evidence, documentation corrections, and focused pull requests are welcome. Before opening a change, review the 0.1.x development guide and run the repository’s relevant verification commands.

💬 Community

• WeChat: scan the Ephemeral AI Lab group QR code. The invitation is time-limited; refresh the image when it expires.
• Discord: join the Ephemeral AI Lab community.
• 𝕏: @yifanxu_ephai.

📄 License

LayerFS is licensed under the MIT License.