layerfs
Supports routing sandboxed workspace command execution to Cloudflare Sandbox through the pluggable ExecutionDriver seam.
Supports routing sandboxed workspace command execution to Modal remote sandboxes through the pluggable ExecutionDriver seam.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
minilfs (RoacherM/minilfs)
One-sentence summary:
minilfsis the zero-Docker macOS-native Agent Runtime for LayerFS v1.1.0: it pairs the official@layerfs/agentSDK (1 call = 1 Commit, full-tree import including.gitand dependencies, explicit Sandbox + NFSv3 Workspace lifecycle, native 3-waybranch.mergewith merge units +.lww) with an Anthropic (@anthropic-ai/sandbox-runtime/srt)-style macOS Seatbelt (sandbox-exec) pure sandbox, so agents read, edit, build, test, commit, and merge entirely inside isolated Branches untilapplywrites back to your host folder.
minilfs (@roacherm/minilfs) is a 100% Native, Zero-Docker LayerFS workspace runtime, Pi / Epi extension, universal CLI / MCP server, and pluggable distributed execution engine.
It isolates coding agents' file operations and shell commands on copy-on-write LayerFS branches, guarded at the OS kernel level by a Claude Code (@anthropic-ai/sandbox-runtime / srt)-inspired macOS Seatbelt (sandbox-exec) sandbox — while providing a clean ExecutionDriver seam to route workloads to remote or distributed Sandboxes without changing a single upper-layer call.
Architecture: Three-Tier Pluggable Design
┌─────────────────────────────────────────────────────────────────────────┐
│ Tier 1: Universal Agent Harness Adapters │
│ ├─ Pi & Epi Extension (`src/index.ts`) │
│ │ `epi install git:github.com/RoacherM/minilfs` │
│ │ `pi install git:github.com/RoacherM/minilfs` │
│ ├─ CLI & MCP Server (`src/cli.ts`) │
│ │ `minilfs mcp` -> Claude Code / Codex / Cursor MCP Server │
│ │ `minilfs exec -- <cmd>` -> Sandboxed branch command runner │
│ └─ Programmatic SDK (`@roacherm/minilfs/core`, `src/core/index.ts`) │
├─────────────────────────────────────────────────────────────────────────┤
│ Tier 2: Harness-Agnostic Workspace & DAG Engine (`src/workspace.ts`) │
│ • In-process APFS SQLite Store (`layerfs.node`) — 1–8ms file ops │
│ • Multi-Agent Team DAG: `merge` (with automatic 3-way path fallback), │
│ `sync`, `diff`, `ls`, `show` (paginated), `checkout`, `apply` │
│ • Persistent post-merge `mtime` refresh across remounts │
├─────────────────────────────────────────────────────────────────────────┤
│ Tier 3: Pluggable ExecutionDriver Seam (`src/core/driver.ts`) │
│ ├─ `LocalNativeDriver` (Default): │
│ │ • Local `layerfs-daemon` NFSv3 loopback + `/sbin/mount_nfs` │
│ │ • Claude Code (`srt`)-style macOS Seatbelt (`sandbox-exec`) │
│ │ • Built-in `cd <hostCwd>` redirect, macOS `timeout` shim, │
│ │ and per-branch APFS scratch (`$MINILFS_SCRATCH_DIR`) │
│ └─ `registerExecutionDriver(name, driver)` (Distributed Seam): │
│ Route `execInWorkspace` to remote/distributed Sandboxes │
│ (Cloudflare Sandbox, E2B, Modal, SSH/RPC compute nodes) │
└─────────────────────────────────────────────────────────────────────────┘Related MCP server: my-pi
1. Prerequisites (Once per Mac — Zero Docker, Zero Root, Zero macFUSE)
Nothing on Apple silicon (macOS 11+): the first start downloads the prebuilt LayerFS bundle (layerfs-daemon, layerfs.node, JS SDK; ~8 MB) from this repository's GitHub releases, checks its pinned sha256 and installs it in ~/.cache/minilfs/bundle-<commit7> (named after the LayerFS commit pinned in layerfs.json; MINILFS_BUNDLE overrides it). A bundle of another LayerFS commit is refused, never used.
The bundle is built in CI: .github/workflows/bundle.yml runs scripts/setup-layerfs.sh on a macOS Apple-silicon runner whenever that recipe changes (or by hand), packs it with scripts/package-bundle.sh, smoke-tests it (scripts/smoke-bundle.mjs: LayerFS Init and a read with the packed binaries), publishes a release and pins its URL and sha256 in src/bundle.json. To upgrade LayerFS, change the commit in scripts/setup-layerfs.sh and push.
To build it from LayerFS source yourself (needs Rust), or on another machine:
git clone https://github.com/RoacherM/minilfs.git
./minilfs/scripts/setup-layerfs.sh2. Install in Epi or Pi
Epi
# Global install (~/.epi/epi.json)
epi install git:github.com/RoacherM/minilfs
# Or project-only (.epi/epi.json)
epi install -l --approve git:github.com/RoacherM/minilfsPi
# Global install (~/.pi/agent/settings.json)
pi install git:github.com/RoacherM/minilfs
# Or project-only (.pi/settings.json)
pi install -l git:github.com/RoacherM/minilfs3. Use in Claude Code, Codex CLI, or Cursor (MCP + CLI)
As an MCP Server (.mcp.json or epi mcp add)
{
"mcpServers": {
"minilfs": {
"command": "node",
"args": ["/path/to/minilfs/src/cli.ts", "mcp"]
}
}
}As a Standalone CLI (minilfs)
# Run any command inside an isolated LayerFS branch + macOS Seatbelt sandbox
node ./src/cli.ts --branch worker-1 exec -- timeout 110 cargo test
# Inspect, diff, merge, apply, and clean scratch caches
node ./src/cli.ts status
node ./src/cli.ts branches
node ./src/cli.ts diff worker-1
node ./src/cli.ts merge worker-1
node ./src/cli.ts apply
node ./src/cli.ts clean4. Pluggable Distributed / Remote Sandbox Driver (@roacherm/minilfs/driver)
To dispatch workspace command execution to remote or distributed sandbox nodes while keeping all upper-layer tool calls unchanged:
import {
registerExecutionDriver,
LayerfsSession,
resolveConfig,
} from "@roacherm/minilfs/core";
registerExecutionDriver("remote-cluster", {
name: "remote-cluster",
async preflight() { return "remote-cluster"; },
async execInWorkspace(ctx) {
// Dispatch ctx.command + ctx.wsReal state to remote worker node, stream stdout to ctx.options.onData
return { exitCode: 0 };
},
async reapWorkspaceHolders() {},
});
const session = new LayerfsSession(process.cwd(), "worker-1", {
...resolveConfig(),
driver: "remote-cluster",
});
await session.open();5. Interactive Commands (/minilfs)
Command | Does |
| branch, logical alias, checkpoints, blocked state |
| files changed on this session's branch (or between any two branches) |
| checkpoints: tool, time, changed files, HEAD / applied |
| 3-way checked write back to your host folder |
| sync external host edits into LayerFS |
| active user/worker branches with logical aliases |
| merge another branch into yours (with automatic path-wise fallback merge) |
| remove temporary scratch build caches for this project |
| retry after a failed checkpoint |
| after an apply that could not finish changing the folder's git: where its previous versions are; |
6. Configuration (MINILFS_*)
Env | Default |
| on; |
|
|
|
|
|
|
|
|
|
|
|
|
| comma-separated build-output patterns (e.g. |
| logical branch alias for this session (defaults to |
|
|
|
|
| LayerFS Init timeout in milliseconds (defaults to |
|
|
| how long the store worker waits with no client before it exits (default |
| force |
What is imported: the full project tree (aligned with official LayerFS). Following LayerFS's core mental model ("A Workspace is a complete mutable filesystem view over an immutable committed root. Include .git and its index, ignored files, dependencies, symlinks, caches and output; Git ignore rules do not filter LayerFS state"), a session's Branch holds the complete project tree, .git/ and dependencies included (06 · Instant Bootstrap). Only secret patterns (MINILFS_EXCLUDES) and explicit MINILFS_BRANCH_ONLY patterns stay out.
Pure Sandbox Model (In-Sandbox Git & Builds, Zero Host Elevation). Every agent's file tools (read, write, edit, ls, find, grep) and bash act strictly on its own isolated LayerFS Branch (1 call = 1 Commit):
Because
.git/lives inside each Branch's Workspace,git status,diff,log,add,commit,branchandmergework natively inside the sandboxedbashwithout touching the host folder..gitis an allowlist (src/gitpaths.ts): only git's data is writable — objects, refs, logs,HEAD,index,packed-refs, in-progress state. Everything else in a git directory can make git run code (config,config.worktree,hooks/,commondir,info/attributes,objects/info/alternates, submodulemodules/*/config|hooks, …): Seatbelt denies it (regex, any letter case), file tools refuse it, and apply never writes it. Sogit config,git remote addand hook installs fail in the sandbox; the user runs those.Merging Branches that both ran git:
.gitis one LayerFS merge unit (branch.merge(…, units)): refs,HEADand the index come whole from one side, so the merged repository is consistent; objects merge as a union, and minilfs then records the join itself: a git merge commit on the checked-out branch whose parents are both sides' heads (lead first), made with git plumbing (merge-tree,commit-tree,update-ref; no work-tree change, no hook), sogit log mainholds every Branch's commits. Where git sees a conflict that LayerFS resolved, the merge commit records LayerFS's merged files. A fast-forward or an up-to-date side needs no commit. The other side's other branch heads are kept asrefs/minilfs/<branch>/heads/<name>.node_modulesis a merge unit too./.lwwdefaults to%include .gitignore(generated output is last-writer-wins).Apply and the folder's git: objects are added (never replaced or deleted); refs,
HEADand the index are three-way (the index by its entries, not its stat data). If the folder's git moved meanwhile (a commit made there), no ref,HEADor index is written: the files are applied and show as uncommitted, and the folder's history is never overwritten. Locks and in-progress state are never applied. A branch apply deletes whilegit worktree addchecks it out in a new worktree is put back (with a warning) when apply sees that worktree after its last rename; a worktree added after that check can still end up on a deleted branch: git's owngit branch -dchecks worktreeHEADs without a lock and has the same narrow window./minilfs diffand the apply preview add one.git:line, since views hide.git.Sub-agents work on their own branches and report their branch name; the lead agent merges sub-agent branches (
minilfs merge <branch>) and writes the result back to the host folder withminilfs_apply(/minilfs apply).
Isolation is for writes, not reads. bash runs under a "wide read, narrow write" Seatbelt profile (like Claude Code's srt): it can read host files outside the Branch except the secret patterns (.env, *.pem, ~/.ssh, the Store, …). Do not treat minilfs as a confidentiality boundary.
7. Architecture & Design Decisions
See docs/ARCHITECTURE-AND-DECISIONS.md for:
Alignment with the LayerFS 2.0 Roadmap (
#446)Three-Tier Architecture (
Adapters->Core Engine->ExecutionDriver)Root-cause diagnosis and solutions for all 10 multi-agent pain points
Architectural Decision Records (ADRs: Native NFSv3 + Seatbelt vs Docker/FUSE, Multi-Harness Store Sharing, Pluggable Distributed Driver)
Full
WayfareandQuarrymulti-agent benchmark comparisons
License
MIT.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Secure Linux sandboxes for AI agents, as MCP tools.
Persistent cloud workspaces for AI agents: run commands, edit files, use git and a browser.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Autonomous agent guardrails, bash sandboxing, MCP rugpull diffing & prompt firewalls.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceGives any MCP-compatible AI chat or agent a safe, model-neutral coding runtime with file read/search, structured multi-file patches, command execution, interactive sessions, and git operations, all confined to a single workspace and gated by permission modes.Apache 2.0
- AlicenseCqualityBmaintenanceLocal-first MCP runtime for coding agents with bounded workspace access, content-preconditioned writes, AST search, LSP navigation and diagnostics, and Git status/diff. Designed to give coding agents useful repository access without treating unrestricted shell access as the default integration boundary.133MIT
- AlicenseNot gradedqualityCmaintenanceEnables ChatGPT and other MCP clients to browse, search, edit and upload files, run commands and interactive terminals, inspect Git history and worktrees, dispatch coding agents, and install composable plugins within locally registered workspaces. Requests execute under the user's own machine with per-request approval or auto-approval, keeping files, tasks and results local unless explicitly returned.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP-capable chat clients like ChatGPT, Claude, and Cursor to read, search, edit, and run commands on a local machine, including git operations and browser automation. Runs as a local daemon with workspace path jails, safety modes, checkpoints, and human-in-the-loop approval for edits and shell commands.MIT