@mastra/mcp-docs-server 1.1.29-alpha.9 → 1.1.30-alpha.2

package/.docs/reference/storage/clickhouse.md

@@ -0,0 +1,274 @@
+# ClickHouse storage
+
+[ClickHouse](https://clickhouse.com/) is a columnar database designed for analytical workloads. The `@mastra/clickhouse` package provides storage adapters for several Mastra storage domains and is the recommended backend for production observability.
+
+ClickHouse is most commonly used as the dedicated observability backend in a [composite storage](https://mastra.ai/reference/storage/composite) setup, with another database serving the remaining domains. It can also back the supported domains on its own through `ClickhouseStore`.
+
+## When to use ClickHouse
+
+- Production observability for traces, logs, metrics, scores, and feedback.
+- Append-heavy workloads where columnar storage and compression help keep costs down.
+- Deployment platforms with ephemeral filesystems (such as [Railway](#deploying-with-railway-and-similar-platforms), Fly.io, Render, Heroku, or container schedulers) where embedded backends like DuckDB cannot persist data.
+
+For local development, [LibSQL](https://mastra.ai/reference/storage/libsql) or `@mastra/duckdb` are usually a better fit because they need no external service.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/clickhouse@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/clickhouse@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/clickhouse@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/clickhouse@latest
+```
+
+You will also need a running ClickHouse server. See [Hosting options](#hosting-options) for managed and self-hosted choices.
+
+## Usage
+
+### Observability with vNext (recommended)
+
+`ObservabilityStorageClickhouseVNext` is the current observability domain implementation. It uses an insert-only schema backed by `ReplacingMergeTree` and is optimized for the volume produced by traces, logs, metrics, scores, and feedback.
+
+Compose it with another storage adapter so observability writes do not contend with your application data:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraCompositeStore } from '@mastra/core/storage'
+import { LibSQLStore } from '@mastra/libsql'
+import { ObservabilityStorageClickhouseVNext } from '@mastra/clickhouse'
+import { Observability, DefaultExporter } from '@mastra/observability'
+
+const observabilityStore = new ObservabilityStorageClickhouseVNext({
+  url: process.env.CLICKHOUSE_URL!,
+  username: process.env.CLICKHOUSE_USERNAME!,
+  password: process.env.CLICKHOUSE_PASSWORD!,
+})
+
+export const mastra = new Mastra({
+  storage: new MastraCompositeStore({
+    id: 'composite-storage',
+    default: new LibSQLStore({
+      id: 'mastra-storage',
+      url: 'file:./mastra.db',
+    }),
+    domains: {
+      observability: observabilityStore,
+    },
+  }),
+  observability: new Observability({
+    configs: {
+      default: {
+        serviceName: 'mastra',
+        exporters: [new DefaultExporter()],
+      },
+    },
+  }),
+})
+```
+
+`DefaultExporter` automatically selects the `insert-only` strategy when ClickHouse is the observability backend, which gives the highest write throughput. See [tracing strategies](https://mastra.ai/docs/observability/tracing/exporters/default) for details.
+
+### Observability with the legacy domain
+
+`ObservabilityStorageClickhouse` is the original observability adapter and remains supported for projects that have not migrated to the vNext schema. The configuration shape is the same as the vNext class.
+
+```typescript
+import { ObservabilityStorageClickhouse } from '@mastra/clickhouse'
+
+const observabilityStore = new ObservabilityStorageClickhouse({
+  url: process.env.CLICKHOUSE_URL!,
+  username: process.env.CLICKHOUSE_USERNAME!,
+  password: process.env.CLICKHOUSE_PASSWORD!,
+})
+```
+
+New projects should use `ObservabilityStorageClickhouseVNext` instead.
+
+### Full storage with `ClickhouseStore`
+
+`ClickhouseStore` implements the `memory`, `workflows`, `scores`, and `observability` domains. Use it when you want a single backend for the supported domains. For most observability deployments, the composite setup above is preferable because it isolates observability writes from primary application data.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { ClickhouseStore } from '@mastra/clickhouse'
+
+export const mastra = new Mastra({
+  storage: new ClickhouseStore({
+    id: 'clickhouse-storage',
+    url: process.env.CLICKHOUSE_URL!,
+    username: process.env.CLICKHOUSE_USERNAME!,
+    password: process.env.CLICKHOUSE_PASSWORD!,
+  }),
+})
+```
+
+### Bring your own ClickHouse client
+
+Pass a pre-configured client when you need custom connection settings such as request timeouts, compression, or interceptors:
+
+```typescript
+import { createClient } from '@clickhouse/client'
+import { ClickhouseStore } from '@mastra/clickhouse'
+
+const client = createClient({
+  url: process.env.CLICKHOUSE_URL!,
+  username: process.env.CLICKHOUSE_USERNAME!,
+  password: process.env.CLICKHOUSE_PASSWORD!,
+  request_timeout: 60_000,
+  compression: { request: true, response: true },
+})
+
+const storage = new ClickhouseStore({ id: 'clickhouse-storage', client })
+```
+
+The same `client` form is accepted by `ObservabilityStorageClickhouse` and `ObservabilityStorageClickhouseVNext`.
+
+## Configuration
+
+### `ClickhouseStore` options
+
+**id** (`string`): Unique identifier for this storage instance.
+
+**url** (`string`): ClickHouse server URL (for example, \`https\://your-instance.clickhouse.cloud:8443\` or \`http\://localhost:8123\`). Required when not passing a pre-configured \`client\`.
+
+**username** (`string`): ClickHouse username. Required when not passing a pre-configured \`client\`.
+
+**password** (`string`): ClickHouse password. Required when not passing a pre-configured \`client\`. Can be an empty string for the default user on a local instance.
+
+**client** (`ClickHouseClient`): Pre-configured ClickHouse client from \`@clickhouse/client\`. Use this when you need custom request settings. Mutually exclusive with the credential fields above.
+
+**ttl** (`object`): Per-table TTL configuration applied at table creation time. Accepts row-level and column-level TTLs in interval units from \`NANOSECOND\` through \`YEAR\`.
+
+**disableInit** (`boolean`): When \`true\`, the store does not run table creation or migrations on first use. Call \`storage.init()\` explicitly from your deployment scripts. (Default: `false`)
+
+`ClickhouseStore` also accepts every option from `ClickHouseClientConfigOptions` (such as `database`, `request_timeout`, `compression`, `keep_alive`, and `max_open_connections`).
+
+### Observability domain options
+
+`ObservabilityStorageClickhouse` and `ObservabilityStorageClickhouseVNext` accept the same connection options as `ClickhouseStore` (`url`, `username`, `password`, or a pre-configured `client`).
+
+## Hosting options
+
+ClickHouse runs anywhere you can reach it over HTTP. Two common choices:
+
+- **[ClickHouse Cloud](https://clickhouse.com/cloud)**: Managed service with a free trial tier. Provides connection details directly compatible with `url`, `username`, and `password`.
+- **Self-hosted**: Run the official [`clickhouse/clickhouse-server`](https://hub.docker.com/r/clickhouse/clickhouse-server) container or install from the [official packages](https://clickhouse.com/docs/en/install). Suitable for VPS, dedicated hardware, or Kubernetes.
+
+For local development:
+
+```bash
+docker run -d --name mastra-clickhouse \
+  -p 8123:8123 -p 9000:9000 \
+  -e CLICKHOUSE_USER=default \
+  -e CLICKHOUSE_PASSWORD=password \
+  clickhouse/clickhouse-server
+```
+
+```typescript
+new ObservabilityStorageClickhouseVNext({
+  url: 'http://localhost:8123',
+  username: 'default',
+  password: 'password',
+})
+```
+
+## Deploying with Railway and similar platforms
+
+Platforms like [Railway](https://railway.com), [Fly.io](https://fly.io), [Render](https://render.com), and Heroku run application containers on ephemeral filesystems. Embedded observability backends such as DuckDB require a writable, persistent local file, so they either lose data on restart or fail to deploy entirely on these platforms.
+
+Use ClickHouse instead. Because ClickHouse is reached over HTTP, the same connection works from any host:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraCompositeStore } from '@mastra/core/storage'
+import { PostgresStore } from '@mastra/pg'
+import { ObservabilityStorageClickhouseVNext } from '@mastra/clickhouse'
+import { Observability, DefaultExporter } from '@mastra/observability'
+
+export const mastra = new Mastra({
+  storage: new MastraCompositeStore({
+    id: 'composite-storage',
+    default: new PostgresStore({
+      id: 'pg',
+      connectionString: process.env.DATABASE_URL!,
+    }),
+    domains: {
+      observability: new ObservabilityStorageClickhouseVNext({
+        url: process.env.CLICKHOUSE_URL!,
+        username: process.env.CLICKHOUSE_USERNAME!,
+        password: process.env.CLICKHOUSE_PASSWORD!,
+      }),
+    },
+  }),
+  observability: new Observability({
+    configs: {
+      default: {
+        serviceName: 'mastra',
+        exporters: [new DefaultExporter()],
+      },
+    },
+  }),
+})
+```
+
+Two ways to provision the database:
+
+- **Managed**: Use ClickHouse Cloud. Set `CLICKHOUSE_URL`, `CLICKHOUSE_USERNAME`, and `CLICKHOUSE_PASSWORD` as environment variables in your hosting platform.
+- **Self-hosted on Railway**: Add a ClickHouse service to your Railway project from the official Docker image, then reference it in the application service through Railway's private networking.
+
+The same approach applies to other hosts with ephemeral filesystems. For application data that should also live off-host, pair this setup with a managed PostgreSQL or LibSQL/Turso instance for the `default` storage.
+
+> **Warning:** Do not point an embedded backend like DuckDB at a path inside an ephemeral container filesystem. Data written there is lost when the container restarts, and on some platforms the path is read-only.
+
+## Initialization
+
+When passed to the `Mastra` class, `ClickhouseStore` calls `init()` automatically to create the schema and run any pending migrations. The same applies to `ObservabilityStorageClickhouseVNext` when used through `MastraCompositeStore`.
+
+If you manage storage outside of `Mastra`, call `init()` explicitly:
+
+```typescript
+import { ObservabilityStorageClickhouseVNext } from '@mastra/clickhouse'
+
+const observability = new ObservabilityStorageClickhouseVNext({
+  url: process.env.CLICKHOUSE_URL!,
+  username: process.env.CLICKHOUSE_USERNAME!,
+  password: process.env.CLICKHOUSE_PASSWORD!,
+})
+
+await observability.init()
+```
+
+In CI/CD pipelines, set `disableInit: true` on `ClickhouseStore` and run `init()` from a deployment step that uses elevated credentials. Runtime application credentials can then be limited to read and insert.
+
+## Observability
+
+ClickHouse is the recommended backend for production observability:
+
+- **Insert-only strategy**: `DefaultExporter` writes completed spans in batches without per-span updates, which is the highest-throughput strategy available.
+- **Columnar compression**: Span attributes and log payloads compress well compared to the same data in row-oriented databases.
+
+For the full strategy matrix and production guidance, see the [`DefaultExporter` reference](https://mastra.ai/docs/observability/tracing/exporters/default).
+
+## Related
+
+- [Storage overview](https://mastra.ai/reference/storage/overview)
+- [Composite storage](https://mastra.ai/reference/storage/composite)
+- [`DefaultExporter`](https://mastra.ai/docs/observability/tracing/exporters/default)
+- [Observability overview](https://mastra.ai/docs/observability/overview)

package/.docs/reference/storage/composite.md

@@ -218,12 +218,12 @@ const storage = new MastraCompositeStore({
 
 Observability data can quickly overwhelm general-purpose databases in production. A single agent interaction can generate hundreds of spans, and high-traffic applications can produce thousands of traces per day.
 
-**ClickHouse** is recommended for production observability because it's optimized for high-volume, write-heavy analytics workloads. Use composite storage to route observability to ClickHouse while keeping other data in your primary database:
+**[ClickHouse](https://mastra.ai/reference/storage/clickhouse)** is recommended for production observability because it's optimized for high-volume, write-heavy analytics workloads. Use composite storage to route observability to ClickHouse while keeping other data in your primary database:
 
 ```typescript
 import { MastraCompositeStore } from '@mastra/core/storage'
 import { MemoryPG, WorkflowsPG, ScoresPG } from '@mastra/pg'
-import { ObservabilityStorageClickhouse } from '@mastra/clickhouse'
+import { ObservabilityStorageClickhouseVNext } from '@mastra/clickhouse'
 
 const storage = new MastraCompositeStore({
   id: 'composite',
@@ -231,7 +231,7 @@ const storage = new MastraCompositeStore({
     memory: new MemoryPG({ connectionString: process.env.DATABASE_URL }),
     workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
     scores: new ScoresPG({ connectionString: process.env.DATABASE_URL }),
-    observability: new ObservabilityStorageClickhouse({
+    observability: new ObservabilityStorageClickhouseVNext({
       url: process.env.CLICKHOUSE_URL,
       username: process.env.CLICKHOUSE_USERNAME,
       password: process.env.CLICKHOUSE_PASSWORD,
@@ -240,4 +240,6 @@ const storage = new MastraCompositeStore({
 })
 ```
 
+> **Note:** `ObservabilityStorageClickhouseVNext` is the current observability domain implementation. The legacy `ObservabilityStorageClickhouse` class is also exported and remains supported for projects that have not migrated. See the [ClickHouse storage reference](https://mastra.ai/reference/storage/clickhouse) for details.
+
 > **Info:** This approach is also required when using storage providers that don't support observability (like Convex, DynamoDB, or Cloudflare). See the [DefaultExporter documentation](https://mastra.ai/docs/observability/tracing/exporters/default) for the full list of supported providers.

package/.docs/reference/streaming/ChunkType.md

@@ -398,6 +398,146 @@ Contains output from workflow step execution, used primarily for usage tracking
 
 **payload.output** (`ChunkType`): Nested chunk data from step execution, typically containing finish events or other step results
 
+## Background task chunks
+
+Emitted when a tool call is dispatched as a [background task](https://mastra.ai/docs/agents/background-tasks) and `streamUntilIdle()` is used.
+
+### background-task-started
+
+Emitted when a tool call is enqueued as a background task and assigned a `taskId`.
+
+**type** (`"background-task-started"`): Chunk type identifier
+
+**payload** (`BackgroundTaskStartedPayload`): Identifies the newly enqueued task
+
+**payload.taskId** (`string`): Unique identifier for the background task
+
+**payload.toolName** (`string`): Name of the tool being executed
+
+**payload.toolCallId** (`string`): Tool-call ID from the originating LLM tool call
+
+### background-task-running
+
+Emitted when a worker picks up the task and execution begins.
+
+**type** (`"background-task-running"`): Chunk type identifier
+
+**payload** (`BackgroundTaskRunningPayload`): Details about the running task
+
+**payload.taskId** (`string`): Unique identifier for the background task
+
+**payload.toolName** (`string`): Name of the tool being executed
+
+**payload.toolCallId** (`string`): Tool-call ID from the originating LLM tool call
+
+**payload.runId** (`string`): Run ID of the agent that dispatched the task
+
+**payload.agentId** (`string`): ID of the agent that dispatched the task
+
+**payload.startedAt** (`Date`): Timestamp at which execution started
+
+**payload.args** (`Record<string, unknown>`): Arguments passed to the tool's execute function
+
+### background-task-progress
+
+Periodic snapshot of how many background tasks are currently running across the agent.
+
+**type** (`"background-task-progress"`): Chunk type identifier
+
+**payload** (`BackgroundTaskProgressPayload`): Aggregate progress for all running tasks
+
+**payload.taskIds** (`string[]`): IDs of all currently running background tasks
+
+**payload.runningCount** (`number`): Number of background tasks currently running
+
+**payload.elapsedMs** (`number`): Milliseconds elapsed since the agent run started
+
+### background-task-output
+
+A streamed output chunk emitted by the task's `execute` function. Wraps an inner [`tool-output`](#tool-output) chunk.
+
+**type** (`"background-task-output"`): Chunk type identifier
+
+**payload** (`BackgroundTaskOutputPayload`): Streamed output from the running task
+
+**payload.taskId** (`string`): Unique identifier for the background task
+
+**payload.toolName** (`string`): Name of the tool being executed
+
+**payload.toolCallId** (`string`): Tool-call ID from the originating LLM tool call
+
+**payload.runId** (`string`): Run ID of the agent that dispatched the task
+
+**payload.agentId** (`string`): ID of the agent that dispatched the task
+
+**payload.payload** (`ToolOutputChunk`): Inner tool-output chunk produced by the task
+
+### background-task-completed
+
+Emitted when the task finishes successfully. Triggers a continuation turn when consumed by [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle).
+
+**type** (`"background-task-completed"`): Chunk type identifier
+
+**payload** (`BackgroundTaskResultPayload`): The completed task's result
+
+**payload.taskId** (`string`): Unique identifier for the background task
+
+**payload.toolName** (`string`): Name of the tool that was executed
+
+**payload.toolCallId** (`string`): Tool-call ID from the originating LLM tool call
+
+**payload.agentId** (`string`): ID of the agent that dispatched the task
+
+**payload.runId** (`string`): Run ID of the agent that dispatched the task
+
+**payload.result** (`unknown`): The tool's resolved return value
+
+**payload.completedAt** (`Date`): Timestamp at which the task completed
+
+**payload.isError** (`boolean`): True when the tool returned an error result rather than throwing
+
+### background-task-failed
+
+Emitted when the task throws or times out. Triggers a continuation turn when consumed by [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle).
+
+**type** (`"background-task-failed"`): Chunk type identifier
+
+**payload** (`BackgroundTaskFailedPayload`): Failure details for the task
+
+**payload.taskId** (`string`): Unique identifier for the background task
+
+**payload.toolName** (`string`): Name of the tool that was executed
+
+**payload.toolCallId** (`string`): Tool-call ID from the originating LLM tool call
+
+**payload.runId** (`string`): Run ID of the agent that dispatched the task
+
+**payload.agentId** (`string`): ID of the agent that dispatched the task
+
+**payload.error** (`{ message: string }`): Error details thrown by the task
+
+**payload.completedAt** (`Date`): Timestamp at which the task failed
+
+### background-task-cancelled
+
+Emitted when the task is cancelled before completing. Triggers a continuation turn when consumed by [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle).
+
+**type** (`"background-task-cancelled"`): Chunk type identifier
+
+**payload** (`BackgroundTaskCancelledPayload`): Cancellation details for the task
+
+**payload.taskId** (`string`): Unique identifier for the background task
+
+**payload.toolName** (`string`): Name of the tool that was executed
+
+**payload.toolCallId** (`string`): Tool-call ID from the originating LLM tool call
+
+**payload.runId** (`string`): Run ID of the agent that dispatched the task
+
+**payload.agentId** (`string`): ID of the agent that dispatched the task
+
+**payload.completedAt** (`Date`): Timestamp at which the task was cancelled
+
 ## Metadata and special chunks
 
 ### response-metadata

package/.docs/reference/streaming/agents/streamUntilIdle.md

@@ -0,0 +1,94 @@
+# Agent.streamUntilIdle()
+
+**Added in:** `@mastra/core@1.29.0`
+
+`streamUntilIdle()` streams an agent's response and keeps the stream open until every background task dispatched during the run completes. When a task finishes, its result is written to memory and the agentic loop re-enters automatically so the LLM can react to it. The stream closes once no tasks are running and no completions are queued.
+
+Use it when the agent dispatches background tasks (typically long-running tools or subagents) and you want a single stream that spans the initial response **plus** every continuation triggered by a task completion. For foreground-only runs or if you prefer to manage the continuation manually (manually prompt agent to process the result), use [`Agent.stream()`](https://mastra.ai/reference/streaming/agents/stream).
+
+## Usage example
+
+```ts
+const stream = await agent.streamUntilIdle('Research solana for me', {
+  memory: { thread: 't1', resource: 'u1' },
+})
+
+for await (const chunk of stream.fullStream) {
+  // chunks from the initial turn AND any continuation turns triggered by
+  // background task completions flow through here
+}
+```
+
+> **Info:** `streamUntilIdle()` requires both a [`BackgroundTaskManager`](https://mastra.ai/reference/configuration) and a [memory](https://mastra.ai/docs/memory/overview) backend. Without either, it falls through to a plain `agent.stream()` call.
+
+## Parameters
+
+**messages** (`string | string[] | CoreMessage[] | AiMessageType[] | UIMessageWithMetadata[]`): The messages to send to the agent. Can be a single string, array of strings, or structured message objects.
+
+**options** (`AgentExecutionOptions<Output> & { maxIdleMs?: number }`): Accepts every option that Agent.stream() accepts, plus maxIdleMs. See the Agent.stream() reference for the full list.
+
+**options.maxIdleMs** (`number`): Closes the outer stream after this many ms of idleness between turns. The timer only runs while the wrapper is between turns, so a slow first token does not close the stream. Default: 5 minutes.
+
+**options.memory** (`{ thread?: string | { id: string }; resource?: string }`): Memory thread and resource for the run. Required for continuations to write background task results back into the conversation.
+
+**options.structuredOutput** (`PublicStructuredOutputOptions<Output>`): Schema-based structured output. Same shape as Agent.stream(). Note that aggregate properties resolve against the first turn only.
+
+For every other option (`maxSteps`, `modelSettings`, `toolChoice`, `outputProcessors`, `onFinish`, `onChunk`, etc.), see the [`Agent.stream()` parameters](https://mastra.ai/reference/streaming/agents/stream). `streamUntilIdle()` forwards them to the initial turn.
+
+## Returns
+
+**stream** (`MastraModelOutput<Output>`): A MastraModelOutput where fullStream spans the initial turn plus every auto-continuation. Aggregate properties (text, toolCalls, toolResults, finishReason, messageList, getFullOutput()) resolve against the first turn only.
+
+### Aggregate properties caveat
+
+`streamUntilIdle()` returns a proxy over the first turn's `MastraModelOutput`. Only `fullStream` is replaced with a combined stream that spans every continuation. Every other property — `text`, `toolCalls`, `toolResults`, `finishReason`, `messageList`, `getFullOutput()` — resolves against the **first turn's** internal buffer.
+
+If you need an aggregate view across all continuations, consume `fullStream` yourself and accumulate.
+
+## Continuation behavior
+
+Internally, `streamUntilIdle()`:
+
+1. Runs the initial turn via `agent.stream(...)` and pipes its `fullStream` into the outer stream.
+2. Subscribes to background-task completion events for the resolved memory scope.
+3. Queues each terminal event (`background-task-completed`, `background-task-failed`, `background-task-cancelled`) and, when the outer wrapper is idle between turns, re-invokes `agent.stream([], ...)` with a directive listing the just-completed `toolCallId`s. The continuation turn flows into the same outer stream.
+4. Closes the outer stream once no tasks are running and no completions are queued.
+
+## Extended usage example
+
+### Cap idle time between turns
+
+```ts
+const stream = await agent.streamUntilIdle('Kick off the long jobs', {
+  memory: { thread: 't1', resource: 'u1' },
+  maxIdleMs: 60_000, // close the stream after 1 minute of idleness between turns
+})
+
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === 'background-task-completed') {
+    console.log('Task complete:', chunk.payload.taskId)
+  }
+}
+```
+
+### Aggregate text across continuations
+
+```ts
+const stream = await agent.streamUntilIdle('Research and summarize', {
+  memory: { thread: 't1', resource: 'u1' },
+})
+
+let fullText = ''
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === 'text-delta') {
+    fullText += chunk.payload.text
+  }
+}
+```
+
+## Related
+
+- [Background tasks](https://mastra.ai/docs/agents/background-tasks)
+- [`Agent.stream()` reference](https://mastra.ai/reference/streaming/agents/stream)
+- [backgroundTasks configuration reference](https://mastra.ai/reference/configuration)
+- [Stream chunk types](https://mastra.ai/reference/streaming/ChunkType)

package/.docs/reference/workspace/s3-filesystem.md

@@ -1,6 +1,6 @@
 # S3Filesystem
 
-Stores files in Amazon S3 or S3-compatible storage services like Cloudflare R2, MinIO, and DigitalOcean Spaces.
+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](https://mastra.ai/reference/workspace/filesystem).
 
@@ -55,6 +55,61 @@ const agent = new Agent({
 })
 ```
 
+### 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.
+
+```typescript
+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**:
+
+```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 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
 
 ```typescript
@@ -83,19 +138,38 @@ const filesystem = new S3Filesystem({
 })
 ```
 
+### 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 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](https://console.tigris.dev/) — access keys are prefixed `tid_` and secrets `tsec_`.
+
 ## 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).
+**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. Optional for public buckets (read-only access).
+**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 temporary credentials. Required when using SSO, AssumeRole, container credentials, or any other temporary credential provider.
+**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, etc.)
+**endpoint** (`string`): Custom endpoint URL for S3-compatible storage (R2, MinIO, Tigris, etc.)
 
 **forcePathStyle** (`boolean`): 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. (Default: `true (when endpoint is set)`)