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 runs git, and on Linux 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; its snapshots stay
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 and joining the mesh there first
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. 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.
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,share, the mesh - 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
|
|
|
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 mesh holds the wire-level building blocks shared by the ovnfs mesh transport: node identities and key files, TLS configurations that pin peers by key, ways to reach a node, and length-prefixed frames.
|
Package mesh holds the wire-level building blocks shared by the ovnfs mesh transport: node identities and key files, TLS configurations that pin peers by key, ways to reach a node, and length-prefixed frames. |
|
node
Package node is the ovnfs mesh runtime, wire-compatible with stencil-net's node: QUIC over a direct UDP socket and through a relay, peers proven by their Ed25519 keys, per-protocol listeners that signal READY, and a pool of dialed connections raced over every known way to a peer.
|
Package node is the ovnfs mesh runtime, wire-compatible with stencil-net's node: QUIC over a direct UDP socket and through a relay, peers proven by their Ed25519 keys, per-protocol listeners that signal READY, and a pool of dialed connections raced over every known way to a peer. |
|
relay
Package relay is a node's link to a stencil relay (`GET /node`, protocols stencil-relay.v2 and v1): it proves the node's identity, keeps the link up, and carries datagrams to and from peers reachable only through the relay.
|
Package relay is a node's link to a stencil relay (`GET /node`, protocols stencil-relay.v2 and v1): it proves the node's identity, keeps the link up, and carries datagrams to and from peers reachable only through the relay. |
|
roster
Package roster keeps who is in this machine's mesh: the members (pinned node keys and where each last said it listens), the single-use invite tickets a new machine joins with, the join token that carries one, and the join and sync exchanges members run on ALPN.
|
Package roster keeps who is in this machine's mesh: the members (pinned node keys and where each last said it listens), the single-use invite tickets a new machine joins with, the join token that carries one, and the join and sync exchanges members run on ALPN. |
|
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.