FAQ
Questions about the boundary
What agentvfs is, what it is not, and how to run it safely. Still stuck? Talk to us.
+ Is agentvfs a sandbox like Docker or a microVM?
No. agentvfs is a workspace runtime: a vault (single-file database) plus a proxy boundary that classifies, checkpoints, mounts, and runs one top-level command at a time. It is explicitly a top-level command boundary, not a syscall monitor or kernel-level sandbox. Full syscall tracing and complete subprocess visibility are listed as explicit non-goals.
+ How is the workspace exposed to commands?
Via a FUSE mount. The MountSession transitions through explicit states, exposes the vault as a real directory, and tears down on drop. Standard CLIs (git, cargo, npm) see a normal filesystem path. FUSE-backed runtime pieces are feature-gated behind --features fuse.
+ What languages can an agent call agentvfs from?
Anything that can spawn a subprocess and parse JSON. There is a native cargo install, an npm CLI wrapper, and a pip wrapper that auto-fetches the matching native binary. Any language that runs avfs --json <cmd> works.
+ What backend should I use in production?
SQLite. It is the recommended production backend; LMDB and Sled backends do not yet have atomic transaction wrappers. Sled and LMDB are pluggable via feature flags (sled-backend, lmdb-backend).
+ Does the proxy guarantee that a script cannot escape the workspace?
No, and agentvfs is honest about this. It is a top-level command boundary: it does not try to observe every subprocess launched from inside scripts. Pair it with OS-level isolation (containers, microVMs, seccomp) if you need stronger guarantees against a hostile process.
+ What does the policy engine actually decide?
PolicyEngine classifies a top-level command and returns one of allow, allow_with_checkpoint, deny, or require_approval. It is side-effect-free and evaluated before any expensive workspace work, so denied commands never touch the mount.
+ How do forks and checkpoints differ?
A fork (avfs vault fork) clones a whole vault into a separate task workspace in milliseconds — useful for running parallel experiments. A checkpoint (avfs checkpoint save) is a rollback point inside a vault you can restore to if an execution goes wrong.
+ What comes back from an execution?
A versioned ExecutionEnvelope: stdout, stderr, exit code, duration, the policy decision, and a ChangeSummary listing the files that changed. Errors return typed { error, message, ... } objects.
+ Is it open source?
Yes — MIT-licensed, published to crates.io as agentvfs. Source lives at github.com/neul-labs/agentvfs.