@mastra/mcp-docs-server 1.2.8-alpha.19 → 1.2.8-alpha.23

package/.docs/models/providers/llmgateway.md

@@ -2,7 +2,7 @@
 
 # ![LLM Gateway logo](https://models.dev/logos/llmgateway.svg)LLM Gateway
 
-Access 171 LLM Gateway models through Mastra's model router. Authentication is handled automatically using the `LLMGATEWAY_API_KEY` environment variable.
+Access 173 LLM Gateway models through Mastra's model router. Authentication is handled automatically using the `LLMGATEWAY_API_KEY` environment variable.
 
 Learn more in the [LLM Gateway documentation](https://llmgateway.io/docs).
 
@@ -64,6 +64,8 @@ for await (const chunk of stream) {
 | `llmgateway/gemini-3.1-flash-lite`             | 1.0M    |       |           |       |       |       | $0.25      | $2          |
 | `llmgateway/gemini-3.1-pro-preview`            | 1.0M    |       |           |       |       |       | $2         | $12         |
 | `llmgateway/gemini-3.5-flash`                  | 1.0M    |       |           |       |       |       | $2         | $9          |
+| `llmgateway/gemini-3.5-flash-lite`             | 1.0M    |       |           |       |       |       | $0.30      | $3          |
+| `llmgateway/gemini-3.6-flash`                  | 1.0M    |       |           |       |       |       | $2         | $8          |
 | `llmgateway/gemini-pro-latest`                 | 1.0M    |       |           |       |       |       | $2         | $12         |
 | `llmgateway/gemma-4-26b-a4b-it`                | 262K    |       |           |       |       |       | $0.07      | $0.34       |
 | `llmgateway/gemma-4-31b-it`                    | 262K    |       |           |       |       |       | $0.13      | $0.38       |

package/.docs/models/providers/opencode.md

@@ -2,7 +2,7 @@
 
 # ![OpenCode Zen logo](https://models.dev/logos/opencode.svg)OpenCode Zen
 
-Access 55 OpenCode Zen models through Mastra's model router. Authentication is handled automatically using the `OPENCODE_API_KEY` environment variable.
+Access 57 OpenCode Zen models through Mastra's model router. Authentication is handled automatically using the `OPENCODE_API_KEY` environment variable.
 
 Learn more in the [OpenCode Zen documentation](https://opencode.ai/docs/zen).
 
@@ -54,6 +54,8 @@ for await (const chunk of stream) {
 | `opencode/gemini-3-flash`         | 1.0M    |       |           |       |       |       | $0.50      | $3          |
 | `opencode/gemini-3.1-pro`         | 1.0M    |       |           |       |       |       | $2         | $12         |
 | `opencode/gemini-3.5-flash`       | 1.0M    |       |           |       |       |       | $2         | $9          |
+| `opencode/gemini-3.5-flash-lite`  | 1.0M    |       |           |       |       |       | $0.30      | $3          |
+| `opencode/gemini-3.6-flash`       | 1.0M    |       |           |       |       |       | $2         | $8          |
 | `opencode/glm-5`                  | 205K    |       |           |       |       |       | $1         | $3          |
 | `opencode/glm-5.1`                | 205K    |       |           |       |       |       | $1         | $4          |
 | `opencode/glm-5.2`                | 1.0M    |       |           |       |       |       | $1         | $4          |
@@ -79,10 +81,10 @@ for await (const chunk of stream) {
 | `opencode/gpt-5.6-terra`          | 1.1M    |       |           |       |       |       | $3         | $15         |
 | `opencode/grok-4.5`               | 500K    |       |           |       |       |       | $2         | $6          |
 | `opencode/grok-build-0.1`         | 256K    |       |           |       |       |       | $1         | $2          |
-| `opencode/hy3-free`               | 190K    |       |           |       |       |       | —          | —           |
 | `opencode/kimi-k2.5`              | 262K    |       |           |       |       |       | $0.60      | $3          |
 | `opencode/kimi-k2.6`              | 262K    |       |           |       |       |       | $0.95      | $4          |
 | `opencode/kimi-k2.7-code`         | 262K    |       |           |       |       |       | $0.95      | $4          |
+| `opencode/laguna-s-2.1-free`      | 256K    |       |           |       |       |       | —          | —           |
 | `opencode/mimo-v2.5-free`         | 200K    |       |           |       |       |       | —          | —           |
 | `opencode/minimax-m2.5`           | 205K    |       |           |       |       |       | $0.30      | $1          |
 | `opencode/minimax-m2.7`           | 205K    |       |           |       |       |       | $0.30      | $1          |

package/.docs/models/providers/wandb.md

@@ -2,7 +2,7 @@
 
 # ![Weights & Biases logo](https://models.dev/logos/wandb.svg)Weights & Biases
 
-Access 25 Weights & Biases models through Mastra's model router. Authentication is handled automatically using the `WANDB_API_KEY` environment variable.
+Access 26 Weights & Biases models through Mastra's model router. Authentication is handled automatically using the `WANDB_API_KEY` environment variable.
 
 Learn more in the [Weights & Biases documentation](https://docs.wandb.ai).
 
@@ -46,6 +46,7 @@ for await (const chunk of stream) {
 | `wandb/meta-llama/Llama-3.1-8B-Instruct`             | 128K    |       |           |       |       |       | $0.22      | $0.22       |
 | `wandb/meta-llama/Llama-3.3-70B-Instruct`            | 128K    |       |           |       |       |       | $0.71      | $0.71       |
 | `wandb/MiniMaxAI/MiniMax-M2.5`                       | 197K    |       |           |       |       |       | $0.30      | $1          |
+| `wandb/MiniMaxAI/MiniMax-M3`                         | 262K    |       |           |       |       |       | $0.29      | $1          |
 | `wandb/moonshotai/Kimi-K2.5`                         | 262K    |       |           |       |       |       | $0.60      | $3          |
 | `wandb/moonshotai/Kimi-K2.6`                         | 262K    |       |           |       |       |       | $0.95      | $4          |
 | `wandb/moonshotai/Kimi-K2.7-Code`                    | 262K    |       |           |       |       |       | $0.94      | $4          |

package/.docs/models/providers.md

@@ -15,6 +15,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [Abacus](https://mastra.ai/models/providers/abacus)
 - [abliteration.ai](https://mastra.ai/models/providers/abliteration-ai)
 - [AI-ROUTER](https://mastra.ai/models/providers/ai-router)
+- [AKI.IO](https://mastra.ai/models/providers/aki-io)
 - [Alibaba](https://mastra.ai/models/providers/alibaba)
 - [Alibaba (China)](https://mastra.ai/models/providers/alibaba-cn)
 - [Alibaba Coding Plan](https://mastra.ai/models/providers/alibaba-coding-plan)
@@ -33,6 +34,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [Chutes](https://mastra.ai/models/providers/chutes)
 - [Clarifai](https://mastra.ai/models/providers/clarifai)
 - [Claudinio](https://mastra.ai/models/providers/claudinio)
+- [ClinePass](https://mastra.ai/models/providers/cline-pass)
 - [CloudFerro Sherlock](https://mastra.ai/models/providers/cloudferro-sherlock)
 - [Cloudflare Workers AI](https://mastra.ai/models/providers/cloudflare-workers-ai)
 - [Cortecs](https://mastra.ai/models/providers/cortecs)

package/.docs/reference/cli/create-mastra.md

@@ -2,9 +2,7 @@
 
 # create-mastra
 
-The `create-mastra` command **creates** a new standalone Mastra project. Use this command to scaffold a complete Mastra setup in a dedicated directory. You can run it with additional flags to customize the setup process.
-
-## Usage
+Create a standalone Mastra project. By default, `create-mastra` installs a default starter and configures it for your selected model provider.
 
 **npm**:
 
@@ -30,116 +28,193 @@ yarn dlx create-mastra@latest
 bun x create-mastra@latest
 ```
 
-`create-mastra` automatically runs in _interactive_ mode, but you can also specify your project name and template with command line arguments.
+## Creation modes
+
+### Default starter
+
+The default starter creates an agent harness with workspace tools, memory, task tracking, web access, recurring schedules, storage, and observability. Select OpenAI, Anthropic, Gemini, or xAI as your model provider.
+
+Provide both the project name and provider to create the project without prompts. This example uses Anthropic; you can also pass `openai`, `google`, or `xai`:
 
 **npm**:
 
 ```bash
-npx create-mastra@latest my-mastra-project -- --template coding-agent
+npx create-mastra@latest my-mastra-project --llm anthropic
 ```
 
 **pnpm**:
 
 ```bash
-pnpm dlx create-mastra@latest my-mastra-project -- --template coding-agent
+pnpm dlx create-mastra@latest my-mastra-project --llm anthropic
 ```
 
 **Yarn**:
 
 ```bash
-yarn dlx create-mastra@latest my-mastra-project -- --template coding-agent
+yarn dlx create-mastra@latest my-mastra-project --llm anthropic
 ```
 
 **Bun**:
 
 ```bash
-bun x create-mastra@latest my-mastra-project -- --template coding-agent
+bun x create-mastra@latest my-mastra-project --llm anthropic
+```
+
+Omit `--llm` to select the provider and optionally enter its API key interactively. The interactive setup also offers to connect your project to the Mastra platform. If enabled, the command opens the browser authentication flow, creates a platform project with the same name as the local project, and writes `MASTRA_PLATFORM_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` to `.env`.
+
+### Template
+
+Use a template slug or a public GitHub URL:
+
+**npm**:
+
+```bash
+npx create-mastra@latest my-mastra-project --template agent-harness
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx create-mastra@latest my-mastra-project --template agent-harness
+```
+
+**Yarn**:
+
+```bash
+yarn dlx create-mastra@latest my-mastra-project --template agent-harness
+```
+
+**Bun**:
+
+```bash
+bun x create-mastra@latest my-mastra-project --template agent-harness
+```
+
+**npm**:
+
+```bash
+npx create-mastra@latest my-mastra-project --template https://github.com/mastra-ai/template-agent-harness
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx create-mastra@latest my-mastra-project --template https://github.com/mastra-ai/template-agent-harness
 ```
 
-Check out the [full list](https://mastra.ai/api/templates.json) of templates and use the `slug` as input to the `--template` CLI flag.
+**Yarn**:
 
-You can also use any GitHub repo as a template (it has to be a valid Mastra project):
+```bash
+yarn dlx create-mastra@latest my-mastra-project --template https://github.com/mastra-ai/template-agent-harness
+```
+
+**Bun**:
 
 ```bash
-npx create-mastra@latest my-mastra-project -- --template mastra-ai/template-coding-agent
+bun x create-mastra@latest my-mastra-project --template https://github.com/mastra-ai/template-agent-harness
 ```
 
-You can install Mastra skills for specific agents during project creation:
+Leave the template value blank to select a template interactively:
 
 **npm**:
 
 ```bash
-npx create-mastra@latest my-project -- --default --skills claude-code,cursor
+npx create-mastra@latest my-mastra-project --template
 ```
 
 **pnpm**:
 
 ```bash
-pnpm dlx create-mastra@latest my-project -- --default --skills claude-code,cursor
+pnpm dlx create-mastra@latest my-mastra-project --template
 ```
 
 **Yarn**:
 
 ```bash
-yarn dlx create-mastra@latest my-project -- --default --skills claude-code,cursor
+yarn dlx create-mastra@latest my-mastra-project --template
 ```
 
 **Bun**:
 
 ```bash
-bun x create-mastra@latest my-project -- --default --skills claude-code,cursor
+bun x create-mastra@latest my-mastra-project --template
 ```
 
-## CLI flags
+Template authors own their dependencies, models, environment variables, and source code. `create-mastra` doesn't apply `--llm` or `--llm-api-key`.
 
-Instead of an interactive prompt you can also define these CLI flags.
+### Empty scaffold
 
-**--version** (`boolean`): Output the version number
+Use `--empty` to create a provider-free project without agents, examples, model SDKs, or environment files:
 
-**--project-name** (`string`): Project name that will be used in package.json and as the project directory name
+**npm**:
 
-**--default** (`boolean`): Quickstart with defaults (src, OpenAI, no examples)
+```bash
+npx create-mastra@latest my-empty-project --empty
+```
 
-**--components** (`string`): Comma-separated list of components (agents, tools, workflows, scorers)
+**pnpm**:
 
-**--llm** (`string`): Default model provider (openai, anthropic, groq, google, or cerebras)
+```bash
+pnpm dlx create-mastra@latest my-empty-project --empty
+```
 
-**--llm-api-key** (`string`): API key for the model provider
+**Yarn**:
 
-**--example** (`boolean`): Include example code
+```bash
+yarn dlx create-mastra@latest my-empty-project --empty
+```
+
+**Bun**:
 
-**--no-example** (`boolean`): Do not include example code
+```bash
+bun x create-mastra@latest my-empty-project --empty
+```
 
-**--template** (`string`): Create project from a template (use template name, public GitHub URL, or leave blank to select from list)
+## Automatic setup
 
-**--timeout** (`number`): Configurable timeout for package installation, defaults to 60000 ms
+After installing dependencies, the command:
 
-**--dir** (`string`): Target directory for Mastra source code (default: src/)
+1. Detects supported coding assistants on `PATH` and installs Mastra skills. If none are detected, it installs universal skills.
+2. Creates an initial Git commit when the current directory and generated project aren't already inside Git repositories.
 
-**--mcp** (`string`): MCP Server for code editor (cursor, cursor-global, windsurf, vscode)
+Use `--no-skills` or `--no-git` to skip these steps. Skills and Git setup failures produce warnings but don't remove a successfully created project.
 
-**--skills** (`string`): Comma-separated list of agents to install Mastra skills for (e.g., claude-code,cursor,windsurf)
+## Conflicts and validation
 
-**--observability** (`boolean`): Enable Observability on the Mastra platform during project creation. This opens browser login when needed, prompts for an organization, provisions a platform project, and configures the observability exporters.
+- `--empty` and `--template` can't be used together.
+- `--llm` and `--llm-api-key` are only valid for the default starter project.
+- The project name must be a safe, lowercase, single directory name and the target must not already exist.
 
-**--no-observability** (`boolean`): Skip the Observability prompt during project creation.
+Invalid input is rejected before templates are fetched or files are created.
 
-**--observability-project** (`string`): Set the platform project name to use when Mastra Observability is enabled.
+## Arguments and flags
 
-**--help** (`boolean`): Display help for command
+**\[project-name]** (`string`): Project directory and package name. When omitted, the command prompts for it.
 
-## Telemetry
+**--empty** (`boolean`): Create a minimal, provider-free Mastra project.
 
-By default, Mastra collects anonymous information about your project like your OS, Mastra version or Node.js version. You can read the [source code](https://github.com/mastra-ai/mastra/blob/main/packages/cli/src/analytics/index.ts) to check what's collected.
+**-l, --llm \<provider>** (`string`): Managed agent-harness provider: openai, anthropic, google, or xai.
 
-You can opt out of the CLI analytics by setting an environment variable:
+**-k, --llm-api-key \<key>** (`string`): Write the selected provider API key to the generated .env file.
 
-```bash
-MASTRA_TELEMETRY_DISABLED=1
-```
+**--no-skills** (`boolean`): Skip automatic Mastra skills installation.
+
+**--no-git** (`boolean`): Skip automatic Git initialization and the initial commit.
+
+**-t, --template \[template]** (`string`): Use a template slug or public GitHub URL. Omit the value to select interactively.
+
+**--timeout \<milliseconds>** (`number`): Positive integer timeout for dependency installation. Defaults to 60000.
+
+**--version** (`boolean`): Print the create-mastra version.
+
+**--help** (`boolean`): Display command help.
+
+## Telemetry
+
+Mastra collects anonymous CLI usage information, such as the operating system, Mastra version, and Node.js version. You can review the [analytics source](https://github.com/mastra-ai/mastra/blob/main/packages/cli/src/analytics/index.ts).
 
-You can also set this while using other `mastra` commands:
+Set `MASTRA_TELEMETRY_DISABLED=1` to opt out:
 
 ```bash
-MASTRA_TELEMETRY_DISABLED=1 npx create-mastra@latest
+MASTRA_TELEMETRY_DISABLED=1 npx create-mastra@latest my-project --empty
 ```

package/.docs/reference/cli/mastra.md

@@ -804,6 +804,40 @@ Use the [`list`](#list) command to get the correct ID.
 
 List all available scorer templates. Use the ID for the `add` command.
 
+## `mastra create`
+
+Create a standalone Mastra project with the same project-creation flow as [`create-mastra`](https://mastra.ai/reference/cli/create-mastra).
+
+**npm**:
+
+```bash
+npx mastra@latest create
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx mastra@latest create
+```
+
+**Yarn**:
+
+```bash
+yarn dlx mastra@latest create
+```
+
+**Bun**:
+
+```bash
+bun x mastra@latest create
+```
+
+Providing both the project name and `--llm` skips the interactive setup prompts. Use `--template [template]` for an arbitrary template or `--empty` for a minimal provider-free scaffold.
+
+The command installs Mastra skills for detected coding assistants and initializes Git when appropriate. Use `--no-skills` or `--no-git` to opt out.
+
+See the [`create-mastra` reference](https://mastra.ai/reference/cli/create-mastra) for mode behavior, conflicts, validation, and complete flag descriptions.
+
 ## `mastra init`
 
 The `mastra init` command initializes Mastra in an existing project. Use this command to scaffold the necessary folders and configuration without generating a new project from scratch.

package/.docs/reference/code-sdk/mount-agent-controller.md

@@ -4,7 +4,7 @@
 
 > **Beta:** The `@mastra/code-sdk` package is experimental and subject to breaking changes in minor versions.
 
-The `mountAgentControllerOnMastra()` function builds the Mastra Code agent controller — the coding agent behind the [`mastracode`](https://www.npmjs.com/package/mastracode) CLI, with its modes, tools, memory, and thread management — and registers it on a server-owned [Mastra](https://mastra.ai/reference/core/mastra-class) instance. Use it to serve the Mastra Code agent to your own UI (web app, editor, bot): each client creates or resumes its own isolated session through the returned [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class).
+The `mountAgentControllerOnMastra()` function builds the Mastra Code agent controller (the coding agent behind the [`mastracode`](https://www.npmjs.com/package/mastracode) CLI, with its modes, tools, memory, and thread management) and registers it on a server-owned [Mastra](https://mastra.ai/reference/core/mastra-class) instance. Use it to serve the Mastra Code agent to your own UI (web app, editor, bot): each client creates or resumes its own isolated session through the returned [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class).
 
 To construct the `Mastra` instance yourself (for example in a deployable entry file), use `prepareAgentControllerMount()` from the same package, which returns the constructor args plus a `finalize()` callback.
 
@@ -48,6 +48,8 @@ const { controller } = await mountAgentControllerOnMastra({ mastra })
 
 **postToolObserver** (`(context: ToolAfterHookContext) => void | Promise<void>`): Observes completed tool calls without replacing the tool or changing hook-manager behavior. Observer errors are logged and do not fail successful tool calls.
 
+**inputProcessors** (`InputProcessor[]`): Stateless input processors prepended before Mastra Code's mandatory safety and compatibility processors. Custom processors extend the pipeline but can't replace the built-in processors.
+
 **disabledTools** (`string[]`): Tools removed from the dynamic tool set before exposure to the model.
 
 **storage** (`StorageConfig`): Custom storage config instead of the auto-detected default.

package/.docs/reference/observability/tracing/exporters/posthog.md

@@ -39,6 +39,14 @@ async exportTracingEvent(event: TracingEvent): Promise<void>
 
 Exports a tracing event to PostHog.
 
+### `onFeedbackEvent`
+
+```typescript
+async onFeedbackEvent(event: FeedbackEvent): Promise<void>
+```
+
+Exports a feedback event to PostHog. See [Feedback export](#feedback-export).
+
 ### flush
 
 ```typescript
@@ -92,4 +100,34 @@ const exporter = new PosthogExporter({
 | `AGENT_RUN`          | `$ai_span`         |
 | `WORKFLOW_RUN`       | `$ai_span`         |
 | All other workflows  | `$ai_span`         |
-| `GENERIC`            | `$ai_span`         |
+| `GENERIC`            | `$ai_span`         |
+
+## Feedback export
+
+Feedback recorded with [`addFeedback()`](https://mastra.ai/docs/observability/feedback) is exported to PostHog as a native `$ai_feedback` event. PostHog shows it as **User feedback** on the linked trace. No extra configuration is needed.
+
+```typescript
+const trace = await mastra.observability.getRecordedTrace({ traceId })
+await trace.addFeedback({
+  feedbackType: 'thumbs',
+  value: 'down',
+  comment: 'Wrong answer',
+})
+```
+
+Feedback events map to these PostHog properties:
+
+| Mastra feedback field                  | PostHog property    |
+| -------------------------------------- | ------------------- |
+| `traceId`                              | `$ai_trace_id`      |
+| `comment` (or `value` when no comment) | `$ai_feedback_text` |
+| `feedbackId`                           | `feedback_id`       |
+| `feedbackType`                         | `feedback_type`     |
+| `value`                                | `feedback_value`    |
+| `feedbackSource`                       | `feedback_source`   |
+| `spanId`                               | `span_id`           |
+| `sourceId`                             | `source_id`         |
+| `metadata.sessionId`                   | `$ai_session_id`    |
+| `metadata` (other keys)                | custom properties   |
+
+Feedback without a `traceId` is dropped because PostHog anchors feedback to a trace through `$ai_trace_id`. The event's distinct ID resolves from `feedbackUserId`, then `metadata.userId`, then `defaultDistinctId`, then `anonymous`.

package/.docs/reference/templates/overview.md

@@ -30,28 +30,28 @@ Install a template using the `create-mastra` command:
 **npm**:
 
 ```sh
-npx create-mastra@latest --template template-name
+npx create-mastra@latest my-project --template template-name
 ```
 
 **pnpm**:
 
 ```sh
-pnpm dlx create-mastra@latest --template template-name
+pnpm dlx create-mastra@latest my-project --template template-name
 ```
 
 **Yarn**:
 
 ```sh
-yarn dlx create-mastra@latest --template template-name
+yarn dlx create-mastra@latest my-project --template template-name
 ```
 
 **Bun**:
 
 ```sh
-bun x create-mastra@latest --template template-name
+bun x create-mastra@latest my-project --template template-name
 ```
 
-This creates a complete project with all necessary code and configuration.
+This creates a complete project and installs its dependencies. The template author controls the models, provider dependencies, environment variables, and source code.
 
 ### Setup Process
 
@@ -71,33 +71,7 @@ After installation:
 
    Edit `.env` with required API keys as documented in the template's README.
 
-3. **Install dependencies** (if not done automatically):
-
-   **npm**:
-
-   ```sh
-   npm install
-   ```
-
-   **pnpm**:
-
-   ```sh
-   pnpm install
-   ```
-
-   **Yarn**:
-
-   ```sh
-   yarn install
-   ```
-
-   **Bun**:
-
-   ```sh
-   bun install
-   ```
-
-4. **Start development server**:
+3. **Start development server**:
 
    **npm**:
 

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

@@ -39,7 +39,7 @@ Configure the platform credentials. The access token, project ID, and bucket nam
 **.env file**:
 
 ```bash
-MASTRA_PLATFORM_ACCESS_TOKEN=your-platform-access-token
+MASTRA_PLATFORM_SECRET_KEY=your-platform-secret-key
 MASTRA_PROJECT_ID=your-project-id
 MASTRA_PLATFORM_BUCKET_NAME=your-bucket-name
 ```
@@ -116,7 +116,7 @@ await fs.writeFile('/analyses/repo.md', 'x') // throws WorkspaceReadOnlyError
 
 ## Constructor parameters
 
-**accessToken** (`string`): Platform access token. Falls back to the MASTRA\_PLATFORM\_ACCESS\_TOKEN environment variable.
+**accessToken** (`string`): Platform secret key. Falls back to the MASTRA\_PLATFORM\_SECRET\_KEY environment variable (MASTRA\_PLATFORM\_ACCESS\_TOKEN is a deprecated fallback).
 
 **projectId** (`string`): Platform project ID. Falls back to the MASTRA\_PROJECT\_ID environment variable.
 

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

@@ -39,7 +39,7 @@ Configure the platform credentials. The access token, project ID, and environmen
 **.env file**:
 
 ```bash
-MASTRA_PLATFORM_ACCESS_TOKEN=your-platform-access-token
+MASTRA_PLATFORM_SECRET_KEY=your-platform-secret-key
 MASTRA_PROJECT_ID=your-project-id
 MASTRA_ENVIRONMENT_ID=your-environment-id
 ```
@@ -135,7 +135,7 @@ console.log(result.exitCode)
 
 ## Constructor parameters
 
-**accessToken** (`string`): Platform access token. Falls back to the MASTRA\_PLATFORM\_ACCESS\_TOKEN environment variable.
+**accessToken** (`string`): Platform secret key. Falls back to the MASTRA\_PLATFORM\_SECRET\_KEY environment variable (MASTRA\_PLATFORM\_ACCESS\_TOKEN is a deprecated fallback).
 
 **projectId** (`string`): Platform project ID. Falls back to the MASTRA\_PROJECT\_ID environment variable.
 

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

@@ -2,7 +2,7 @@
 
 # RailwaySandbox
 
-Executes commands in ephemeral, isolated [Railway](https://docs.railway.com/sandboxes) sandboxes. Each sandbox is an isolated Debian Linux VM provisioned on demand through the Railway TypeScript SDK. Supports command execution with streaming output, command timeouts, configurable idle timeout, `ISOLATED`/`PRIVATE` network isolation, custom base images via the Railway template builder, forking a running sandbox, and reattaching to an existing sandbox by ID. For interface details, see [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox).
+Executes commands in ephemeral, isolated [Railway](https://docs.railway.com/sandboxes) sandboxes. Each sandbox is an isolated Debian Linux VM provisioned on demand through the Railway TypeScript SDK. Supports command execution with streaming output, command timeouts, configurable idle timeout, `ISOLATED`/`PRIVATE` network isolation, custom base images via the Railway template builder, checkpoint-backed recovery, forking a running sandbox, and reattaching to an existing sandbox by ID. For interface details, see [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox).
 
 ## Installation
 
@@ -128,6 +128,38 @@ console.log(result.stdout)
 
 The forked sandbox inherits the parent's credentials and defaults unless overridden via the `fork()` options.
 
+### Checkpoint recovery
+
+Set `checkpointName` to preserve a sandbox filesystem across Railway sandbox replacement. On `start()`, `RailwaySandbox` first tries to create the sandbox from the named checkpoint. If the checkpoint is missing, it creates a sandbox from the configured template or default image, then captures the checkpoint.
+
+```typescript
+const sandbox = new RailwaySandbox({
+  checkpointName: 'project-session-42',
+  idleTimeoutMinutes: 30,
+})
+```
+
+`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.
+
+Use one stable checkpoint name for each independent filesystem. Do not share a checkpoint name across unrelated sessions or projects.
+
+### Derived sandbox checkpoints
+
+Use `derive({ checkpointName })` when a configured `RailwaySandbox` acts as the template for a sandbox fleet:
+
+```typescript
+const template = new RailwaySandbox({ idleTimeoutMinutes: 30 })
+
+const sessionSandbox = template.derive({
+  id: 'session-42',
+  checkpointName: 'project-session-42',
+})
+
+await sessionSandbox.start()
+```
+
+A derived sandbox uses the checkpoint passed to `derive()`. If no override is passed, it inherits the template sandbox's `checkpointName`.
+
 ### Streaming output
 
 Stream command output in real time via `onStdout` and `onStderr` callbacks:
@@ -162,6 +194,8 @@ const result = await sandbox.executeCommand('cat', ['/tmp/state.txt'])
 
 **sandboxId** (`string`): Reattach to an existing Railway sandbox by its Railway ID instead of creating a new one. When set, start() calls Sandbox.connect().
 
+**checkpointName** (`string`): Named Railway checkpoint used to seed new sandboxes and preserve the filesystem before idle teardown. Use a unique stable name for each independent filesystem.
+
 **idleTimeoutMinutes** (`number`): How long the sandbox can sit idle (no exec interaction) before Railway destroys it automatically. The valid range and default depend on your Railway plan.
 
 **networkIsolation** (`'ISOLATED' | 'PRIVATE'`): Network access mode. 'ISOLATED' allows outbound internet only; 'PRIVATE' joins the environment's private network. (Default: `'ISOLATED'`)
@@ -192,6 +226,8 @@ const result = await sandbox.executeCommand('cat', ['/tmp/state.txt'])
 
 **fork** (`(options?) => Promise<RailwaySandbox>`): Clone this running sandbox into a new, independent RailwaySandbox. The returned sandbox is already started and reattached to the forked Railway sandbox. Accepts optional id, idleTimeoutMinutes, networkIsolation, and env overrides. Throws SandboxNotReadyError if this sandbox has not been started.
 
+**derive** (`(options?) => RailwaySandbox`): Construct an unstarted sibling sandbox that inherits credentials and defaults. Accepts optional id, sandboxId, env, idleTimeoutMinutes, and checkpointName overrides. The derived sandbox uses options.checkpointName when set, otherwise it inherits the template checkpointName.
+
 ## Background processes
 
 `RailwaySandbox` includes a built-in process manager for spawning and managing background processes. Each spawned process runs as a Railway `exec` session.

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @mastra/mcp-docs-server
 
+## 1.2.8-alpha.23
+
+### Patch Changes
+
+- Updated dependencies [[`c7d30cd`](https://github.com/mastra-ai/mastra/commit/c7d30cd86009c407df91105591f03cd6e3d2854d), [`ef03fbc`](https://github.com/mastra-ai/mastra/commit/ef03fbcc556bcbc04c9b3d06fab88771ecaa043c), [`a7bbe77`](https://github.com/mastra-ai/mastra/commit/a7bbe773577f60bc4761b534ef7ec6b476332dad), [`a7bbe77`](https://github.com/mastra-ai/mastra/commit/a7bbe773577f60bc4761b534ef7ec6b476332dad), [`4e68363`](https://github.com/mastra-ai/mastra/commit/4e683634f94ebd062d26a3bb6093a8dfc7263d37), [`9251370`](https://github.com/mastra-ai/mastra/commit/9251370ad413af464aa22d7566338bec5613e8de)]:
+  - @mastra/core@1.52.0-alpha.11
+
+## 1.2.8-alpha.20
+
+### Patch Changes
+
+- Updated dependencies [[`41a5392`](https://github.com/mastra-ai/mastra/commit/41a5392d9f6c5e18d6b227f0fc0ddf49c50774e9), [`675fbff`](https://github.com/mastra-ai/mastra/commit/675fbff84d3274391b33e852f76083c38a5514e5), [`da009e1`](https://github.com/mastra-ai/mastra/commit/da009e1aacd89ed94b8d1b2af09c9d4fe7c4db49), [`35c2181`](https://github.com/mastra-ai/mastra/commit/35c2181e6a50e47c90ba36260db7c9723d54696f), [`b4b7ea8`](https://github.com/mastra-ai/mastra/commit/b4b7ea8733f033fc441ea47ed03f6afb17ec2248), [`675fbff`](https://github.com/mastra-ai/mastra/commit/675fbff84d3274391b33e852f76083c38a5514e5), [`c328769`](https://github.com/mastra-ai/mastra/commit/c3287698ff8ef98dba86d415faa566fa3e5f4d56), [`232fcbc`](https://github.com/mastra-ai/mastra/commit/232fcbc14fce625dd672ba043329c0b732c62be2), [`3491666`](https://github.com/mastra-ai/mastra/commit/34916663c4fdd43b48c21f4ab2d5fb6dcccc94f9)]:
+  - @mastra/core@1.52.0-alpha.10
+
 ## 1.2.8-alpha.18
 
 ### Patch Changes