Field noteNov 11, 20265 min read1 source

LayerFS 1.1.0 splits the SDK into three packages, adds a CLI, and supports macOS and Windows

In one minute

LayerFS 1.1.0 reorganizes its JavaScript SDK into three packages, adds a JSON-returning CLI and routes Store calls through workers on macOS and Windows. For builders, the practical change is broader platform support and a shell-friendly interface—but existing 1.0.0 integrations must be migrated because the release breaks SDK compatibility despite its minor-version number.

What happened

LayerFS's 1.1.0 release record describes work from issue #428 and fixes merged since v1.0.0. It replaces the single @layerfs/sdk package with @layerfs/agent, @layerfs/backend and @layerfs/runtime. The agent package covers projects, branches, files, sandboxes, workspaces, execution and commits. Backend provides Store and daemon reads for tools and interfaces. Runtime handles a LayerFS home, including status, initialization and removal, the macOS and Windows worker, sandbox and volume upkeep, and live call events.

The release also adds the layerfs command, distributed as @layerfs/cli. Each command makes one @layerfs/agent call and returns JSON, allowing a shell-based agent to use LayerFS. Release tests run SDK cases through both the SDK and CLI and require matching answers. Sandbox placement is now explicit: sandbox.create() starts one, and workspace.mount(sandbox, branch) mounts a branch into the named sandbox; mounting does not create or choose a sandbox automatically.

Client creation changes as well. LayerFS.open(name) opens an existing project and checks that it exists; LayerFS.init(name, folder, timeout?) creates one. Settings now come only from LAYERFS_* environment variables. Initialization has an optional timeout that defaults to 300 seconds, rather than a fixed 60-second deadline. On Linux, Store calls still run in the caller's process. On macOS, calls go to a Linux container worker; on Windows, they go to a Node process in WSL2. The worker endpoint is LAYERFS_WORKER_ENDPOINT.

The record says 1.0.0 code must change: the import becomes @layerfs/agent; the public constructor is replaced by asynchronous factories; options are refused in favor of environment variables; mount requires an explicit sandbox; operator APIs move to backend and runtime; and a closed client refuses later calls. The owner chose 1.1.0 despite a prior promise that incompatible JavaScript SDK changes would require a major version, and recorded a waiver. The packages are private, not published to npm. Release checks reported 1,222 passing tests and 21 ignored. Linux-only FUSE tests and real-Store/Docker JavaScript tests were not run; macOS live scenarios passed nine of ten initially, with the remaining scenario passing after an image setup fix.

What the archive adds

New Runtime's earlier coverage, on 2026-10-22, described LayerFS workspaces as disposable filesystem forks over a shared base, with selected state retained separately (earlier note). This is a new release on that known project, adding package boundaries, CLI access and platform support rather than restating the filesystem model.

Trend signal

This release weakly supports harness architecture outlives model choice: the SDK, runtime and CLI define how agents interact with isolated workspaces, independently of a particular model. The release documents an interface and deployment change, not evidence that this architecture is more durable in production, so the signal remains limited.

Why it matters

For a team already building on LayerFS, the package split makes responsibilities easier to target: an agent can use the narrow agent API, while a UI or operator tool can use backend reads. The CLI makes the same operations reachable through a shell, which can simplify integration with agents whose tool surface is Bash rather than a custom SDK adapter. Worker routing also gives macOS and Windows users a path to the Linux-based Store implementation.

The cost is a migration that cannot be inferred from the minor version. Existing imports, construction, configuration, sandbox mounting and operator calls change, and the release says 1.0.0 clients against a 1.1.0 daemon are unsupported and untested. Teams should treat the release as a breaking upgrade: pin matching package, daemon, native addon and runtime-image versions, migrate deliberately, and run their own integration checks before rollout. The recorded test gaps make that especially important for Linux FUSE and real Store/Docker paths.

Limits and uncertainty

The release record says Linux FUSE mount tests and several real-Store/Docker tests were not run for this candidate; it also says opening a v1.0.0 Store under 1.1.0 was inferred from source rather than tested. A 1.0.0 client talking to a 1.1.0 daemon is unsupported and untested. Durable storage is disabled pending explicit reauthorization; only the Disposable profile was executed, with no crash or power-loss durability. The record does not establish how the release performs in broader production use.

Skill to build now

If your team has a LayerFS 1.0.0 integration, make a migration checklist against the release's compatibility table this week. Update imports and client factories, replace options with LAYERFS_* settings, pass an explicit sandbox to mounts, and move operator calls to the relevant package. Then test with a matched 1.1.0 set of packages, daemon, addon and runtime image; include the platform and Store paths your deployment actually uses.

Reader takeaway

LayerFS 1.1.0 makes its agent, backend and runtime interfaces more explicit, adds a shell CLI and supports worker-mediated Store calls on macOS and Windows. But it is a breaking SDK migration labelled as a minor release, not a drop-in update. Existing users should check every API change and validate their own platform-specific paths before upgrading.

Evidence / sources

  1. 1raw.githubusercontent.com/Ephemeral-AI-Lab/layerfs/v1.1.0/docs/release-notes/1.1.0/README.md
All Field Notes

Next reads

Read next

Open the graph
  1. 01topicDeveloper ToolsExplore the developer-tools topic hub.
  2. 02topicInfrastructureExplore the infrastructure topic hub.
  3. 03archiveField NotesOpen the latest editorial analysis.
  4. 04sourcesSourcesSee the original sources this archive cites.
Who read this page?Machine requests, hidden until opened

Loading the privacy-safe route aggregate...

Open the JSON contract