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:

 1npm install @mastra/s3

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

 1import { Agent } from "@mastra/core/agent";
 2import { Workspace } from "@mastra/core/workspace";
 3import { S3Filesystem } from "@mastra/s3";
 4
 5const workspace = new Workspace({
 6  filesystem: new S3Filesystem({
 7    bucket: "mastra-agent-files",
 8    region: "us-east-1",
 9    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
10    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY
11  })
12});
13
14const fileAgent = new Agent({
15  id: "file-agent",
16  name: "File Agent",
17  model: "anthropic/claude-opus-4-6",
18  instructions: "You are a file management agent. Use the filesystem to read and write files.",
19  workspace
20});

Once configured, the agent can read and write files:

 1await agent.stream(`Read hn-weekly-report-2026-04-29.md.
 2Write a concise summary to hn-weekly-summary-2026-04-29.md.
 3List 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.