Single-file vaults
Each agent operates inside a vault — a single-file workspace (SQLite by default, Sled or LMDB behind feature flags) at ~/.avfs/vaults/<name>.avfs. The agent never touches your real filesystem.
Features
Everything inside the boundary
agentvfs gives an agent an isolated workspace and one carefully-drawn execution line. Here is the full surface — grounded in the crate, nothing invented.
Isolation & vault
The agent works inside a sealed workspace, never your host filesystem.
Mounts as a real directory
MountSession exposes the vault over FUSE as an ordinary path, so git, cargo, npm, python, and jq all run unchanged inside the boundary — no syscall shimming, no special SDK.
Quotas
Per-vault max_size_mb, max_files, and max_file_size_mb block runaway writes with typed QuotaExceeded errors before disk fills.
Atomic transactions
SQLite mutations use BEGIN IMMEDIATE / COMMIT / ROLLBACK, so concurrent access to a vault never races.
Forks & checkpoints
Cheap per-task copies and a rollback point before anything risky.
Instant forks
avfs vault fork clones a vault into a task workspace in milliseconds. Run experiments in parallel without copying files; discard the fork when the task is done.
Checkpoint & rollback
avfs checkpoint save creates a rollback point; checkpoint restore snaps the workspace back if an execution mutated state you did not want.
Policy-driven auto-checkpoint
Commands the policy engine grades as risky can auto-checkpoint before they run, so a rollback point always exists when it matters.
Open-file state tracking
FUSE file handles move Open → Dirty → Persisting → Flushed, eliminating double-persist races during rollback and normal writes.
Policy-gated proxy boundary
One top-level command surface, classified before any work happens.
Single execution surface
avfs proxy exec -- <cmd> is the agent-facing surface. The command is classified, the workspace is mounted, the command runs, and a structured result comes back — one call.
PolicyEngine decisions
A side-effect-free engine classifies each top-level command as allow, allow_with_checkpoint, deny, or require_approval, evaluated before any expensive workspace work.
Bounded execution
ExecutionTimeout is None or Millis(u64) (default 300s) with SIGTERM-then-SIGKILL escalation and dedicated pipe-drain threads.
Honest scope
agentvfs draws one line — the top-level command the agent asks to run. It is deliberately not a syscall monitor; compose it under a container or microVM when you need stronger guarantees.
Structured results
Everything an agent needs to reason about an execution, as JSON.
ExecutionEnvelope
proxy exec returns a versioned envelope with stdout, stderr, exit code, duration, the policy decision, and the list of changed files.
Typed errors
Errors return typed { error, message, ... } objects instead of scraped text, so an agent can branch on the failure class.
Change summaries
A ChangeSummary reports exactly which files an execution touched, giving the agent an audit trail of every mutation.
--json everywhere
Every command supports --json, so the whole CLI is drivable by an agent or orchestrator without parsing human output.
See how the pieces fit
Read the architecture, walk the guides, or browse use cases.