Remote Filesystem Support for Mastra Agents

Your agents can now access the same filesystems your team's already using. Attach a provider to the workspace and the agent gets tools to read, write, edit, list, search, and delete files. Any changes made by either humans or agents happen in the same bucket, folder, or drive.

Filesystems are configurable — grant access by user, role, or tenant, or restrict agent access to read-only.

Mastra currently supports the following remote filesystems:

And our own filesystem on the Mastra Platform.

Every filesystem exposes the following tools your agents can use:

Tool	Description
`read_file`	Reads all or part of a file.
`write_file`	Creates or overwrites a file.
`edit_file`	Replaces matching text in an existing file.
`list_files`	Lists files and directories.
`delete`	Deletes a file or directory.
`file_stat`	Returns metadata about a file or directory.
`mkdir`	Creates a directory and any missing parent directories.
`grep`	Searches file contents with a regular expression.
`ast_edit`	Applies structural code edits. Available when `@ast-grep/napi` is installed.

Get started

Install a filesystem provider. This example uses Google Drive:

Terminal

npm install @mastra/google-drive

note

All listed providers work with @mastra/core@1.51.0 or later, added in PR #18908.

Create a workspace with a GoogleDriveFilesystem pointed at a Shared Drive folder:

src/mastra/workspaces/google-drive-workspace.ts

import { Workspace } from "@mastra/core/workspace";
import { GoogleDriveFilesystem } from "@mastra/google-drive";
 
export const googleDriveWorkspace = new Workspace({
  id: "google-drive-workspace",
  filesystem: new GoogleDriveFilesystem({
    folderId: process.env.GOOGLE_DRIVE_FOLDER_ID,
    serviceAccount: {
      clientEmail: process.env.GOOGLE_DRIVE_CLIENT_EMAIL,
      privateKey: process.env.GOOGLE_DRIVE_PRIVATE_KEY
    }
  })
});

Attach the workspace to an agent. The filesystem's file-management tools are exposed to the agent automatically:

src/mastra/agents/recruiter-agent.ts

import { Agent } from "@mastra/core/agent";
import { Memory } from "@mastra/memory";
import { readPdfTool } from "../tools/read-pdf-tool";
import { googleDriveWorkspace } from "../workspaces/google-drive-workspace";
 
export const recruiterAgent = new Agent({
  id: "recruiter-agent",
  // ...
  workspace: googleDriveWorkspace
});

src/mastra/index.ts

import { Mastra } from "@mastra/core/mastra";
import { googleDriveWorkspace } from "./workspaces/google-drive-workspace";
 
export const mastra = new Mastra({
  // ...
  workspace: googleDriveWorkspace
});

Dynamic filesystems

Pass filesystem a function that reads values from requestContext to scope the folder per user, tenant, or thread:

src/mastra/workspaces/google-drive-workspace.ts

import { Workspace } from "@mastra/core/workspace";
import { GoogleDriveFilesystem } from "@mastra/google-drive";
 
const workspace = new Workspace({
  // ...
  filesystem: ({ requestContext }) => {
    return new GoogleDriveFilesystem({
      folderId: requestContext.get("folder-id") as string,
      serviceAccount: {
        clientEmail: process.env.GOOGLE_DRIVE_CLIENT_EMAIL,
        privateKey: process.env.GOOGLE_DRIVE_PRIVATE_KEY
      }
    });
  }
});

Filesystem constraints

Policies and containment vary by provider with some supporting allowedPaths and others prefix, but every provider listed above supports readOnly: true:

src/mastra/workspaces/google-drive-workspace.ts

import { Workspace } from "@mastra/core/workspace";
import { GoogleDriveFilesystem } from "@mastra/google-drive";
 
const workspace = new Workspace({
  // ...
  filesystem: new GoogleDriveFilesystem({
    folderId: process.env.GOOGLE_DRIVE_FOLDER_ID,
    serviceAccount: {
      clientEmail: process.env.GOOGLE_DRIVE_CLIENT_EMAIL,
      privateKey: process.env.GOOGLE_DRIVE_PRIVATE_KEY
    },
    readOnly: true
  })
});

For more information and full configuration options, see: