@mastra/mcp-docs-server 1.2.13 → 1.2.14-alpha.3

package/.docs/docs/agents/a2a.md

@@ -68,7 +68,7 @@ Use `A2AAgent` when another Mastra agent should delegate work to a remote agent.
 
 ## Consume A2A agents as subagents
 
-Use `A2AAgent` to wrap a remote A2A agent, then add it to a parent agent with the [supervisor agents](https://mastra.ai/docs/agents/supervisor-agents) pattern. Pass an explicit agent card URL when the remote server hosts multiple agents or uses a custom well-known path.
+Use `A2AAgent` to wrap a remote A2A agent, then add it to a parent agent with the [supervisor agents](https://mastra.ai/docs/capabilities/subagents) pattern. Pass an explicit agent card URL when the remote server hosts multiple agents or uses a custom well-known path.
 
 ```typescript
 import { Agent } from '@mastra/core/agent'

package/.docs/docs/agents/acp.md

@@ -151,6 +151,6 @@ See the [AcpAgent workspace integration](https://mastra.ai/reference/acp/acp-age
 - [AcpAgent reference](https://mastra.ai/reference/acp/acp-agent)
 - [createACPTool() reference](https://mastra.ai/reference/acp/create-acp-tool)
 - [Agent reference](https://mastra.ai/reference/agents/agent)
-- [Subagents](https://mastra.ai/docs/agents/supervisor-agents)
+- [Subagents](https://mastra.ai/docs/capabilities/subagents)
 - [Agent Client Protocol introduction](https://agentclientprotocol.com/overview/introduction)
 - [Agent Client Protocol schema](https://agentclientprotocol.com/protocol/schema)

package/.docs/docs/agents/agent-approval.md

@@ -498,7 +498,7 @@ The same discovery is available over HTTP as `GET /agents/:agentId/suspended-run
 
 ## Tool approval: Supervisor agents
 
-A [supervisor agent](https://mastra.ai/docs/agents/supervisor-agents) coordinates multiple subagents using `.stream()` or `.generate()`. When a subagent calls a tool that requires approval, the request propagates up through the delegation chain and surfaces at the supervisor level:
+A [supervisor agent](https://mastra.ai/docs/capabilities/subagents) coordinates multiple subagents using `.stream()` or `.generate()`. When a subagent calls a tool that requires approval, the request propagates up through the delegation chain and surfaces at the supervisor level:
 
 1. The supervisor delegates a task to a subagent.
 2. The subagent calls a tool that has `requireApproval: true` or uses `suspend()`.

package/.docs/docs/agents/networks.md

@@ -2,7 +2,7 @@
 
 # Agent networks
 
-> **Deprecated:** Agent networks are deprecated and will be removed in a future major release. [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents) using `agent.stream()` or `agent.generate()` are now the recommended approach. It provides the same multi-agent coordination with better control, a simpler API, and easier debugging.
+> **Deprecated:** Agent networks are deprecated and will be removed in a future major release. [Supervisor agents](https://mastra.ai/docs/capabilities/subagents) using `agent.stream()` or `agent.generate()` are now the recommended approach. It provides the same multi-agent coordination with better control, a simpler API, and easier debugging.
 >
 > See the [migration guide](https://mastra.ai/guides/migrations/network-to-supervisor) to upgrade.
 
@@ -180,5 +180,5 @@ Requirements for automatic resumption:
 
 ## Related
 
-- [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents)
+- [Supervisor agents](https://mastra.ai/docs/capabilities/subagents)
 - [Migration: `.network()` to supervisor agents](https://mastra.ai/guides/migrations/network-to-supervisor)

package/.docs/docs/agents/overview.md

@@ -204,11 +204,11 @@ Once your agent is running, use this table to find the right page for what you w
 | Keep context and preferences across conversations              | [Memory](https://mastra.ai/docs/memory/overview)                       |
 | Get typed objects back instead of plain text                   | [Structured output](https://mastra.ai/docs/agents/structured-output)   |
 | Human-in-the-loop: Pause execution and wait for human approval | [Approval](https://mastra.ai/docs/agents/agent-approval)               |
-| Build a multi-agent network                                    | [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents)   |
+| Build a multi-agent network                                    | [Supervisor agents](https://mastra.ai/docs/capabilities/subagents)     |
 | Register subagents                                             | [Tools](https://mastra.ai/docs/agents/using-tools)                     |
 | Intercept or transform messages before and after generation    | [Processors](https://mastra.ai/docs/agents/processors)                 |
 | Keep your agent safe                                           | [Guardrails](https://mastra.ai/docs/agents/guardrails)                 |
-| Build agents that correct their work                           | [Rubric scorer](https://mastra.ai/docs/agents/supervisor-agents)       |
+| Build agents that correct their work                           | [Rubric scorer](https://mastra.ai/docs/capabilities/subagents)         |
 | Swap instructions or models based on request context           | [Dynamic configuration](https://mastra.ai/docs/server/request-context) |
 | Add speech-to-text or text-to-speech                           | [Voice](https://mastra.ai/guides/voice/overview)                       |
 | Connect to Slack, Discord, or Telegram                         | [Channels](https://mastra.ai/docs/capabilities/channels/overview)      |

package/.docs/docs/agents/using-tools.md

@@ -166,7 +166,7 @@ export const weatherAgent = new Agent({
 
 ## Agents as tools
 
-Add subagents through the `agents` configuration to create a [supervisor](https://mastra.ai/docs/agents/supervisor-agents). Mastra converts each subagent to an `agent-<key>` tool. Include a `description` on each subagent so the supervisor knows when to delegate.
+Add subagents through the `agents` configuration to create a [supervisor](https://mastra.ai/docs/capabilities/subagents). Mastra converts each subagent to an `agent-<key>` tool. Include a `description` on each subagent so the supervisor knows when to delegate.
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -606,7 +606,7 @@ const agent = new Agent({
 
 Only one task can be `in_progress` at a time. The list is stored in the thread-scoped `threadState` storage domain and projected onto the agent's [state-signal](https://mastra.ai/docs/long-running-agents/signals) lane, so it survives observational-memory truncation. See the [Task tools reference](https://mastra.ai/reference/tools/task-tools) for full schemas.
 
-The [AgentController](https://mastra.ai/docs/agent-controller/overview) automatically includes all built-in tools in every mode, you don't need to add them manually. See [Tool approvals](https://mastra.ai/docs/agent-controller/tool-approvals) for AgentController-specific behavior.
+The [AgentController](https://mastra.ai/docs/harness/agent-controller) automatically includes all built-in tools in every mode, you don't need to add them manually. See [Tool approvals](https://mastra.ai/docs/harness/agent-controller) for AgentController-specific behavior.
 
 ## Related
 

package/.docs/docs/capabilities/channels/overview.md

@@ -258,5 +258,5 @@ Vercel's managed Redis integration and Upstash Redis both work well. For more on
 ## Related
 
 - [Channels reference](https://mastra.ai/reference/agents/channels)
-- [AgentController channels](https://mastra.ai/docs/agent-controller/channels)
+- [AgentController channels](https://mastra.ai/docs/harness/agent-controller)
 - 📹 [Mastra channels workshop](https://www.youtube.com/watch?v=E9KFsZEnQO8\&t=5s)

package/.docs/docs/{agents/supervisor-agents.md → capabilities/subagents.md}

@@ -1,14 +1,14 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# Supervisor agents
+# Subagents
 
 **Added in:** `@mastra/core@1.8.0`
 
-A supervisor agent coordinates multiple subagents using [`Agent.stream()`](https://mastra.ai/reference/streaming/agents/stream) or [`Agent.generate()`](https://mastra.ai/reference/agents/generate). You configure subagents on the supervisor's `agents` property, and the supervisor uses its instructions and each subagent's `description` to decide when and how to delegate tasks.
+Subagents are specialized agents that another agent can delegate tasks to. Add them to the parent agent's `agents` property, then call [`Agent.stream()`](https://mastra.ai/reference/streaming/agents/stream) or [`Agent.generate()`](https://mastra.ai/reference/agents/generate). The parent agent uses its instructions and each subagent's `description` to decide when and how to delegate tasks.
 
-## When to use supervisor agents
+## When to use subagents
 
-Use supervisor agents when a task requires multiple agents with different specializations to work together. The supervisor handles delegation decisions and context passing, plus result synthesis.
+Use subagents when a task requires agents with different specializations to work together. The parent agent decides when to delegate and passes context to each subagent. It then synthesizes their results.
 
 Common use cases:
 
@@ -16,11 +16,11 @@ Common use cases:
 - Multi-step tasks that need different expertise at each stage
 - Tasks where you need fine-grained control over delegation behavior
 
-> **Note:** Supervisor agents are one approach to building multi-agent systems in Mastra. For other patterns, read the [conceptual overview](https://mastra.ai/guides/concepts/multi-agent-systems).
+> **Note:** A parent agent that coordinates subagents is often called a supervisor. The supervisor pattern is one approach to building multi-agent systems in Mastra. For other patterns, read the [conceptual overview](https://mastra.ai/guides/concepts/multi-agent-systems).
 
 ## Quickstart
 
-Define subagents with clear descriptions, then create a supervisor agent that references them:
+Define subagents with clear descriptions, then add them to a parent agent:
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -39,8 +39,8 @@ const writingAgent = new Agent({
   model: 'openai/gpt-5-mini',
 })
 
-const supervisor = new Agent({
-  id: 'supervisor',
+const parentAgent = new Agent({
+  id: 'parent-agent',
   instructions: `You coordinate research and writing using specialized agents.
     Delegate to research-agent for facts, then writing-agent for content.`,
   model: 'openai/gpt-5.6-sol',
@@ -50,7 +50,7 @@ const supervisor = new Agent({
   }),
 })
 
-const stream = await supervisor.stream('Research AI in education and write an article', {
+const stream = await parentAgent.stream('Research AI in education and write an article', {
   maxSteps: 10,
 })
 
@@ -65,7 +65,7 @@ Delegation hooks let you intercept, modify, or reject delegations as they happen
 
 ### `onDelegationStart`
 
-Called before the supervisor delegates to a subagent. Return an object to control the delegation:
+Called before the parent agent delegates to a subagent. Return an object to control the delegation:
 
 - `proceed: true`: Allow the delegation (default behavior)
 - `proceed: false`: Reject the delegation with a `rejectionReason`
@@ -73,7 +73,7 @@ Called before the supervisor delegates to a subagent. Return an object to contro
 - `modifiedMaxSteps`: Limit the subagent's iteration count
 
 ```typescript
-const stream = await supervisor.stream('Research AI trends', {
+const stream = await parentAgent.stream('Research AI trends', {
   maxSteps: 10,
   delegation: {
     onDelegationStart: async context => {
@@ -107,18 +107,18 @@ The `context` object includes:
 | Property      | Description                               |
 | ------------- | ----------------------------------------- |
 | `primitiveId` | The ID of the subagent being delegated to |
-| `prompt`      | The prompt the supervisor is sending      |
+| `prompt`      | The prompt the parent agent is sending    |
 | `iteration`   | Current iteration number                  |
 
 ### `onDelegationComplete`
 
 Called after a delegation finishes. Use it to inspect results or provide feedback, or alternatively stop execution:
 
-- `context.bail()`: Stop the supervisor loop immediately
-- Return `{ feedback: '...' }`: Add feedback that gets saved to the supervisor's memory and is visible to subsequent iterations
+- `context.bail()`: Stop the parent agent's loop immediately
+- Return `{ feedback: '...' }`: Add feedback that gets saved to the parent agent's memory and is visible to subsequent iterations
 
 ```typescript
-const stream = await supervisor.stream('Research AI trends', {
+const stream = await parentAgent.stream('Research AI trends', {
   maxSteps: 10,
   delegation: {
     onDelegationComplete: async context => {
@@ -138,19 +138,19 @@ const stream = await supervisor.stream('Research AI trends', {
 
 The `context` object includes:
 
-| Property      | Description                          |
-| ------------- | ------------------------------------ |
-| `primitiveId` | The ID of the subagent that ran      |
-| `result`      | The subagent's response              |
-| `error`       | Error if the delegation failed       |
-| `bail()`      | Function to stop the supervisor loop |
+| Property      | Description                              |
+| ------------- | ---------------------------------------- |
+| `primitiveId` | The ID of the subagent that ran          |
+| `result`      | The subagent's response                  |
+| `error`       | Error if the delegation failed           |
+| `bail()`      | Function to stop the parent agent's loop |
 
 ## Message filtering
 
-By default, subagents receive the full conversation context from the supervisor. Use `messageFilter` to control what messages are shared, for example, to remove sensitive data or limit context size.
+By default, subagents receive the full conversation context from the parent agent. Use `messageFilter` to control what messages are shared, for example, to remove sensitive data or limit context size.
 
 ```typescript
-const stream = await supervisor.stream('Research AI trends', {
+const stream = await parentAgent.stream('Research AI trends', {
   maxSteps: 10,
   delegation: {
     messageFilter: ({ messages, primitiveId, prompt }) => {
@@ -171,16 +171,16 @@ The callback receives `messages` (the full conversation history), `primitiveId`
 
 ## Subagent result context
 
-When a subagent completes, the supervisor model receives the subagent's text response in later iterations. Nested tool calls and subagent metadata, such as thread and resource IDs, aren't added to the supervisor model context.
+When a subagent completes, the parent agent's model receives the subagent's text response in later iterations. Nested tool calls and subagent metadata, such as thread and resource IDs, aren't added to the parent agent's model context.
 
 Application code and UI integrations can still inspect `subAgentToolResults` and the rest of the raw delegation result in the tool result payload.
 
-This keeps debugging and display data available without sending nested tool arguments or outputs back into the supervisor's next model call.
+This keeps debugging and display data available without sending nested tool arguments or outputs back into the parent agent's next model call.
 
-Set `includeSubAgentToolResultsInModelContext` to include the full subagent result, including nested tool results and subagent metadata, in the supervisor model context.
+Set `includeSubAgentToolResultsInModelContext` to include the full subagent result, including nested tool results and subagent metadata, in the parent agent's model context.
 
 ```typescript
-await supervisor.generate('Research AI trends', {
+await parentAgent.generate('Research AI trends', {
   delegation: {
     includeSubAgentToolResultsInModelContext: true,
   },
@@ -189,10 +189,10 @@ await supervisor.generate('Research AI trends', {
 
 ## Iteration monitoring
 
-`onIterationComplete` is called after each iteration of the supervisor loop. Use it to log progress or inject feedback, or alternatively stop execution early.
+`onIterationComplete` is called after each iteration of the parent agent's loop. Use it to monitor execution or guide the next iteration. You can also stop execution early.
 
 ```typescript
-const stream = await supervisor.stream('Research AI trends', {
+const stream = await parentAgent.stream('Research AI trends', {
   maxSteps: 10,
   onIterationComplete: async context => {
     console.log(`Iteration ${context.iteration}/${context.maxIterations}`)
@@ -220,19 +220,19 @@ Return `{ continue: true }` to keep iterating, or `{ continue: false }` to stop.
 
 ## Memory isolation
 
-Supervisor agents implement memory isolation. Subagents receive the full conversation context for better decision-making, but only their specific delegation prompt and response are saved to their memory.
+Mastra isolates subagent memory during delegation. Subagents receive the full conversation context for better decision-making, but only their specific delegation prompt and response are saved to their memory.
 
 How it works:
 
-1. **Full context forwarded**: When the supervisor delegates, the subagent receives all messages from the supervisor's conversation
+1. **Full context forwarded**: When the parent agent delegates, the subagent receives all messages from the parent agent's conversation
 2. **Scoped memory saves**: Only the delegation prompt and the subagent's response are saved to the subagent's memory
 3. **Fresh thread per invocation**: Each delegation uses a unique thread ID, ensuring clean separation
 
-As a result, subagents have the context they need without cluttering their memory with the entire supervisor conversation. Visit [memory in multi-agent systems](https://mastra.ai/docs/memory/overview) for more details.
+As a result, subagents have the context they need without cluttering their memory with the parent agent's entire conversation. Visit [memory in multi-agent systems](https://mastra.ai/docs/memory/overview) for more details.
 
 ## Tool approval propagation
 
-Tool approvals propagate through the delegation chain. When a subagent uses a tool with `requireApproval: true` or calls `suspend()`, the approval request surfaces to the supervisor level.
+Tool approvals propagate through the delegation chain. When a subagent uses a tool with `requireApproval: true` or calls `suspend()`, the approval request surfaces in the parent agent's stream.
 
 ```typescript
 const sensitiveDataTool = createTool({
@@ -248,13 +248,13 @@ const dataAgent = new Agent({
   tools: { sensitiveDataTool },
 })
 
-const supervisor = new Agent({
-  id: 'supervisor',
+const parentAgent = new Agent({
+  id: 'parent-agent',
   agents: { dataAgent },
   memory: new Memory(),
 })
 
-const stream = await supervisor.stream('Get data for user 123')
+const stream = await parentAgent.stream('Get data for user 123')
 
 for await (const chunk of stream.fullStream) {
   if (chunk.type === 'tool-call-approval') {
@@ -265,22 +265,22 @@ for await (const chunk of stream.fullStream) {
 
 ## Cancellation
 
-When you pass an `abortSignal` to the supervisor's [`stream()`](https://mastra.ai/reference/streaming/agents/stream) or [`generate()`](https://mastra.ai/reference/agents/generate) call, Mastra forwards that same signal to delegated subagents. Calling `AbortController.abort()` cancels in-flight subagent runs at their next step instead of letting them run to completion.
+When you pass an `abortSignal` to the parent agent's [`stream()`](https://mastra.ai/reference/streaming/agents/stream) or [`generate()`](https://mastra.ai/reference/agents/generate) call, Mastra forwards that same signal to delegated subagents. Calling `AbortController.abort()` cancels in-flight subagent runs at their next step instead of letting them run to completion.
 
 ```typescript
 const controller = new AbortController()
 
-const stream = await supervisor.stream('Research AI trends', {
+const stream = await parentAgent.stream('Research AI trends', {
   abortSignal: controller.signal,
 })
 
-// Cancel the supervisor and any in-flight subagents
+// Cancel the parent agent and any in-flight subagents
 controller.abort()
 ```
 
 ## Task completion scoring
 
-Agents don't always produce a complete, correct output on the first try. Task completion scorers can help with that by validating whether the task is complete after each iteration. If validation fails, the supervisor continues iterating. Feedback from failed scorers is included in the conversation context so subagents can see what was missing.
+Agents don't always produce a complete, correct output on the first try. Task completion scorers can help by validating whether the task is complete after each iteration. If validation fails, the parent agent continues iterating. Feedback from failed scorers is included in the conversation context so subagents can see what was missing.
 
 ```typescript
 import { createScorer } from '@mastra/core/evals'
@@ -295,7 +295,7 @@ const taskCompleteScorer = createScorer({
   return hasAnalysis && hasRecommendations ? 1 : 0
 })
 
-const stream = await supervisor.stream('Research AI in education', {
+const stream = await parentAgent.stream('Research AI in education', {
   maxSteps: 10,
   isTaskComplete: {
     scorers: [taskCompleteScorer],
@@ -319,8 +319,8 @@ This is most effective for tasks with clear, verifiable success criteria. You ca
 import { Agent } from '@mastra/core/agent'
 import { createRubricScorer } from '@mastra/evals/scorers/prebuilt'
 
-const supervisor = new Agent({
-  id: 'supervisor',
+const parentAgent = new Agent({
+  id: 'parent-agent',
   instructions: 'You coordinate research and writing using specialized agents.',
   model: 'openai/gpt-5.6-sol',
   agents: { researchAgent, writingAgent },
@@ -334,7 +334,7 @@ const rubricScorer = createRubricScorer({
   ],
 })
 
-const stream = await supervisor.stream('Research AI in education', {
+const stream = await parentAgent.stream('Research AI in education', {
   maxSteps: 10,
   isTaskComplete: {
     scorers: [rubricScorer],
@@ -349,15 +349,15 @@ For full API details, see the [rubric scorer reference](https://mastra.ai/refere
 
 Clear instructions are essential for effective delegation.
 
-Your supervisor's `instructions` should specify the available resources and when to use each one. They should also define coordination behavior and success criteria.
+The parent agent's `instructions` should specify the available resources and when to use each one. They should also define coordination behavior and success criteria.
 
-Each subagent should have a clear `description` that explains its purpose and return format, including when the supervisor should use it.
+Each subagent should have a clear `description` that explains its purpose and return format, including when the parent agent should use it.
 
-The supervisor uses these descriptions to make delegation decisions.
+The parent agent uses these descriptions to make delegation decisions.
 
 ```typescript
-const supervisor = new Agent({
-  id: 'supervisor',
+const parentAgent = new Agent({
+  id: 'parent-agent',
   instructions: `You coordinate research and writing tasks.
 
 Available resources:
@@ -378,13 +378,13 @@ Success criteria:
 
 ## Running subagents in the background
 
-Subagent invocations are dispatched as tool calls, so they can run as [background tasks](https://mastra.ai/docs/long-running-agents/background-tasks). This is useful when one or more delegations are long-running and you don't want them to block the supervisor's response.
+Subagent invocations are dispatched as tool calls, so they can run as [background tasks](https://mastra.ai/docs/long-running-agents/background-tasks). This is useful when one or more delegations are long-running and you don't want them to block the parent agent's response.
 
-Enable the [backgroundTasks manager](https://mastra.ai/reference/configuration) on the Mastra instance, then opt subagents in on the supervisor:
+Enable the [backgroundTasks manager](https://mastra.ai/reference/configuration) on the Mastra instance, then opt subagents in on the parent agent:
 
 ```typescript
-const supervisor = new Agent({
-  id: 'supervisor',
+const parentAgent = new Agent({
+  id: 'parent-agent',
   instructions: 'Coordinate research and writing using the available agents.',
   model: 'openai/gpt-5.6-sol',
   agents: { researchAgent, writingAgent },
@@ -396,21 +396,21 @@ const supervisor = new Agent({
   },
 })
 
-const stream = await supervisor.streamUntilIdle('Research AI in education and write an article', {
+const stream = await parentAgent.streamUntilIdle('Research AI in education and write an article', {
   memory: { thread: 't1', resource: 'u1' },
 })
 ```
 
-Use [`streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle) instead of `stream()` so the stream stays open until the subagents complete and the supervisor has had a chance to respond to their results.
+Use [`streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle) instead of `stream()` so the stream stays open until the subagents complete and the parent agent has had a chance to respond to their results.
 
-If a subagent isn't listed on the supervisor but has its own background-eligible tools, the supervisor still dispatches the subagent as a background task and inherits its config. See [Inheriting from the subagent](https://mastra.ai/docs/long-running-agents/background-tasks) for details.
+If a subagent isn't listed under the parent agent's `backgroundTasks.tools` but has its own background-eligible tools, the parent agent still dispatches the subagent as a background task and inherits its config. See [Inheriting from the subagent](https://mastra.ai/docs/long-running-agents/background-tasks) for details.
 
 ## Subagent versioning
 
-When using the [editor](https://mastra.ai/docs/editor/overview), you can control which stored version of each subagent the supervisor uses at runtime. Set version overrides on the Mastra instance or per invocation:
+When using the [editor](https://mastra.ai/docs/editor/overview), you can control which stored version of each subagent the parent agent uses at runtime. Set version overrides on the Mastra instance or per invocation:
 
 ```typescript
-const result = await supervisor.generate('Research and write about AI safety', {
+const result = await parentAgent.generate('Research and write about AI safety', {
   versions: {
     agents: {
       'research-agent': { status: 'published' },

package/.docs/docs/deployment/sandbox.md

@@ -62,13 +62,18 @@ export const mastra = new Mastra({
   deployer: new SandboxDeployer({
     sandbox: new VercelSandbox({
       sandboxName: 'my-preview',
-      timeout: 3_600_000, // 1 hour
+      timeout: 2_400_000, // 40 minutes
       ports: [4111],
     }),
   }),
 })
 ```
 
+Two Vercel-specific requirements:
+
+- `timeout` can't exceed the maximum sandbox lifetime of your plan, 45 minutes on Pro. A higher value fails the deploy with a 400 from the Vercel API.
+- Declare the server port in `ports`. Vercel exposes only ports declared at creation, unlike E2B and Daytona.
+
 Build and deploy in one command:
 
 ```bash
@@ -86,6 +91,83 @@ The manifest includes `expiresAt` when the sandbox provider reports an expiratio
 
 Redeploys to the same sandbox skip the dependency install when its inputs are unchanged. These inputs are `package.json`, the bundled lockfiles, and the install command.
 
+### What the URLs serve
+
+The Studio URL is the sandbox root, without `/api`. Open it in a browser to use Studio. When the deploy runs with `studio: false`, the root serves the Mastra welcome page instead.
+
+The API URL is only a prefix for the endpoints below it, such as `/api/agents`. `/api` has no handler of its own, so opening it in a browser returns a "Not Found" response even though the server is healthy.
+
+To check a deployment, call an endpoint directly:
+
+```bash
+curl -s -X POST https://4111-<sandbox-id>.e2b.app/api/agents/weatherAgent/generate \
+  -H "Content-Type: application/json" \
+  -d '{"messages":[{"role":"user","content":"Weather in London"}]}' | jq -r '.text'
+```
+
+### Provider credentials
+
+Each provider authenticates with its own credentials. Set the ones for the sandbox you deploy to:
+
+```bash
+# E2B
+E2B_API_KEY=
+
+# Daytona
+DAYTONA_API_KEY=
+
+# Vercel
+VERCEL_TOKEN=
+VERCEL_TEAM_ID=
+VERCEL_PROJECT_ID=
+```
+
+Every provider also accepts these as constructor options. Self-hosted E2B and Daytona installations take `E2B_DOMAIN` or `DAYTONA_API_URL`.
+
+Unlike `mastra dev`, `mastra build` doesn't load `.env` files. The deploy happens inside the build, so a sandbox provider that reads its credentials from the environment, such as E2B with `E2B_API_KEY`, sees an empty value and the deploy fails with an authentication error.
+
+Adding `import 'dotenv/config'` to `src/mastra/index.ts` doesn't fix this. To find the deployer, the build extracts only the `deployer` option from your entry file and tree-shakes everything else away, including that import.
+
+Load the `.env` file into the shell environment before the build runs. [`dotenv-cli`](https://www.npmjs.com/package/dotenv-cli) is one way to do that:
+
+**npm**:
+
+```bash
+npm install --save-dev dotenv-cli
+```
+
+**pnpm**:
+
+```bash
+pnpm add --save-dev dotenv-cli
+```
+
+**Yarn**:
+
+```bash
+yarn add --dev dotenv-cli
+```
+
+**Bun**:
+
+```bash
+bun add --dev dotenv-cli
+```
+
+```json
+{
+  "scripts": {
+    "deploy": "dotenv -e .env -- mastra build"
+  }
+}
+```
+
+Then run `npm run deploy`. The script is named for what it does, since `mastra build` deploys once a `SandboxDeployer()` is configured. Keep it separate from a plain `build` script so a hosting platform or CI job that runs `npm run build` doesn't deploy a sandbox by accident.
+
+In continuous integration (CI), export the credentials as secrets instead. Whatever mechanism you use, the variables must exist in the shell environment, not only in the `.env` file.
+
+This applies to credentials the deployer needs on your machine. Variables the deployed server needs are handled separately: the deployer reads `.env`, `.env.production`, and `.env.local` and injects them into the sandbox. See [Security](#security).
+
 ### Using E2B
 
 For E2B, the `id` identifies the deployment, so subsequent deployments with the same value reconnect to the existing sandbox, whether it's running or paused.
@@ -124,6 +206,18 @@ const deployer = new SandboxDeployer({
 
 Stopping a Daytona sandbox persists its filesystem but not running processes, so waking works like Vercel: the resolver relaunches the server on `wake: true`.
 
+Daytona filters outbound traffic per destination. Requests to some hosts connect over Transport Layer Security (TLS) normally, while others are reset during the handshake, which surfaces in an agent or a tool as Node's generic `fetch failed`. Rule out your code before debugging it, by running `curl` against the same host from inside the sandbox:
+
+```typescript
+const sandbox = new DaytonaSandbox({ id: 'my-preview' })
+await sandbox.start()
+
+const result = await sandbox.executeCommand('curl -v --max-time 10 https://api.example.com')
+console.info(result.stdout, result.stderr)
+```
+
+A `Connection reset by peer` during the TLS handshake points at the filtering rather than your agent. Ask Daytona support to allow the destination. Restricted Daytona tiers also block cloud storage endpoints, which the mount helpers report with a dedicated error.
+
 ## Deploying programmatically
 
 `deployToSandbox()` deploys a prebuilt output directory without the bundler. Unlike `SandboxDeployer()`, it doesn't include Studio unless you pass `studio: true`. Use it in CI or from agent code:

package/.docs/docs/getting-started/develop.md

@@ -139,6 +139,8 @@ See the [project structure reference](https://mastra.ai/reference/project-struct
 ## File-based agents
 
 > **Beta:** File-based agents are in beta and may change before they're stable.
+>
+> File-based discovery only runs through `mastra dev` or `mastra build`. If your app imports `mastra` directly, including through a web framework or server adapter, file-based agents aren't discovered. Register those agents in code or run Mastra as a separate server.
 
 > **📹 Watch:** [How to create your first file-based agent](https://www.youtube.com/watch?v=5Kfn-oYkJNg\&t=18s)