01 · Request
proxy exec -- <cmd>
The agent asks to run one top-level command. This is the entire surface it interacts with — a single, auditable execution line.
Architecture
One line, drawn carefully
Every agentvfs execution is a request to run one top-level command. Five stages sit between that request and the structured result — and knowing them explains exactly what agentvfs does, and what it deliberately does not.
agent asks to run one top-level command │ avfs proxy exec -- <cmd> ▼ ┌─────────────────────────────────────────────┐ │ PolicyEngine (side-effect-free classify) │ │ allow · allow_with_checkpoint · deny · │ │ require_approval │ └─────────────────────────────────────────────┘ │ on allow_with_checkpoint → save rollback point ▼ ┌─────────────────────────────────────────────┐ │ MountSession (FUSE) │ │ vault mounted as a REAL directory │ │ git · cargo · npm · python run here │ └─────────────────────────────────────────────┘ │ bounded by ExecutionTimeout (default 300s) ▼ ExecutionEnvelope stdout · stderr · exit · duration policy decision · ChangeSummary # one line drawn — NOT a syscall monitor
02 · Gate
PolicyEngine
Side-effect-free classification returns allow, allow_with_checkpoint, deny, or require_approval — evaluated before any workspace work, so denied commands never touch the mount.
03 · Checkpoint
Rollback point
When policy says allow_with_checkpoint, a checkpoint is saved first, so the workspace can snap back if the command mutates state you did not want.
04 · Mount
MountSession (FUSE)
The vault mounts as a real directory through an explicit state machine with double-unmount protection and automatic cleanup on drop. Standard CLIs see a normal path.
05 · Result
ExecutionEnvelope
The command runs bounded by ExecutionTimeout, then a versioned envelope returns stdout, stderr, exit code, duration, the policy decision, and a ChangeSummary of files touched.
Why it is not a syscall monitor
agentvfs classifies and mediates the top-level command an agent asks to run. It does not try to observe every subprocess a script spawns underneath — the README and ROADMAP list full syscall tracing and complete subprocess visibility as explicit non-goals. That is a feature, not a gap: the boundary stays cheap, predictable, and easy to reason about.
How to get stronger guarantees
Because the boundary is one clean line, agentvfs composes under OS-level isolation. Run it inside a container, a microVM, or with seccomp when you need to defend against a hostile process. You keep the vault, forks, checkpoints, and structured results; the kernel provides the containment.
See the guides to run your first command, or the comparisons for how this differs from Docker and E2B.