> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/llms.txt

# S3Filesystem

Amazon S3、または Cloudflare R2、MinIO、DigitalOcean Spaces、Tigris などの S3 互換ストレージサービスにファイルを保存します。インターフェースの詳細は、[WorkspaceFilesystem インターフェース](https://mastra.zisheng.pro/ja/reference/workspace/filesystem)を参照してください。

## インストール

**npm**:

```bash
npm install @mastra/s3
```

**pnpm**:

```bash
pnpm add @mastra/s3
```

**Yarn**:

```bash
yarn add @mastra/s3
```

**Bun**:

```bash
bun add @mastra/s3
```

## 使用方法

Workspace に `S3Filesystem` を追加して Agent に割り当てます。

```typescript
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({
  id: 'file-agent',
  name: 'file-agent',
  model: 'anthropic/claude-opus-4-7',
  workspace,
})
```

### AWS 認証情報 Provider チェーン

認証情報を指定しない場合、`S3Filesystem` は AWS SDK のデフォルト認証情報 Provider チェーンを使用します。環境変数、`~/.aws` 設定ファイル、ECS コンテナ認証情報、EC2 インスタンスプロファイル、その他の標準ソースから認証情報を自動検出します。

```typescript
import { S3Filesystem } from '@mastra/s3'

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

認証情報を自動更新するには、認証情報 Provider 関数を渡します。ECS や Lambda へのデプロイ、または有効期限のある一時認証情報を更新する必要がある SSO / AssumeRole の使用時に便利です。

`fromNodeProviderChain()` を直接呼び出す場合は、AWS SDK の認証情報 Provider パッケージをインストールします。

**npm**:

```bash
npm install @aws-sdk/credential-providers
```

**pnpm**:

```bash
pnpm add @aws-sdk/credential-providers
```

**Yarn**:

```bash
yarn add @aws-sdk/credential-providers
```

**Bun**:

```bash
bun add @aws-sdk/credential-providers
```

```typescript
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 関数は `S3Filesystem` API の呼び出しにのみ適用されます。Filesystem を E2B Sandbox にマウントする場合、マウント設定は静的な `accessKeyId`、`secretAccessKey`、`sessionToken` の値にしか対応しないため、認証情報の更新はマウントの外部で処理する必要があります。

### Cloudflare R2

```typescript
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

```typescript
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

```typescript
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 は仮想ホスト形式のアドレス指定を使用するため、`forcePathStyle` を `false` に設定する必要があります（カスタムエンドポイントを指定した場合のデフォルトは `true`）。認証情報は [Tigris ダッシュボード](https://console.tigris.dev/)で作成します。アクセスキーには `tid_`、シークレットには `tsec_` の接頭辞が付きます。

## コンストラクターパラメーター

**bucket** (`string`): S3 バケット名。

**region** (`string`): AWS リージョン（R2 では 'auto' を使用）。

**credentials** (`AwsCredentialIdentity | AwsCredentialIdentityProvider`): AWS 認証情報または認証情報 Provider 関数。静的な認証情報、または自動更新する Provider（@aws-sdk/credential-providers の fromNodeProviderChain() など）を指定できます。accessKeyId / secretAccessKey / sessionToken より優先されます。すべての認証情報オプションを省略すると、SDK のデフォルト認証情報 Provider チェーンを使用します。

**accessKeyId** (`string`): AWS アクセスキー ID。secretAccessKey と credentials とともに省略した場合は、SDK のデフォルト認証情報 Provider チェーンを使用します。

**secretAccessKey** (`string`): AWS シークレットアクセスキー。accessKeyId と credentials とともに省略した場合は、SDK のデフォルト認証情報 Provider チェーンを使用します。

**sessionToken** (`string`): 静的な一時認証情報用の AWS セッショントークン。完全な一時認証情報一式を手動で渡す場合にのみ、accessKeyId / secretAccessKey とともに使用します。自動更新する SSO、AssumeRole、コンテナ認証情報には、credentials Provider パラメーターまたは SDK のデフォルト認証情報 Provider チェーンを使用してください。

**endpoint** (`string`): S3 互換ストレージ（R2、MinIO、Tigris など）のカスタムエンドポイント URL。

**forcePathStyle** (`boolean`): 仮想ホスト形式ではなくパス形式の URL を強制します。MinIO など一部の S3 互換サービスで必要です。カスタムエンドポイントを指定した場合のデフォルトは true です。 (Default: `true (when endpoint is set)`)

**prefix** (`string`): すべてのキーに付加する任意のプレフィックス（サブディレクトリとして機能します）。

**id** (`string`): この Filesystem インスタンスの一意な識別子。 (Default: `Auto-generated`)

**displayName** (`string`): UI に表示するわかりやすい名前。

**icon** (`FilesystemIcon`): UI に表示するアイコンの識別子。

**description** (`string`): UI に表示する Filesystem の短い説明。

**readOnly** (`boolean`): true の場合、すべての書き込み操作を禁止します。 (Default: `false`)

## プロパティ

**id** (`string`): Filesystem インスタンスの識別子。

**name** (`string`): Provider 名（'S3Filesystem'）。

**provider** (`string`): Provider 識別子（'s3'）。

**bucket** (`string`): S3 バケット名。

**readOnly** (`boolean | undefined`): Filesystem が読み取り専用モードかどうか。

## メソッド

S3Filesystem は [WorkspaceFilesystem インターフェース](https://mastra.zisheng.pro/ja/reference/workspace/filesystem)を実装し、標準の Filesystem メソッドをすべて提供します。

- `readFile(path, options?)` - ファイルの内容を読み取ります
- `writeFile(path, content, options?)` - ファイルに内容を書き込みます
- `appendFile(path, content)` - ファイルに内容を追記します
- `deleteFile(path, options?)` - ファイルを削除します
- `copyFile(src, dest, options?)` - ファイルをコピーします
- `moveFile(src, dest, options?)` - ファイルを移動または名前変更します
- `mkdir(path, options?)` - ディレクトリを作成します
- `rmdir(path, options?)` - ディレクトリを削除します
- `readdir(path, options?)` - ディレクトリの内容を一覧表示します
- `exists(path)` - パスが存在するか確認します
- `stat(path)` - ファイルまたはディレクトリのメタデータを取得します

### `init()`

Filesystem を初期化し、バケットへのアクセスと認証情報を検証します。

```typescript
await filesystem.init()
```

### `getInfo()`

この Filesystem インスタンスのメタデータを返します。

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

### `getMountConfig()`

この種類の Filesystem のマウントに対応する Sandbox 向けに、マウント設定を返します。

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

## E2B Sandbox にマウントする

S3Filesystem を E2B Sandbox にマウントすると、バケットへローカルディレクトリとしてアクセスできます。

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

マウントの詳細は、[E2BSandbox リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/e2b-sandbox)を参照してください。

## 関連項目

- [WorkspaceFilesystem インターフェース](https://mastra.zisheng.pro/ja/reference/workspace/filesystem)
- [ArchilFilesystem リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/archil-filesystem)
- [GCSFilesystem リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/gcs-filesystem)
- [AzureBlobFilesystem リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/azure-blob-filesystem)
- [E2BSandbox リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/e2b-sandbox)
- [Workspace の概要](https://mastra.zisheng.pro/ja/docs/workspace/overview)