README
¶
ovnfs
Checkouts for agents: isolated, copy-on-write views of any folder, a git
repository or not, opened without copying it. Agents work in
the checkout; you review with diff and merge back with a three-way apply.
Checkouts can be snapshotted, forked, and attached to another machine, where
their content arrives on first read.
One daemon serves every checkout as a folder of a single mount: NFSv3 on macOS, FUSE on Linux, SMB or WinFsp on Windows. No root, and no kernel extension beyond WinFsp where you install it.
Install
Linux and macOS:
curl -fsSL https://stencil.so/ovnfs.sh | sh
Windows (PowerShell):
irm https://stencil.so/ovnfs.ps1 | iex
The installers download the latest release binary (Linux, macOS and Windows on
amd64 and arm64) from build.stencil.so, check its SHA-256 and put it in
~/.local/bin, or on Windows in %LOCALAPPDATA%\Programs\ovnfs, added to the
user PATH. OVNFS_INSTALL_DIR picks another folder, --version v0.2.3
(-Version on Windows) another release. With Go (see go.mod):
go install github.com/stencil-hq/ovnfs@latest
go build -o bin/ovnfs . builds a clone. ovnfs reads and writes git
repositories itself, so it needs no git installation (fetches use git when it
is on the PATH); on Linux it needs
fusermount3 (the fuse3 package). ovnfs version prints the build;
ovnfs update replaces it with the latest, through go install when that
built it, and ovnfs restart then moves the daemon onto it.
GitHub releases carry the same
binaries as archives.
Quick start
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 and its unused snapshots
More, from ~/src/app:
ovnfs run -- make test # a disposable checkout: run, then remove
ovnfs new --rev main # start from a revision instead of the working tree
ovnfs attach app --to devbox # the same checkout on another machine, fetched lazily
ovnfs send . devbox:src/app # attach over ssh, installing ovnfs there first if missing
ovnfs push app # copy what devbox still reads from here, so it works with this machine off
ovnfs grep 'TODO' app # search in the daemon, without traversing the mount
ovnfs glob '*.go' app # matching paths, recursively and ignore-aware
ovnfs ls . # the checkouts of this folder
ovnfs prune . --idle 7d # remove those untouched for a week (--dry-run first)
ovnfs help lists every verb, grouped by what they do and coloured on a
terminal (--color auto|always|never, NO_COLOR honoured; a pipe gets plain
text). Bash, zsh and fish completion come from the same grammar:
eval "$(ovnfs completion bash -c)", or ovnfs completion zsh -c for the
shell to source. Verbs start the daemon when none is running;
start, stop, restart and status manage it, serve runs it in the
foreground. restart swaps in the daemon of the binary you run, e.g. after an
upgrade, leaving an NFS or SMB mount and the shells inside it in place. stop
fails while something uses the mount; a second stop forces the unmount.
How it works
Opening a folder sorts every path into a class. source paths are captured:
they are what diff, apply and snapshots see, and the only bytes that leave
the machine. cache and local paths (build outputs, ignored files, secrets)
show the live folder until the checkout writes them: a path it writes or
deletes stays its own from then on, and apply never carries it back.
hidden paths are absent. Built-in rules
handle the common cases; .o2/ovnfs.yml and --rule override them, and
ovnfs explain PATH says which rule decided.
Writes go to the checkout's own copy-on-write layer, so the folder is never
written until you apply. In a git repository the checkout gets a private git
directory: commit freely, then apply --branch NAME to bring the commits back.
ovnfs isolates files, not processes: it is not a sandbox.
Documentation
- Configuration: classes, rules,
.o2/ovnfs.yml, where state and checkouts live - Checkouts:
--rev,--take,run, snapshots, forks,diffandapply - Remote checkouts:
attach,send,pull,push,share - Platforms: NFS, FUSE, SMB and WinFsp frontends
- Internals: admin protocol for embedding, persistence, memory tiers
- Limitations
- Development: tests and benchmarks
- Agent skill: teaches coding agents to work in checkouts; copy
skills/ovnfsinto your agent's skills directory
License
Documentation
¶
Overview ¶
Command ovnfs opens copy-on-write checkouts of any folder and serves them to agents.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package admin implements the daemon's local control protocol.
|
Package admin implements the daemon's local control protocol. |
|
Package api defines the admin operations shared by the daemon and the CLI.
|
Package api defines the admin operations shared by the daemon and the CLI. |
|
Package base provides persistent, fork-time views of a captured source folder.
|
Package base provides persistent, fork-time views of a captured source folder. |
|
Package checkout manages checkouts: isolated, copy-on-write copies of any folder that agents work in, plus their snapshots, forks and the way back to the source.
|
Package checkout manages checkouts: isolated, copy-on-write copies of any folder that agents work in, plus their snapshots, forks and the way back to the source. |
|
Package export presents checkout filesystems through one shared export root.
|
Package export presents checkout filesystems through one shared export root. |
|
Package fuse serves the export root over the Linux kernel's FUSE protocol: the root lists checkouts read-only and each checkout below it is fully writable.
|
Package fuse serves the export root over the Linux kernel's FUSE protocol: the root lists checkouts read-only and each checkout below it is fully writable. |
|
Package git reads facts from git repositories found under a source folder.
|
Package git reads facts from git repositories found under a source folder. |
|
internal/config
Package config reads git configuration: the config file syntax, the merged view git builds from its system, global, repository, worktree and command-line scopes (with include and includeIf directives), typed queries (boolean, integer, pathname), and the <section>.<url>.<key> URL matching used by http.* and credential.* settings.
|
Package config reads git configuration: the config file syntax, the merged view git builds from its system, global, repository, worktree and command-line scopes (with include and includeIf directives), typed queries (boolean, integer, pathname), and the <section>.<url>.<key> URL matching used by http.* and credential.* settings. |
|
internal/fetch
Package fetch transfers objects into a repository from another one: a local object database copied in-process, a remote upload-pack service spoken to over smart HTTP(S), ssh, git://, a local path or a remote helper's connection, using protocol v2 with fallback to v0, a dumb HTTP server's files, or a remote helper's own fetch.
|
Package fetch transfers objects into a repository from another one: a local object database copied in-process, a remote upload-pack service spoken to over smart HTTP(S), ssh, git://, a local path or a remote helper's connection, using protocol v2 with fallback to v0, a dumb HTTP server's files, or a remote helper's own fetch. |
|
internal/index
Package index reads, edits and writes git's index file ("dircache"): versions 2, 3 and 4, split and sparse indexes, and the extensions git records alongside the entries.
|
Package index reads, edits and writes git's index file ("dircache"): versions 2, 3 and 4, split and sparse indexes, and the extensions git records alongside the entries. |
|
internal/merge
Package merge is git's three-way file merge, the in-process equivalent of `git merge-file -p`: it combines the changes from base to ours and from base to theirs line by line and brackets overlapping changes with conflict markers, byte for byte as git writes them.
|
Package merge is git's three-way file merge, the in-process equivalent of `git merge-file -p`: it combines the changes from base to ours and from base to theirs line by line and brackets overlapping changes with conflict markers, byte for byte as git writes them. |
|
internal/object
Package object is git's object model: object names (ID) in either hash format, object kinds, file modes, tree entries, and the object database that stores objects loose and in packs.
|
Package object is git's object model: object names (ID) in either hash format, object kinds, file modes, tree entries, and the object database that stores objects loose and in packs. |
|
internal/refs
Package refs reads and updates a repository's references — branches, tags, HEAD and other pseudorefs — and their reflogs, in either of git's ref storage formats: the "files" backend (loose ref files, packed-refs, logs/) and the "reftable" backend (a stack of binary tables under reftable/).
|
Package refs reads and updates a repository's references — branches, tags, HEAD and other pseudorefs — and their reflogs, in either of git's ref storage formats: the "files" backend (loose ref files, packed-refs, logs/) and the "reftable" backend (a stack of binary tables under reftable/). |
|
internal/repo
Package repo locates and opens git repositories the way git itself does: discovery from a directory inside a work tree (gitfiles, linked worktrees, core.worktree, GIT_CEILING_DIRECTORIES, filesystem boundaries, safe.directory and repository format checks), opening an explicit git directory, and creating a bare repository.
|
Package repo locates and opens git repositories the way git itself does: discovery from a directory inside a work tree (gitfiles, linked worktrees, core.worktree, GIT_CEILING_DIRECTORIES, filesystem boundaries, safe.directory and repository format checks), opening an explicit git directory, and creating a bare repository. |
|
internal/rev
Package rev resolves git revision expressions (gitrevisions) to object names, maps branches to their upstream and push destinations, and answers commit-graph questions (ancestry, merge bases).
|
Package rev resolves git revision expressions (gitrevisions) to object names, maps branches to their upstream and push destinations, and answers commit-graph questions (ancestry, merge bases). |
|
internal
|
|
|
clone
Package clone copies regular files and directory hierarchies by sharing their data blocks where the filesystem supports it, and by copying bytes everywhere else, so callers get one portable copy primitive:
|
Package clone copies regular files and directory hierarchies by sharing their data blocks where the filesystem supports it, and by copying bytes everywhere else, so callers get one portable copy primitive: |
|
dirbottom
Package dirbottom provides a live host-directory bottom for overlay tests.
|
Package dirbottom provides a live host-directory bottom for overlay tests. |
|
durable
Package durable flushes ovnfs's own metadata files (state.json, pins.log, nodes.log and the directories holding them) to stable storage.
|
Package durable flushes ovnfs's own metadata files (state.json, pins.log, nodes.log and the directories holding them) to stable storage. |
|
hostfile
Package hostfile opens, renames and removes host files, and sets a symlink's own times, with POSIX semantics on every platform.
|
Package hostfile opens, renames and removes host files, and sets a symlink's own times, with POSIX semantics on every platform. |
|
nfstest
Package nfstest drives an in-process NFSv3 server without a kernel mount.
|
Package nfstest drives an in-process NFSv3 server without a kernel mount. |
|
release
Package release finds ovnfs release binaries on Stencil's build service, where release.yml publishes them (see the upload command beside this package).
|
Package release finds ovnfs release binaries on Stencil's build service, where release.yml publishes them (see the upload command beside this package). |
|
release/upload
command
Command upload publishes a release's binaries to Stencil's build service, which the installers, `ovnfs update` and `ovnfs send` download them from.
|
Command upload publishes a release's binaries to Stencil's build service, which the installers, `ovnfs update` and `ovnfs send` download them from. |
|
search/fsys
Package fsys is the filesystem layer the search tools read through: directory listings, file contents, and change stamps.
|
Package fsys is the filesystem layer the search tools read through: directory listings, file contents, and change stamps. |
|
search/glob
Package glob finds the files and directories below a root whose walk-relative paths match a glob, using the shared filesystem walker.
|
Package glob finds the files and directories below a root whose walk-relative paths match a glob, using the shared filesystem walker. |
|
search/grep
Package grep searches file contents for a regular expression using the shared walker and filesystem layer.
|
Package grep searches file contents for a regular expression using the shared walker and filesystem layer. |
|
search/pattern
Package pattern compiles glob patterns with the semantics of Rust's `globset` crate built with literal separators, the dialect gitignore rules (via the `ignore` crate) and the glob/grep filters use:
|
Package pattern compiles glob patterns with the semantics of Rust's `globset` crate built with literal separators, the dialect gitignore rules (via the `ignore` crate) and the glob/grep filters use: |
|
search/walk
Package walk is the parallel directory walker the search tools traverse with: gitignore-aware, cache-backed, and reading only through fsys.
|
Package walk is the parallel directory walker the search tools traverse with: gitignore-aware, cache-backed, and reading only through fsys. |
|
unixstat
Package unixstat reads the POSIX metadata that os.FileInfo keeps in Sys, for the frontends that report it (NFS, FUSE, remote-fs).
|
Package unixstat reads the POSIX metadata that os.FileInfo keeps in Sys, for the frontends that report it (NFS, FUSE, remote-fs). |
|
Package manifest resolves the rules, cache recipes and environment of a checkout from command-line overrides, the folder's `.o2/ovnfs.yml`, the user's `~/.o2/ovnfs.yml` and the builtin rules, and freezes the result as a Lock.
|
Package manifest resolves the rules, cache recipes and environment of a checkout from command-line overrides, the folder's `.o2/ovnfs.yml`, the user's `~/.o2/ovnfs.yml` and the builtin rules, and freezes the result as a Lock. |
|
Package nfs serves a Backend over NFSv3 (RFC 1813, with MOUNT v3) and NFSv4.0 (RFC 7530) on one TCP port.
|
Package nfs serves a Backend over NFSv3 (RFC 1813, with MOUNT v3) and NFSv4.0 (RFC 7530) on one TCP port. |
|
Package ntinfo describes export files in Windows NT terms (FILETIME stamps, FILE_ATTRIBUTE_* masks, allocation sizes, symlink reparse buffers, NTSTATUS codes) for the frontends that serve Windows clients: the SMB server and the WinFsp drive.
|
Package ntinfo describes export files in Windows NT terms (FILETIME stamps, FILE_ATTRIBUTE_* masks, allocation sizes, symlink reparse buffers, NTSTATUS codes) for the frontends that serve Windows clients: the SMB server and the WinFsp drive. |
|
Package overlay merges a writable upper over indexed immutable layers and a read-only bottom.
|
Package overlay merges a writable upper over indexed immutable layers and a read-only bottom. |
|
Package peer is the link protocol that attaches a checkout on one machine to another: the source machine offers a snapshot (every leaf with its git id), the remote machine accepts it and then fetches blob content lazily, verifying each blob by its id before it enters the remote's store.
|
Package peer is the link protocol that attaches a checkout on one machine to another: the source machine offers a snapshot (every leaf with its git id), the remote machine accepts it and then fetches blob content lazily, verifying each blob by its id before it enters the remote's store. |
|
Package remotefs serves one checkout over remote-fs v1, the Unix-socket protocol a vibevmm VM's virtio-fs `home` device (`--remote-fs TAG:SOCK[:rw]`) speaks: 9-byte frames carrying path-addressed JSON requests, one in flight per connection, no hello, no handles and no inode numbers.
|
Package remotefs serves one checkout over remote-fs v1, the Unix-socket protocol a vibevmm VM's virtio-fs `home` device (`--remote-fs TAG:SOCK[:rw]`) speaks: 9-byte frames carrying path-addressed JSON requests, one in flight per connection, no hello, no handles and no inode numbers. |
|
Package rules classifies every path of a source folder into source, cache, local or hidden with an ordered list of `<class> <predicate>` rules.
|
Package rules classifies every path of a source folder into source, cache, local or hidden with an ordered list of `<class> <predicate>` rules. |
|
Package smb serves an overlay filesystem over SMB2 and SMB3 Direct TCP.
|
Package smb serves an overlay filesystem over SMB2 and SMB3 Direct TCP. |
|
auth
Package auth implements NTLMv2 authentication and SMB signing primitives.
|
Package auth implements NTLMv2 authentication and SMB signing primitives. |
|
Package source captures a folder into a snapshot: it walks the folder once, classifies every path with the checkout's rules, and stores the content of source-class files.
|
Package source captures a folder into a snapshot: it walks the folder once, classifies every path with the checkout's rules, and stores the content of source-class files. |
|
Package store keeps git-format objects (blobs and trees) content-addressed under one directory, without git's "<type> <len>\x00" header.
|
Package store keeps git-format objects (blobs and trees) content-addressed under one directory, without git's "<type> <len>\x00" header. |
|
Package watch reports changes below host directories: FSEvents on macOS, inotify on Linux, ReadDirectoryChangesW on Windows.
|
Package watch reports changes below host directories: FSEvents on macOS, inotify on Linux, ReadDirectoryChangesW on Windows. |
|
Package winfsp serves the export root as a Windows drive through WinFsp (https://winfsp.dev), a user-mode filesystem driver installed once per machine: the root lists checkouts read-only and each checkout below it is fully writable.
|
Package winfsp serves the export root as a Windows drive through WinFsp (https://winfsp.dev), a user-mode filesystem driver installed once per machine: the root lists checkouts read-only and each checkout below it is fully writable. |
Click to show internal directories.
Click to hide internal directories.