Tool VFS

Overview

The Tool VFS operator gives agents access to TouchDesigner’s built-in Virtual File System (VFS) — a sandboxed, in-memory file store that lives entirely inside your TD project. Agents can read, write, list, search, copy, move, and delete files without ever touching the real filesystem. You can also bulk-load files from disk into the VFS at any time, or export VFS contents back to a folder.

Agent Tool Integration

🔧 GetTool Enabled 7 tools

This operator exposes 7 tools that allow Agent and Gemini Live LOPs to read files, write files, list files, search file contents and names, delete files, copy files, and move or rename files within the Virtual File System.

Use the Tool Debugger operator to inspect exact tool definitions, schemas, and parameters.

When connected to an Agent LOP, the operator exposes up to seven tools named after the Tool Name parameter (default: file_tool):

Tool	Enabled by	What it does
file_tool_read_file	Enable Read	Reads a file’s content from the VFS
file_tool_write_file	Enable Write	Creates or overwrites a file in the VFS
file_tool_list_files	Enable List	Lists VFS files, optionally filtered by pattern
file_tool_search_files	Enable Search	Searches file contents and/or names
file_tool_delete_file	Enable Delete	Removes a file from the VFS
file_tool_copy_file	Enable Grab/Move	Copies a file to a new VFS path
file_tool_move_file	Enable Grab/Move	Moves or renames a file within the VFS

Each tool is only registered when its corresponding toggle on the Tool Toggles page is enabled. If Enable Operations is off, no tools are registered regardless of individual toggles. The VirtualFile component must also be set (or auto-created) before any tools become available.

Input/Output

Inputs

None — the operator has no wired inputs.

Outputs

One output wire that connects to an Agent LOP’s tool input.

Usage Examples

Basic Agent Setup

1. Drop a tool_vfs operator into your network.
2. On the Settings page, pulse Create External VirtualFile to create the VFS component in your project (it will be placed at the parent level and the VirtualFile Component field will update automatically).
3. Connect the tool_vfs output to an Agent LOP’s tool input.
4. The agent can now read and write files in the VFS using calls like: “Write my results to a file named output.json” or “List all files in the workspace.”

Loading Files from Disk

1. On the Settings page, set Source Folder to a folder on disk.
2. Pulse Load Folder. All files with extensions matching Allowed Extensions are imported into the VFS.
3. The agent can immediately read those files using the read_file tool.

Exporting VFS Contents to Disk

1. Set Export Folder to the destination path.
2. Toggle Overwrite Existing Files on or off depending on whether you want to replace existing files.
3. Pulse Export All to write all VFS files to disk.

Restricting Agent Capabilities

Use the Tool Toggles page to limit what the agent can do:

• Disable Enable Write and Enable Delete to give agents read-only access.
• Disable Enable Search if you want to limit agent discovery of file contents.
• Turn off Enable Operations entirely to suspend all VFS tools without removing the operator from the network.

Context Injection

Enable Enable Context Injection on the Tool Toggles page to automatically append the current VFS file listing to the agent’s system prompt on every tool call. Set Context Format on the Settings page to:

• Simple List — just filenames, minimal token usage.
• Detailed Info — filenames, sizes, and modification dates.

This is useful when you want the agent to know what files exist without having to call list_files first.

Best Practices

• Keep Allowed Extensions restricted to the file types you actually need. The default covers common text formats (txt json md py js css html xml yml yaml log).
• Set Max Files and Max File Size (MB) to sensible limits before giving agents write access, especially in long-running sessions where an agent might generate many files.
• Enable Show Full Virtual Paths on the Tool Toggles page if your project uses multiple VFS components and you need the agent to distinguish between them by full path.
• Pulse Check VFS on the Settings page to verify the component reference is valid and the VFS is accessible before starting an agent session.
• Enable Enable Logging on the About page to record all VFS operations to the internal log table — useful for debugging agent file activity.

Troubleshooting

No tools appear in the agent / agent says it has no file tools. The VirtualFile component reference is required. Pulse Create External VirtualFile on the Settings page, or manually point VirtualFile Component to an existing virtualFile COMP in your project. Also confirm Enable Operations is on.

Agent cannot write files. Check that Enable Write is on in the Tool Toggles page. Also verify the file extension is in the Allowed Extensions list and the file count is below Max Files.

Load Folder imports nothing. Verify the Source Folder path is correct and that the files’ extensions are listed in Allowed Extensions. Files exceeding Max File Size (MB) are also skipped.

Export All produces no files. Confirm Export Folder is set to a valid writable path. If Overwrite Existing Files is off and all files already exist at the destination, nothing will be written.

Parameters

Settings

Tool Name (Toolname) op('tool_vfs').par.Toolname Str

Name of the tool used in function calls

Default:

file_tool

VirtualFile Component (Virtualfilecomponent) op('tool_vfs').par.Virtualfilecomponent COMP

The virtualFile component to use for VFS operations. Auto-updated when external copy is created.

Default:

"" (Empty String)

Create External VirtualFile (Createifmissing) op('tool_vfs').par.Createifmissing Toggle

Copy internal virtualFile template to parent level for operations

Default:

True

Source Folder (Sourcefolder) op('tool_vfs').par.Sourcefolder Folder

Folder path to load into VFS

Default:

"" (Empty String)

Load Folder (Loadfolder) op('tool_vfs').par.Loadfolder Pulse

Load all files from source folder into VFS

Default:

False

Export Folder (Exportfolder) op('tool_vfs').par.Exportfolder Folder

Folder path to export VFS contents to

Default:

"" (Empty String)

Export All (Exportall) op('tool_vfs').par.Exportall Pulse

Export all VFS files to export folder

Default:

False

Clear All VFS (Clearall) op('tool_vfs').par.Clearall Pulse

Remove all files from VFS

Default:

False

Max Files (Maxfiles) op('tool_vfs').par.Maxfiles Int

Maximum number of files allowed in VFS

Default:

100

Range:

0 to 1

Slider Range:

0 to 1

Max File Size (MB) (Maxfilesize) op('tool_vfs').par.Maxfilesize Int

Maximum individual file size in megabytes

Default:

10

Range:

0 to 1

Slider Range:

0 to 1

Allowed Extensions (Allowedextensions) op('tool_vfs').par.Allowedextensions Str

Space-separated list of allowed file extensions (empty = all allowed)

Default:

txt json md py js css html xml yml yaml log

Context Format (Contextformat) op('tool_vfs').par.Contextformat Menu

Format for VFS context information

Default:

simple

Options:

simple, detailed

Overwrite Existing Files (Overwriteexisting) op('tool_vfs').par.Overwriteexisting Toggle

Overwrite existing files when exporting (prevents duplicates)

Default:

True

Check VFS (Checkvfs) op('tool_vfs').par.Checkvfs Pulse

Default:

False

Tool Toggles

Enable Operations (Enableoperations) op('tool_vfs').par.Enableoperations Toggle

Master switch for all VFS operations

Default:

True

Enable Read (Enableread) op('tool_vfs').par.Enableread Toggle

Allow reading files from VFS

Default:

True

Enable Write (Enablewrite) op('tool_vfs').par.Enablewrite Toggle

Allow writing files to VFS

Default:

True

Enable List (Enablelist) op('tool_vfs').par.Enablelist Toggle

Allow listing VFS files

Default:

True

Enable Search (Enablesearch) op('tool_vfs').par.Enablesearch Toggle

Allow searching VFS file contents and names

Default:

True

Enable Delete (Enabledelete) op('tool_vfs').par.Enabledelete Toggle

Allow deleting files from VFS

Default:

True

Enable Grab/Move (Enablegrab) op('tool_vfs').par.Enablegrab Toggle

Allow copying/moving files within VFS

Default:

True

Enable Context Injection (Enablecontext) op('tool_vfs').par.Enablecontext Toggle

Include VFS file listing in tool context

Default:

False

Show Full Virtual Paths (Showvirtualpaths) op('tool_vfs').par.Showvirtualpaths Toggle

Include full VFS virtual paths in responses (vfs:/component/path:filename)

Default:

False

Changelog

v1.0.22026-03-12

• add vf_comp passthrough arg to get_virtual_file_component, get_virtual_file_ext, ClearVFS, AddFile - callers can now inject a virtualFile component directly instead of relying on parameter lookup
• Initial commit

v1.0.12025-09-01

clean menu and remove unnecessary parameters.

Related Operators

• Agent