AgentVFS

#Introduction

Large language models (LLMs) [1] increasingly act as agents, which reason about a task and act on it by calling tools [2], [3]. Coding agents are a prominent example. They complete coding tasks in a terminal, where they view, search and edit files and use CLIs [4], [5]. Many tasks, however, also need data that is held not in local files but in external services such as email, documents, chat and databases.

#Tool Calling with MCP

Today, agents most often reach these services through the Model Context Protocol (MCP) [6], an open standard that exposes each service operation as a tool. Each tool's schema is placed in the model's context before the agent starts, and a single server can take 7–9% of the context window [7]. Each call also returns its result to the context, where it stays for the rest of the task.

Since code is a better action format than JSON tool calls [8], recent work has the model call MCP tools from code, as in code execution with MCP [9], Code Mode [10] and Pi's Codemode [11]. This keeps intermediate results out of the context, but the data still sits behind each service's tools. The model still has to learn every service's tools and write code even to read or search the data, and it cannot use the shell commands it learned in training, such as grep and jq.

#The Terminal

A terminal does not have this limit. Since Unix [12], it has presented data of every kind as files, which small programs read, filter and combine through pipes. Agents increasingly work in a terminal [13], reading instructions and data from files on demand [14] with shell tools that models learn from code in pretraining [15] and from agentic coding in post-training [16], [17].

These files, however, are local, and the services that people use every day, such as Gmail, Slack, Google Drive, Notion, GitHub and databases, lie outside them. An agent cannot grep a mailbox or open a Google Sheet as a file, so it falls back on MCP or on each service's CLI, which act on the service but do not present its data as files. Downloading the data instead leaves copies that go stale and must be synced back, and a local grep scans the copies byte by byte, without the service's own cloud-based search or index.

#Security and Reward Hacking

A real shell also raises security problems. It can read anything its user can, including credentials and SSH keys, and instructions hidden in the data can turn the agent's commands against the machine [18]. Agents are therefore run in sandboxes [19], [20], but inside one the same access lets an agent game its task. Coding agents have edited tests instead of solving the problem [21], and agents in common evaluation setups can tamper with grading or look up the answer online [22]. A sandbox bounds the machine, but the shell inside it still sees every file.

#AgentVFS, VFS.md and VFS-Bench 1.0

To resolve these problems, we propose an interface called the Agent Virtual Filesystem (AgentVFS), which virtualizes the terminal together with its underlying filesystem. It presents external services as files, so that an agent works on remote data with shell commands, as it does on local files, without downloading copies. Like virtual filesystems in operating systems [23] and Plan 9 [24], and like cloud-based virtual filesystems [25], it places many services behind one interface. Since one agent virtual filesystem now holds many services, we also propose VFS.md, a short Markdown file that guides the agent through its paths and file formats. AgentVFS defines what the agent sees and can do, not how it is built.

Because AgentVFS is purely virtual, every command the agent runs passes through it rather than through a machine. Policies can therefore decide what the agent may see and change, hide credentials and files that lie outside its task, and refuse a command or hold it for approval before it runs.

In summary, the AgentVFS interface consists of four parts.

1. Virtual Filesystem. Each service's data storage appears as files in formats that agents read easily, such as JSON in the shape of the service's API resources. Agents can then work on the data with the Unix-like tools already in their memory, such as ls, grep, cat and jq, instead of learning a tool for each service.
2. VFS.md. A short VFS.md describes the overall layout of the virtual filesystem and the format of its files. It gives agents a shortcut into each service, so they find the data they need without trial and error.
3. Virtual CLIs. Actions with side effects, such as sending a message, are separated from the data and run as virtual CLIs, which SKILL.md describes. Agents learn new commands only for actions, and every change to a service is an explicit command that can be reviewed or controlled.
4. Policy. Every read, write and command passes through the implementation before it runs, so that policies can keep credentials and unrelated data out of the agent's reach and stop a command before it does harm.

AgentVFS is thus a general interface between agents and external services. To evaluate it, we build VFS-Bench 1.0, a benchmark that compares AgentVFS with MCP on the same tasks, measuring how often agents succeed, how many tokens each interface costs, and how often agents break a rule that their instructions state.

#AgentVFS

AgentVFS is an interface with four parts that presents external services to agents as files. A virtual filesystem holds each service's data, VFS.md describes it, virtual CLIs carry out some operations, and policies control access to all three. For each part, we describe what the interface specifies.

#Virtual Filesystem

Each service's data storage is virtualized under its own path as virtual directories and files, in the shape of the service's own resources, so that email, documents, chat and code sit side by side in one virtual filesystem. The interface provides Unix-like tools, such as ls, grep, cat and jq, that run in memory over these virtual files, so the agent searches, filters and compares remote data as if it were in local files, and keeps intermediate results as virtual files of its own.

Reading a virtual file calls the service's API. Google Drive, for example, appears at /gd, with folders as directories and each spreadsheet as a .gsheet.json file in the shape of the Sheets API's spreadsheet resource. Canvas appears at /canvas, with its courses, conversations and files as directories, and a mailbox at /mail, where each message is a .email.json file under its folder and day, beside a directory of the same name that holds its attachments. An email with a course schedule attached, for example, is Course_Schedule_Notification__6.email.json in /mail/INBOX/2026-09-09, and the schedule is course_schedule.md in the directory beside it.

AgentVFS can also integrate search and retrieval. Under the virtual filesystem, a grep -r over a mailbox can run on the service's own search, or even on an embedding index, as in retrieval-augmented generation (RAG) [26], so the agent searches remote data without reading every file first.

#VFS.md

A VFS.md at the root of the virtual filesystem describes its overall layout. It opens with a name and a short description, which the agent can read before the rest. The body lists each path and what it holds, and gives the format of each kind of file, so the agent knows where the data is and how to read it before its first command. A folder can carry its own VFS.md when its formats need more detail, and the agent loads it only when it works there. The VFS.md below, abridged, comes from a Toolathlon task over Google Drive.

---
name: workspace-filesystem
description: The virtual filesystem layout of this workspace.
---

# Virtual Filesystem

Google Drive is virtualized at `/gd`. Read it with shell commands; spreadsheet operations are listed in SKILL.md.

| Path | Description |
|---|---|
| `/gd` | Google Drive, read-only. Directories are Drive folders; change spreadsheets with the `google-sheet` CLI. |

## `.gsheet.json` format

```json
{
  "spreadsheetId": "...",
  "properties": {"title": "..."},
  "sheets": [{"properties": {"title": "..."},
              "data": [{"rowData": [{"values": [{"formattedValue": "..."}]}]}]}]
}
```

{
  "spreadsheetId": "...",
  "properties": {"title": "..."},
  "sheets": [{"properties": {"title": "..."},
              "data": [{"rowData": [{"values": [{"formattedValue": "..."}]}]}]}]
}

#Virtual CLIs

Operations with side effects, such as creating a course, sending a message or updating cells, are kept apart from the data and run as virtual CLIs. Each service's operations form one CLI, with one subcommand per operation that takes JSON arguments, for example canvas create-course '{"account_id": 1, "name": "Philosophy-7"}' or google-sheet update-cells. A subcommand's --help prints its schema, so the agent loads a schema only when it needs one. Because the CLIs run like any shell command, their output can be filtered, saved to a file or passed to the next command, and a loop can run one over many inputs. In our experiments the subcommands are the operations of the task's MCP servers, with the same arguments, so both interfaces reach the same operations.

#Policy

A shell also widens what an agent can reach. An MCP tool carries out one operation that its server defines, whereas a shell lets the agent list, search and read anything in the virtual filesystem, so the interface itself must bound what the agent sees and does. Policies in AgentVFS serve this purpose, keeping an agent within its task and protecting the services and data it reaches. AgentVFS is purely virtual and runs no command on the machine's own filesystem, so the agent's shell sees nothing outside it, and every read, write and command passes through policies before it runs. A policy can hide a service or a folder, make a service read-only, or refuse a command, such as a search of the whole virtual filesystem. Such policies address security, by keeping credentials and unrelated data out of the agent's reach, and reward hacking, by keeping answer keys and grading files out of its view.

#VFS-Bench 1.0

VFS-Bench 1.0 is a benchmark that compares AgentVFS with MCP as the interface between an agent and external services. It contains 200 tasks, 100 from MCP-Atlas [27] and 100 from Toolathlon [28], two benchmarks of realistic, multi-step tasks over real MCP servers. We select tasks that read or change data in external services, preferring those that combine several, such as email, Canvas, Google Drive and Sheets, GitHub, Notion and Slack. Most tasks combine two or more services. Table 1 summarizes the two datasets.

Each task keeps its original instruction, data and evaluator, and both arms run the original benchmark's agent harness, with its loop, request limit and context handling. Many of the services run in simulated environments that reproduce their APIs, so that future work can rerun the benchmark on the same services and data without live accounts. Before every run, the services are reset and seeded with the task's data, so that each run starts from the same state. A task then runs in two arms. In the MCP arm, the agent calls the task's MCP servers, as in the original benchmark. In the VFS arm, it runs shell commands over an agent virtual filesystem of the same services, guided by a VFS.md and a SKILL.md, and its virtual CLIs offer the same operations as the MCP servers, with the same arguments. We implement the VFS arm with Mirage [29].

The VFS arm also adds a policy for each dataset. On Toolathlon, it limits the agent to the paths that the task's VFS.md lists, as Toolathlon's original terminal server limits it to the task's workspace. On MCP-Atlas, whose harness returns command output whole, it refuses commands that read a whole mount at once, which the task's VFS.md asks the agent to avoid. The original evaluator grades every run, and we record whether the run passes and how many tokens it uses. The two arms therefore differ only in the interface and the policy that comes with it.

VFS-Bench reports three metrics for each model and dataset.

#Pass@1

Pass@1 is the share of tasks that pass the original evaluator.

#Token Reduction Rate

The token reduction rate is the share of MCP's average total tokens per task that AgentVFS saves on the same tasks.

#Instruction Violations

The instruction violation rate is the share of VFS runs in which the policy refused a command that VFS.md told the agent not to run. We measure it only on MCP-Atlas. On Toolathlon, the policy only limits the agent to the task's paths, as Toolathlon's own terminal server does, so that the VFS arm stays close to the original benchmark, and its VFS.md does not include such a rule.

#Experiments

#Setup

We run all 200 tasks of VFS-Bench 1.0 in both arms with five models in two tiers. The advanced tier, Claude Opus 5.5 and GPT-6.1 Sol, runs at medium reasoning effort, and the efficient tier, GPT-5.6 Luna, Gemini 3.8 Flash and Claude Haiku 5.5, runs at maximum reasoning effort. We use the first trial of each arm. Each benchmark's evaluator grades pass@1, a run that read the task's published answer counts as a failure, and total tokens are input plus output tokens over all requests of a run.

#Results

Tokens. AgentVFS reduces tokens per task by 52% on average, by 44–88% on MCP-Atlas and by 10–73% on Toolathlon (Figure 1).

Success rate. With AgentVFS, pass@1 rises on average from 77.6% to 81.6% (Figure 2). It is higher or the same for every pair of dataset and model, with the largest gain for GPT-5.6 Luna on Toolathlon, from 61% to 73%.

Instruction violations. On MCP-Atlas, the instruction violation rate ranges from 2% for GPT-6.1 Sol to 50% for Gemini 3.8 Flash (Figure 3). Most of Claude Opus 5.5's violations are listings such as find /data | head -100, which cut the output short, while Gemini 3.8 Flash's are searches for data in the middle of a task, such as grep -rn "2017-05-29" /notion /data.

#Analysis

We analyze the VFS runs to see how each part of AgentVFS contributes to these results, how the parts combine, and what the policy caught.

#Virtual Filesystem

The agent reads and searches data with Unix-like tools that models know from training, such as grep, cat and jq, together with the shell, so no tool schemas for them enter the context. These tools also work on services that have no files. The agents used them heavily, as built-in Unix-like tools make up most of the commands they ran (Figure 4), so direct access to data in the virtual filesystem is useful to them.

Shell commands filter remote data before the model reads it, so only the part a task needs enters the context. In sync-todo-to-readme, the agent updates the TODO list in a README from the changes between two branches of a GitHub repository. With the branches available as files, the VFS agent compared them with standard tools.

diff -ruN --exclude='.git' /repo/main /repo/dev | sed -n '1,500p'
grep -RIn --include='*.py' -E 'TODO|FIXME|todo' /repo/dev | sed -n '1,300p'

The MCP agent read the repository one file or directory per call, 81 calls in all, and reached the limit of 100 requests per run after 11.3M tokens without finishing. The VFS agent passed with 15 requests and 1.2M tokens. The same holds on MCP-Atlas. In the Notion task great-recession, Gemini 3.8 Flash's MCP run received query results of about 300,000 characters per call and used 17.3M tokens, and its VFS run used 173K.

Even in code mode [9], [10], an MCP agent cannot apply diff or grep in this way, because the data is reachable only through tools, so its code must first fetch every file or result with a tool call.

Conversely, a local terminal has the shell but not the services. It could run the same commands on a downloaded copy, but the agent explores to find the data a task needs, so the copy would have to hold each whole service, from a mailbox to a drive. The copy also goes stale once the agent changes a service, and in 21% of the runs that changed a service, the agent then read its files to confirm the change. In apply-phd-email, for example, Gemini 3.8 Flash sends an application with the emails CLI and then opens it in /mail/Sent. A virtual filesystem avoids both problems, as it loads each file from its service only when the agent reads it, so the agent can explore a whole service without a copy and sees each change at once. Because the agent explores, it also needs to know where to look, which VFS.md provides.

#VFS.md

VFS.md gives the path of each service and the format of its files, so the agent can go straight to the data. In nhl-b2b-analysis, Claude Opus 5.5 reads the NHL schedule in its first command with the field path that VFS.md documents for a .gsheet.json file, and in its second command turns the whole sheet into a TSV file for cut, sort and uniq.

jq -c '.sheets[0].data[0].rowData[0:5][] | [.values[].formattedValue]' "$f"
jq -r '.sheets[0].data[0].rowData[1:][] | [.values[].formattedValue] | @tsv' "$f" > s.tsv

With MCP, the agent fetched the sheet with get_sheet_data over the range A1:H1500. The result was too long to return whole, so the agent read it back in pieces with Python. Both runs passed, the VFS run with 6 requests and 51K tokens and the MCP run with 10 requests and 498K tokens.

#Virtual CLIs

Virtual CLIs run like any shell command, so one command can chain several operations, passing each output to the next without a round trip through the model. In canvas-art-manager, the agent creates 27 Canvas courses from an emailed schedule, enrolls each course's teacher, posts an announcement, uploads the syllabus and publishes the course. The VFS agent wrote each step as a loop in which one command's output becomes the next command's input.

while IFS= read -r row; do
  name=$(printf '%s' "$row" | jq -r '.name')
  args=$(jq -n --arg n "$name" '{account_id:1,name:$n,course_code:$n,time_zone:"America/Denver"}')
  out=$(canvas create-course "$args")
  id=$(printf '%s' "$out" | jq -r '.id')
  printf '%s\t%s\n' "$id" "$name" >> /workspace/admin3_course_ids.tsv
done < <(jq -c '.[]' /workspace/admin3_courses.json)

The MCP agent issued every operation as a separate tool call, 636 in all, and reached the request limit after 20.3M tokens. The VFS agent passed with 29 requests and 0.69M tokens.

#Patterns Combined

Together, the three parts give rise to four patterns that save tokens and improve performance over MCP.

1. Memorized tools (virtual filesystem). The agent works with Unix-like tools it already knows, so no tool schemas for them enter its context.
2. Data reduction (virtual filesystem and VFS.md). Knowing each file's format from VFS.md, the agent filters data with shell commands before the model reads it, so only the part a task needs enters the context.
3. Composition (virtual CLIs and virtual filesystem). Pipes and loops pass each result, from a file or a CLI, to the next operation without a round trip through the model.
4. State reuse (virtual filesystem and virtual CLIs). Intermediate results, such as the IDs a CLI returns, are saved to files that later commands read, instead of the model restating them.

#Stronger Models

The token savings also grow with the model's strength. On both datasets, the two advanced models, Claude Opus 5.5 and GPT-6.1 Sol, reduce tokens the most, by about 71% on average against about 39% for the efficient tier (Figure 1). Claude Opus 5.5 reduces them by 88% on MCP-Atlas and 73% on Toolathlon, while Claude Haiku 5.5 reduces them by 10% on Toolathlon. Stronger models likely plan better in a shell, doing more of a task in each script or pipeline, and may be trained more for terminal-like environments, so they make more use of the patterns above. As models improve, the advantage of AgentVFS over MCP is therefore likely to grow.

#Policy

Giving an agent a shell over every service also raises security concerns, since the agent can search for credentials or wander beyond its task. Since AgentVFS is purely virtual, a policy sees each command before it runs and can refuse it. The original benchmarks already restrict the agent in a similar way. Toolathlon's terminal server, for example, refuses any path outside the task's workspace. VFS-Bench therefore gives each dataset a policy of its own.

MCP-Atlas. Every task's VFS.md asks the agent to point grep -r, rg, find and cat at the directory or file it needs rather than at a whole mount, so the policy's refusals measure instruction following, which we report as the instruction violation rate (Figure 3).

Toolathlon. VFS.md lists the task's paths but states no rule, and the policy, like Toolathlon's terminal server, refuses commands that reach outside those paths. It refused a command in 74 of Gemini 3.8 Flash's 100 runs, 40 of Claude Haiku 5.5's and at most three of each other model's. Most of these commands searched from the root for data or credentials. In sync-todo-to-readme, for example, Gemini 3.8 Flash ran the search below, and the policy refused it before it read anything. Gemini 3.8 Flash also tried to open the programs behind the virtual CLIs, such as /usr/bin/google-sheet, read the shell history and listed system paths such as /etc.

find / -name "*github_token*" 2>/dev/null
# find: Permission denied

These refusals show where today's models fall short. Claude Opus 5.5, GPT-6.1 Sol and GPT-5.6 Luna almost always stay within the task's paths, while Gemini 3.8 Flash and Claude Haiku 5.5 search the whole virtual filesystem even though VFS.md lists where the task's data lives. Since every model runs with the same interface and instructions, these differences on both datasets likely come from how each model was trained, for example on real machines, where searching from the root is cheap and harmless.

On Toolathlon, we also observe agents looking up the benchmark itself, on pages that publish Toolathlon's tasks and other models' runs, such as autobenchaudit.com/benchmark/toolathlon/task/nvidia-market. Gemini 3.8 Flash did so in 13 of its VFS runs and 23 of its MCP runs, GPT-5.6 Luna in 2 and 3, and no other model in any run. Since these lookups happen under both interfaces, they point to habits from the models' training rather than to the interface.

#Limitations

• We run many of the services in simulated environments, which may differ in minor ways from the upstream tasks.
• The virtual filesystem matters more when a task needs complex composition and context from several resources.
• We implement AgentVFS with Mirage, and another implementation of the interface may perform differently.
• Toolathlon's VFS.md states no rule for its policy, so we measure instruction violations on MCP-Atlas only, and VFS-Bench 2.0 will state one on both datasets.

#References

1. Tom B. Brown, Benjamin Mann, Nick Ryder, et al. Language Models are Few-Shot Learners. NeurIPS 2020.
2. Shunyu Yao, Jeffrey Zhao, Dian Yu, Nan Du, Izhak Shafran, Karthik Narasimhan and Yuan Cao. ReAct: Synergizing Reasoning and Acting in Language Models. ICLR 2023.
3. Timo Schick, Jane Dwivedi-Yu, Roberto Dessì, et al. Toolformer: Language Models Can Teach Themselves to Use Tools. NeurIPS 2023.
4. Carlos E. Jimenez, John Yang, Alexander Wettig, et al. SWE-bench: Can Language Models Resolve Real-World GitHub Issues? ICLR 2024.
5. John Yang, Carlos E. Jimenez, Alexander Wettig, et al. SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering. NeurIPS 2024.
6. Anthropic. Introducing the Model Context Protocol. Anthropic, November 2024.
7. Mario Zechner. What I learned building an opinionated and minimal coding agent. November 2025.
8. Xingyao Wang, Yangyi Chen, Lifan Yuan, Yizhe Zhang, Yunzhu Li, Hao Peng and Heng Ji. Executable Code Actions Elicit Better LLM Agents. ICML 2024.
9. Adam Jones and Conor Kelly. Code execution with MCP: Building more efficient agents. Anthropic, November 2025.
10. Kenton Varda and Sunil Pai. Code Mode: the better way to use MCP. Cloudflare, September 2025.
11. Earendil Engineering. "You Said No MCP!" Earendil, September 2026.
12. Dennis M. Ritchie and Ken Thompson. The UNIX Time-Sharing System. Communications of the ACM 17(7), July 1974.
13. Mike A. Merrill, Alexander G. Shaw, Nicholas Carlini, et al. Terminal-Bench: Benchmarking Agents on Hard, Realistic Tasks in Command Line Interfaces. ICLR 2026.
14. Barry Zhang, Keith Lazuka and Mahesh Murag. Equipping agents for the real world with Agent Skills. Anthropic, October 2025.
15. Raymond Li, Loubna Ben Allal, Yangtian Zi, et al. StarCoder: may the source be with you! TMLR 2023.
16. Kimi Team. Kimi K2: Open Agentic Intelligence. arXiv, July 2025.
17. GLM-4.5 Team. GLM-4.5: Agentic, Reasoning, and Coding (ARC) Foundation Models. arXiv, August 2025.
18. Kai Greshake, Sahar Abdelnabi, Shailesh Mishra, Christoph Endres, Thorsten Holz and Mario Fritz. Not what you've signed up for: Compromising Real-World LLM-Integrated Applications with Indirect Prompt Injection. ACM AISec 2023.
19. David Dworken and Oliver Weller-Davies. Beyond permission prompts: making Claude Code more secure and autonomous. Anthropic, October 2025.
20. Ian Goldberg, David Wagner, Randi Thomas and Eric A. Brewer. A Secure Environment for Untrusted Helper Applications: Confining the Wily Hacker. USENIX Security Symposium, 1996.
21. Jonathan Gabor, Jayson Lynch and Jonathan Rosenfeld. EvilGenie: A Reward Hacking Benchmark. arXiv, November 2025.
22. Felipe Peter. Karotte: A Technical Deep Dive. Preference Model, October 2026.
23. Steve R. Kleiman. Vnodes: An Architecture for Multiple File System Types in Sun UNIX. USENIX Summer Conference, 1986.
24. Rob Pike, Dave Presotto, Sean Dorward, Bob Flandrena, Ken Thompson, Howard Trickey and Phil Winterbottom. Plan 9 from Bell Labs. Computing Systems 8(3), 1995.
25. Asaf Cidon. Cloud Based Operating and Virtual File System. US Patent Application 2011/0252071, October 2011.
26. Patrick Lewis, Ethan Perez, Aleksandra Piktus, et al. Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks. NeurIPS 2020.
27. Chaithanya Bandi, Razvan-Gabriel Dumitru, Ben Hertzberg, et al. MCP-Atlas: A Large-Scale Benchmark for Tool-Use Competency with Real MCP Servers. arXiv, January 2026.
28. Junlong Li, Wenshuo Zhao, Jian Zhao, et al. The Tool Decathlon: Benchmarking Language Agents for Diverse, Realistic, and Long-Horizon Task Execution. ICLR 2026.
29. Zecheng Zhang. Mirage: A Virtual Terminal for AI Agents. GitHub, 2026.

#Citation

If you find AgentVFS or VFS-Bench useful in your work, please cite it as follows.

@misc{zhang2026agentvfs,
  title  = {AgentVFS: A Virtual Filesystem Interface for AI Agents},
  author = {Zhang, Zecheng and Li, Guohao and Xiao, Yuxin and He, Yuan and
            Shen, Qijia and Lai, Douglas and Qi, Zhenting and Bevilacqua, Alex and
            Huang, Xingyue and Song, Bowen and Xu, Yue and Zheng, Han and
            Qi, Fangfang and Li, Li and Nkemdilim, Tochukwu and
            Akinyemi, Stephen and Qu, Ao and Cidon, Asaf and You, Jiaxuan and
            Ying, Rex and Luan, Xiaofan and Tang, Siddon},
  year   = {2026},
  month  = oct,
  url    = {https://agentvfs.org/blogs/agentvfs-1}
}