Workspace runtime and execution boundary for AI agents
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.
With cargo:
cargo install agentvfsWith npm:
npm install -g agentvfs-cliWith pip:
pip install agentvfs-cliThe pip wrapper auto-fetches the matching native binary on first invocation
and caches it under ~/.cache/agentvfs/<version>/. See
packaging/pypi/README.md
for resolution order, the AGENTVFS_BIN override, and offline-install notes.
# 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.pyfrom 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_filesSee the full documentation for more integration patterns.
- Agent requests a command →
avfs proxy exec -- cargo build - Proxy checks policy → Is this command allowed?
- Checkpoint created → Automatic rollback point if configured
- Workspace mounted → FUSE exposes the vault as a real directory
- Command executes → Standard tools run normally, with configurable timeouts
- 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.
- Atomic transactions — SQLite backend uses
BEGIN IMMEDIATEfor 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 → Flushedstates to eliminate persist races
| 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.
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
Full documentation is available at docs.neullabs.com/agentvfs
- Getting Started — Installation and first steps
- Core Concepts — Vaults, forks, checkpoints, mounts
- Agent Integration — Building agents with agentvfs
- Proxy Boundary — Execution model and policy
- Command Reference — All CLI commands
MIT