@mastra/mcp-docs-server 1.2.15-alpha.7 → 1.2.15

package/.docs/reference/vectors/oracledb.md

@@ -0,0 +1,347 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# OracleDB vector store
+
+`OracleVector` stores embeddings in Oracle Database `VECTOR` columns and exposes them through Mastra's vector interface. Each logical Mastra vector index is mapped to an Oracle vector table through a registry table, while metadata is stored as Oracle JSON for structured filtering.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/oracledb@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/oracledb@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/oracledb@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/oracledb@latest
+```
+
+## Usage
+
+```ts
+import { OracleVector } from '@mastra/oracledb'
+
+const vector = new OracleVector({
+  id: 'oracle-vector',
+  user: process.env.ORACLE_DATABASE_USER,
+  password: process.env.ORACLE_DATABASE_PASSWORD,
+  connectString: process.env.ORACLE_DATABASE_CONNECT_STRING,
+})
+
+await vector.createIndex({
+  indexName: 'memory_messages',
+  dimension: 1536,
+  metric: 'cosine',
+})
+
+await vector.upsert({
+  indexName: 'memory_messages',
+  vectors: [embedding],
+  metadata: [{ resource_id: 'user-1', thread_id: 'thread-1' }],
+})
+
+const results = await vector.query({
+  indexName: 'memory_messages',
+  queryVector,
+  topK: 5,
+  filter: { resource_id: 'user-1' },
+})
+```
+
+By default, `OracleVector` uses exact search with no approximate vector index. Configure IVF or HNSW when your dataset and latency requirements need approximate search.
+
+## Constructor options
+
+Pass Oracle connection options (`user`, `password`, `connectString`, `pool`, wallet options, or `externalAuth`) directly, or pass `poolManager` to share the pool used by `OracleStore`. The vector-specific options are:
+
+**id** (`string`): Unique identifier for this vector store instance.
+
+**poolManager** (`OraclePoolManager`): Shared Oracle pool manager. Use this to share one Oracle pool with OracleStore.
+
+**schemaName** (`string`): Oracle schema name used to qualify the vector registry and vector tables.
+
+**tablePrefix** (`string`): Prefix used for physical Oracle vector tables. (Default: `'MASTRA_VEC'`)
+
+**registryTableName** (`string`): Oracle table used to map Mastra logical index names to physical vector tables. (Default: `'MASTRA_VECTOR_INDEXES'`)
+
+**defaultIndexConfig** (`OracleVectorIndexConfig`): Default Oracle vector index configuration. (Default: `{ type: 'none', accuracy: 95 }`)
+
+**defaultMetadataIndexes** (`string[]`): Metadata fields to index automatically when vector tables are created. (Default: `['thread_id', 'resource_id', 'message_id', 'source_id']`)
+
+**defaultVectorFormat** (`'vector' | 'bit' | 'int8'`): Default Oracle vector format for dense, binary, and int8 embeddings. (Default: `'vector'`)
+
+**upsertBatchSize** (`number`): Number of vectors sent per Oracle executeMany call. The full upsert commits once after all batches succeed. (Default: `200`)
+
+## Constructor examples
+
+### Shared pool with OracleStore
+
+```ts
+import { OracleStore, OracleVector } from '@mastra/oracledb'
+
+const storage = new OracleStore({ id: 'oracle-storage', user, password, connectString })
+
+const vector = new OracleVector({
+  id: 'oracle-vector',
+  poolManager: storage.getPoolManager(),
+})
+```
+
+For Autonomous Database and mTLS connections, pass `walletLocation`, `walletPassword`, and `configDir` in the same constructor.
+
+## Methods
+
+### `createIndex()`
+
+Creates the registry row, physical Oracle vector table, metadata indexes, and optionally an Oracle vector index.
+
+**indexName** (`string`): Logical Mastra index name. The provider maps this to a valid Oracle table name internally.
+
+**dimension** (`number`): Vector dimension. This must match the embedding model output size.
+
+**metric** (`'cosine' | 'euclidean' | 'dotproduct' | 'hamming' | 'jaccard'`): Distance metric for similarity search. Binary vectors support hamming and jaccard. (Default: `cosine`)
+
+**vectorFormat** (`'vector' | 'bit' | 'int8'`): Oracle vector storage format. (Default: `vector`)
+
+**indexConfig** (`OracleVectorIndexConfig`): Oracle vector index configuration. none means exact search with no approximate vector index. (Default: `{ type: 'none', accuracy: 95 }`)
+
+**buildIndex** (`boolean`): Whether to build the Oracle vector index when indexConfig.type is ivf or hnsw. (Default: `true`)
+
+**metadataIndexes** (`string[]`): Metadata field names to index for faster JSON metadata filtering.
+
+#### `OracleVectorIndexConfig`
+
+**type** (`'none' | 'ivf' | 'hnsw'`): Oracle vector index type. (Default: `'none'`)
+
+**accuracy** (`number`): Target accuracy for approximate vector search. (Default: `95`)
+
+**ivf.neighborPartitions** (`number`): Oracle IVF neighbor partitions setting.
+
+**hnsw\.neighbors** (`number`): Oracle HNSW neighbor setting.
+
+**hnsw\.efConstruction** (`number`): Oracle HNSW build-time construction setting.
+
+#### Index configuration
+
+```ts
+await vector.createIndex({
+  indexName: 'support_articles',
+  dimension: 1536,
+  metric: 'cosine',
+  indexConfig: {
+    type: 'ivf',
+    accuracy: 95,
+    ivf: {
+      neighborPartitions: 32,
+    },
+  },
+})
+```
+
+The default is `indexConfig: { type: 'none' }`, which uses exact search and requires no approximate index tuning. Use IVF or HNSW only when your data volume and latency requirements justify approximate search. HNSW is configured with `indexConfig: { type: 'hnsw', hnsw: { neighbors, efConstruction } }` and requires Oracle Vector Pool memory, which `configureVectorMemory()` can allocate for local or self-managed databases.
+
+### `upsert()`
+
+**indexName** (`string`): Name of the index to upsert vectors into.
+
+**vectors** (`number[][]`): Array of embedding vectors.
+
+**metadata** (`Record<string, any>[]`): Metadata stored as Oracle JSON. Must align by position with vectors.
+
+**ids** (`string[]`): Optional vector IDs. IDs are generated when omitted.
+
+### `query()`
+
+**indexName** (`string`): Name of the index to query.
+
+**queryVector** (`number[]`): Query vector.
+
+**topK** (`number`): Number of results to return. (Default: `10`)
+
+**filter** (`Record<string, any>`): Mastra metadata filter translated to Oracle JSON predicates.
+
+**includeVector** (`boolean`): Whether to include the vector in each result. (Default: `false`)
+
+**minScore** (`number`): Minimum similarity score threshold. (Default: `-1`)
+
+**queryMode** (`'exact' | 'approx'`): Oracle query mode. Exact search is used by default when no approximate vector index is configured.
+
+**targetAccuracy** (`number`): Target accuracy for approximate Oracle vector queries.
+
+### `listIndexes()`
+
+Returns the logical Mastra index names recorded in the Oracle vector registry table.
+
+### `describeIndex()`
+
+Returns Oracle index metadata, including the physical table name, dimension, vector count, metric, index type, vector format, and configured accuracy.
+
+### `deleteIndex()`
+
+Deletes the Oracle vector table and removes the registry entry for the logical index.
+
+### `updateVector()`
+
+Update vectors by ID or metadata filter. Either `id` or `filter` must be provided, but not both. The `update` object may include `vector`, `metadata`, or both.
+
+```ts
+await vector.updateVector({
+  indexName: 'support_articles',
+  id: 'doc-1',
+  update: { metadata: { status: 'reviewed' } },
+})
+```
+
+### `deleteVector()`
+
+Deletes a single vector by ID.
+
+### `deleteVectors()`
+
+Deletes multiple vectors by IDs or by metadata filter. Either `ids` or `filter` must be provided, but not both.
+
+### `buildIndex()`
+
+Builds an Oracle vector index for an existing logical index. If the resolved index type is `none`, this method is a no-op.
+
+### `rebuildIndex()`
+
+Drops and recreates the Oracle vector index for an existing logical index, typically after changing approximate-index tuning.
+
+### Index diagnostics
+
+Use `getIndexStatus({ indexName })` to inspect Oracle catalog status, and `indexAccuracyQuery({ indexName, queryVector, topK, targetAccuracy })` to run `DBMS_VECTOR.INDEX_ACCURACY_QUERY` for approximate indexes.
+
+### `configureVectorMemory()`
+
+Allocates Oracle Vector Pool memory, which HNSW indexes require. This calls `ALTER SYSTEM SET VECTOR_MEMORY_SIZE`, so it requires a privileged connection such as `SYSDBA` or `SYSTEM`.
+
+**size** (`string`): Vector pool size, as an integer optionally followed by K, M, or G (for example "512M").
+
+**scope** (`'MEMORY' | 'SPFILE' | 'BOTH'`): Oracle ALTER SYSTEM scope. Use 'SPFILE' or 'BOTH' so the setting survives a database restart. (Default: `'MEMORY'`)
+
+### `disconnect()`
+
+Closes the Oracle pool when `OracleVector` created the pool manager. If you provide `pool` or `poolManager`, you own that lifecycle.
+
+## Metadata filters
+
+`OracleVector` accepts Mastra's standard metadata filter syntax. Filters are translated into Oracle JSON predicates with bound values:
+
+- scalar comparisons use `JSON_VALUE`
+- array, existence, and element-match checks use `JSON_EXISTS`
+- regex filters use `REGEXP_LIKE`
+- string contains filters use case-insensitive `LIKE`
+
+```ts
+const results = await vector.query({
+  indexName: 'memory_messages',
+  queryVector,
+  topK: 5,
+  filter: {
+    resource_id: 'user-1',
+    tags: { $contains: 'support' },
+    score: { $gte: 0.8 },
+    $or: [{ source: 'docs' }, { source: 'tickets' }],
+  },
+})
+```
+
+Metadata is stored as native Oracle JSON, so the rows are also readable directly with standard Oracle JDBC tools such as DBeaver and SQL Developer.
+
+Use `ORACLEDB_PROMPT` when an agent should generate Oracle-compatible metadata filters for `createVectorQueryTool()`:
+
+```ts
+import { Agent } from '@mastra/core/agent'
+import { createVectorQueryTool } from '@mastra/rag'
+import { fastembed } from '@mastra/fastembed'
+import { ORACLEDB_PROMPT } from '@mastra/oracledb'
+
+const vectorQueryTool = createVectorQueryTool({
+  vectorStoreName: 'oracle',
+  indexName: 'support_articles',
+  model: fastembed,
+  enableFilter: true,
+})
+
+export const ragAgent = new Agent({
+  id: 'oracle-rag-agent',
+  name: 'Oracle RAG Agent',
+  model: 'openai/gpt-5.6-sol',
+  instructions: `
+Use the retrieval tool when you need source context.
+Available metadata fields: resource_id, thread_id, source, category, tags.
+${ORACLEDB_PROMPT}
+`,
+  tools: { vectorQueryTool },
+})
+```
+
+## Response types
+
+Query results are returned in this format:
+
+```ts
+interface QueryResult {
+  id: string
+  score: number
+  metadata: Record<string, any>
+  vector?: number[]
+}
+```
+
+## Usage example
+
+```ts
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { fastembed } from '@mastra/fastembed'
+import { OracleStore, OracleVector } from '@mastra/oracledb'
+
+const storage = new OracleStore({
+  id: 'oracle-storage',
+  user: process.env.ORACLE_DATABASE_USER,
+  password: process.env.ORACLE_DATABASE_PASSWORD,
+  connectString: process.env.ORACLE_DATABASE_CONNECT_STRING,
+})
+
+const vector = new OracleVector({
+  id: 'oracle-vector',
+  poolManager: storage.getPoolManager(),
+})
+
+export const oracleAgent = new Agent({
+  id: 'oracle-agent',
+  name: 'Oracle Agent',
+  instructions: 'You are an assistant with OracleDB-backed memory and semantic recall.',
+  model: 'openai/gpt-5.6-sol',
+  memory: new Memory({
+    storage,
+    vector,
+    embedder: fastembed,
+    options: {
+      semanticRecall: { topK: 3, messageRange: 2 },
+    },
+  }),
+})
+```
+
+## Related
+
+- [OracleDB storage](https://mastra.ai/integrations/databases/oracledb)
+- [Metadata Filters](https://mastra.ai/reference/rag/metadata-filters)
+- [Vector databases](https://mastra.ai/reference/rag/vector-databases)

package/.docs/reference/workers/overview.md

@@ -2,6 +2,8 @@
 
 # Workers
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 For usage patterns and deployment topologies, see [Workers](https://mastra.ai/docs/deployment/workers).
 
 ## Environment variables
@@ -75,13 +77,13 @@ Executes background tool calls dispatched by agents.
 
 A deployment running all worker types requires a storage backend that implements the `workflows`, `backgroundTasks`, and `schedules` domains. The `schedules` domain is specifically required by the SchedulerWorker. If you don't use scheduled workflows, backends without it can still support orchestration and background tasks. The following backends support all three:
 
-| Backend    | Package                                                          |
-| ---------- | ---------------------------------------------------------------- |
-| PostgreSQL | [`@mastra/pg`](https://mastra.ai/reference/storage/postgresql)   |
-| LibSQL     | [`@mastra/libsql`](https://mastra.ai/reference/storage/libsql)   |
-| MySQL      | `@mastra/mysql`                                                  |
-| MongoDB    | [`@mastra/mongodb`](https://mastra.ai/reference/storage/mongodb) |
-| Spanner    | [`@mastra/spanner`](https://mastra.ai/reference/storage/spanner) |
-| Convex     | [`@mastra/convex`](https://mastra.ai/reference/storage/convex)   |
+| Backend    | Package                                                               |
+| ---------- | --------------------------------------------------------------------- |
+| PostgreSQL | [`@mastra/pg`](https://mastra.ai/integrations/databases/postgresql)   |
+| LibSQL     | [`@mastra/libsql`](https://mastra.ai/integrations/databases/libsql)   |
+| MySQL      | `@mastra/mysql`                                                       |
+| MongoDB    | [`@mastra/mongodb`](https://mastra.ai/integrations/databases/mongodb) |
+| Spanner    | [`@mastra/spanner`](https://mastra.ai/integrations/databases/spanner) |
+| Convex     | [`@mastra/convex`](https://mastra.ai/integrations/databases/convex)   |
 
 Other storage backends (Upstash, DynamoDB, Cloudflare D1, ClickHouse, Redis) support workflows and some worker features, but are missing the `schedules` domain. They can still be used for orchestration and background task workers if you don't deploy the scheduler.

package/.docs/reference/workflows/{stored-workflow-definition.md → dynamic-workflow-definition.md}

@@ -1,12 +1,12 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# Stored workflow definition
+# Dynamic workflow definition
 
-> **Beta:** Stored workflows are in beta. Breaking changes may occur without a major version bump until the API is stable.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
-A stored workflow definition is a JSON-compatible `StoredWorkflowGraph` accepted by [`Mastra.addStoredWorkflow()`](https://mastra.ai/reference/core/addStoredWorkflow), the stored-workflow server routes, and the Client SDK workflows API.
+A dynamic workflow definition is a JSON-compatible `DynamicWorkflowGraph` accepted by [`Mastra.addDynamicWorkflow()`](https://mastra.ai/reference/core/addDynamicWorkflow), the stored-workflow server routes, and the Client SDK workflows API.
 
-See [Stored workflows](https://mastra.ai/docs/workflows/stored-workflows) for a complete setup and usage example.
+See [Dynamic workflows](https://mastra.ai/docs/workflows/dynamic-workflows) for a complete setup and usage example.
 
 ## Definition fields
 
@@ -132,6 +132,8 @@ Tool entries accept the same optional `description` and `options` fields as agen
 
 A `mapping` entry reshapes data. Its `mapConfig` is a JSON string that encodes an object. Each key becomes a key in the step output, and each descriptor defines one source.
 
+When you call [`Mastra.addDynamicWorkflow()`](https://mastra.ai/reference/core/addDynamicWorkflow) directly, `mapConfig` also accepts the object itself. Mastra encodes it to a JSON string before registering and storing the definition, so the persisted row is the same either way. A stored definition always carries the JSON string form.
+
 | Descriptor                             | Description                               |
 | -------------------------------------- | ----------------------------------------- |
 | `{ "value": ... }`                     | A constant JSON value                     |
@@ -286,7 +288,7 @@ Validation errors include a dotted path, such as `graph.2.steps.0`, that identif
 
 ## Related
 
-- [Use stored workflows](https://mastra.ai/docs/workflows/stored-workflows)
-- [`Mastra.addStoredWorkflow()`](https://mastra.ai/reference/core/addStoredWorkflow)
-- [`Mastra.addStoredWorkflows()`](https://mastra.ai/reference/core/addStoredWorkflows)
+- [Use dynamic workflows](https://mastra.ai/docs/workflows/dynamic-workflows)
+- [`Mastra.addDynamicWorkflow()`](https://mastra.ai/reference/core/addDynamicWorkflow)
+- [`Mastra.addDynamicWorkflows()`](https://mastra.ai/reference/core/addDynamicWorkflows)
 - [Client SDK workflows API](https://mastra.ai/reference/client-js/workflows)

package/.docs/reference/workflows/run-methods/timeTravel.md

@@ -150,6 +150,7 @@ const result = await run.timeTravel({
 - When re-executing a workflow, the workflow loads the existing snapshot from storage (if available)
 - Step results before the target step are reconstructed from the snapshot or provided context
 - Execution begins from the specified step with the provided or reconstructed input data
+- If a step that precedes the target in the current workflow definition has no recorded entry in the snapshot (for example, the step was renamed since the run was recorded, or the run never reached it), `timeTravel` rejects with a descriptive error before anything executes and the stored snapshot is left unchanged
 - The workflow continues to completion from that point forward
 - Time travel can be used on workflows that haven't been run yet by providing custom context or input data for the step to start from.
 

package/.docs/reference/workflows/workflow-methods/agent.md

@@ -4,7 +4,7 @@
 
 The `.agent()` method adds an agent as a declarative step. The step accepts `{ prompt: string }` as input and returns `{ text: string }` by default. Use `.map()` before the agent to build the prompt from workflow data.
 
-Unlike wrapping an agent with `createStep()`, `.agent()` records a declarative entry in the workflow graph. This makes the workflow portable: the same graph can be serialized and persisted as a [stored workflow](https://mastra.ai/docs/workflows/stored-workflows).
+Unlike wrapping an agent with `createStep()`, `.agent()` records a declarative entry in the workflow graph. This makes the workflow portable: the same graph can be serialized and persisted as a [dynamic workflow](https://mastra.ai/docs/workflows/dynamic-workflows).
 
 ## Usage example
 
@@ -53,10 +53,10 @@ workflow.agent("test-agent", { maxSteps: 3 }).commit();
 
 ## Persisting agent steps
 
-Workflows built with `.agent()` serialize to the same declarative entries that [stored workflows](https://mastra.ai/docs/workflows/stored-workflows) use. Only `retries` and `metadata` round-trip through storage. Options that hold functions, such as `onFinish` or a function-valued `toolChoice`, throw an error when the workflow is stored.
+Workflows built with `.agent()` serialize to the same declarative entries that [dynamic workflows](https://mastra.ai/docs/workflows/dynamic-workflows) use. Only `retries` and `metadata` round-trip through storage. Options that hold functions, such as `onFinish` or a function-valued `toolChoice`, throw an error when the workflow is stored.
 
 ## Related
 
 - [Agents and Tools](https://mastra.ai/docs/workflows/agents-and-tools)
-- [Stored workflows](https://mastra.ai/docs/workflows/stored-workflows)
+- [Dynamic workflows](https://mastra.ai/docs/workflows/dynamic-workflows)
 - [Workflow.tool()](https://mastra.ai/reference/workflows/workflow-methods/tool)

package/.docs/reference/workflows/workflow-methods/tool.md

@@ -4,7 +4,7 @@
 
 The `.tool()` method adds a tool as a declarative step. The tool's own input and output schemas apply, so the previous step's output must satisfy the tool's input schema. Use `.map()` to transform the data if they don't match.
 
-Unlike wrapping a tool with `createStep()`, `.tool()` records a declarative entry in the workflow graph. This makes the workflow portable: the same graph can be serialized and persisted as a [stored workflow](https://mastra.ai/docs/workflows/stored-workflows).
+Unlike wrapping a tool with `createStep()`, `.tool()` records a declarative entry in the workflow graph. This makes the workflow portable: the same graph can be serialized and persisted as a [dynamic workflow](https://mastra.ai/docs/workflows/dynamic-workflows).
 
 ## Usage example
 
@@ -34,10 +34,10 @@ workflow.tool("lookup-customer", { retries: 2 }).commit();
 
 ## Persisting tool steps
 
-Workflows built with `.tool()` serialize to the same declarative entries that [stored workflows](https://mastra.ai/docs/workflows/stored-workflows) use. Only `retries` and `metadata` round-trip through storage. A function-valued `scorers` option throws an error when the workflow is stored.
+Workflows built with `.tool()` serialize to the same declarative entries that [dynamic workflows](https://mastra.ai/docs/workflows/dynamic-workflows) use. Only `retries` and `metadata` round-trip through storage. A function-valued `scorers` option throws an error when the workflow is stored.
 
 ## Related
 
 - [Agents and Tools](https://mastra.ai/docs/workflows/agents-and-tools)
-- [Stored workflows](https://mastra.ai/docs/workflows/stored-workflows)
+- [Dynamic workflows](https://mastra.ai/docs/workflows/dynamic-workflows)
 - [Workflow.agent()](https://mastra.ai/reference/workflows/workflow-methods/agent)

package/.docs/reference/workflows/workflow.md

@@ -127,6 +127,24 @@ export const testWorkflow = createWorkflow({
 
 **options.pruneSnapshot** (`(params: { snapshot: WorkflowRunState; workflowStatus: WorkflowRunStatus }) => WorkflowRunState`): Optional hook to transform the workflow snapshot immediately before it is persisted. Must return JSON-serializable data and preserve everything the workflow needs to resume (suspended step suspendPayloads, suspendedPaths, executionPath, etc.). Used internally by agent runs to keep snapshots minimal; user workflows persist full snapshots by default.
 
+**options.onStart** (`(info: WorkflowStartCallbackInfo) => void | Promise<void>`): Callback awaited before a run starts executing, and before any step runs. Fires only on initial start, not on resume, restart, or time travel. Unlike onFinish and onError, errors thrown here are propagated: they reject the start() or stream() call and the run never executes, so this can be used as a pre-flight gate such as a quota check. The run record created by createRun() stays at status pending.
+
+**options.onStart.runId** (`string`): The workflow run ID
+
+**options.onStart.workflowId** (`string`): The workflow identifier
+
+**options.onStart.resourceId** (`string`): Resource or user identifier for multi-tenant scenarios
+
+**options.onStart.getInitData** (`() => any`): Returns the initial workflow input data
+
+**options.onStart.state** (`Record<string, any>`): The initial workflow state
+
+**options.onStart.requestContext** (`RequestContext`): The request context for the run
+
+**options.onStart.mastra** (`Mastra`): The Mastra instance, when the workflow is registered
+
+**options.onStart.logger** (`IMastraLogger`): The Mastra logger
+
 **options.onFinish** (`(result: WorkflowFinishCallbackResult) => void | Promise<void>`): Callback invoked when workflow completes with any status (success, failed, suspended, tripwire). Receives the workflow result including status, output, error, and step results. Errors thrown in this callback are caught and logged, not propagated.
 
 **options.onFinish.status** (`WorkflowRunStatus`): The workflow status: 'success', 'failed', 'suspended', or 'tripwire'

package/.docs/reference/workspace/local-sandbox.md

@@ -64,7 +64,7 @@ Configuration options for native OS sandboxing (used with `isolation: 'seatbelt'
 
 **readWritePaths** (`string[]`): Additional paths to allow read-write access beyond the workspace directory.
 
-**seatbeltProfilePath** (`string`): Path to a custom seatbelt profile file (macOS only). If the file exists, it's used; if not, a default profile is generated and written to this path.
+**seatbeltProfilePath** (`string`): Path to a custom seatbelt profile file (macOS only). If you wrote the file, it's used exactly as written: Mastra doesn't add mounted paths to it, so the profile must already allow every path you mount. If the file doesn't exist, a default profile is generated and written to this path, and that generated profile allows mounted paths. Mastra marks the profiles it generates, so a later run regenerates them instead of reading them back as your own. To edit a generated profile and keep your edits, delete its marker comment: the file then counts as yours, and mounted paths are no longer added to it.
 
 **bwrapArgs** (`string[]`): Additional arguments to pass to bwrap (Linux only).
 

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

@@ -4,9 +4,9 @@
 
 Stores files in a Mastra Platform workspace bucket. Each Mastra Platform environment can have one bucket, and `PlatformFilesystem` gives agents `read`, `write`, `list`, `delete`, and `move` operations against it.
 
-Related providers: [`S3Filesystem`](https://mastra.ai/reference/workspace/s3-filesystem) for direct S3 access, [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem) for local directories.
+Related providers: [`S3Filesystem`](https://mastra.ai/integrations/file-storage/amazon-s3) for direct S3 access, [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem) for local directories.
 
-> **Info:** For interface details, see [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem).
+> **Note:** For interface details, see [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem).
 
 ## Installation
 
@@ -181,5 +181,5 @@ try {
 ## Related
 
 - [PlatformSandbox reference](https://mastra.ai/reference/workspace/platform-sandbox)
-- [S3Filesystem reference](https://mastra.ai/reference/workspace/s3-filesystem)
+- [S3Filesystem reference](https://mastra.ai/integrations/file-storage/amazon-s3)
 - [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem)

package/.docs/reference/workspace/platform-sandbox.md

@@ -6,9 +6,9 @@ Client for provisioning sandboxes in a Mastra Platform environment. Each `Platfo
 
 Sandboxes boot from a pre-built recipe checkpoint with Python 3, Node 22, TypeScript, tsx, and common build tooling already installed. Pass a stable `id` to opt into [checkpoint recovery](#checkpoint-recovery) so a new sandbox boots from the previous one's filesystem.
 
-Related providers: [`RailwaySandbox`](https://mastra.ai/reference/workspace/railway-sandbox) for self-hosted Railway sandboxes, [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) for local sandboxes.
+Related providers: [`RailwaySandbox`](https://mastra.ai/integrations/sandboxes/railway) for self-hosted Railway sandboxes, [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) for local sandboxes.
 
-> **Info:** For interface details, see [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox).
+> **Note:** For interface details, see [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox).
 
 ## Installation
 
@@ -136,6 +136,12 @@ await sandbox.start() // Boots from the most recent checkpoint for this id, or f
 
 Checkpoint recovery is coarser than `sandboxId` reattachment. Reattaching (via `sandboxId`) rejoins the exact live sandbox and its running processes. Checkpoint recovery constructs a brand new sandbox and restores its filesystem from the latest checkpoint the platform captured for the previous sandbox with that `id`. Running processes and any filesystem writes made after the last checkpoint aren't restored.
 
+Call `snapshot()` after a filesystem update to capture the configured recovery checkpoint immediately. It resolves without capturing when the sandbox has no caller-provided `id` or isn't running.
+
+```typescript
+await sandbox.snapshot()
+```
+
 Each `id` maps to one independent filesystem. Reusing the same `id` across unrelated sandboxes causes the platform to boot them from each other's checkpoint.
 
 ### Cloning for a fleet of sandboxes
@@ -219,6 +225,8 @@ console.log(result.exitCode)
 
 **clone** (`(options?: SandboxCloneOptions) => PlatformSandbox`): Construct an unstarted sibling PlatformSandbox that inherits credentials and defaults with per-instance overrides (id, sandboxId, env, idleTimeoutMinutes). Performs no I/O. Use to build a fleet of independent sandboxes from one configured template.
 
+**snapshot** (`() => Promise<void>`): Capture the configured recovery checkpoint immediately. Resolves without work when no caller-provided id exists or the sandbox is not running.
+
 **getInfo** (`() => Promise<SandboxInfo>`): Return the sandbox's platform id, provider, status, createdAt, and metadata (sandboxId, providerResourceId, platformStatus).
 
 **getInstructions** (`(opts?: { requestContext?: RequestContext }) => string`): Return the sandbox instructions the workspace surfaces in tool descriptions. Honors the instructions constructor option; otherwise returns platform-default instructions that include the current remote sandbox id when running.
@@ -271,6 +279,6 @@ try {
 ## Related
 
 - [PlatformFilesystem reference](https://mastra.ai/reference/workspace/platform-filesystem)
-- [RailwaySandbox reference](https://mastra.ai/reference/workspace/railway-sandbox)
+- [RailwaySandbox reference](https://mastra.ai/integrations/sandboxes/railway)
 - [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox)
 - [SandboxProcessManager reference](https://mastra.ai/reference/workspace/process-manager)

package/.docs/reference/workspace/process-manager.md

@@ -6,7 +6,7 @@
 
 Abstract base class for managing background processes in sandboxes. Provides methods to spawn processes, list them, get handles by PID, and kill them.
 
-[`BlaxelSandbox`](https://mastra.ai/reference/workspace/blaxel-sandbox), [`DaytonaSandbox`](https://mastra.ai/reference/workspace/daytona-sandbox), [`E2BSandbox`](https://mastra.ai/reference/workspace/e2b-sandbox), [`ModalSandbox`](https://mastra.ai/reference/workspace/modal-sandbox), and [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) all include built-in process managers. You don't need to instantiate this class directly unless you're building a custom sandbox provider.
+[`BlaxelSandbox`](https://mastra.ai/integrations/sandboxes/blaxel), [`DaytonaSandbox`](https://mastra.ai/integrations/sandboxes/daytona), [`E2BSandbox`](https://mastra.ai/integrations/sandboxes/e2b), [`ModalSandbox`](https://mastra.ai/integrations/sandboxes/modal), and [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) all include built-in process managers. You don't need to instantiate this class directly unless you're building a custom sandbox provider.
 
 ## Usage example
 
@@ -294,5 +294,5 @@ When a process manager is provided, `MastraSandbox` automatically creates a defa
 - [Sandbox](https://mastra.ai/docs/workspace/sandbox)
 - [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox)
 - [LocalSandbox reference](https://mastra.ai/reference/workspace/local-sandbox)
-- [E2BSandbox reference](https://mastra.ai/reference/workspace/e2b-sandbox)
-- [DaytonaSandbox reference](https://mastra.ai/reference/workspace/daytona-sandbox)
+- [E2BSandbox reference](https://mastra.ai/integrations/sandboxes/e2b)
+- [DaytonaSandbox reference](https://mastra.ai/integrations/sandboxes/daytona)

package/.docs/reference/workspace/sandbox.md

@@ -38,6 +38,16 @@ Clean up sandbox resources. Called by `workspace.destroy()`.
 await sandbox.destroy()
 ```
 
+### `snapshot()`
+
+Persists the sandbox's current state when the provider supports snapshots. Other providers resolve without doing work.
+
+```typescript
+await sandbox.snapshot()
+```
+
+**Returns:** `Promise<void>`
+
 ### `executeCommand(command, args?, options?)`
 
 Execute a shell command.