The cheapest useful boundary between agent and host.

What agentvfs is

agentvfs is a Rust runtime, distributed on crates.io as agentvfs, with thin npm and pip wrappers that fetch the native binary. It exposes a CLI (avfs) and a library API, and it ships a JSON output mode on every command so an agent harness can drive it from any language.

The product surface is four things on top of a persistent vault:

• Vaults — single-file workspaces (.avfs by default, SQLite-backed) that hold durable filesystem state, version history, metadata, snapshots, and an audit log.
• Forks — cheap task-scoped clones of a vault. The README's outcome view treats forks as the default unit of agent work.
• Checkpoints — explicit rollback points inside a vault. Policy can auto-checkpoint around risky commands.
• Proxy boundary — the agent-facing execution surface (avfs proxy exec -- <cmd>) that classifies, mounts, runs, and reports.

Design rationale

The architecture document is explicit about what agentvfs is not: it is "a top-level command boundary, not a syscall monitor." That is a load-bearing design decision. Two questions drove it:

1. Where do agent failures actually happen? In practice, the vast majority of harmful agent behavior is one top-level command: a stray rm -rf, a misconfigured migration, a curl piped to bash that should never have been allowed. Catching that command before it executes — and rolling back if it executes badly — covers most real incidents without paying the cost of a full sandbox.
2. What lets standard CLI tooling stay unchanged? Agents already know how to call git, cargo, npm, jq, python. A workspace that mounts as a real directory means none of that ecosystem has to be re-implemented inside a sandbox. FUSE provides the directory; the proxy provides the policy.

That choice has costs. agentvfs cannot stop a hostile subprocess from making syscalls; it does not try to. If you need defense against a malicious binary, layer agentvfs on top of OS isolation (containers, microVMs, seccomp). The runtime's value is the layer above that, where you choose which commands to allow, decide what to roll back, and report what changed.

Threat model summary

agentvfs is built for an honest-but-fallible agent, not a malicious one. The threats it does address:

• Accidental host-filesystem damage. The agent operates in a vault. The vault is one file (or directory, depending on backend). Damage to the host's real filesystem requires the agent to break out of the proxy, which the boundary makes hard but does not enforce at the kernel.
• Unrecoverable state. Checkpoints exist. Policy can auto-checkpoint before destructive commands. Rollback is one CLI invocation.
• Unbounded execution. ExecutionTimeout is configurable, default 300 seconds, with SIGTERM → SIGKILL escalation. Dedicated pipe-drain threads collect stdout and stderr so a hung child cannot wedge the proxy.
• Resource exhaustion. Quotas (max_size_mb, max_files, max_file_size_mb) block runaway writes with typed errors before the disk fills.
• Concurrent corruption. The SQLite backend uses BEGIN IMMEDIATE for all mutations. A weak-reference cache deduplicates backend handles per vault. Mount sessions guard against double-unmount. Open file handles transition through explicit states to avoid persist races.
• Opaque failure. Every operation goes to the audit log. --json output returns typed errors with the data needed to diagnose them. The ExecutionEnvelope returns the changed-files summary after each proxy run.

The threats it does not address: full syscall tracing, complete subprocess visibility, kernel-level isolation, multi-tenant permission systems. The ROADMAP names all four as explicit non-goals for this phase.

What is shipped today

The runtime services are split: PolicyEngine, WorkspaceService, CheckpointService, MountSession, ChangeSummaryService, and ProxyRuntime, with the CLI as a thin adapter. SQLite is the default and production-recommended storage backend; Sled and LMDB are pluggable via feature flags. FUSE-backed runtime pieces are gated behind --features fuse. The benchmark page in the repo reports SQLite read throughput from 109 MiB/s at 1 KB up to 4.5 GiB/s at 1 MB on an Apple M3 Pro.

What it is part of

agentvfs is a neul-labs project. Project documentation lives at agentvfs.docs.neullabs.com — neullabs uses subdomain-per-project documentation rather than path-based docs.

How to engage

Install with cargo install agentvfs, npm install -g agentvfs-cli, or pip install agentvfs-cli. The source is at github.com/neul-labs/agentvfs under the MIT license. The contribution guide is in CONTRIBUTING.md. The strategic roadmap is in ROADMAP.md — the most useful read if you want to know which parts of the proxy boundary are about to stabilize next.