@mastra/mcp-docs-server 1.2.15-alpha.19 → 1.2.15-alpha.21

package/.docs/{docs/observability/integrations/exporters/otel.md → integrations/observability/opentelemetry.md}

@@ -1,16 +1,18 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# OpenTelemetry exporter
+# OpenTelemetry
 
-The OpenTelemetry (OTEL) exporter sends your traces and logs to any OTEL-compatible observability platform using standardized [OpenTelemetry Semantic Conventions for GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/). This ensures broad compatibility with platforms like Datadog, New Relic, SigNoz, MLflow, Latitude, Dash0, Traceloop, Laminar, telemetry.dev, and more.
+Mastra supports OpenTelemetry (OTEL) through an exporter for sending traces and logs to OTEL-compatible platforms and a bridge for participating in existing OTEL tracing contexts.
 
-> **Looking for bidirectional OTEL integration?:** If you have existing OpenTelemetry instrumentation and want Mastra traces to inherit context from active OTEL spans, see the [OpenTelemetry Bridge](https://mastra.ai/docs/observability/integrations/bridges/otel) instead.
+## Exporter
 
-## Installation
+The OpenTelemetry exporter sends your traces and logs using standardized [OpenTelemetry Semantic Conventions for GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/). This ensures broad compatibility with platforms like Datadog, New Relic, SigNoz, MLflow, Latitude, Dash0, Traceloop, Laminar, telemetry.dev, and more.
+
+### Installation
 
 Each provider requires specific protocol packages. Install the base exporter plus the protocol package for your provider:
 
-### For HTTP/Protobuf Providers (SigNoz, New Relic, Laminar, MLflow, Latitude, telemetry.dev)
+#### For HTTP/Protobuf Providers (SigNoz, New Relic, Laminar, MLflow, Latitude, telemetry.dev)
 
 **npm**:
 
@@ -36,7 +38,7 @@ yarn add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto
 bun add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto
 ```
 
-### For `gRPC` Providers (Dash0, Datadog)
+#### For `gRPC` Providers (Dash0, Datadog)
 
 **npm**:
 
@@ -62,7 +64,7 @@ yarn add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-grpc @g
 bun add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-grpc @grpc/grpc-js
 ```
 
-### For HTTP/JSON Providers (Traceloop)
+#### For HTTP/JSON Providers (Traceloop)
 
 **npm**:
 
@@ -88,7 +90,7 @@ yarn add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-http
 bun add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-http
 ```
 
-## Environment variables
+### Environment variables
 
 All providers support zero-config setup via environment variables. Set the appropriate variables and the exporter will automatically use them:
 
@@ -100,9 +102,9 @@ All providers support zero-config setup via environment variables. Set the appro
 | Traceloop | `TRACELOOP_API_KEY` (required), `TRACELOOP_DESTINATION_ID`, `TRACELOOP_ENDPOINT` (optional) |
 | Laminar   | `LMNR_PROJECT_API_KEY` (required), `LAMINAR_ENDPOINT` (optional)                            |
 
-## Provider configurations
+### Provider configurations
 
-### MLflow
+#### MLflow
 
 [MLflow](https://mlflow.org/docs/latest/genai/tracing/integrations/listing/mastra) supports native Mastra tracing through its OTLP endpoint at `/v1/traces`. Use the `custom` provider with HTTP/Protobuf and include the experiment header so traces are routed to the correct MLflow experiment:
 
@@ -120,7 +122,7 @@ new OtelExporter({
 })
 ```
 
-### Latitude
+#### Latitude
 
 [Latitude](https://latitude.so) is an open-source LLM observability and evaluation platform that ingests OTLP traces. Use the `custom` provider with HTTP/Protobuf, pointing at Latitude's ingestion endpoint and authenticating with your API key and project slug:
 
@@ -141,7 +143,7 @@ new OtelExporter({
 
 Sign up at [console.latitude.so](https://console.latitude.so/login), or self-host and point the endpoint at your own ingestion host.
 
-### telemetry.dev
+#### telemetry.dev
 
 [telemetry.dev](https://telemetry.dev) ingests OTLP/HTTP protobuf traces and normalizes OpenTelemetry GenAI semantic conventions into model, provider, token, latency, and cost fields. Use the `custom` provider with your project API key:
 
@@ -163,11 +165,11 @@ new OtelExporter({
 })
 ```
 
-### Dash0
+#### Dash0
 
 [Dash0](https://www.dash0.com/) provides real-time observability with automatic insights.
 
-#### Zero-Config Setup
+##### Zero-Config Setup
 
 Set environment variables and use the exporter with an empty config:
 
@@ -197,7 +199,7 @@ export const mastra = new Mastra({
 })
 ```
 
-#### Explicit Configuration
+##### Explicit Configuration
 
 ```typescript
 import { Mastra } from '@mastra/core'
@@ -232,11 +234,11 @@ export const mastra = new Mastra({
 
 > **Note:** Get your Dash0 endpoint from your dashboard. It should be in the format `ingress.{region}.aws.dash0.com:4317`.
 
-### `SigNoz`
+#### `SigNoz`
 
 [SigNoz](https://signoz.io/) is an open-source APM alternative with built-in Tracing support.
 
-#### Zero-Config Setup
+##### Zero-Config Setup
 
 ```bash
 # Required
@@ -251,7 +253,7 @@ SIGNOZ_ENDPOINT=https://my-signoz.example.com  # For self-hosted
 new OtelExporter({ provider: { signoz: {} } })
 ```
 
-#### Explicit Configuration
+##### Explicit Configuration
 
 ```typescript
 new OtelExporter({
@@ -265,11 +267,11 @@ new OtelExporter({
 })
 ```
 
-### New Relic
+#### New Relic
 
 [New Relic](https://newrelic.com/) provides complete observability with AI monitoring capabilities.
 
-#### Zero-Config Setup
+##### Zero-Config Setup
 
 ```bash
 # Required
@@ -283,7 +285,7 @@ NEW_RELIC_ENDPOINT=https://otlp.eu01.nr-data.net  # For EU region
 new OtelExporter({ provider: { newrelic: {} } })
 ```
 
-#### Explicit Configuration
+##### Explicit Configuration
 
 ```typescript
 new OtelExporter({
@@ -296,11 +298,11 @@ new OtelExporter({
 })
 ```
 
-### Traceloop
+#### Traceloop
 
 [Traceloop](https://www.traceloop.com/) specializes in LLM observability with automatic prompt tracking.
 
-#### Zero-Config Setup
+##### Zero-Config Setup
 
 ```bash
 # Required
@@ -315,7 +317,7 @@ TRACELOOP_ENDPOINT=https://custom.traceloop.com
 new OtelExporter({ provider: { traceloop: {} } })
 ```
 
-#### Explicit Configuration
+##### Explicit Configuration
 
 ```typescript
 new OtelExporter({
@@ -328,11 +330,11 @@ new OtelExporter({
 })
 ```
 
-### Laminar
+#### Laminar
 
 [Laminar](https://laminar.sh/) provides specialized LLM observability and analytics.
 
-#### Zero-Config Setup
+##### Zero-Config Setup
 
 ```bash
 # Required
@@ -346,7 +348,7 @@ LAMINAR_ENDPOINT=https://api.lmnr.ai/v1/traces
 new OtelExporter({ provider: { laminar: {} } })
 ```
 
-#### Explicit Configuration
+##### Explicit Configuration
 
 ```typescript
 new OtelExporter({
@@ -358,9 +360,9 @@ new OtelExporter({
 })
 ```
 
-> **Laminar-Native Exporter:** For Laminar-specific features like native span paths, metadata, and tags rendering in the Laminar dashboard, consider using the dedicated [`@mastra/laminar`](https://mastra.ai/docs/observability/integrations/exporters/laminar) exporter instead. It provides optimized integration with Laminar's platform.
+> **Laminar-Native Exporter:** For Laminar-specific features like native span paths, metadata, and tags rendering in the Laminar dashboard, consider using the dedicated [`@mastra/laminar`](https://mastra.ai/integrations/observability/laminar) exporter instead. It provides optimized integration with Laminar's platform.
 
-### Datadog
+#### Datadog
 
 [Datadog](https://www.datadoghq.com/) APM provides application performance monitoring with distributed tracing. To send traces to Datadog via OTLP, you need the Datadog Agent running with OTLP ingestion enabled.
 
@@ -414,9 +416,9 @@ export const mastra = new Mastra({
 
 > **Warning:** The explicit imports of `@grpc/grpc-js` and `@opentelemetry/exporter-trace-otlp-grpc` at the top of the file, along with the [`bundler.externals`](https://mastra.ai/reference/configuration) configuration, are required for the gRPC transport to work correctly. Without these, you may encounter connection issues.
 
-> **Datadog-Native Exporter:** For Datadog-specific features like automatic span type mapping, LLM span categorization, and simplified setup without gRPC configuration, consider using the dedicated [`@mastra/datadog`](https://mastra.ai/docs/observability/integrations/exporters/datadog) exporter instead. It provides optimized integration with Datadog's APM platform.
+> **Datadog-Native Exporter:** For Datadog-specific features like automatic span type mapping, LLM span categorization, and simplified setup without gRPC configuration, consider using the dedicated [`@mastra/datadog`](https://mastra.ai/integrations/observability/datadog) exporter instead. It provides optimized integration with Datadog's APM platform.
 
-### Custom/Generic OTEL Endpoints
+#### Custom/Generic OTEL Endpoints
 
 For other OTEL-compatible platforms or custom collectors:
 
@@ -434,7 +436,7 @@ new OtelExporter({
 })
 ```
 
-## Signals
+### Signals
 
 The exporter sends two OpenTelemetry signals:
 
@@ -503,9 +505,9 @@ bun add @opentelemetry/exporter-logs-otlp-grpc @grpc/grpc-js
 
 If the matching log exporter package isn't installed, log export is silently disabled and traces continue to work.
 
-## Configuration options
+### Configuration options
 
-### Complete Configuration
+#### Complete Configuration
 
 ```typescript
 new OtelExporter({
@@ -529,18 +531,18 @@ new OtelExporter({
 })
 ```
 
-## `OpenTelemetry` semantic conventions
+### `OpenTelemetry` semantic conventions
 
 The exporter follows [OpenTelemetry Semantic Conventions for GenAI v1.38.0](https://github.com/open-telemetry/semantic-conventions/tree/v1.38.0/docs/gen-ai), ensuring compatibility with observability platforms:
 
-### Span Naming
+#### Span Naming
 
 - **LLM Operations**: `chat {model}`
 - **Tool Execution**: `execute_tool {tool_name}`
 - **Agent Runs**: `invoke_agent {agent_id}`
 - **Workflow Runs**: `invoke_workflow {workflow_id}`
 
-### Key Attributes
+#### Key Attributes
 
 - `gen_ai.operation.name` - Operation type (chat, tool.execute, etc.)
 - `gen_ai.provider.name` - AI provider (openai, anthropic, etc.)
@@ -552,7 +554,7 @@ The exporter follows [OpenTelemetry Semantic Conventions for GenAI v1.38.0](http
 - `gen_ai.request.temperature` - Sampling temperature
 - `gen_ai.response.finish_reasons` - Completion reasons
 
-## Protocol selection guide
+### Protocol selection guide
 
 Choose the right protocol package based on your provider:
 
@@ -568,9 +570,9 @@ Choose the right protocol package based on your provider:
 
 > **Warning:** Make sure to install the correct protocol package for your provider. The exporter will provide a helpful error message if the wrong package is installed.
 
-## Troubleshooting
+### Troubleshooting
 
-### Missing Dependency Error
+#### Missing Dependency Error
 
 If you see an error like:
 
@@ -582,15 +584,245 @@ To use HTTP/Protobuf export, install the required package:
 
 Install the suggested package for your provider.
 
-### Common Issues
+#### Common Issues
 
 1. **Wrong protocol package**: Verify you installed the correct exporter for your provider
 2. **Invalid endpoint**: Check endpoint format matches provider requirements
 3. **Authentication failures**: Verify API keys and headers are correct
 
-## Related
+### Related
 
 - [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview)
-- [OpenTelemetry Bridge](https://mastra.ai/docs/observability/integrations/bridges/otel)
+- [OpenTelemetry Bridge](#bridge)
 - [OpenTelemetry Semantic Conventions for GenAI v1.38.0](https://github.com/open-telemetry/semantic-conventions/tree/v1.38.0/docs/gen-ai)
-- [OTEL Exporter Reference](https://mastra.ai/reference/observability/tracing/exporters/otel)
+- [OTEL Exporter Reference](https://mastra.ai/reference/observability/tracing/exporters/otel)
+
+## Bridge
+
+> **Warning:** The OpenTelemetry Bridge is currently **experimental**. APIs and configuration options may change in future releases.
+
+The OpenTelemetry (OTEL) Bridge enables bidirectional integration between Mastra's tracing system and existing OpenTelemetry infrastructure. Unlike exporters that send trace data to external platforms, the bridge creates native OTEL spans that participate in your distributed tracing context.
+
+### When to use the bridge
+
+Use the `OtelBridge` when you:
+
+- Have existing OTEL instrumentation in your application (HTTP servers, database clients, etc.)
+- Want Mastra operations to appear as child spans of your existing OTEL traces
+- Need OTEL-instrumented code inside Mastra tools to maintain proper parent-child relationships
+- Are building a distributed system where trace context must propagate across services
+
+### How it works
+
+The `OtelBridge` provides two-way integration:
+
+**From OTEL to Mastra:**
+
+- Reads from OTEL ambient context (AsyncLocalStorage) automatically
+- Inherits trace ID and parent span ID from active OTEL spans
+- Respects OTEL sampling decisions: if a trace isn't sampled, Mastra won't create spans for it
+- No manual trace ID passing required when OTEL auto-instrumentation is active
+
+**From Mastra to OTEL:**
+
+- Creates native OTEL spans for Mastra operations (agents, LLM calls, tools, workflows)
+- Maintains proper parent-child relationships in distributed traces
+- Allows OTEL-instrumented code (HTTP clients, database calls) within Mastra operations to nest correctly
+- Forwards Mastra log events to the globally registered OTEL `LoggerProvider`. Logs that originate inside a Mastra span are emitted under that span's OTEL context so backends correlate them with the trace. If no `LoggerProvider` is registered, log emission is a silent no-op.
+
+### Installation
+
+**npm**:
+
+```bash
+npm install @mastra/otel-bridge
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/otel-bridge
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/otel-bridge
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/otel-bridge
+```
+
+The bridge works with your existing OpenTelemetry setup. Depending on your configuration, you may also need some of these packages:
+
+- `@opentelemetry/sdk-node` - Core Node.js SDK for OTEL
+- `@opentelemetry/auto-instrumentations-node` - Auto-instrumentation for common libraries
+- `@opentelemetry/exporter-trace-otlp-proto` - OTLP exporter (Protobuf over HTTP)
+- `@opentelemetry/exporter-trace-otlp-http` - OTLP exporter (JSON over HTTP)
+- `@opentelemetry/exporter-trace-otlp-grpc` - OTLP exporter (gRPC)
+- `@opentelemetry/sdk-trace-base` - Base tracing SDK (for `BatchSpanProcessor`, etc.)
+- `@opentelemetry/core` - Core utilities (for `W3CTraceContextPropagator`, etc.)
+- `@opentelemetry/sdk-logs` and an OTLP log exporter (e.g. `@opentelemetry/exporter-logs-otlp-http`) - Required if you want the bridge to forward Mastra log events too
+
+### Configuration
+
+Using the `OtelBridge` requires two steps:
+
+1. Configure OpenTelemetry instrumentation in your application
+2. Add the `OtelBridge` to your Mastra observability config
+
+#### Step 1: OpenTelemetry Instrumentation
+
+Create an instrumentation file that initializes OTEL. This must run before your application code:
+
+```typescript
+import { NodeSDK } from '@opentelemetry/sdk-node'
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto'
+import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base'
+import { W3CTraceContextPropagator } from '@opentelemetry/core'
+
+const sdk = new NodeSDK({
+  serviceName: 'my-service',
+  spanProcessors: [
+    new BatchSpanProcessor(
+      new OTLPTraceExporter({
+        url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4318/v1/traces',
+      }),
+    ),
+  ],
+  instrumentations: [getNodeAutoInstrumentations()],
+  textMapPropagator: new W3CTraceContextPropagator(),
+})
+
+sdk.start()
+
+export { sdk }
+```
+
+#### Step 2: Mastra Configuration
+
+Add the `OtelBridge` to your Mastra observability config:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { Observability } from '@mastra/observability'
+import { OtelBridge } from '@mastra/otel-bridge'
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      default: {
+        serviceName: 'my-service',
+        bridge: new OtelBridge(),
+      },
+    },
+  }),
+  agents: {/* your agents */},
+})
+```
+
+No Mastra exporters are required when using the bridge. Traces are sent via your OTEL SDK configuration. You can optionally add Mastra exporters if you want to send traces to additional destinations.
+
+#### Forwarding logs (optional)
+
+The bridge also forwards Mastra log events to the globally registered OTEL `LoggerProvider`. To wire up logs alongside traces, register a `logRecordProcessor` on `NodeSDK`:
+
+```typescript
+import { NodeSDK } from '@opentelemetry/sdk-node'
+import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http'
+import { BatchLogRecordProcessor } from '@opentelemetry/sdk-logs'
+
+const sdk = new NodeSDK({
+  // ...trace config as usual
+  logRecordProcessor: new BatchLogRecordProcessor(
+    new OTLPLogExporter({
+      url: process.env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT || 'http://localhost:4318/v1/logs',
+    }),
+  ),
+})
+```
+
+Logs that originate inside a Mastra span are emitted under that span's OTEL context, so backends like Datadog, Grafana, and Honeycomb correlate them with the surrounding trace automatically. Logs without trace context use the currently active OTEL context.
+
+If you don't register a `LoggerProvider`, log emission is a silent no-op. Traces continue to work as configured.
+
+#### Running Your Application
+
+Use the `--import` flag to ensure instrumentation loads before your application:
+
+```bash
+tsx --import ./instrumentation.ts ./src/index.ts
+```
+
+### Semantic conventions
+
+The `OtelBridge` exports Mastra spans using [OpenTelemetry Semantic Conventions for GenAI v1.38.0](https://github.com/open-telemetry/semantic-conventions/tree/v1.38.0/docs/gen-ai). This includes standardized span names (`chat {model}`, `execute_tool {tool_name}`, etc.) and attributes (`gen_ai.usage.input_tokens`, `gen_ai.request.model`, etc.).
+
+For details on span naming and attributes, see the [OpenTelemetry Exporter semantic conventions](#opentelemetry-semantic-conventions).
+
+### Trace hierarchy
+
+With the `OtelBridge`, your traces maintain proper hierarchy across OTEL and Mastra boundaries:
+
+```text
+HTTP POST /api/chat (from Hono middleware)
+└── agent.assistant (from Mastra via OtelBridge)
+    ├── chat gpt-5.4 (LLM call)
+    ├── tool.execute search (tool execution)
+    │   └── HTTP GET api.example.com (from OTEL auto-instrumentation)
+    └── chat gpt-5.4 (follow-up LLM call)
+```
+
+### Multi-service distributed tracing
+
+The `OtelBridge` enables trace propagation across service boundaries. When Service A calls Service B via HTTP, trace context propagates automatically:
+
+```text
+Service A: HTTP POST /api/process
+└── HTTP POST service-b/api/analyze (outgoing call)
+
+Service B: HTTP POST /api/analyze (incoming call - same trace!)
+└── agent.analyzer (Mastra agent inherits trace context)
+    └── chat gpt-5.4
+```
+
+Both services must have:
+
+1. OTEL instrumentation configured
+2. W3C Trace Context propagator enabled
+3. Mastra with `OtelBridge` configured
+
+### Using tags
+
+Tags help you categorize and filter traces in your OTEL backend. Add tags when executing agents or workflows:
+
+```typescript
+const result = await agent.generate('Hello', {
+  tracingOptions: {
+    tags: ['production', 'experiment-v2', 'user-request'],
+  },
+})
+```
+
+Tags are exported as a JSON string in the `mastra.tags` span attribute for broad backend compatibility. Common use cases include:
+
+- Environment labels: `"production"`, `"staging"`
+- Experiment tracking: `"experiment-v1"`, `"control-group"`
+- Priority levels: `"priority-high"`, `"batch-job"`
+
+### Troubleshooting
+
+If traces aren't displaying or connecting as expected:
+
+- Verify OTEL SDK is initialized before Mastra (use the `--import` flag or import at the top of the entry point)
+- Ensure the `OtelBridge` is added to your observability config
+- Check that your OTEL backend is running and accessible
+
+### Related
+
+- [Tracing overview](https://mastra.ai/docs/observability/tracing/overview)
+- [OtelBridge reference](https://mastra.ai/reference/observability/tracing/bridges/otel)

package/.docs/{docs/observability/integrations/exporters → integrations/observability}/posthog.md

@@ -1,6 +1,6 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# PostHog exporter
+# PostHog
 
 [PostHog](https://posthog.com/) is an analytics platform with AI observability features for monitoring LLM applications. The PostHog exporter sends your traces to PostHog as structured events, providing insights into token usage, costs, latency, and conversation flows.
 

package/.docs/{docs/observability/integrations/exporters → integrations/observability}/sentry.md

@@ -1,6 +1,6 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# Sentry exporter
+# Sentry
 
 [Sentry](https://sentry.io/) is an application monitoring platform with AI-specific tracing capabilities. The Sentry exporter sends your traces to Sentry using OpenTelemetry semantic conventions, providing insights into model performance and token usage, plus tool executions.
 

package/.docs/{reference/workspace/apple-container-sandbox.md → integrations/sandboxes/apple-container.md}

@@ -252,6 +252,6 @@ const editor = new MastraEditor({
 ## Related
 
 - [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox)
-- [DockerSandbox reference](https://mastra.ai/reference/workspace/docker-sandbox)
+- [DockerSandbox reference](https://mastra.ai/integrations/sandboxes/docker)
 - [LocalSandbox reference](https://mastra.ai/reference/workspace/local-sandbox)
 - [Workspace overview](https://mastra.ai/docs/workspace/overview)

package/.docs/{reference/workspace/daytona-sandbox.md → integrations/sandboxes/daytona.md}

@@ -501,6 +501,6 @@ Resources are only applied when `image` is set. Passing `resources` without `ima
 - [SandboxProcessManager reference](https://mastra.ai/reference/workspace/process-manager)
 - [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox)
 - [LocalSandbox reference](https://mastra.ai/reference/workspace/local-sandbox)
-- [S3Filesystem reference](https://mastra.ai/reference/workspace/s3-filesystem)
-- [GCSFilesystem reference](https://mastra.ai/reference/workspace/gcs-filesystem)
+- [S3Filesystem reference](https://mastra.ai/integrations/file-storage/amazon-s3)
+- [GCSFilesystem reference](https://mastra.ai/integrations/file-storage/google-cloud-storage)
 - [Workspace overview](https://mastra.ai/docs/workspace/overview)

package/.docs/{reference/workspace/docker-sandbox.md → integrations/sandboxes/docker.md}

@@ -255,5 +255,5 @@ const sandbox = new DockerSandbox({
 - [SandboxProcessManager reference](https://mastra.ai/reference/workspace/process-manager)
 - [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)
+- [E2BSandbox reference](https://mastra.ai/integrations/sandboxes/e2b)
 - [Workspace overview](https://mastra.ai/docs/workspace/overview)

package/.docs/{reference/workspace/e2b-sandbox.md → integrations/sandboxes/e2b.md}

@@ -271,7 +271,7 @@ const { tool, instructions } = createCodeMode(
 - [SandboxProcessManager reference](https://mastra.ai/reference/workspace/process-manager)
 - [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox)
 - [LocalSandbox reference](https://mastra.ai/reference/workspace/local-sandbox)
-- [S3Filesystem reference](https://mastra.ai/reference/workspace/s3-filesystem)
-- [GCSFilesystem reference](https://mastra.ai/reference/workspace/gcs-filesystem)
-- [Azure Blob Filesystem reference](https://mastra.ai/reference/workspace/azure-blob-filesystem)
+- [S3Filesystem reference](https://mastra.ai/integrations/file-storage/amazon-s3)
+- [GCSFilesystem reference](https://mastra.ai/integrations/file-storage/google-cloud-storage)
+- [Azure Blob Filesystem reference](https://mastra.ai/integrations/file-storage/azure-blob)
 - [Workspace overview](https://mastra.ai/docs/workspace/overview)

package/.docs/{reference/workspace/modal-sandbox.md → integrations/sandboxes/modal.md}

@@ -163,6 +163,6 @@ See [`SandboxProcessManager` reference](https://mastra.ai/reference/workspace/pr
 
 - [SandboxProcessManager reference](https://mastra.ai/reference/workspace/process-manager)
 - [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/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)
 - [Workspace overview](https://mastra.ai/docs/workspace/overview)

package/.docs/{reference/workspace/railway-sandbox.md → integrations/sandboxes/railway.md}

@@ -141,6 +141,12 @@ const sandbox = new RailwaySandbox({
 
 `RailwaySandbox` refreshes the checkpoint shortly before the idle timeout. Recovery restores the latest successful checkpoint. It doesn't restore running processes or filesystem writes made after the last checkpoint.
 
+Call `snapshot()` after a filesystem update to capture the configured checkpoint immediately. It resolves without capturing when `checkpointName` isn't configured or the sandbox isn't running.
+
+```typescript
+await sandbox.snapshot()
+```
+
 Use one stable checkpoint name for each independent filesystem. Don't share a checkpoint name across unrelated sessions or projects.
 
 ### Cloned sandbox checkpoints
@@ -228,6 +234,8 @@ const result = await sandbox.executeCommand('cat', ['/tmp/state.txt'])
 
 **clone** (`(options?) => RailwaySandbox`): Construct an unstarted sibling sandbox that inherits credentials and defaults. Accepts optional id, sandboxId, env, idleTimeoutMinutes, and checkpointName overrides. The cloned sandbox uses options.checkpointName when set, otherwise it inherits the template checkpointName.
 
+**snapshot** (`() => Promise<void>`): Capture the configured recovery checkpoint immediately. Resolves without work when checkpointName is not configured or the sandbox is not running.
+
 ## Background processes
 
 `RailwaySandbox` includes a built-in process manager for spawning and managing background processes. Each spawned process runs as a Railway `exec` session.