{"id":50897709,"url":"https://github.com/neul-labs/agentvfs","last_synced_at":"2026-07-03T16:01:18.807Z","repository":{"id":356167553,"uuid":"1186718459","full_name":"neul-labs/agentvfs","owner":"neul-labs","description":"Workspace runtime and execution boundary for AI agents","archived":false,"fork":false,"pushed_at":"2026-06-08T12:56:06.000Z","size":1421,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-30T17:20:50.150Z","etag":null,"topics":["agent-runtime","agent-sandbox","agentic-ai","ai-agents","execution-boundary","filesystem","neul-labs","rust","sandbox","sqlite","vfs","virtual","workspace"],"latest_commit_sha":null,"homepage":"https://agentvfs.neullabs.com","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/neul-labs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-19T23:18:33.000Z","updated_at":"2026-06-11T17:04:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/neul-labs/agentvfs","commit_stats":null,"previous_names":["neul-labs/agentvfs"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/neul-labs/agentvfs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neul-labs%2Fagentvfs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neul-labs%2Fagentvfs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neul-labs%2Fagentvfs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neul-labs%2Fagentvfs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/neul-labs","download_url":"https://codeload.github.com/neul-labs/agentvfs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neul-labs%2Fagentvfs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35092185,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-03T02:00:05.635Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-runtime","agent-sandbox","agentic-ai","ai-agents","execution-boundary","filesystem","neul-labs","rust","sandbox","sqlite","vfs","virtual","workspace"],"created_at":"2026-06-16T01:31:30.076Z","updated_at":"2026-07-03T16:01:18.798Z","avatar_url":"https://github.com/neul-labs.png","language":"Rust","funding_links":[],"categories":["ai-agents"],"sub_categories":[],"readme":"# agentvfs\n\n\u003cp align=\"center\"\u003e\u003cstrong\u003eWorkspace runtime and execution boundary for AI agents\u003c/strong\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://crates.io/crates/agentvfs\"\u003e\u003cimg src=\"https://img.shields.io/crates/v/agentvfs.svg\" alt=\"Crates.io\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://docs.neullabs.com/agentvfs\"\u003e\u003cimg src=\"https://img.shields.io/badge/docs-neullabs.com-blue.svg\" alt=\"Documentation\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License: MIT\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://crates.io/crates/agentvfs\"\u003e\u003cimg src=\"https://img.shields.io/crates/d/agentvfs.svg\" alt=\"Downloads\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://agentvfs.neullabs.com\"\u003eWebsite\u003c/a\u003e ·\n  \u003ca href=\"https://docs.neullabs.com/agentvfs\"\u003eDocumentation\u003c/a\u003e ·\n  \u003ca href=\"https://github.com/neul-labs/agentvfs\"\u003eGitHub\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Why agentvfs?\n\nBuilding autonomous agents means giving them shell access. The naive\nchoices all have a known pain point:\n\n- **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\n- **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\n- **Per-tool sandboxing (Anthropic, OpenAI)** — works until you need two tools to share state, or until you need to roll back\n- **Pyfilesystem2 / go-cloud** — VFS libraries, not execution boundaries; you still have to build the proxy yourself\n\nagentvfs gives you a **single proxy surface** (`avfs proxy exec -- cmd`)\nthat handles checkpoints, isolation, timeouts, and change tracking\nwithout the syscall-level complexity or the daemon overhead.\n\n| Feature | agentvfs | Docker bind-mount | bubblewrap | pyfilesystem2 | E2B / Fly sandboxes |\n|---|---|---|---|---|---|\n| Cold start | ~5ms (fork) | ~500ms | ~50ms | in-process | 1-3s (network) |\n| Checkpoint / rollback | ✅ first-class | ❌ (manual layers) | ❌ | ❌ | ❌ |\n| Network-free | ✅ | ❌ | ✅ | ✅ | ❌ |\n| Standard tooling works | ✅ | ✅ | ⚠️ | ❌ | ✅ |\n| Designed for agent loops | ✅ | ⚠️ | ❌ | ❌ | ✅ |\n| Open source | ✅ MIT | ✅ Apache | ✅ | ✅ | ❌ |\n\n## What You Get\n\nFor **agent developers** and **architects** building autonomous systems:\n\n| Capability | What It Means |\n|------------|---------------|\n| **Isolated Workspaces** | Agents operate in contained vaults, not your host filesystem |\n| **Instant Forks** | Spin up cheap task workspaces in milliseconds |\n| **Rollback Points** | Checkpoint before risky operations, restore if needed |\n| **Proxy Boundary** | Single execution surface with policy control and change tracking |\n| **Standard Tooling** | Mount workspaces as real directories—`git`, `cargo`, `npm` just work |\n| **Structured Output** | JSON responses designed for agent integration |\n\nThe proxy boundary mediates between your agent and the workspace:\n\n```text\nagent → proxy boundary → mounted forked workspace → cli tools\n```\n\nIt governs what commands run, creates checkpoints, and reports filesystem deltas back to your agent.\n\n## Quick Start\n\n### Install\n\n**With cargo:**\n```bash\ncargo install agentvfs\n```\n\n**With npm:**\n```bash\nnpm install -g agentvfs-cli\n```\n\n**With pip:**\n```bash\npip install agentvfs-cli\n```\nThe pip wrapper auto-fetches the matching native binary on first invocation\nand caches it under `~/.cache/agentvfs/\u003cversion\u003e/`. See\n[packaging/pypi/README.md](packaging/pypi/README.md#native-binary-resolution)\nfor resolution order, the `AGENTVFS_BIN` override, and offline-install notes.\n\n### Basic Usage\n\n```bash\n# Create a workspace vault\navfs vault create myproject\n\n# Add files\navfs mkdir /src\navfs write /src/main.py \"print('hello')\"\n\n# Fork for a task\navfs vault fork myproject task-001 --use\n\n# Checkpoint before risky work\navfs checkpoint save before-refactor\n\n# Run commands via proxy (recommended for agents)\navfs proxy exec -- python /src/main.py\n```\n\n### Agent Integration (Python)\n\n```python\nfrom agentvfs import AVFS\n\navfs = AVFS(\"agent-workspace\")\n\n# Create isolated workspace\navfs.create_vault(\"agent-workspace\")\navfs.fork_vault(\"agent-workspace\", \"task-001\")\n\n# Checkpoint, execute, get structured result\navfs.checkpoint_save(\"pre-change\")\nresult = avfs.proxy_exec(\"cargo\", \"test\")\n# result contains: stdout, stderr, exit_code, changed_files\n```\n\nSee the [full documentation](https://docs.neullabs.com/agentvfs) for more integration patterns.\n\n## How It Works\n\n1. **Agent requests a command** → `avfs proxy exec -- cargo build`\n2. **Proxy checks policy** → Is this command allowed?\n3. **Checkpoint created** → Automatic rollback point if configured\n4. **Workspace mounted** → FUSE exposes the vault as a real directory\n5. **Command executes** → Standard tools run normally, with configurable timeouts\n6. **Result returned** → stdout, stderr, exit code, and changed files list\n\nThis is a **top-level command boundary**—cheap, practical, and designed for agent orchestration rather than syscall-level tracing.\n\n## Production Features\n\n- **Atomic transactions** — SQLite backend uses `BEGIN IMMEDIATE` for all filesystem mutations, eliminating race conditions during concurrent access\n- **Execution timeouts** — Proxy commands support millisecond-level timeouts with automatic SIGKILL escalation\n- **Mount session state machine** — Explicit mount/unmount lifecycle with double-unmount protection and automatic cleanup on drop\n- **Backend deduplication** — Weak-reference cache ensures only one backend handle per vault, preventing resource leaks\n- **Open file state tracking** — FUSE file handles track `Open → Dirty → Persisting → Flushed` states to eliminate persist races\n\n## Commands\n\n| Category | Commands |\n|----------|----------|\n| **Files** | `ls`, `cat`, `write`, `cp`, `mv`, `rm`, `tree`, `mkdir` |\n| **Search** | `grep`, `find`, `search` |\n| **Versioning** | `log`, `checkout`, `revert`, `diff` |\n| **Vaults** | `vault create`, `vault list`, `vault use`, `vault fork`, `vault delete` |\n| **Rollback** | `checkpoint save`, `checkpoint restore`, `checkpoint list` |\n| **Runtime** | `mount`, `unmount`, `proxy exec` |\n| **Maintenance** | `stats`, `audit`, `quota`, `gc`, `prune` |\n\nRun `avfs --help` for the full command reference, or see the [command documentation](https://docs.neullabs.com/agentvfs/reference/commands).\n\n## Benchmarks\n\nSee [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.\n\nHighlights (SQLite on Apple M3 Pro):\n- **Reads:** 109 MiB/s (1 KB) → 4.5 GiB/s (1 MB)\n- **Writes:** 9.2 MiB/s (1 KB) → 163.6 MiB/s (1 MB)\n- **Search:** Sub-millisecond FTS across 100 documents\n- **Scale:** ~16,500 ops/sec across 100 independent vaults\n\n## Documentation\n\nFull documentation is available at **[docs.neullabs.com/agentvfs](https://docs.neullabs.com/agentvfs)**\n\n- [Getting Started](https://docs.neullabs.com/agentvfs/getting-started) — Installation and first steps\n- [Core Concepts](https://docs.neullabs.com/agentvfs/concepts) — Vaults, forks, checkpoints, mounts\n- [Agent Integration](https://docs.neullabs.com/agentvfs/agent-integration) — Building agents with agentvfs\n- [Proxy Boundary](https://docs.neullabs.com/agentvfs/proxy-boundary) — Execution model and policy\n- [Command Reference](https://docs.neullabs.com/agentvfs/reference/commands) — All CLI commands\n\n## License\n\nMIT\n\n## Part of the Neul Labs toolchain\n\nPart of the [Neul Labs](https://www.neullabs.com) agent-infrastructure toolchain:\n\n| Project | Description |\n| --- | --- |\n| [memorg](https://memorg.neullabs.com) | Give your LLM a memory that actually works. |\n| [ormai](https://ormai.neullabs.com) | Give your AI agents database access without the risk — safe text-to-SQL. |\n| [mcp-pay](https://mcp-pay.neullabs.com) | Payment awareness layer for MCP (Model Context Protocol). |\n| [closegate](https://closegate.neullabs.com) | The policy chokepoint for finance AI agents. |\n| [regulus](https://regulus.neullabs.com) | The EU \u0026 UK compliance plane for Google ADK. |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneul-labs%2Fagentvfs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fneul-labs%2Fagentvfs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneul-labs%2Fagentvfs/lists"}