Skip to main content

S3Filesystem

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

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-5',
  workspace,
})

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

Constructor parameters
Direct link to Constructor parameters

bucket:

string
S3 bucket name

region:

string
AWS region (use 'auto' for R2)

accessKeyId?:

string
AWS access key ID. Optional for public buckets (read-only access).

secretAccessKey?:

string
AWS secret access key. Optional for public buckets (read-only access).

sessionToken?:

string
AWS session token for temporary credentials. Required when using SSO, AssumeRole, container credentials, or any other temporary credential provider.

endpoint?:

string
Custom endpoint URL for S3-compatible storage (R2, MinIO, 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