LayerFSv1.1.0 releases

LayerFS for Pi

previewv0.1.0

Pi on persistent LayerFS projects: worker agents on their own Branches, plus a dashboard.

cydia2001 · for Pi

#pi#agents#multi-agent#workspaces#history#dashboard

Install

Paste this into a coding agent on the machine that will run it. It installs v0.1.0 at b6bdc7f4d0 with LayerFS v1.1.0 at ad78914e36, the commit it was tested with. It runs the author’s build, so read it first.

Install prompt · v0.1.0
Install LayerFS for Pi 0.1.0 for me.

1. Clone https://github.com/Ephemeral-AI-Lab/layerfs and check out commit ad78914e36b258b360daf13aec164b5655814689 (v1.1.0). Use exactly this commit: it is the one this version was tested with.
2. Clone https://github.com/anyin233/pi-layerfs beside it and check out commit b6bdc7f4d03a55ae91d4c8379da5d0b430ce4fb3.
3. Check the machine before building: Linux x86_64, `/dev/fuse` present, `docker info` works through the local Unix socket, and Node 22.19 or newer (Rust runs in its builder image; no host toolchain is needed). If any is missing, stop and tell me which.
4. Build in the plugin checkout:
   - `npm ci`
   - `bash scripts/build-native.sh ../layerfs`: it refuses a LayerFS checkout that is not at ad78914e36b258b360daf13aec164b5655814689 or has tracked changes, then builds the native binding and `layerfs-daemon` in the `rust:1.85.1-bookworm` image.
   - `npm run release:build -- --upstream ../layerfs`: it builds the plugin, the runtime image (Pi 1.4.0 included) and `release-out/pi-layerfs-0.1.0-linux-x64.tar.gz`.
5. Install: `tar -xzf release-out/pi-layerfs-0.1.0-linux-x64.tar.gz -C release-out`, then `bash release-out/pi-layerfs-0.1.0-linux-x64/install.sh`. It installs to `~/.local/share/pi-layerfs` and `~/.local/bin/pi-layerfs`; ask me before passing `--prefix`, `--bin-dir` or `--skip-register`.
6. Check that it works: `pi-layerfs --self-test` (add `~/.local/bin` to PATH if needed) must pass. To use it, run `pi-layerfs` in a disposable copy of a project and sign in to a model provider with Pi's `/login`; do not copy any credentials yourself.

Report what you ran and what each step returned. If anything fails, stop and give me the exact error, and don't retry it on your own.

A Pi extension that runs Pi on persistent, branchable LayerFS projects. Pi’s ordinary file and Bash tools work on a LayerFS Branch instead of the host directory; the lead agent can spawn independent worker agents, each on its own Branch, then merge and publish their work; and a local dashboard shows every actor’s calls, the Commit history, saved files and storage. It uses Pi’s public extension and AgentSession APIs without modifying Pi core.

What it adds

  • SDK-backed replacements for Pi’s read, write, edit, bash, ls, find and grep. Each Bash command mounts the active Branch, runs, commits a completed command (normal nonzero exits included) and unmounts.
  • layerfs_branch: list, fork, switch, merge into a new named Branch, lead-only publish, and Branch/Commit differences.
  • layerfs_fs: historical read/list/stat/blame/diff, text and base64 writes, edit, mkdir/cp/mv/rm/apply.
  • layerfs_workspace and layerfs_process: a retained Workspace kept between commands, and tracked background processes, each needing an explicit commit or discard.
  • layerfs_agent: spawn, list, message and cancel for lead-owned Pi workers. Workers are public Pi AgentSessions with independent Branches and their own transcripts; they cannot publish, manage projects or spawn further workers.
  • layerfs_project and pi-layerfs --manage-projects: create, import, select and remove projects, each in its own Docker volume.
  • /layerfs ui: a dashboard on 127.0.0.1 with a random token. Work shows per-actor command and SDK-call records and live Sandbox/Workspace snapshots; History shows Branches, Commits, merge parents and published Layers with playback of recorded calls; Files shows saved state, blame, revisions and comparisons; Storage shows logical, stored and metadata metrics per Commit.

History dashboard

How it works

The pi-layerfs launcher runs Pi 1.4.0 with the extension in a bundled Docker image. It mounts the host source read-only, generates a deterministic project and Branch outside it, and gives each canonical project directory its own Store volume, so reopening the same directory reuses its Store and history; nothing is written into the host source. The extension calls the LayerFS 1.1.0 @layerfs/agent and @layerfs/backend packages (from the pinned LayerFS commit, unmodified) and the bundled layerfs-daemon. Each SDK call is attempted once; refusals such as Busy, Dirty or Conflict are reported for explicit resolution. Model credentials and Pi settings live in a separate private volume; use Pi’s /login as usual.

You need

  • Linux x86_64 with /dev/fuse.
  • Docker Engine reachable through its Unix socket, and plain local Docker volumes on ext4, xfs or btrfs.
  • To build from source: Git and Node 22.19 or newer. The native build runs in the rust:1.85.1-bookworm image, so no host Rust toolchain is needed.
  • Credentials for a model provider.

The built archive contains the plugin, the LayerFS packages, native binding and daemon, Pi 1.4.0 and the runtime image; installing it downloads nothing.

Limits

  • The install prompt covers Linux x86_64. The linux/arm64 archive built from the same commit also passed the plugin’s real-host acceptance on an Apple Silicon Mac with OrbStack (macOS notes); no macOS archive is released.
  • LayerFS 1.1.0 can refuse to unmount a Workspace and keep it wedged (#426). The plugin avoids the deterministic trigger by waiting until a new Sandbox is 1.5 s old before mounting. The rarer variant can still occur after a timed-out command; start a new session if it does.
  • LayerFS here uses a Disposable Store (WAL, synchronous=OFF): history persists across normal sessions but has no crash or power-loss durability. Keep another copy of irreplaceable source data.
  • edit takes {path, oldText, newText}, not Pi’s edits[]; read is bounded UTF-8 text. Binary files go through base64 in layerfs_fs.
  • Foreground commands cannot be aborted mid-run; cancellation waits for the command (or its timeout) to finish, then discards. A Workspace is not a security sandbox, and other extensions or direct host APIs can bypass the integration.
  • Initialization and removal locks have no automatic stale takeover; after a crash, recovery is manual and evidence is kept rather than deleted.
  • Not published to the npm registry; install from the GitHub release.

Versions

Each version pins the plugin’s commit and the LayerFS release and commit it was tested with.

VersionDatePlugin commitLayerFS
v0.1.0newestFirst release: self-contained Linux x86_64 archive with Pi 1.4.0, the LayerFS 1.1.0 agent and backend packages, daemon and runtime image.2026-10-25b6bdc7f4d0v1.1.0 @ ad78914e36