The Agent Virtual Filesystem — the FS tier of the OS analogy

fak’s mental model is one borrowed idea carried at every scale: the tool call is a syscall, the model proposes and the kernel disposes. That analogy already has a process layer (adjudication), a memory-management unit (internal/ctxmmu — paging and durability), an egress layer (internal/egressfloor), and a discipline for what crosses into durable store (memory engineering). The filesystem layer of the same analogy has never been named — even though every coding agent’s most-used tools (Read, Write, Edit, Glob, Grep) are file syscalls, and fak already adjudicates them.

This page names that layer. A virtual filesystem (VFS) in an operating system is the indirection between “a program asks to read a path” and “some backing store answers” — one uniform open/read/write/stat interface over many different backends (a local disk, a network mount, /proc, a FUSE process), with the kernel deciding, per call, what the program is even allowed to see. The agent virtual filesystem is the same indirection for an AI agent: the layer between the file-shaped tool call the model emits and the bytes that answer it. Its first job is context management — keeping each span addressable and cache-backed so a long session reuses bytes cheaply instead of re-reading them — and, on the same seam, the kernel decides what tree exists, what may be read, what may be written, and whether a returned byte is trusted.

Why it needs naming: six things wear the word “file” (or “memory”)

The trap is that an agent uses one vocabulary — files, memory — for six distinct concepts with six distinct mechanisms, trust models, and lifetimes. Conflate them and you get the failures the field keeps re-hitting: a scratchpad artifact promoted to durable memory, a poisoned document read back as fact, two fleet agents silently overwriting the same path, a “delete” that leaves the bytes in a cached prefix. The disambiguation:

Tier What it is Lifetime Who owns it fak’s role
T0 — host/VM store the real block device / sandbox FS the process runs on machine/session the VM or sandbox provider (E2B, Fly, Cloudflare, Anthropic’s sandbox) not fak — fak rides into it
T1 — path namespace / mount view the virtual tree the agent is allowed to see and touch: deny-by-default path scope, self-modify floor session fak (the reference monitor) mediate every path syscall
T2 — read / query surface the unified read: local tree query (Glob/Grep) and remote-document retrieval (MCP resources, RAG), each trust-gated on the way back per-call fak boundary over any backend adjudicate reads, cache the repeatable ones, quarantine poisoned results
T3 — scratchpad / tmpfs the agent’s ephemeral working FS: intermediate outputs, journaled, GC’d, checkpoint-included turn → session the agent, leased expire-by-default; a lease, not durable memory
T4 — durable memory promoted, verified, forgettable facts across sessions bounded → durable the memory-engineering discipline write-time admission gate + verified recall
T5 — KV-cache substrate the “in-memory filesystem” of the inference plane: where a context span physically lives, its stable address, addressable eviction run the serving layer (internal/ctxmmu, radix KV) placement + bit-exact forgetting

The one-line separations, each drawn against the sibling it blurs with:

The question everyone asks: is fak becoming a VM?

As compute moved into isolated cloud VMs and control moved onto phones, the natural read is “fak should grow a filesystem — snapshots, forks, a sandbox.” That is the wrong tier. The isolation-primitive ladder the field settled on is a T0 ladder:

Level Primitive Isolation Who
Strongest hardware microVM (Firecracker / Kata / Cloud Hypervisor) dedicated guest kernel E2B, Fly Sprites, Vercel, Northflank
Strong user-space kernel (gVisor) syscall interception Modal
Fast/narrow V8 isolate per-request JS sandbox Cloudflare Workers
Local OS sandbox (bubblewrap / Seatbelt) per-process Anthropic Claude Code
Weak baseline container / devcontainer shared kernel DIY self-host
Orthogonal git worktree file/concurrency only, not security nearly everyone

Every row is a way to provide a filesystem and isolate the process on it. fak builds none of them — that is a hardware/hypervisor play the sandbox vendors own (landscape note). fak is the T1–T2 reference monitor that rides inside whichever T0 the operator chose: the layer that decides what the agent sees and may do, independent of which box provides the disk. The distinction is exactly Unix’s own: the VFS and the block device are different layers, and the interesting security decisions live in the VFS. A microVM with no path-scope floor still lets a prompt-injected agent read every file it can reach; the floor is worth more, not less, when the human has stepped away into an autonomous cloud run. fak is the virtual filesystem, not the virtual machine. (The same fusion fak already owns — a capability floor and KV/prefix reuse at one in-process hop — is why the T1 mount view and the T5 substrate are one boundary, not two pieces of infra.)

The T0-vs-T1 proof for that claim is a reproducible witness: examples/vm-fs-guard/ runs fak inside a container/microVM standing in for a T0 sandbox and captures fak adjudicating FS syscalls on a disk it did not provision — an out-of-scope write refused (T1 · SELF_MODIFY), an out-of-view read refused (T1 · DEFAULT_DENY) with a read-only subtree’s write refused beside it (T1 · POLICY_BLOCK), a poisoned read quarantined (T2 · TRUST_VIOLATION), and the exit ledger of FS decisions, while the sandbox’s own disk stays readable and writable. The read-side refusals are enforced through the wired arg_rules path view rather than the mount_view vocabulary this tier names — the capability is live, its declarative spelling is still #5310 (the example says so). Crucially the T0 half is witnessed, not asserted: the run reads the box off the guest’s own kernel (systemd-detect-virt, /proc, findmnt), names the source device and filesystem type backing the rootfs (whatever the substrate turns out to be), and fails if any fak-backed mount, device, or FUSE server exists — so “fak did not provide this disk” is evidence the script can red-line on, not a sentence it prints. A run that cannot find a T0 declines to claim the VM half rather than printing it anyway (FAK_REQUIRE_T0=1 makes that an exit 1). Both T0 kinds this tier names are now captured — a hypervisor guest (rootfs on a hypervisor-attached ext4 device) and an OCI container (rootfs an overlay the runtime composed from image layers) — and their FS-decision ledgers agree row for row, which is the point: the substrate varies, the boundary’s verdicts do not. It is the filesystem twin of the network-egress witness (examples/remote-vm-guard/): together they show one capability floor riding into any T0, over two syscall families.

Prior art (fak invents none of this)

Per the project’s honesty discipline (CLAIMS.md: a 0/29-novel prior-art audit), every primitive here is decades old; the contribution is naming the tiers at one adjudicated boundary.

Where fak stands today (honest fences)

Shipped pieces that already live in these tiers — with the gaps named, not hidden:

The one-line test

If your agent stack cannot say, for a given “file” or “memory,” which of the six tiers it is — whose box provides it, whether the agent may see it, whether the read is trusted, whether it survives the session, and whether it can be proven gone — you have file access, not a virtual filesystem.