/layerfs-js-sdk

name: layerfs-js-sdk
description: Use when building, editing, testing or inspecting a project through LayerFS with the JavaScript SDK (`@layerfs/agent`) from the command line. Activates on LayerFS projects, Branches, Commits, Workspaces or Sandboxes; `LayerFS.open`, `LayerFS.init`, `layerfs.project.*`, `layerfs.fs.*`, `layerfs.branch.*`, `layerfs.sandbox.*` or `layerfs.workspace.*` calls; running npm install, build or tests inside a mounted Workspace; or resolving LayerFS Conflict, Dirty or Busy refusals.

LayerFS JavaScript SDK

> **Status:** Current general guide for the current SDK source. Base example > outputs were captured live in issue #334 Phase A at `b30e4fb8f`; the > Workspace API and idle close are #373's (section 8 of > [its design](https://github.com/Ephemeral-AI-Lab/layerfs/blob/9f97a7ec95b662e9cb288704afa165feff132cfa/core/docs/issues/373/README.md)). The `@layerfs/agent` > package, its client factories and the `sandbox` methods are #428's > ([its design](https://github.com/Ephemeral-AI-Lab/layerfs/blob/9f97a7ec95b662e9cb288704afa165feff132cfa/core/docs/issues/428/layerfs-agent.md)). There is no > placement since 2026-10-23 (owner): a mount names its Sandbox.

Your project lives in LayerFS, not on your local disk. You read and change it through the SDK, from small Node scripts you run with `node`.

Inside an integration: start here

An integration is a host that runs you with a LayerFS project already set up. When it has, its own instructions name the project, how to import the SDK and how to run the `layerfs` command. Use those, and skip [Import the SDK](#import-the-sdk), [Connect to a project](#connect-to-a-project) and `LayerFS.init`:

• The SDK reads every setting from `LAYERFS_*` variables, which the integration provides.

`LayerFS.open(<project>)` needs nothing else.

• If the SDK's location is given in a variable, import it with `await import(<path>)` in a

module script. A static `import` of a variable is a syntax error.

• Don't look into Docker, Store containers, Store files or the integration host's source.

Nothing there helps, and the SDK is the only way in.

• Your current folder is for temporary files only: your scripts, notes and scratch output.

Files you find there may be an old copy, not the project. Do all work on the project through the SDK: `fs.*` and Workspaces for files and commands, and `project.*` and `branch.*` for versioning, as you would use git.

• The `layerfs` command makes one SDK call per command, for example

`layerfs project list_branches` or `layerfs fs read <branch> <path>`. Use it for single steps and an SDK script for anything more.

• **Always unmount.** Put every `workspace.unmount` in a `finally` block. A forgotten

Workspace stays mounted, and its Sandbox never closes. To clear idle, clean leftovers, see [Clearing idle Workspaces](references/methods/workspace.md#clearing-idle-workspaces). End every script with `await layerfs.close()`, in a `finally` block too.

• **`main` is read-only.** It's published, not a Branch: read it and fork from it, but

don't write, edit, mount or commit to it. Those calls, and `branch.list_commits("main")`, are refused with `NoSuchBranch`. Fork a Branch, work there, and publish it. A new project's `main` is empty.

How an agent works in LayerFS

Every tool call an agent makes is one **step**, and every step that changes files becomes a Commit on the agent's Branch. The Branch's history is the record of what the agent did, step by step.

| Agent tool | LayerFS calls | Recorded as | | --- | --- | --- | | File read: read, list, search, diff | `fs.read`, `fs.list`, `fs.grep`, `fs.glob`, `fs.diff_files` | Nothing: reads don't change history | | File change: write, edit, many-file change | `fs.write`, `fs.edit`, `fs.apply`, `fs.mkdir`, `fs.mv`, `fs.cp`, `fs.rm` | One Commit per call. Atomic: the whole change lands, or nothing does | | Bash | A Workspace per call: `workspace.mount` → `workspace.exec` → `workspace.commit` → `workspace.unmount` | One Commit with everything the command changed: sources, lockfiles, `node_modules`, build output |

Two ways in: **`fs.*` for cheap, targeted file work; a Workspace for Bash commands**, which often change files too, and for file work too heavy for single calls.

Cheap file work: `fs.*`

Use `fs.*` for the reads and small changes your own file tools make: read a file, list a folder, search, diff, write or edit one file, move or delete a path, or a handful of related changes as one Commit (`fs.apply`).

• **Why:** an `fs.*` call runs in your process on the project's Store, without a

Workspace or kernel mount, so it avoids the Bash mount lifecycle. A change is atomic and is exactly one Commit with your message, so the Branch records each edit as its own step. A read returns the Branch's latest Commit, so it sees what every Workspace and every other writer has committed.

• **When:** reading code before you change it, creating a file, editing source, renaming

or deleting a path.

• **No merge:** if another writer committed on the Branch during the call, it's refused

with `HeadMoved` and nothing is written. Read the file again, then redo your change.

• **Reads see committed state only**, never a mounted Workspace's uncommitted changes.

Bash commands: a Workspace

Use a Workspace to run Bash commands. Most of them change files as well, and all of those changes are recorded:

• **Commands that change files as a side effect:** `npm install` (`node_modules`,

the lockfile), builds (`dist/`), code generators, formatters, `git`, tests that write snapshots or coverage. The Commit holds everything the command changed.

• **Heavier file work:** changes across many files or a large tree (`find … | xargs

sed -i …`, a scaffolder, unpacking an archive), where one command beats many `fs.*` calls.

• **Files `fs.*` can't reach:** a mounted Workspace's uncommitted state, such as

conflict markers after a Commit merge ([resolving confli