Introducing Remote Filesystems for Mastra Workspaces

Instead of relying only on local storage, your agents can now work directly with remote filesystems. Attach a provider to your agent's workspace and it can read, write, and manage remote files.

Mastra currently supports the following remote filesystems: S3, GCS, Azure Blob, and AgentFS, with Google Drive support in progress: #15756.

Remote filesystems work alongside workspace sandboxes, which give agents the ability to run scripts, install packages, and safely execute commands.

Get started

Install a remote filesystem provider:

npm install @mastra/s3

Create a workspace instance, configure a filesystem and assign it to an agent. This example uses S3Filesystem.

import { Agent } from "@mastra/core/agent";
import { Workspace } from "@mastra/core/workspace";
import { S3Filesystem } from "@mastra/s3";
 
const workspace = new Workspace({
  filesystem: new S3Filesystem({
    bucket: "mastra-agent-files",
    region: "us-east-1",
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY
  })
});
 
const fileAgent = new Agent({
  id: "file-agent",
  name: "File Agent",
  model: "anthropic/claude-opus-4-6",
  instructions: "You are a file management agent. Use the filesystem to read and write files.",
  workspace
});

Once configured, the agent can read and write files:

await agent.stream(`Read hn-weekly-report-2026-04-29.md.
Write a concise summary to hn-weekly-summary-2026-04-29.md.
List the files in the bucket.`);

For more information and full configuration options, see:

• Workspace overview
• Filesystem docs
• Sandbox docs

To see remote filesystems in action, watch the walkthrough below. At 07:50, Alex demonstrates mounting a remote filesystem into a sandbox.

Also, Shane demos the Google Drive provider (in progress) at 49:02 in this workshop.