stencil-hq/ovnfs

What it does

ovnfs gives agents an isolated checkout of a folder — a git repository or just a directory tree — without copying it. The agent writes into a copy-on-write layer; the original folder stays untouched until you review with diff and merge changes with a three-way apply. Checkouts can be snapshotted, forked, and attached to another machine, with content fetched lazily on first read.

A single daemon mounts every checkout as a folder under one mount, using NFSv3 on macOS, FUSE on Linux, and SMB or WinFsp on Windows. It needs no root and no kernel extension except WinFsp on Windows. Paths inside a checkout are classified as source (captured and synchronized), cache/local (live folder, read-only) or hidden, which keeps build outputs and secrets out of the diff and off the wire.

Getting started

Requirements: Go (see go.mod), git, and on Linux fusermount3 from the fuse3 package. Prebuilt binaries for Linux, macOS and Windows on amd64 and arm64 are available from Releases; alternatively install with go install github.com/stencil-hq/ovnfs@latest or build a clone with go build -o bin/ovnfs .. Check the build with ovnfs version.

A typical flow starts in the folder you want the agent to work on:

cd ~/src/app
cd "$(ovnfs new)"              # starts the daemon, prints the checkout's path
git status                     # same status as ~/src/app; nothing is written there
# ...let the agent work...
ovnfs diff app -p              # what changed
ovnfs apply app                # merge it back into ~/src/app
cd ~/src/app && ovnfs rm app   # remove the checkout; its snapshots stay

Other verbs cover common workflows: ovnfs run -- make test for a disposable checkout, ovnfs new --rev main to start from a revision, ovnfs attach app --to devbox to open the same checkout on another machine, and ovnfs grep / ovnfs glob to search inside the daemon. Commands start the daemon when none is running; start, stop, restart, status and serve manage it explicitly. See the checkout documentation and remote checkout guide for details.

Configuration and platform notes

Path classification is driven by built-in rules and can be overridden through .o2/ovnfs.yml or --rule; ovnfs explain PATH reports which rule decided a path's class. In a git repository, each checkout gets a private git directory, so commits made inside it can be brought back with apply --branch NAME. Frontend differences between NFS, FUSE, SMB and WinFsp are documented in the platform guide.

Constraints

ovnfs isolates files, not processes: it is not a sandbox. apply mutates the original folder, so review the diff before merging. Remote checkouts (attach, pull, share) transmit captured source bytes between machines, which matters for data handling. The project maintains a dedicated limitations page worth reading before relying on it. It is MIT licensed.

HotRepo's take

ovnfs was recorded in the Go new-project ranking on 2026-11-08, gaining 5 stars over a roughly one-hour window that ended with 105 stars, while forks stayed at 7. That is a single short observation window, so it speaks to early attention rather than sustained adoption; the commit-level review and merge workflow, plus remote checkouts that arrive on first read, are the parts worth evaluating when deciding whether it fits an agent workflow.