Filesystem

Added in: @mastra/core@1.1.0

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.

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

Supported providers

Available providers:

• LocalFilesystem - Stores files in a directory on disk
• S3Filesystem - Stores files in Amazon S3 or S3-compatible storage (R2, MinIO)
• GCSFilesystem - Stores files in Google Cloud Storage

tip

LocalFilesystem is the simplest way to get started as it requires no external services. For cloud storage, use S3Filesystem or GCSFilesystem.

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:

src/mastra/agents/file-agent.ts

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');

Containment

By default, LocalFilesystem runs in contained mode — all file operations are restricted to stay within basePath. This prevents path traversal attacks and symlink escapes.

In contained mode, absolute paths that fall within basePath are used as-is, while other absolute paths are treated as virtual paths relative to basePath (e.g. /file.txt resolves to basePath/file.txt). Any resolved path that escapes basePath throws a PermissionError.

If your agent needs to access paths outside basePath (for example, global skills directories or user home folders), disable containment:

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: './workspace',
    contained: false,
  }),
});

When contained is false, absolute paths are treated as real filesystem paths with no restriction.

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.

Mounts and CompositeFilesystem

When you use the mounts option on a workspace, Mastra creates a CompositeFilesystem that routes file operations to the correct provider based on path prefix.

import { Workspace } from '@mastra/core/workspace';
import { S3Filesystem } from '@mastra/s3';
import { GCSFilesystem } from '@mastra/gcs';
import { E2BSandbox } from '@mastra/e2b';

const workspace = new Workspace({
  mounts: {
    '/data': new S3Filesystem({
      bucket: 'my-bucket',
      region: 'us-east-1',
      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    }),
    '/skills': new GCSFilesystem({
      bucket: 'agent-skills',
    }),
  },
  sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
});

With this configuration:

• read_file('/data/input.csv') reads from the S3 bucket
• write_file('/skills/guide.md', content) writes to the GCS bucket
• list_directory('/') returns virtual entries for /data and /skills
• Commands in the sandbox can access files at /data and /skills via FUSE mounts

Path routing

All file paths must start with a mount prefix. Operations on paths that don't match any mount will fail. Listing the root directory (/) returns virtual directory entries for each mount point.

Mount paths cannot be nested — for example, you cannot mount at both /data and /data/sub.

filesystem vs mounts

filesystem and mounts are mutually exclusive options on a workspace:

• Use filesystem when you have a single storage provider and don't need to mount it into a sandbox. The agent gets file tools that operate directly against the provider.
• Use mounts when you need cloud storage accessible inside a sandbox, or when you want to combine multiple providers. The workspace creates a CompositeFilesystem for file tools and FUSE-mounts the storage into the sandbox.

For local development, you typically don't need mounts — a LocalFilesystem and LocalSandbox pointed at the same directory gives you both file tools and command execution on the same files. See configuration patterns for more detail.

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.

Related

• LocalFilesystem reference
• S3Filesystem reference
• GCSFilesystem reference
• Workspace overview
• Sandbox