https://github.com/neul-labs/agentvfs
Workspace runtime and execution boundary for AI agents
https://github.com/neul-labs/agentvfs
agent-runtime agent-sandbox agentic-ai ai-agents execution-boundary filesystem neul-labs rust sandbox sqlite vfs virtual workspace
Last synced: 1 day ago
JSON representation
Workspace runtime and execution boundary for AI agents
- Host: GitHub
- URL: https://github.com/neul-labs/agentvfs
- Owner: neul-labs
- License: mit
- Created: 2026-03-19T23:18:33.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-06-08T12:56:06.000Z (26 days ago)
- Last Synced: 2026-06-30T17:20:50.150Z (4 days ago)
- Topics: agent-runtime, agent-sandbox, agentic-ai, ai-agents, execution-boundary, filesystem, neul-labs, rust, sandbox, sqlite, vfs, virtual, workspace
- Language: Rust
- Homepage: https://agentvfs.neullabs.com
- Size: 1.36 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Roadmap: ROADMAP.md
Awesome Lists containing this project
README
# agentvfs
Workspace runtime and execution boundary for AI agents
Website ·
Documentation ·
GitHub
---
## Why agentvfs?
Building autonomous agents means giving them shell access. The naive
choices all have a known pain point:
- **Docker bind-mounts** — Docker [moby/moby #1820](https://github.com/moby/moby/issues/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.
| Feature | agentvfs | Docker bind-mount | bubblewrap | pyfilesystem2 | E2B / Fly sandboxes |
|---|---|---|---|---|---|
| Cold start | ~5ms (fork) | ~500ms | ~50ms | in-process | 1-3s (network) |
| Checkpoint / rollback | ✅ first-class | ❌ (manual layers) | ❌ | ❌ | ❌ |
| Network-free | ✅ | ❌ | ✅ | ✅ | ❌ |
| Standard tooling works | ✅ | ✅ | ⚠️ | ❌ | ✅ |
| Designed for agent loops | ✅ | ⚠️ | ❌ | ❌ | ✅ |
| Open source | ✅ MIT | ✅ Apache | ✅ | ✅ | ❌ |
## 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:
```text
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:**
```bash
cargo install agentvfs
```
**With npm:**
```bash
npm install -g agentvfs-cli
```
**With pip:**
```bash
pip install agentvfs-cli
```
The pip wrapper auto-fetches the matching native binary on first invocation
and caches it under `~/.cache/agentvfs//`. See
[packaging/pypi/README.md](packaging/pypi/README.md#native-binary-resolution)
for resolution order, the `AGENTVFS_BIN` override, and offline-install notes.
### Basic Usage
```bash
# 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)
```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](https://docs.neullabs.com/agentvfs) 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](https://docs.neullabs.com/agentvfs/reference/commands).
## Benchmarks
See [BENCHMARKS.md](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](https://docs.neullabs.com/agentvfs)**
- [Getting Started](https://docs.neullabs.com/agentvfs/getting-started) — Installation and first steps
- [Core Concepts](https://docs.neullabs.com/agentvfs/concepts) — Vaults, forks, checkpoints, mounts
- [Agent Integration](https://docs.neullabs.com/agentvfs/agent-integration) — Building agents with agentvfs
- [Proxy Boundary](https://docs.neullabs.com/agentvfs/proxy-boundary) — Execution model and policy
- [Command Reference](https://docs.neullabs.com/agentvfs/reference/commands) — All CLI commands
## License
MIT
## Part of the Neul Labs toolchain
Part of the [Neul Labs](https://www.neullabs.com) agent-infrastructure toolchain:
| Project | Description |
| --- | --- |
| [memorg](https://memorg.neullabs.com) | Give your LLM a memory that actually works. |
| [ormai](https://ormai.neullabs.com) | Give your AI agents database access without the risk — safe text-to-SQL. |
| [mcp-pay](https://mcp-pay.neullabs.com) | Payment awareness layer for MCP (Model Context Protocol). |
| [closegate](https://closegate.neullabs.com) | The policy chokepoint for finance AI agents. |
| [regulus](https://regulus.neullabs.com) | The EU & UK compliance plane for Google ADK. |