Workspace runtime and execution boundary for AI agents

Building autonomous agents means giving them shell access. The naive choices all have a known pain point:

• Docker bind-mounts — Docker moby/moby #1820 and follow-ups make cross-platform bind-mounts fragile on macOS hosts; containerised agents inherit Docker's daemon, cgroup, and network stack overhead
• Syscall tracing (bubblewrap/firejail) — strong isolation, but tools that read their own /proc or query uname break; agents that need to call the host compiler fail mysteriously
• Per-tool sandboxing (Anthropic, OpenAI) — works until you need two tools to share state, or until you need to roll back
• Pyfilesystem2 / go-cloud — VFS libraries, not execution boundaries; you still have to build the proxy yourself

agentvfs gives you a single proxy surface (avfs proxy exec -- cmd) that handles checkpoints, isolation, timeouts, and change tracking without the syscall-level complexity or the daemon overhead.

For agent developers and architects building autonomous systems:

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 agentvfs

With npm:

npm install -g agentvfs-cli

With pip:

pip install agentvfs-cli

The 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.py

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.

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.

• 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

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