Skip to main content

S3Filesystem

Stores files in Amazon S3 or S3-compatible storage services like Cloudflare R2, MinIO, DigitalOcean Spaces, and Tigris.

info

For interface details, see WorkspaceFilesystem Interface.

Installation
Direct link to Installation

npm install @mastra/s3

Usage
Direct link to Usage

Add an S3Filesystem to a workspace and assign it to an agent:

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: 'file-agent',
  model: 'anthropic/claude-opus-4-6',
  workspace,
})

AWS credential provider chain
Direct link to AWS credential provider chain

When no credentials are provided, S3Filesystem uses the AWS SDK default credential provider chain. This discovers credentials automatically from environment variables, ~/.aws config files, ECS container credentials, EC2 instance profiles, and other standard sources.

import { S3Filesystem } from '@mastra/s3'

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

Pass a credential provider function for auto-refreshing credentials. This is useful for deployments on ECS, Lambda, or when using SSO/AssumeRole where temporary credentials expire and need to be refreshed.

Install the AWS SDK credential providers package when calling fromNodeProviderChain() directly:

npm install @aws-sdk/credential-providers
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(),
})

Provider functions only apply to S3Filesystem API calls. When mounting the filesystem into an E2B sandbox, mount configuration only supports static accessKeyId, secretAccessKey, and sessionToken values, so credential refresh must be handled outside the mount.

Cloudflare R2
Direct link to Cloudflare R2

import { S3Filesystem } from '@mastra/s3'

const 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,
})

MinIO
Direct link to MinIO

import { S3Filesystem } from '@mastra/s3'

const filesystem = new S3Filesystem({
  bucket: 'my-bucket',
  region: 'us-east-1',
  endpoint: 'http://localhost:9000',
  accessKeyId: 'minioadmin',
  secretAccessKey: 'minioadmin',
})

Tigris
Direct link to Tigris

import { S3Filesystem } from '@mastra/s3'

const filesystem = new S3Filesystem({
  bucket: 'my-bucket',
  region: 'auto',
  endpoint: 'https://t3.storage.dev',
  accessKeyId: process.env.TIGRIS_ACCESS_KEY_ID,
  secretAccessKey: process.env.TIGRIS_SECRET_ACCESS_KEY,
  forcePathStyle: false,
})

Tigris uses virtual-hosted-style addressing, so forcePathStyle must be set to false (the default is true when a custom endpoint is provided). Create credentials from the Tigris Dashboard — access keys are prefixed tid_ and secrets tsec_.

Constructor parameters
Direct link to Constructor parameters

bucket:

string
S3 bucket name

region:

string
AWS region (use 'auto' for R2)

credentials?:

AwsCredentialIdentity | AwsCredentialIdentityProvider
AWS credentials or credential provider function. Accepts static credentials or a provider that auto-refreshes (e.g. `fromNodeProviderChain()` from `@aws-sdk/credential-providers`). Takes precedence over `accessKeyId`/`secretAccessKey`/`sessionToken`. When all credential options are omitted, the SDK default credential provider chain is used.

accessKeyId?:

string
AWS access key ID. When omitted along with `secretAccessKey` and `credentials`, the SDK default credential provider chain is used.

secretAccessKey?:

string
AWS secret access key. When omitted along with `accessKeyId` and `credentials`, the SDK default credential provider chain is used.

sessionToken?:

string
AWS session token for static temporary credentials. Use with `accessKeyId`/`secretAccessKey` only when passing a complete temporary credential set manually. For auto-refreshing SSO, AssumeRole, or container credentials, use the `credentials` provider parameter or the SDK default credential provider chain.

endpoint?:

string
Custom endpoint URL for S3-compatible storage (R2, MinIO, Tigris, etc.)

forcePathStyle?:

boolean
= true (when endpoint is set)
Force path-style URLs instead of virtual-hosted-style. Required for some S3-compatible services like MinIO. Defaults to true when a custom endpoint is provided.

prefix?:

string
Optional prefix for all keys (acts like a subdirectory)

id?:

string
= Auto-generated
Unique identifier for this filesystem instance

displayName?:

string
Human-friendly display name for the UI

icon?:

FilesystemIcon
Icon identifier for the UI

description?:

string
Short description of this filesystem for the UI

readOnly?:

boolean
= false
When true, all write operations are blocked

Properties
Direct link to Properties

id:

string
Filesystem instance identifier

name:

string
Provider name ('S3Filesystem')

provider:

string
Provider identifier ('s3')

bucket:

string
The S3 bucket name

readOnly:

boolean | undefined
Whether the filesystem is in read-only mode

Methods
Direct link to Methods

S3Filesystem implements the WorkspaceFilesystem interface, providing all standard filesystem methods:

  • readFile(path, options?) - Read file contents
  • writeFile(path, content, options?) - Write content to a file
  • appendFile(path, content) - Append content to a file
  • deleteFile(path, options?) - Delete a file
  • copyFile(src, dest, options?) - Copy a file
  • moveFile(src, dest, options?) - Move or rename a file
  • mkdir(path, options?) - Create a directory
  • rmdir(path, options?) - Remove a directory
  • readdir(path, options?) - List directory contents
  • exists(path) - Check if a path exists
  • stat(path) - Get file or directory metadata

init()
Direct link to init

Initialize the filesystem. Verifies bucket access and credentials.

await filesystem.init()

getInfo()
Direct link to getinfo

Returns metadata about this filesystem instance.

const info = filesystem.getInfo()
// { id: '...', name: 'S3Filesystem', provider: 's3', status: 'ready' }

getMountConfig()
Direct link to getmountconfig

Returns the mount configuration for sandboxes that support mounting this filesystem type.

const config = filesystem.getMountConfig()
// { type: 's3', bucket: 'my-bucket', region: 'us-east-1', ... }

Mounting in E2B sandboxes
Direct link to Mounting in E2B sandboxes

S3Filesystem can be mounted into E2B sandboxes, making the bucket accessible as a local directory:

import { Workspace } from '@mastra/core/workspace'
import { S3Filesystem } from '@mastra/s3'
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,
    }),
  },
  sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
})

See E2BSandbox reference for more details on mounting.

On this page