@mastra/s3

@mastra/s3

S3-compatible filesystem provider for Mastra workspaces. Works with AWS S3, Cloudflare R2, MinIO, DigitalOcean Spaces, and other S3-compatible storage services.

Installation

npm install @mastra/s3

Usage

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: 'my-bucket',
    region: 'us-east-1',
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  }),
});

const agent = new Agent({
  name: 'my-agent',
  model: 'anthropic/claude-opus-4-5',
  workspace,
});

AWS credential provider chain

When no credentials are provided, S3Filesystem uses the AWS SDK default credential provider chain to discover credentials from the environment automatically (environment variables, ~/.aws config, ECS container credentials, EC2 instance profiles, etc.).

import { S3Filesystem } from '@mastra/s3';

// SDK discovers credentials from the environment
const filesystem = new S3Filesystem({
  bucket: 'my-bucket',
  region: 'us-east-1',
});

You can also pass a credential provider function for auto-refreshing credentials, which is useful for ECS, Lambda, SSO, or AssumeRole deployments:

import { S3Filesystem } from '@mastra/s3';
import { fromNodeProviderChain } from '@aws-sdk/credential-providers';

const filesystem = new S3Filesystem({
  bucket: 'my-bucket',
  region: 'us-east-1',
  credentials: fromNodeProviderChain(),
});

Cloudflare R2

const workspace = new Workspace({
  filesystem: new S3Filesystem({
    bucket: 'my-r2-bucket',
    region: 'auto',
    endpoint: `https://${process.env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
    accessKeyId: process.env.R2_ACCESS_KEY_ID,
    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
  }),
});

With E2B Sandbox

When used with @mastra/e2b, S3 filesystems can be mounted into E2B sandboxes via s3fs-fuse:

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

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

Documentation

For more information, see the Mastra Workspaces documentation.