agentvfs 0.1.6

Virtual filesystem CLI backed by embedded databases for AI agents
Documentation

agentvfs

What You Get

For agent developers and architects building autonomous systems:

Capability What It Means
Isolated Workspaces Agents operate in contained vaults, not your host filesystem
Instant Forks Spin up cheap task workspaces in milliseconds
Rollback Points Checkpoint before risky operations, restore if needed
Proxy Boundary Single execution surface with policy control and change tracking
Standard Tooling Mount workspaces as real directories—git, cargo, npm just work
Structured Output JSON responses designed for agent integration

The proxy boundary mediates between your agent and the workspace:

agent → proxy boundary → mounted forked workspace → cli tools

It governs what commands run, creates checkpoints, and reports filesystem deltas back to your agent.

Quick Start

Install

With cargo:

cargo install agentvfs

With npm:

npm install -g agentvfs-cli

With pip:

pip install agentvfs

Basic Usage

# Create a workspace vault
avfs vault create myproject

# Add files
avfs mkdir /src
avfs write /src/main.py "print('hello')"

# Fork for a task
avfs vault fork myproject task-001 --use

# Checkpoint before risky work
avfs checkpoint save before-refactor

# Run commands via proxy (recommended for agents)
avfs proxy exec -- python /src/main.py

Agent Integration (Python)

from agentvfs import AVFS

avfs = AVFS("agent-workspace")

# Create isolated workspace
avfs.create_vault("agent-workspace")
avfs.fork_vault("agent-workspace", "task-001")

# Checkpoint, execute, get structured result
avfs.checkpoint_save("pre-change")
result = avfs.proxy_exec("cargo", "test")
# result contains: stdout, stderr, exit_code, changed_files

See the full documentation for more integration patterns.

How It Works

  1. Agent requests a command → avfs proxy exec -- cargo build
  2. Proxy checks policy → Is this command allowed?
  3. Checkpoint created → Automatic rollback point if configured
  4. Workspace mounted → FUSE exposes the vault as a real directory
  5. Command executes → Standard tools run normally, with configurable timeouts
  6. Result returned → stdout, stderr, exit code, and changed files list

This is a top-level command boundary—cheap, practical, and designed for agent orchestration rather than syscall-level tracing.

Production Features

  • Atomic transactions — SQLite backend uses BEGIN IMMEDIATE for all filesystem mutations, eliminating race conditions during concurrent access
  • Execution timeouts — Proxy commands support millisecond-level timeouts with automatic SIGKILL escalation
  • Mount session state machine — Explicit mount/unmount lifecycle with double-unmount protection and automatic cleanup on drop
  • Backend deduplication — Weak-reference cache ensures only one backend handle per vault, preventing resource leaks
  • Open file state tracking — FUSE file handles track Open → Dirty → Persisting → Flushed states to eliminate persist races

Commands

Category Commands
Files ls, cat, write, cp, mv, rm, tree, mkdir
Search grep, find, search
Versioning log, checkout, revert, diff
Vaults vault create, vault list, vault use, vault fork, vault delete
Rollback checkpoint save, checkpoint restore, checkpoint list
Runtime mount, unmount, proxy exec
Maintenance stats, audit, quota, gc, prune

Run avfs --help for the full command reference, or see the command documentation.

Benchmarks

See BENCHMARKS.md for detailed performance data across SQLite, Sled, and LMDB backends—including single-vault throughput, concurrent agent workloads, and multi-vault scale tests.

Highlights (SQLite on Apple M3 Pro):

  • Reads: 109 MiB/s (1 KB) → 4.5 GiB/s (1 MB)
  • Writes: 9.2 MiB/s (1 KB) → 163.6 MiB/s (1 MB)
  • Search: Sub-millisecond FTS across 100 documents
  • Scale: ~16,500 ops/sec across 100 independent vaults

Documentation

Full documentation is available at docs.neullabs.com/agentvfs

License

MIT