Filesystem
Filesystem providers give agents the ability to read, write, and manage files. When you configure a filesystem on a workspace, agents receive tools for file operations.
How it worksDirect link to How it works
A filesystem provider handles all file operations for a workspace:
- Read - Read file contents
- Write - Create and update files
- List - Browse directories
- Delete - Remove files and directories
- Stat - Get file metadata
When you assign a workspace with a filesystem to an agent, Mastra automatically includes the corresponding tools in the agent's toolset.
Supported providersDirect link to Supported providers
Each provider page includes configuration options and usage examples:
- LocalFilesystem - Stores files in a directory on disk
LocalFilesystem is the simplest way to get started - it requires no external services.
Basic usageDirect link to Basic usage
Create a workspace with a filesystem and assign it to an agent. The agent can then read, write, and manage files as part of its tasks:
import { Agent } from '@mastra/core/agent';
import { Workspace, LocalFilesystem } from '@mastra/core/workspace';
const workspace = new Workspace({
filesystem: new LocalFilesystem({
basePath: './workspace',
}),
});
const agent = new Agent({
id: 'file-agent',
model: 'openai/gpt-4o',
instructions: 'You are a helpful file management assistant.',
workspace,
});
// The agent now has filesystem tools available
const response = await agent.generate('List all files in the workspace');
Read-only modeDirect link to Read-only mode
To prevent agents from modifying files, enable read-only mode:
const workspace = new Workspace({
filesystem: new LocalFilesystem({
basePath: './workspace',
readOnly: true,
}),
});
When read-only, write tools (write_file, edit_file, delete, mkdir) are not added to the agent's toolset. The agent can still read and list files.
Agent toolsDirect link to Agent tools
When you configure a filesystem on a workspace, agents receive tools for reading, writing, listing, and deleting files. See Workspace Class Reference for details.