# Virtual Filesystem

> A per-agent persistent filesystem the agent reads and writes through builtin tools. Files survive across executions, so it doubles as long-term memory.

Source: https://0.0.0.0:8080/docs/virtual-filesystem

A per-agent filesystem the agent reads and writes through builtin tools. Files survive between executions, so the agent can take notes on Monday and refer to them on Tuesday. Users browse the same tree from the Studio — it's a real shared surface, not a hidden cache.

## Why it exists

LLM context windows reset between runs. Vector memory captures concepts but loses the verbatim text. The Virtual Filesystem sits between the two:

- **Cross-run state** — write `/memory/notes.md` in one execution, grep it in the next.
- **Structured artifacts** — write JSON, CSV, YAML and read it back without re-deriving.
- **User-visible** — open the Studio Files panel and edit what the agent wrote, the same way you'd edit any other agent setting.
- **Auditable** — see at a glance whether the most recent write came from the agent, the user, or a trigger payload.

The feature is **opt-in per agent.** Toggle it on from the Studio panel; existing agents keep their previous behavior until you flip the switch.

## Tools the agent gets

When you enable the Virtual Filesystem the agent picks up ten LLM-visible tools:

| Tool         | Purpose                                                               |
| ------------ | --------------------------------------------------------------------- |
| `vfs_list`   | List directory entries (optionally recursive)                         |
| `vfs_read`   | Read a file; optional line range for paged reads of large files       |
| `vfs_write`  | Create or update a file; overwrite or append                          |
| `vfs_stat`   | Metadata for a single path                                            |
| `vfs_mkdir`  | Create a directory (parents auto-created, idempotent)                 |
| `vfs_delete` | Delete a file or, recursively, a subtree                              |
| `vfs_move`   | Rename or move                                                        |
| `vfs_copy`   | Duplicate a file or directory                                         |
| `vfs_grep`   | Search file contents and return matching lines with line numbers      |
| `vfs_glob`   | Find files by name or path pattern (`*.md`, `memory/**/*.json`, etc.) |

Attach the **Virtual Filesystem** builtin tool to an agent the same way you attach any other MCP tool — the template ships with every workspace.

## Example: a support agent that remembers

A Slack support agent that remembers what it has already answered:

```text
User: "@bot is staging down again?"
Agent (turn 1):
  vfs_grep("staging outage")            → match in /memory/incidents.md
  vfs_read("/memory/incidents.md")      → reads the surrounding context
  → replies "we had a staging outage on 2026-05-19; details in /memory/incidents.md"

User: "log this one too — staging is down right now"
Agent (turn 2):
  vfs_write("/memory/incidents.md", append, "\n2026-05-21 staging down")
  → replies "logged"
```

## Limits

Defaults are conservative so a runaway tool call can't blow up your agent:

| Limit           | Default |
| --------------- | ------- |
| Per-file size   | 1 MiB   |
| Per-agent total | 100 MiB |
| Path depth      | 16      |
| Filename length | 255     |

Raise them via environment variables when you trust the workload.

## Path rules

The path normalizer is strict on purpose:

- Paths must be absolute (`/notes.md`, not `notes.md`)
- `..` segments are rejected anywhere in the input — there is no silent resolution
- Names are capped at 255 characters; depth at 16 segments

Writes that would overwrite a directory entry are refused so children aren't orphaned. Moves and copies refuse to land inside their own descendants.

## Browsing from Studio

The Studio ships with a **Virtual FS** tab on every agent. When the toggle is on:

- Collapsible folder tree on the left with hover actions (new file, new folder, delete)
- Inline editor on the right with overwrite-on-save
- Grep bar that searches across the whole filesystem
- Path breadcrumbs and a usage indicator

Files written by the agent and files written by a user share the same store. The Studio panel tells you who wrote each entry most recently.

## API

Every tool action is also exposed over REST so the Studio panel and your own tooling can drive the same operations. See the [API Reference](/docs/rest-api-reference) for endpoint specs and the OpenAPI schema.

## Related Topics

- [Agents](/docs/agents) — Enable VFS per agent
- [Memory](/docs/memory) — Vector memory for semantic recall (complementary to VFS for verbatim recall)
- [Agent Triggers](/docs/agent-triggers) — Chat triggers benefit most from cross-run memory
- [MCP Tools](/docs/mcp-tools) — How the Virtual Filesystem builtin attaches to the tool surface