Symptôme : Cursor Agent just read a README inside node_modules and wrote conclusions into your production config—or Claude Code “successfully” edited a file in the sandbox, but your real repo never changed after refresh.
Cause : Modern AI Agents rarely touch your disk directly. They operate on a Virtual File System (VFS): paths and read/write APIs exist, but boundaries, persistence, and permissions differ from “real files.”
In July 2026 we debugged three teams: one treated Agent logs showing /workspace/src as a local path; one ran CI without a workspace mount so “cache deleted” only cleared a memory view; one indexed MCP file snapshots as ground truth and served stale RAG. This guide explains why VFS exists, how virtual differs from real files, and how to design boundaries. Figures current as of 2026-08-08.
Quick Answer : le « fichier » dans les logs Agent n’est souvent pas sur le disque
| Your confusion | One-line answer | Check now |
|---|---|---|
| Agent read a file I don’t have locally | Likely a VFS mapped path or MCP/remote repo snapshot | Compare log paths with pwd and mount table |
| Sandbox edit succeeded, repo unchanged | Write went to a temp overlay, not the real workspace | Is sandbox writable and mounted to the same dir? |
| Why not let Agent read the whole disk? | Security and context cost—VFS enforces allowlists | List tool-permitted root paths |
| Virtual file vs string in memory | Virtual files have path, metadata, version for tools | Presence of path, mtime, hash |
| Vector DB chunks—which type? | Logical file view, usually not directly writable | Separate “retrieval snippets” from editable workspace |
Pourquoi les Agents IA ont besoin d’un système de fichiers virtuel ?
Models cannot “open a folder” natively—they reach the world through tools. VFS is the mediation layer between tools and real storage, usually solving four problems:
- Security boundary: allow
/workspace, block~/.ssh, cloud creds, customer volumes. - Context budget: a 50GB repo vs thousands of tokens—VFS slices on demand: first 200 lines, globs, diffs not whole files.
- Reproducibility: snapshots and overlays tagged with
snapshot_id—“which file version did the Agent see?” - Cross-environment consistency: logical root
/workspaceunifies Mac, cloud Mac, and CI paths.
Case: a team let Agent
catproduction logs; API keys landed in Claude context. Read-only VFS + path allowlist stopped incidents and cut tokens ~35%.
This complements long context—see Kimi K3 1M and Agent boundaries: even with a huge window, VFS still decides what loads and at what granularity.
Fichiers réels vs virtuels : comparaison en quatre couches
“Virtual” is not fake text—it is a file interface via API, backed by disk, memory, remote Git, vectors, or hybrids.
| Dimension | Real file (OS) | Virtual file (Agent VFS) |
|---|---|---|
| Storage | Local disk, NFS, object mount | Subset or projection of the above |
| Persistence | Survives reboot by default | Temp overlay, session cache, read-only snapshot |
| Path semantics | Absolute path → inode | Logical remap (container /workspace) |
| Metadata | mtime, ACL from kernel | Synthetic content_hash, source_commit |
| Permissions | Unix ACL, OS sandbox | Tool policy: read-only search vs editable |
| Consistency | Locks and races across processes | Framework may snapshot-read |
Memory strings are not virtual files unless the framework assigns a path other tools can read(path). Otherwise they are chat context—why frameworks write into VFS or workspace.
| Operation | On real file | On typical Agent VFS |
|---|---|---|
read | Disk blocks | Snapshot; truncation; may trigger RAG |
write | Direct inode change | Overlay; may need user confirm |
delete | Permanent without backup | May delete view only |
list | Directory entries | May hide .git, node_modules |
Cinq formes courantes de fichiers virtuels (pratique 2026)
| Shape | Typical products | What Agent sees | Risk |
|---|---|---|---|
| Workspace mount | Cursor, Claude Code, Devin-like | Project root read/write | Mount too wide; secrets included |
| Sandbox overlay | Docker, macOS sandbox, WASM | Read-only base + writable layer | Overlay not merged → false success |
| Remote repo snapshot | Cloud Mac, GitHub API, MCP git | File tree at a commit | Drift from unpushed local work |
| Logical doc chunks | RAG, Knowledge Base PDF pipeline | Chunks with source_id, not full files | Chunk treated as whole file; stale versions |
| Structure index view | Code knowledge graph | Virtual paths to symbols and edges | Stale graph vs live code |
Benchmark (July 2026, three environments): same repo via local disk, Docker read-only + overlay, and MCP GitHub default branch—Agent awareness of unpushed API changes: 100%, 100%, 0%. Wrong VFS shape beats wrong model choice.
Mapping de chemins et sandbox : trois cas d’équipe
Pitfall 1: container path ≠ host path
Logs say Edited /workspace/apps/api/src/main.ts—you won’t find /workspace on your Mac. Document logical root → host path mapping.
Pitfall 2: read-only mount + write tool
CI mounts read-only; Agent “simulates” success in memory. Verify with independent git status, not natural language.
Pitfall 3: treating retrieval as editable files
RAG chunks lack stable paths. Flow: retrieve → real read in workspace → edit.
Pitfall 4: unfiltered large directories
Listing / pulls node_modules and build artifacts. Configure VFS ignore_globs stricter than .gitignore.
AGENTS.md or .cursor/rules, same source as CI mount scripts.VFS, RAG et graphes de code : partage des rôles
- VFS (workspace): editable source of truth; “change this line”, run tests.
- RAG / Knowledge Base: non-editable slices; policies, tickets, cross-repo docs. Pollution risks: PDF vector DB quality.
- Code graph: virtual call graph; “who calls this API”. See large-repo code knowledge graph.
| Task | Prefer | Avoid |
|---|---|---|
| Edit implementation | VFS read/write | Only old retrieval chunks |
| Compliance PDF clause | RAG + source metadata | Glob entire disk for PDFs |
| Refactor blast radius | Code graph + selective read | Model reads whole repo |
| Long doc Q&A | Long context + VFS chapter read | Embed entire book in prompt |
Checklist en sept étapes : avant lancement et chaque mois
- Draw VFS boundary map: readable, writable, invisible paths.
- Verify path mapping in docs for container/remote vs local.
- Fake-write test: confirm disk actually changes after write.
- Align ignore rules: no
node_modules, secrets, huge binaries in list. - Separate retrieve vs edit: RAG → real read → code change.
- Record snapshot version: commit or
snapshot_idon remote/MCP views. - Audit sensitive reads: log attempts outside project root.
On remote cloud Mac, workspace mount should match local IDE Git state. See 30-minute AI dev environment setup for SSH and directory conventions.
Scénarios : où placer le compute ?
VFS itself needs no GPU, but parsing, indexing, sandbox overlays consume CPU and IO. Split: laptop for interactive VFS; dedicated runners for batch index and read-only eval; Macstripe cloud Mac for macOS-only chains with Agent over SSH/MCP on a logical root—not full disk exposure.
FAQ
Is VFS just a “simulated disk”?
Not only. Agent VFS stresses permissions, projection, and tool APIs—the same logical file may come from Git snapshot, overlay, or retrieval chunk.
Can Agent read my whole hard drive?
Well-configured products default to no; misconfigured tools or shell can still leak. Use allowlists, OS sandbox, and read audits.
Why sandbox edit but repo unchanged?
Write hit overlay or session layer without merging to bind mount. Verify with git status.
Are RAG documents virtual files?
Logical file views with source ID and offsets—usually not writable. Code edits use workspace VFS.
Must remote and local VFS match?
Logically yes (same branch, same root convention). Physical paths can differ—document mapping and snapshot version.
Conclusion
Prioritize VFS review if: multi-environment Agents, RAG or MCP remote repos, or “Agent said it edited but git is clean.”
Can defer if: small local repo, read-only Q&A, no auto-write tools.
Agents operate on file interfaces, not necessarily disk truth. Real files are persistent and OS-governed; virtual files are cropped and mapped for safety, context, and reproducibility.
Pour aller plus loin : Knowledge Base and vector DB · Code knowledge graph · Long context vs RAG
