# LayerFS and the case for disposable workspaces under coding agents

> LayerFS gives each agent a writable Workspace mounted over a shared Store of Commits, so a command runs, commits and vanishes. It is a 0.1.7 Developer Preview without crash durability, which shapes who can use it today.

**Ephemeral-AI-Lab/layerfs** — LayerFS gives every agent an isolated, disposable filesystem fork without copying the shared base. Useful states become durable, deduplicated checkpoints with workspace-scoped tool history—ready to branch, rewind, or reuse across parallel development, environment experiments, and MCTS-style rollouts.

- Repository: https://github.com/Ephemeral-AI-Lab/layerfs
- Website: https://learn.layerfs.ai/
- Stars: 2,699 · Forks: 150
- Language: Rust
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/ephemeral-ai-lab-layerfs

## Every agent mounts a writable Workspace over one shared history

LayerFS is a filesystem substrate for coding agents. The README describes the loop in one sentence: each agent mounts a complete, writable Workspace over shared committed history, does its work, commits what it changed, and goes away.

The problem behind that loop is the state problem in agentic development. An agent that runs shell commands needs a working directory, and if several agents share one directory they collide, if each agent copies the tree to a sandbox they pay for copies, and if their outputs vanish at the end of a run nothing can be inspected later. LayerFS attacks all three at once. Compute exists only while a command runs, yet what the command produced survives as a Commit in a shared Store.

The intended users are agent runtime developers and the teams embedding agents, not general storage users. The README frames the project as the substrate under your agents and positions it for parallel development, environment experiments and MCTS-style rollouts, where many candidate states are tried and the useful ones are kept. The description also names the interesting property: useful states become durable, deduplicated checkpoints with workspace-scoped tool history that can be branched, rewound or reused.

The primary language is Rust, and the licence field on the repository says MIT. The project is not archived, and the last push was on 2026-10-20.

## A Bash call mounts, runs, commits and unmounts

The data flow is visible in the diagram captions the README uses to explain each idea. File calls go straight into the Store as Commits, and each Bash call mounts a Workspace, runs, commits and unmounts. There is no long-lived writable copy of the tree that has to be reconciled later, because the Workspace is assembled from the Store when the command starts and reduced back to a Commit when it ends.

Two properties follow from that arrangement. Dependencies come with every mount, so the README argues that without LayerFS the tests fail until packages are installed, while with a LayerFS mount the packages are already present. And because a Workspace is scoped, the tool history that comes with it is workspace-scoped, which is what makes a run inspectable rather than a pile of side effects on a shared disk.

The project also draws a distinction it calls decentralized agents: agents on different computers share one serverless Store. There is no single coordinating server in the design, and the Store is a shared object everyone can read from and commit to.

The third idea is coordination, and it is where the interesting failure appears. A project has many Branches, and a Branch has many agents. When a commit touches a file that has already changed, the commit is refused with a Conflict. That refusal is a feature in a multi-agent setup, because silently overwriting another agent's edit is exactly the outcome this design is trying to prevent.

## Append-only objects, deduplicated chunks and per-file conflict rules

The storage design underneath the agent loop is built around a simple rule: saved objects are never rewritten, and the Store only grows. Nothing is edited in place, so a Commit is a value rather than a mutation of a previous one.

On top of that, the README lists several smaller mechanisms. The first is deduplication. The diagram for the storage idea describes four agents committing the same packages, where the first stores every chunk and each later Commit adds only what is new. The headline figure the README gives for this is that 10 copies compress into 0.31.

The second is that an edit costs the size of the edit rather than the size of the file. That is the single most consequential property for agent workloads, where an agent typically rewrites a small part of a large file and the naive approach would copy the whole thing.

The third is a conflict escape hatch stored under the name .lww. The rule is simple: name the files that should never conflict, and the newest edit wins for those files. Everything else keeps the refuse-on-conflict behaviour, so a file that several agents touch is protected unless the team explicitly says otherwise. This is one of the few places in the project where a team must make a deliberate configuration decision rather than accept a default, and the README does not describe a way to preview the effect of that decision before it is made.

Forking is recursive. Any Commit can be forked at any depth into a new Branch, which is the mechanism behind both branching experiments and the MCTS-style rollout pattern the description mentions.

## Setting up LayerFS on a Linux host with a local Store

The setup path runs through the JavaScript SDK, and the project is explicit that the SDK, its native binding, the Linux daemon and the environment it reads are all explained in sdk/js/README.md. That guide names five environment variables.

```bash
LAYERFS_HOME
LAYERFS_DOCKER
LAYERFS_IMAGE
LAYERFS_VOLUME
LAYERFS_DAEMON
```

The requirements are listed just as plainly, and they are where a first attempt usually stops. You need a Linux host, Docker Engine, Node 20 or newer, and a local ext4, xfs or btrfs filesystem for the Store. A missing prerequisite should be fixed before anything else is attempted, which is why the setup instruction the README offers to an agent tells it to stop and report which requirement is missing.

The first API call is project.init, run once on the repository. It captures the whole tree, ignored files included, as main at level L0. Including ignored files is the detail that connects directly to the instant bootstrap idea: dependency directories and build output are part of the captured state, so a later mount does not have to reinstall them.

From there the workflow for an agent is: fork a Branch for the work, use sdk.fs for file reads and edits, and for each Bash command mount a Workspace on the Branch, exec, commit, then unmount. Verification is a matter of writing a file on the Branch and confirming that list_commits shows the Commit.

The README also offers a copy-paste setup prompt for a coding agent that encodes exactly those steps, and it asks the agent to report what it ran and what each step returned, and to stop with the exact error rather than retrying on its own. That last instruction is a sensible default for a system where a failed mount can leave state in a shape the agent cannot see.

## Where LayerFS is the wrong tool today

The status line in the README is the most important sentence in the document. LayerFS 0.1.7 is a Developer Preview released as source, and it is for evaluation and agent-runtime integration, not production storage, because there is no crash or power-loss durability. The README points at the release record and its waivers before you rely on it.

That waiver is not a detail to note and move past. A Store that grows without rewriting its objects is exactly the kind of structure where a power loss can leave you with a state you cannot recover, and the project does not claim otherwise. Any workflow that depends on the Commits surviving a machine failure is outside the current scope, whatever the storage efficiency numbers look like.

The platform requirements narrow the audience further. A Linux host, Docker Engine, Node 20 or newer and a local ext4, xfs or btrfs filesystem for the Store mean a macOS or Windows developer machine is not a supported setup as written. For a team whose agents run on developer laptops, that rules the project out until the requirements change.

The integrations are also early. LayerFS with DSH is marked as a preview, where agents in a DeepSeek Harness session fork, test, merge and publish from bash and a LayerFS tab draws what each one did. LayerFS with Pi is listed as planned, which means it does not exist yet. The repository layout also carries sdk_sim/, benchmark_agent_report.md, a cluster_one_handbook.md and a cas_cdc_deltaencoding_handbook.md, which is what an early project accumulating design notes looks like.

## Releases, benchmarks and what the 0.1.7 rewrite changed

The release history shows fast movement on a pre-1.0 version line. v0.1.6 shipped on 2026-09-16 with sandbox-local Workspace state and an unchanged Store format, and v0.1.7 followed on 2026-10-15 with a rewritten core, a JavaScript SDK and a live terminal UI. The repository also carries a release tagged issue334-diagnostic-evidence-20261016, which the project itself labels as diagnostic evidence rather than a product release, a good sign of how the maintainers are distinguishing artifacts from releases.

The benchmark story deserves a careful reading. The README points at released fs-bench-pro results for v0.1.4, v0.1.5 and v0.1.6, and states plainly that 0.1.7 published none. Since 0.1.7 rewrote the core, the published numbers describe a codebase that no longer exists in the same form. Anyone citing them for the current release would be citing a different system.

The documentation for the current version is versioned, with a 0.1.7 manual, a concepts page, an SDK reference and a known limits section, plus release records per version. That structure is a positive sign for a project that will need to keep old behaviour reproducible while the design changes.

One number in the README deserves a caveat. The claim that 10 copies compress into 0.31 is presented as the headline of the storage optimization idea, without a stated baseline for what those copies would weigh uncompressed. It tells you deduplication works. It does not tell you what your own repository will cost.

## Conclusion

LayerFS is worth evaluating for teams running several coding agents in parallel on one repository, or agents doing repeated experiments where each rollout needs a clean tree and a durable record of what changed, provided the team accepts losing the Store on a crash and hosts it on the supported filesystems. It is the wrong tool for a production storage system, for a macOS or Windows workstation, and for anyone who needs the old behaviour of an ordinary working directory. Verify three things before committing to it: that the host is Linux with Docker Engine and Node 20 or newer, that the Store sits on a local ext4, xfs or btrfs filesystem, and that the durability waivers in the 0.1.7 release record match how much your workload can afford to lose.

## FAQ

### What are the system requirements for running LayerFS?

A Linux host, Docker Engine, Node 20 or newer, and a local ext4, xfs or btrfs filesystem for the Store. The JavaScript SDK, its native binding, the Linux daemon and the environment variables it reads are documented in sdk/js/README.md.

### How do I create the first LayerFS Commit for a repository?

Run project.init once on the repository. It captures the whole tree, ignored files included, as main at level L0, which is what makes dependencies available on later mounts.

### Is LayerFS safe to use as production storage?

No. The README states that 0.1.7 is a Developer Preview for evaluation and agent-runtime integration, with no crash or power-loss durability, and points to the release record and its waivers.

### How do LayerFS Branches handle two agents editing the same file?

A commit to a file that has already changed is refused with a Conflict. You can name files that should never conflict in the .lww rules, and for those the newest edit wins.

## Sources

- [Ephemeral-AI-Lab/layerfs on GitHub](https://github.com/Ephemeral-AI-Lab/layerfs)
- [License: MIT](https://github.com/Ephemeral-AI-Lab/layerfs/blob/main/LICENSE)
- [Project website](https://learn.layerfs.ai/)
- [README](https://github.com/Ephemeral-AI-Lab/layerfs/blob/main/README.md)
- [Releases](https://github.com/Ephemeral-AI-Lab/layerfs/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ephemeral-ai-lab-layerfs