Help
How LayerFS compares
LayerFS is an open-source (MIT) filesystem for AI coding agents. Each tool call gets a complete, writable Workspace over shared committed history, does its work, and commits what it changed. This page answers the first question people ask: how is that different from what I use today?
At a glance
| The whole tree, ignored files too | One more agent costs | History of each step | Merging two agents' work | |
|---|---|---|---|---|
| LayerFS | Yes, .git and node_modules included | A mount: no copy, a small overlay database | Every change is a Commit | Three-way; same file both sides changed is a Conflict |
| git worktree | Tracked files only | A checkout, then install and build | Only what you commit | Yes, by hand with Git |
| Copying the project | Yes | Every file, read and written | None | None |
| overlayfs | Yes | A mount | None | None |
| Btrfs or ZFS snapshots | Yes | A snapshot | The snapshots you take | None |
How is LayerFS different from git worktrees?
A git worktree checks out the files Git tracks. Everything Git ignores, such as node_modules, build output and caches, is missing, so each new worktree installs and builds again before an agent can run a test. Its history is whatever someone chose to commit.
A LayerFS Workspace is the whole tree: tracked files, ignored files, dependencies and .git itself. Mounting one binds the committed tree without copying it, so dependencies come with every mount. Every fs write and every sandbox.commit becomes aCommit on the agent's Branch, a failing step included. Git is not replaced:.git is a folder like any other, and Git commands work inside a Workspace as usual.
How is LayerFS different from copying the project for each agent?
Copying a project, with cp -r, rsync or a fresh container volume, reads and writes every file before the agent starts, and the space grows with every agent.
A LayerFS mount copies nothing. It binds the committed tree and creates only the Workspace's own small overlay database; content loads as it is read, and the overlay is deleted at unmount. Forking a Branch records where it starts and copies no files. In the Store, repeated content is stored once and compressed.
How is LayerFS different from overlayfs?
overlayfs, the layer under most containers, puts a writable directory over a read-only one. That gives an agent a cheap scratch copy, but nothing more: no history of what changed, no branches, and no way to bring two agents' upper directories together.
LayerFS keeps the cheap mount and adds history. Each step is a Commit on a Branch, and Branchesmerge three ways: changes to different files land together, a change to a file both sides changed is refused as a Conflict (a Workspace keeps the merge with conflict markers to fix), and paths named in /.lww keep the newer version instead.
How is LayerFS different from Btrfs or ZFS snapshots?
Copy-on-write snapshots are cheap to take, but blocks are shared only while they stay where they are: a file rewritten in full is new data in every snapshot. Snapshots also cannot merge concurrent work.
On the whole history of a real project, 157 snapshots of the DeepSeek harness (4.94 GB of trees), LayerFS kept every one as a mountable Commit in 100.1 MB. Btrfs with zstd needed1,994.6 MB for the same trees, 19.9 times the space, and 2,068.9 MB after deduplicating with bees.
How does LayerFS compare with Cloudflare Computer?
On Cloudflare Computer's own filesystem benchmark, twelve shell scenarios run unchanged on the same image, LayerFS took 5.20 s in total against 8.88 s, faster in 10 of the 12 scenarios. That is one sample per side; the sum is a convenience total, not an agent's turn.
When is LayerFS not the right choice?
- Not Linux, or no local disk. Everything that opens a Store must share one Linux kernel, with the Store on a local ext4, xfs or btrfs filesystem. See Supported platforms.
- Agents on different machines sharing one Store. Not today: agents on one host, each in its own Sandbox, share a Store.
- Guaranteed durability. The Store runs without waiting for the disk, so a power loss can lose recent history. See Durability.
- A compact archive of a finished history. Git packs it smaller: for the same 157 snapshots, 55.1 MB against LayerFS's 100.1 MB. LayerFS keeps history live, every version mountable and every step mergeable.