# 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 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 providers

Each provider page includes configuration options and usage examples:

- [LocalFilesystem](https://mastra.ai/reference/workspace/local-filesystem/llms.txt) - Stores files in a directory on disk

LocalFilesystem is the simplest way to get started - it requires no external services.

## 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:

```typescript
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 mode

To prevent agents from modifying files, enable read-only mode:

```typescript
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 tools

When you configure a filesystem on a workspace, agents receive tools for reading, writing, listing, and deleting files. See [Workspace Class Reference](https://mastra.ai/reference/workspace/workspace-class/llms.txt) for details.

## Related

- [LocalFilesystem Reference](https://mastra.ai/reference/workspace/local-filesystem/llms.txt)
- [Workspace Overview](https://mastra.ai/docs/workspace/overview/llms.txt)
- [Sandbox](https://mastra.ai/docs/workspace/sandbox/llms.txt)