@mastra/mcp-docs-server 1.2.13-alpha.1 → 1.2.13-alpha.12

package/.docs/docs/agent-builder/workspace.md

@@ -1,62 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Workspace
-
-> **Note:** The Agent Builder is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. [Contact sales](https://mastra.ai/contact) for more information.
-
-A [workspace](https://mastra.ai/docs/workspace/overview) gives agents filesystem access, command execution, and skill loading. The Agent Builder pins a default workspace onto every new agent through `builder.configuration.agent.workspace`. End users can still override the workspace per agent through the Builder UI.
-
-## Quickstart
-
-Pin an inline workspace snapshot as the Builder default:
-
-```typescript
-import { Mastra } from '@mastra/core'
-import { MastraEditor } from '@mastra/editor'
-
-export const mastra = new Mastra({
-  editor: new MastraEditor({
-    builder: {
-      enabled: true,
-      configuration: {
-        agent: {
-          workspace: {
-            type: 'inline',
-            config: {
-              name: 'project-workspace',
-              filesystem: {
-                provider: 'local',
-                config: { basePath: './workspace' },
-              },
-            },
-          },
-        },
-      },
-    },
-  }),
-})
-```
-
-The Builder derives a deterministic id from the inline config and persists the snapshot, so identical inline configs are deduplicated across agents.
-
-## Workspace references
-
-`configuration.agent.workspace` accepts a `StorageWorkspaceRef`:
-
-- **`{ type: 'inline', config }`**: Embeds a serialized workspace snapshot directly on the agent. Useful for per-agent, ad-hoc configurations.
-- **`{ type: 'id', workspaceId }`**: References a workspace already registered on the `Mastra` instance via `new Mastra({ workspace })` or `mastra.addWorkspace(...)`. Use this for shared, named workspaces.
-
-See the [StorageWorkspaceRef reference](https://mastra.ai/reference/editor/storage-workspace-ref) for both variants.
-
-## Filesystem and sandbox
-
-A workspace combines a `filesystem` (file tools) and an optional `sandbox` (command execution). For local development, point both at the same directory so files written through the filesystem are immediately visible to commands in the sandbox.
-
-For cloud deployments, swap `LocalFilesystem` / `LocalSandbox` for managed providers (e.g., S3, E2B). See [Deploying](https://mastra.ai/docs/agent-builder/deploying) for the cloud-swap pattern.
-
-## Related
-
-- [Workspace overview](https://mastra.ai/docs/workspace/overview): The underlying workspace model.
-- [Filesystem](https://mastra.ai/docs/workspace/filesystem) and [Sandbox](https://mastra.ai/docs/workspace/sandbox): The building blocks.
-- [BuilderAgentDefaults reference](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults): The full `workspace` field schema.
-- [Configuration](https://mastra.ai/docs/agent-builder/configuration): Wire `workspace` alongside the rest of the Builder config.

package/.docs/docs/editor/prompts.md

@@ -1,140 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Prompts
-
-Prompt blocks are reusable instruction templates that you compose into an agent's system prompt. Each block can contain plain text, template variables, and display conditions.
-
-Non-technical team members can edit and test prompt content before publishing changes. Every edit is versioned, so you can compare prompt variations and roll back. The history also records what changed over time.
-
-You can create and manage prompt blocks through the Studio UI or programmatically through the server API, then reference them across multiple agents.
-
-## Quickstart
-
-1. Go to the **Prompts** tab in Studio.
-2. Select **Create prompt** and enter a name and your instruction text.
-3. Save the prompt block and publish it.
-4. Open an agent's **Instructions** section and select **Add block**.
-5. Pick the saved prompt block from the block picker dialog.
-
-The block is added as a reference in the agent's instruction list. Changes to the original prompt block update every agent that references it.
-
-## Block types
-
-An agent's instructions are made up of an ordered list of blocks. Each block is one of three types:
-
-| Type                   | Description                                                                                                                        |
-| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| Inline text            | Free-form text written directly in the agent's instruction list. Lives only on that agent.                                         |
-| Prompt block           | A standalone block with its own content, stored in the agent snapshot. You can save an inline block as a prompt block to reuse it. |
-| Prompt block reference | A pointer to a saved prompt block. The content is resolved at runtime from the referenced block.                                   |
-
-To turn an inline block into a reusable prompt block, open the block's menu and select **Save as prompt block**. To reference an existing prompt block, select **Add block** and pick one from the dialog.
-
-## Template variables
-
-Prompt blocks support `{{variable}}` syntax for runtime content. Variables are resolved at runtime from the agent's variables and request context.
-
-```text
-You are helping {{userName}} with their {{task || 'request'}}.
-```
-
-| Syntax                        | Behavior                                                                                    |
-| ----------------------------- | ------------------------------------------------------------------------------------------- |
-| `{{variableName}}`            | Replaced with the variable value. Left as-is if not found.                                  |
-| `{{nested.path.value}}`       | Resolves dot-notation paths in the context object.                                          |
-| `{{variable \|\| 'default'}}` | Uses the fallback value when the variable is missing. Single or double quotes are accepted. |
-
-Variables are passed through the agent's `variables` configuration or through [request context](https://mastra.ai/docs/server/request-context).
-
-## Display conditions
-
-Each block can have a **display condition**. A rule group that controls whether the block is included in the final prompt. Conditions are evaluated at runtime against the agent's variables and request context.
-
-A rule group uses `AND` or `OR` logic with one or more conditions. Each condition checks a context field against a value using an operator:
-
-| Operator                                       | Description                           |
-| ---------------------------------------------- | ------------------------------------- |
-| `equals` / `not_equals`                        | Exact match comparison.               |
-| `contains` / `not_contains`                    | String inclusion or array membership. |
-| `greater_than` / `less_than`                   | Numeric comparison.                   |
-| `greater_than_or_equal` / `less_than_or_equal` | Numeric comparison with equality.     |
-| `in` / `not_in`                                | Checks if a value is in an array.     |
-| `exists` / `not_exists`                        | Checks if the field is present.       |
-
-Rule groups can be nested, so you can combine `AND` and `OR` conditions for complex logic.
-
-In the Studio, open a block's **Display conditions** panel to set up rules visually. You can also configure conditions programmatically through the API. Blocks without conditions are always included.
-
-## Programmatic control
-
-Prompt blocks can be managed from code through [`mastra.getEditor().prompt`](https://mastra.ai/reference/editor/mastra-editor). This is useful for seeding a set of starter prompts or syncing blocks between environments, or alternatively generating prompt variants from a script.
-
-Create a new prompt block with `editor.prompt.create()`:
-
-```typescript
-import { mastra } from '../mastra'
-
-const editor = mastra.getEditor()!
-
-await editor.prompt.create({
-  id: 'brand-voice',
-  name: 'Brand voice',
-  description: 'Acme Inc. tone and style guidelines',
-  content:
-    'You write in a friendly, concise tone. Always address the user as {{userName || "there"}}.',
-})
-```
-
-Update an existing block with `editor.prompt.update()`. Each update creates a new draft version:
-
-```typescript
-import { mastra } from '../mastra'
-
-const editor = mastra.getEditor()!
-
-await editor.prompt.update({
-  id: 'brand-voice',
-  content: 'You write in a friendly, concise tone. Always greet the user by name when available.',
-})
-```
-
-Use `editor.prompt.list()` to paginate through stored blocks or `editor.prompt.getById()` to fetch a specific block. To preview an agent's full instructions with a set of prompt blocks applied, call `editor.prompt.preview()` with the draft content.
-
-The same operations are available over HTTP through the Mastra server:
-
-| Method   | Path                                         | Description                      |
-| -------- | -------------------------------------------- | -------------------------------- |
-| `GET`    | `/stored/prompt-blocks`                      | List all stored prompt blocks.   |
-| `POST`   | `/stored/prompt-blocks`                      | Create a stored prompt block.    |
-| `GET`    | `/stored/prompt-blocks/:storedPromptBlockId` | Get a stored prompt block by ID. |
-| `PATCH`  | `/stored/prompt-blocks/:storedPromptBlockId` | Update a stored prompt block.    |
-| `DELETE` | `/stored/prompt-blocks/:storedPromptBlockId` | Delete a stored prompt block.    |
-
-Once a prompt block is created, reference it from an agent's `instructions` field as a `prompt_block_ref`:
-
-```typescript
-import { mastra } from '../mastra'
-
-const editor = mastra.getEditor()!
-
-await editor.agent.update({
-  id: 'support-agent',
-  instructions: [
-    { type: 'prompt_block_ref', id: 'brand-voice' },
-    { type: 'text', content: 'Answer only questions about Acme products.' },
-  ],
-})
-```
-
-See the [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor) for the full `editor.prompt` API.
-
-## Versioning
-
-Prompt blocks follow the same [versioning lifecycle](https://mastra.ai/docs/editor/overview) as agents. Each prompt block has a draft that you can edit and publish as a versioned snapshot. As a result, prompt content can be versioned and rolled back independently from the agent that uses it.
-
-When an agent references a prompt block, the resolved content comes from the block's active published version by default. During editing, draft content is used for previews. This separation makes it safe for non-technical team members to experiment with prompt wording. The published version stays stable until they explicitly activate a new one.
-
-## Related
-
-- [Editor overview](https://mastra.ai/docs/editor/overview): Setup and versioning.
-- [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor): Full configuration options for the editor.

package/.docs/docs/editor/tools.md

@@ -1,148 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Tools
-
-The editor gives you three ways to add tools to agents:
-
-- **Code tools**: Tools already registered in your Mastra instance.
-- **Integration providers**: Third-party tool platforms like Composio and Arcade.
-- **MCP clients**: Tools from MCP servers, configured as reusable client definitions.
-
-You can manage all three sources through the Studio UI or programmatically through the server API. Non-technical team members can browse tool catalogs and add tools to agents, plus test different tool combinations without code changes. Tool configurations are versioned alongside the rest of the agent, so you can roll back tool changes and compare versions, plus experiment safely.
-
-## Description overrides
-
-Every tool, regardless of source, can have its description overridden at the agent level. This changes the description the agent sees during tool selection without modifying the original tool definition.
-
-This is useful when you want to:
-
-- Tailor a generic tool's purpose for a specific agent's context.
-- Add instructions about when or how to use a tool.
-- Clarify ambiguous tool descriptions.
-
-In the Studio, select a tool in the agent's tool list and edit the **Description** field. The override applies only to that agent.
-
-## Display conditions
-
-Each tool in an agent can have display conditions, rule groups that control whether the tool is available at runtime. This uses the same rule system as [prompt blocks](https://mastra.ai/docs/editor/prompts).
-
-When a request comes in, the editor evaluates each tool's rules against the current context (agent variables and request context). Tools whose conditions aren't met are excluded from that run.
-
-Use display conditions to:
-
-- Restrict expensive tools to specific users or roles.
-- Enable tools based on feature flags or environment variables.
-- Conditionally include tools based on the conversation context.
-
-Tools without display conditions are always available.
-
-## Studio
-
-Go to the **Agents** tab in Studio and select an agent to edit. Select the **Editor** tab. Scroll to the **Tools** section.
-
-Here you are able to add tools and configure MCP clients.
-
-Once you've made the changes, be sure to save the agent configuration.
-
-## Integration providers
-
-Integration providers connect external tool platforms to the editor. Once registered, you can browse available tools in the Studio and add them to any agent.
-
-### Composio
-
-[Composio](https://composio.dev) gives access to hundreds of integration tools organized into toolkits (GitHub, Slack, Gmail, and others).
-
-1. Get a **project** API key (the `x-api-key` type) from your [Composio dashboard](https://dashboard.composio.dev).
-
-2. Register the provider in your Editor configuration:
-
-   ```typescript
-   import { Mastra } from '@mastra/core'
-   import { MastraEditor } from '@mastra/editor'
-   import { ComposioToolProvider } from '@mastra/editor/composio'
-
-   export const mastra = new Mastra({
-     agents: {/* your agents */},
-     editor: new MastraEditor({
-       toolProviders: {
-         composio: new ComposioToolProvider({
-           apiKey: process.env.COMPOSIO_API_KEY!,
-         }),
-       },
-     }),
-   })
-   ```
-
-   Composio tool slugs use a format like `GITHUB_CREATE_ISSUE`. By default, tool calls use the connection pinned by the agent's author. To route calls to each end user's own account instead, see [connection scope](https://mastra.ai/docs/agent-builder/integrations) in the Agent Builder docs.
-
-### Arcade
-
-[Arcade](https://arcade.dev) provides a curated catalog of tools with built-in authentication handling.
-
-1. Get an API key from your Arcade dashboard.
-
-2. Register the provider in your Editor configuration:
-
-   ```typescript
-   import { Mastra } from '@mastra/core'
-   import { MastraEditor } from '@mastra/editor'
-   import { ArcadeToolProvider } from '@mastra/editor/arcade'
-
-   export const mastra = new Mastra({
-     agents: {/* your agents */},
-     editor: new MastraEditor({
-       toolProviders: {
-         arcade: new ArcadeToolProvider({
-           apiKey: process.env.ARCADE_API_KEY!,
-         }),
-       },
-     }),
-   })
-   ```
-
-   Arcade tools use a `Toolkit.ToolName` format (for example, `Github.GetRepository`). The provider pre-seeds common toolkits to reduce API calls during browsing.
-
-## MCP clients
-
-The editor lets you create stored MCP client configurations that connect to MCP servers. Once created, you can reference these clients in any agent to give it access to the server's tools.
-
-### Transport types
-
-Stored MCP clients support two transport types:
-
-| Transport | Description                                                                                                       |
-| --------- | ----------------------------------------------------------------------------------------------------------------- |
-| **stdio** | Launches a local process and communicates over standard I/O. Specify the `command` and optional `args` and `env`. |
-| **HTTP**  | Connects to a remote MCP server over HTTP. Specify the server `url` and optional `headers`.                       |
-
-### Tool filtering
-
-You can filter MCP tools at two levels:
-
-1. **Client level**: On the MCP client itself, specify which tools from the server to include or exclude. This applies to every agent that references the client.
-2. **Agent level**: On the agent's MCP client reference, further limit which tools are available. This lets you use the same MCP client in multiple agents while exposing different tool subsets.
-
-### Tool namespacing
-
-Tools from MCP servers are namespaced as `serverName_toolName` to avoid conflicts. For example, a `search` tool from the `docs` server becomes `docs_search`.
-
-### Conditional activation
-
-MCP client references in an agent can have display conditions, like [prompt blocks](https://mastra.ai/docs/editor/prompts). This lets you conditionally include MCP tools based on request context or agent variables.
-
-## How tools are merged
-
-When an agent runs, tools from all sources are merged in this order:
-
-1. Code tools
-2. Integration tools
-3. MCP tools
-
-If a tool ID exists in multiple sources, later sources take precedence. Description overrides set at the agent level always take priority over the original tool description. See the [ToolProvider reference](https://mastra.ai/reference/editor/tool-provider) for the full provider API.
-
-## Related
-
-- [Editor overview](https://mastra.ai/docs/editor/overview): Setup and versioning.
-- [Prompts](https://mastra.ai/docs/editor/prompts): Display conditions reference for prompt blocks.
-- [ToolProvider reference](https://mastra.ai/reference/editor/tool-provider): Composio and Arcade API details.
-- [MCP overview](https://mastra.ai/docs/mcp/overview): General MCP documentation.

package/.docs/docs/getting-started/file-based-agents.md

@@ -1,121 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# File-based agents
-
-**Added in:** `@mastra/core@1.50.0`
-
-> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
-
-File-based agents are an experimental, convention-based way to define [Mastra agents](https://mastra.ai/docs/agents/overview) and the primitives they use in files under `src/mastra/`, instead of registering them manually on your [`Mastra`](https://mastra.ai/reference/core/mastra-class) instance.
-
-This approach reduces glue code and makes the file system itself a direct representation of your [project structure](https://mastra.ai/reference/project-structure), so both you and your coding agent can understand it at a glance.
-
-You can build your entire project with file-based agents or combine this approach with agents and other primitives defined directly in code for incremental adoption.
-
-File-based agents have some limitations while in beta. They don't support every Mastra feature yet. Runtime configuration and wiring are usually better defined directly in code, along with any related primitives.
-
-> **Note:** All Mastra documentation currently shows agents and primitives defined directly in code. File-based agents use the same underlying concepts and APIs, so the guidance elsewhere in the docs still applies. As file-based agents mature, more examples may use this structure where appropriate.
-
-## Basic layout
-
-A small file-based agent looks like this:
-
-```text
-src/mastra/
-  agents/
-    weather/
-      config.ts
-      instructions.md
-      tools/
-        get-weather.ts
-      skills/
-        forecast-review.md
-```
-
-The main files in an agent directory are:
-
-- [`config.ts`](https://mastra.ai/reference/file-based-agents/config): Model selection and runtime options
-- [`instructions.md`](https://mastra.ai/reference/file-based-agents/instructions): The prompt that applies to every response
-- [`tools/`](https://mastra.ai/reference/file-based-agents/tools): Typed functions the model can call
-- [`skills/`](https://mastra.ai/reference/file-based-agents/skills): Reusable instructions
-
-You need to define `config.ts` and `instructions.md` at a minimum. Add optional files as needed. Learn more in the [add capabilities](#add-capabilities) section.
-
-## Quickstart
-
-Create a folder at `src/mastra/agents/weather`. Inside, add a `config.ts` and an `instructions.md` file with these contents:
-
-```typescript
-import { agentConfig } from '@mastra/core/agent'
-
-export default agentConfig({
-  model: 'openai/gpt-5.6-sol',
-})
-```
-
-```markdown
-You are a helpful weather assistant. Answer questions about current conditions and forecasts.
-```
-
-Start Mastra's development server with `mastra dev`. Inside Studio, you can now call the `weather` agent and ask it about the weather.
-
-## Add capabilities
-
-Map each primitive or feature to its file convention:
-
-| Primitive or feature                                                             | File convention                                                                           |
-| -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| [Agent config](https://mastra.ai/reference/file-based-agents/config)             | `src/mastra/agents/<agent-id>/config.ts`                                                  |
-| [Agent instructions](https://mastra.ai/reference/file-based-agents/instructions) | `src/mastra/agents/<agent-id>/instructions.md`                                            |
-| [Tools](https://mastra.ai/reference/file-based-agents/tools)                     | `src/mastra/agents/<agent-id>/tools/`                                                     |
-| [Skills](https://mastra.ai/reference/file-based-agents/skills)                   | `src/mastra/agents/<agent-id>/skills/`                                                    |
-| [Memory](https://mastra.ai/reference/file-based-agents/memory)                   | `src/mastra/agents/<agent-id>/memory.ts`                                                  |
-| [Workspace](https://mastra.ai/reference/file-based-agents/workspace)             | `src/mastra/agents/<agent-id>/workspace.ts` and `src/mastra/agents/<agent-id>/workspace/` |
-| [Processors](https://mastra.ai/reference/file-based-agents/processors)           | `src/mastra/agents/<agent-id>/processors/`                                                |
-| [Scorers](https://mastra.ai/reference/file-based-agents/scorers)                 | `src/mastra/agents/<agent-id>/scorers/`                                                   |
-| [Subagents](https://mastra.ai/reference/file-based-agents/subagents)             | `src/mastra/agents/<agent-id>/subagents/`                                                 |
-| [Workflows](https://mastra.ai/reference/file-based-agents/workflows)             | `src/mastra/workflows/`                                                                   |
-| [Storage](https://mastra.ai/reference/file-based-agents/storage)                 | `src/mastra/storage.ts`                                                                   |
-| [Observability](https://mastra.ai/reference/file-based-agents/observability)     | `src/mastra/observability.ts`                                                             |
-| [Logger](https://mastra.ai/reference/file-based-agents/logger)                   | `src/mastra/logger.ts`                                                                    |
-| [Server config](https://mastra.ai/reference/file-based-agents/server)            | `src/mastra/server.ts`                                                                    |
-| [Studio config](https://mastra.ai/reference/file-based-agents/studio)            | `src/mastra/studio.ts`                                                                    |
-| [Schedules](https://mastra.ai/docs/long-running-agents/schedules)                | Not yet file-based, create at runtime with `mastra.schedules.create()`                    |
-
-## Discovery lifecycle
-
-File-based primitives are discovered by the Mastra bundler under `mastra dev` and `mastra build`. During discovery, Mastra reads supported files under `src/mastra/`, imports TypeScript and JavaScript modules, reads markdown instructions and skills, copies workspace seed files, and registers the assembled primitives with your Mastra app.
-
-After discovery, a file-based agent runs as a normal [`Agent`](https://mastra.ai/reference/agents/agent). Calling it from the Agent API, Studio, workflows, or your application code uses the same runtime as a code-defined agent.
-
-Discovery is source-based and conservative.
-
-It skips symlinks, test files, and directories that aren't agent directories. Workflows and singleton project files are file-routed only when they have a default export.
-
-Start your app through the Mastra CLI so discovery runs:
-
-**npm**:
-
-```bash
-npx mastra dev
-```
-
-**pnpm**:
-
-```bash
-pnpm dlx mastra dev
-```
-
-**Yarn**:
-
-```bash
-yarn dlx mastra dev
-```
-
-**Bun**:
-
-```bash
-bun x mastra dev
-```
-
-If you import your `mastra` instance directly, `agents/<name>/` directories and the other conventions aren't discovered. When you consume Mastra as a library, register those primitives in code instead.

package/.docs/docs/mastra-platform/workspace.md

@@ -1,111 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Workspace
-
-A workspace gives an environment two things your agents can use at runtime:
-
-- A **bucket** for filesystem storage, exposed to your code as [`PlatformFilesystem`](https://mastra.ai/reference/workspace/platform-filesystem).
-- A **sandbox** for executing commands, exposed as [`PlatformSandbox`](https://mastra.ai/reference/workspace/platform-sandbox).
-
-Workspaces are provisioned per [environment](https://mastra.ai/docs/mastra-platform/environments), so `production` and `staging` each get their own bucket and sandbox. The platform manages provisioning, credentials, and lifecycle. Your deploy code only needs to construct the providers.
-
-## When workspaces are provisioned
-
-New projects have workspaces enabled by default. When you create an environment, the platform provisions a bucket for it automatically. The sandbox base image is warmed in the background so the first `PlatformSandbox` call starts quickly.
-
-Existing projects that haven't opted in show an **Enable workspaces** action in the Workspaces tab. Enabling provisions a bucket for every environment on the project.
-
-If provisioning fails for an environment, for example while Railway is under load, the Workspaces tab shows the failure and offers a retry. The environment itself is still created. Only the workspace is unavailable until you retry.
-
-## Use the workspace from your code
-
-Install the provider package:
-
-**npm**:
-
-```bash
-npm install @mastra/platform-workspace
-```
-
-**pnpm**:
-
-```bash
-pnpm add @mastra/platform-workspace
-```
-
-**Yarn**:
-
-```bash
-yarn add @mastra/platform-workspace
-```
-
-**Bun**:
-
-```bash
-bun add @mastra/platform-workspace
-```
-
-Compose the providers into a workspace and register it with Mastra:
-
-```typescript
-import { Workspace } from '@mastra/core/workspace'
-import { PlatformFilesystem, PlatformSandbox } from '@mastra/platform-workspace'
-
-export const workspace = new Workspace({
-  filesystem: new PlatformFilesystem(),
-  sandbox: new PlatformSandbox(),
-})
-```
-
-```typescript
-import { Mastra } from '@mastra/core'
-import { workspace } from './workspace'
-
-export const mastra = new Mastra({
-  workspace,
-})
-```
-
-`PlatformFilesystem` and `PlatformSandbox` read their credentials from environment variables the platform injects at deploy time, so you don't pass any options on the platform.
-
-## Injected environment variables
-
-Every deploy that runs on a platform environment with a workspace receives these variables:
-
-| Variable                      | Contents                                                                                                                                                 |
-| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `MASTRA_PLATFORM_SECRET_KEY`  | Secret key scoped to the deploy. Used by the workspace providers to authenticate. `MASTRA_PLATFORM_ACCESS_TOKEN` is also injected as a deprecated alias. |
-| `MASTRA_PROJECT_ID`           | Project the deploy belongs to.                                                                                                                           |
-| `MASTRA_ENVIRONMENT_ID`       | Environment the deploy belongs to. Selects which sandbox pool the platform uses.                                                                         |
-| `MASTRA_PLATFORM_BUCKET_NAME` | Bucket name attached to the environment. Selects which bucket `PlatformFilesystem` reads and writes.                                                     |
-
-These names are reserved. If your project sets any of them explicitly, the platform-managed values take precedence.
-
-## Local development
-
-Reuse the same providers locally by putting the four variables in your `.env` file. Get the values from your project's Workspaces tab:
-
-```bash
-MASTRA_PLATFORM_SECRET_KEY=your-secret-key
-MASTRA_PROJECT_ID=your-project-id
-MASTRA_ENVIRONMENT_ID=your-environment-id
-MASTRA_PLATFORM_BUCKET_NAME=your-bucket-name
-```
-
-`PlatformFilesystem` and `PlatformSandbox` behave the same locally as on the platform, they connect to the same bucket and sandbox pool for that environment. Use a `staging` or `preview` environment's variables for local runs if you want to keep production data isolated.
-
-For a purely offline loop that never touches the platform, swap the providers for [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem) and [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) in a local build.
-
-## Inspect the workspace
-
-The Workspaces tab in your platform project shows, per environment:
-
-- Bucket status and its contents, with upload, download, and delete actions.
-- Recent sandbox sessions with their command, exit code, and duration.
-- Provisioning failures with a **Retry** action.
-
-## See also
-
-- [`PlatformFilesystem`](https://mastra.ai/reference/workspace/platform-filesystem): reference for the filesystem provider.
-- [`PlatformSandbox`](https://mastra.ai/reference/workspace/platform-sandbox): reference for the sandbox provider.
-- [Environments](https://mastra.ai/docs/mastra-platform/environments): how environments scope workspaces, variables, and databases.