VFS Component

The Virtual Filesystem (VFS) component provides file operations in an isolated, session-scoped environment. Each session gets its own virtual filesystem that doesn't persist across samples.

Available Tools

Tool	Description	Parameters
read_file	Read file content	file_path (string)
write_file	Write to file	file_path (string), content (string)
list_files	List all files	None
delete_file	Delete a file	file_path (string)

Need another builtin tool?

If you need a generic tool that would see wide use, open an issue to request it.

Configuration

config.yaml

generation:
  tools:
    spin_endpoint: "http://localhost:3000"
    components:
      builtin:  # Routes to /vfs/execute
        - read_file
        - write_file
        - list_files

Builtin Component

The builtin component maps to VFS tools and routes to /vfs/execute. List specific tools or omit the list to include all builtin tools.

Seeding Initial Files

Pre-populate files for scenarios:

config.yaml

generation:
  tools:
    spin_endpoint: "http://localhost:3000"
    components:
      builtin:
        - read_file
        - write_file
        - list_files
    scenario_seed:
      files:
        "main.py": |
          def greet(name):
              return f"Hello, {name}!"

          if __name__ == "__main__":
              print(greet("World"))
        "config.json": |
          {
            "version": "1.0.0",
            "debug": true,
            "max_retries": 3
          }

The agent can then read and modify these files during generation.

API Reference

Execute Tool

Execute request

POST /vfs/execute
Content-Type: application/json

{
  "session_id": "sample-001",
  "tool": "read_file",
  "args": {"file_path": "config.json"}
}

Response Format

Success response

{
  "success": true,
  "result": "{\"debug\": true}",
  "error_type": null
}

Error Types

Error	Description
FileNotFound	File doesn't exist
InvalidArguments	Missing required parameter
IOError	Storage error