@mastra/mcp-docs-server 1.2.18-alpha.1 → 1.2.18-alpha.5

package/.docs/docs/sandbox/overview.md

@@ -1,30 +1,28 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# Sandbox
+# Sandboxes and filesystems
 
-Sandboxes give Mastra agents an environment for running commands and working with files. Agents can also start background processes when the selected backend supports process management; otherwise, background-process tools are unavailable.
+A sandbox gives your agent an environment where it can run commands, execute code, install dependencies, and manage processes. Sandboxes can isolate potentially risky agent-run code from your host, and they can also provide a place to run longer-lived or more resource-intensive work outside your application process.
 
-In Mastra, you attach a sandbox backend to a `Workspace`. You can use one sandbox for an application or agent, or resolve separate environments for each user, tenant, or thread.
+[Filesystems](https://mastra.ai/docs/sandbox/filesystem) give the agent files it can read, write, and [search](https://mastra.ai/docs/sandbox/search). They can provide a knowledge base for your agent, or be shared with a sandbox so commands can work with the same files and keep data beyond the sandbox's lifetime.
 
-Supported backends can FUSE-mount filesystems into the sandbox, letting you seed ephemeral environments with files and persist their output between runs.
+## When to use sandboxes
 
-## When to use sandboxes?
-
-Sandboxes are useful for:
+Sandboxes work well for:
 
 - **Coding agents and software factories**: Clone repositories and run shell, Git, build, or test workflows without giving autonomous agents access to the host system.
 - **Deep research and analysis**: Use specialized libraries to process downloaded PDFs or presentations and produce new artifacts.
 - **Long-running and parallel tasks**: Run work in separate environments without tying it to one request or sharing files and processes.
 
-## Quickstart
+If an agent only needs to read, write, or search files, configure [direct filesystem access](https://mastra.ai/docs/sandbox/filesystem).
 
-In Mastra, a sandbox operates through a `Workspace`. Its `sandbox` backend defines where commands run.
+## Quickstart
 
-Create an agent with a workspace and sandbox:
+Give an agent a local sandbox and filesystem:
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
-import { LocalSandbox, Workspace } from '@mastra/core/workspace'
+import { LocalFilesystem, LocalSandbox, Workspace } from '@mastra/core/workspace'
 
 export const codingAgent = new Agent({
   id: 'coding-agent',
@@ -35,16 +33,21 @@ export const codingAgent = new Agent({
     sandbox: new LocalSandbox({
       workingDirectory: './workspace',
     }),
+    filesystem: new LocalFilesystem({
+      basePath: './workspace',
+    }),
   }),
 })
 
-await codingAgent.generate('List the files in the workspace directory')
+await codingAgent.generate('List the files in the sandbox directory')
 ```
 
 > **Warning:** `LocalSandbox` is the quickest sandbox to set up, but commands run on the host by default. Enable [native isolation](#localsandbox) whenever possible. For applications exposed to untrusted users, use a remote or container backend with a stronger isolation boundary instead.
 
 To use a different sandbox for each user, tenant, or thread, configure a [sandbox resolver](#multi-tenant-sandboxes) instead.
 
+The `LocalSandbox` above is one static instance. Every request and memory thread that uses `codingAgent` shares its files, processes, and lifecycle state. A memory thread doesn't create an isolated sandbox by itself.
+
 ## Using the sandbox
 
 Agents receive tools for the capabilities supported by the sandbox backend:
@@ -55,12 +58,29 @@ Agents receive tools for the capabilities supported by the sandbox backend:
 | `get_process_output` | Gets stdout, stderr, and status for a background process. Supports `tail` to limit output and `wait: true` to wait for the process to exit. This tool and `kill_process` are only added when the backend supports background processes. |
 | `kill_process`       | Stops a background process and returns its recent output.                                                                                                                                                                               |
 
-You can disable or rename each tool and require approval before it runs. You can also limit how much output it adds to the model's context. See the [workspace tool configuration reference](https://mastra.ai/reference/workspace/workspace-class).
+Configured capabilities determine which tools are available. Tool configuration can then disable, rename, or add policies to those tools:
+
+```typescript
+import { LocalSandbox, Workspace, WORKSPACE_TOOLS } from '@mastra/core/workspace'
+
+const workspace = new Workspace({
+  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
+  tools: {
+    requireApproval: true,
+    [WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND]: {
+      enabled: false,
+    },
+  },
+})
+```
+
+Omitting a tool entry keeps its capability-driven default. Set `{ enabled: false }` on one tool to remove it, or set the top-level `enabled: false` to disable generated tools by default. A per-tool `{ enabled: true }` overrides that global setting. The top-level `requireApproval` policy applies to every generated tool unless a per-tool entry overrides it.
+
+See the [sandbox tools reference](https://mastra.ai/reference/workspace/workspace-class) for all generated tools and the [tool configuration reference](https://mastra.ai/reference/workspace/workspace-class) for approvals, output limits, and hooks.
 
-Authored runtime functions, including tools and workflow steps, can get the live sandbox from their execution context. Start a server, watcher, notebook kernel, browser, or worker and interact with it across agent turns.
+Authored runtime functions, including tools and workflow steps, can get the live sandbox from their execution context. Use it to execute commands, install dependencies, process files, or spawn a long-running process.
 
 ```typescript
-import type { ProcessHandle } from '@mastra/core/sandbox'
 import { createTool } from '@mastra/core/tools'
 import { z } from 'zod'
 
@@ -71,15 +91,24 @@ export const startServerTool = createTool({
     command: z.string(),
   }),
   execute: async ({ command }, ctx) => {
-    const sandbox = await ctx.getSandbox()
-    const server: ProcessHandle = await sandbox.spawn({ command })
+    if (!ctx.workspace || !ctx.requestContext) {
+      throw new Error('This tool requires a workspace execution context')
+    }
+
+    const sandbox = await ctx.workspace.resolveSandbox({
+      requestContext: ctx.requestContext,
+    })
+
+    if (!sandbox?.processes) {
+      throw new Error('The configured sandbox does not support background processes')
+    }
+
+    const server = await sandbox.processes.spawn(command)
     return { pid: server.pid }
   },
 })
 ```
 
-The authored function itself runs in your application process. Only operations called through the sandbox handle run inside the sandbox.
-
 ## Supported backends
 
 ### `LocalSandbox`
@@ -102,11 +131,11 @@ const sandbox = new LocalSandbox({
 })
 ```
 
-Use `LocalSandbox.detectIsolation()` to check whether Seatbelt or Bubblewrap is available on the current operating system. The `nativeSandbox` options control network access, read-only or writable paths, workspace write access, and system binaries. You can also provide a custom Seatbelt profile or Bubblewrap arguments. See [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) for the full configuration.
+Use `LocalSandbox.detectIsolation()` to check whether Seatbelt or Bubblewrap is available on the current operating system. The [`nativeSandbox` options](https://mastra.ai/reference/workspace/local-sandbox) control network access, read-only or writable paths, write access to the working directory, and system binaries. You can also provide a custom Seatbelt profile or Bubblewrap arguments. See [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) for the full configuration.
 
 ### Other backends
 
-Use a remote or container backend when commands need a stronger boundary from the host application. Each backend has its own isolation, persistence, networking, and mount behavior:
+Use a remote or container backend when commands need a stronger boundary from the host application or when workloads need to scale beyond the resources of your application server. Each backend has its own isolation, persistence, networking, and mount behavior:
 
 - [AgentCore](https://mastra.ai/integrations/sandboxes/agentcore)
 - [Apple Container](https://mastra.ai/integrations/sandboxes/apple-container)
@@ -120,39 +149,47 @@ Use a remote or container backend when commands need a stronger boundary from th
 - [Railway](https://mastra.ai/integrations/sandboxes/railway)
 - [Vercel](https://mastra.ai/integrations/sandboxes/vercel)
 
-If Mastra doesn't support your execution backend, implement [`WorkspaceSandbox`](https://mastra.ai/reference/workspace/sandbox) to add it.
+If Mastra doesn't support your execution backend, implement the [sandbox provider interface](https://mastra.ai/reference/workspace/sandbox) to add it.
+
+## Filesystem
 
-## Persistent storage
+Each sandbox has a native filesystem that commands can use. Treat it as ephemeral because its contents follow the sandbox's lifecycle.
 
-Some execution backends can also mount cloud filesystems through FUSE. Mounted files appear as local directories inside the sandbox, so commands such as `cat /data/report.md` or `python /data/analyze.py` can use them directly.
+To seed a sandbox with files or keep files between runs, give the agent a [filesystem](https://mastra.ai/docs/sandbox/filesystem). Use mounts when sandbox commands need access to the same files.
 
-Configure mounts on the workspace alongside the sandbox:
+## Multi-tenant sandboxes
+
+Use a **resolver** when each user, tenant, or thread needs a separate sandbox. Set `sandboxCacheKey` to the identity that owns the sandbox so later requests reuse the same live environment.
+
+This example creates and caches one Daytona sandbox per user:
 
 ```typescript
+import type { RequestContext } from '@mastra/core/request-context'
 import { Workspace } from '@mastra/core/workspace'
 import { DaytonaSandbox } from '@mastra/daytona'
-import { S3Filesystem } from '@mastra/s3'
+
+const getUserId = (requestContext: RequestContext) => {
+  const userId = requestContext.get('user-id')
+  if (typeof userId !== 'string' || !userId) {
+    throw new Error('A user ID is required to resolve this sandbox')
+  }
+
+  return userId
+}
 
 const workspace = new Workspace({
-  mounts: {
-    '/data': new S3Filesystem({
-      bucket: 'agent-data',
-      region: 'us-east-1',
-    }),
+  sandbox: async ({ requestContext }) => {
+    const sandbox = new DaytonaSandbox({ id: `user-${getUserId(requestContext)}` })
+    await sandbox.start()
+    return sandbox
   },
-  sandbox: new DaytonaSandbox(),
+  sandboxCacheKey: ({ requestContext }) => getUserId(requestContext),
 })
 ```
 
-The agent receives filesystem tools for the mounted storage, and commands in the sandbox can access the same files under `/data`. This lets you seed an ephemeral sandbox with existing files and persist its output after the sandbox stops.
-
-Mount support varies by sandbox backend. See [Filesystem](https://mastra.ai/docs/sandbox/filesystem) for supported storage backends, detailed mount configuration, and how to mount multiple filesystems.
-
-## Multi-tenant sandboxes
-
-Use a **resolver** when each user, tenant, or thread needs a separate sandbox. Set `sandboxCacheKey` to the identity that owns the sandbox so later requests reuse the same live environment.
+The first request from a user creates the sandbox. Later requests with the same user ID reuse it.
 
-This example creates one Daytona sandbox and one S3 storage prefix per memory thread. The S3 filesystem is also mounted at `/workspace` inside the sandbox:
+For a sandbox with persistent storage, create the filesystem and mount it inside the resolver. This example creates one Daytona sandbox and one S3 storage prefix per memory thread, then mounts the storage at `/workspace`:
 
 ```typescript
 import { MASTRA_THREAD_ID_KEY, type RequestContext } from '@mastra/core/request-context'
@@ -163,7 +200,7 @@ import { S3Filesystem } from '@mastra/s3'
 const getThreadId = (requestContext: RequestContext) => {
   const threadId = requestContext.get(MASTRA_THREAD_ID_KEY)
   if (typeof threadId !== 'string' || !threadId) {
-    throw new Error('A memory thread is required to use this workspace')
+    throw new Error('A memory thread is required to resolve this sandbox')
   }
 
   return threadId
@@ -195,32 +232,27 @@ const workspace = new Workspace({
 
 The first request in a thread runs the resolver and starts the sandbox. Later requests with the same thread ID reuse the cached sandbox. A different thread ID creates a different sandbox and storage prefix.
 
-Workspace-level `mounts` can't be combined with a sandbox resolver. This is a known limitation, so the example mounts the filesystem inside the resolver instead. Workspace tools resolve the filesystem and sandbox from the request context automatically.
+The example mounts the filesystem inside the resolver because static `mounts` can't be combined with a sandbox resolver. Generated tools resolve the filesystem and sandbox from the request context automatically.
 
 ### Resolver ownership
 
-The workspace doesn't own sandboxes returned by a resolver. Return a sandbox that's ready to use, and destroy it through your application's lifecycle code when it's no longer needed. `workspace.destroy()` doesn't destroy resolver-returned sandboxes.
+You are responsible for every sandbox returned by a resolver. It must be ready to use when returned. Keep track of it and destroy it through your application lifecycle code when it's no longer needed. `workspace.destroy()` doesn't destroy resolver-returned sandboxes.
 
-Resolvers are incompatible with `mounts` and [`lsp: true`](https://mastra.ai/docs/sandbox/lsp), because both require a static sandbox when the workspace is constructed. Using a resolver with `mounts` throws an `INVALID_CONFIG` error. With `lsp: true`, Mastra disables LSP and logs a warning.
+Resolvers are incompatible with `mounts` and [`lsp: true`](https://mastra.ai/docs/sandbox/lsp), because both require a static sandbox during configuration. Using a resolver with `mounts` throws an `INVALID_CONFIG` error. With `lsp: true`, Mastra disables LSP and logs a warning.
 
 ### Tool availability
 
-With a static sandbox, Mastra knows which capabilities the backend supports and only gives the agent the corresponding tools. With a resolver-backed sandbox, the backend isn't known until a request runs, so Mastra initially makes all sandbox tools available. If the resolved backend doesn't support the tool the agent calls, the call fails with `SandboxFeatureNotSupportedError`.
-
-For example, this resolver returns a Daytona sandbox for development requests and an AgentCore sandbox for other requests:
+With a static sandbox, Mastra knows which capabilities the backend supports and only gives the agent the corresponding tools. Application code should also check that an optional capability is available before using it:
 
 ```typescript
-const workspace = new Workspace({
-  sandbox: ({ requestContext }) =>
-    requestContext.get('environment') === 'development'
-      ? new DaytonaSandbox()
-      : new AgentCoreRuntimeSandbox({
-          agentRuntimeArn: process.env.AGENTCORE_RUNTIME_ARN!,
-        }),
-})
+const processManager = workspace.sandbox?.processes
+
+if (processManager) {
+  await processManager.spawn('pnpm dev')
+}
 ```
 
-Mastra exposes the process tools because `DaytonaSandbox` supports background processes. If a request resolves to `AgentCoreRuntimeSandbox`, one-shot commands still work, but calling `get_process_output` or `kill_process` fails with `SandboxFeatureNotSupportedError` because that backend doesn't support background processes.
+With a [resolver-backed sandbox](#multi-tenant-sandboxes), the backend isn't known until a request runs, so Mastra initially makes all sandbox tools available. If the resolved backend doesn't support the tool the agent calls, the call fails with `SandboxFeatureNotSupportedError`.
 
 ## Background processes
 
@@ -247,26 +279,26 @@ These callbacks fire for all background processes started by the agent through `
 
 By default, background processes inherit the agent's abort signal and stop when the agent disconnects. Set `abortSignal` to a custom signal, or use `null` or `false` when the process should continue after the request ends.
 
-For the full `SandboxProcessManager` API (spawning processes programmatically and reading output, plus sending stdin), see the [`SandboxProcessManager` reference](https://mastra.ai/reference/workspace/process-manager).
+For the full `SandboxProcessManager` API, including programmatic process spawning, output, and standard input, see the [`SandboxProcessManager` reference](https://mastra.ai/reference/workspace/process-manager).
 
 ## Lifecycle and persistence
 
-Sandbox scope depends on where you assign the workspace and whether you use a resolver:
+Who shares a sandbox depends on where you configure it and whether you use a resolver:
 
-| Configuration            | Sandbox scope                                                                    |
-| ------------------------ | -------------------------------------------------------------------------------- |
-| Mastra-level workspace   | Agents that inherit the workspace from the Mastra instance use the same sandbox. |
-| Agent-level workspace    | Every request handled by that agent instance uses the same sandbox.              |
-| Resource-scoped resolver | The resolver caches one sandbox for each resource ID.                            |
-| Thread-scoped resolver   | A memory thread keeps its sandbox across requests in that thread.                |
+| Configuration              | Who shares the sandbox                                                                                                              |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| Mastra-level configuration | Agents that inherit the configuration from the [`Mastra`](https://mastra.ai/reference/configuration) instance use the same sandbox. |
+| Agent-level configuration  | Every request handled by that agent instance uses the same sandbox.                                                                 |
+| Resource-scoped resolver   | The resolver caches one sandbox for each resource ID.                                                                               |
+| Thread-scoped resolver     | A memory thread keeps its sandbox across requests in that thread.                                                                   |
 
 A static sandbox isn't automatically scoped to the current resource or memory thread. For resource or thread scope, use a resolver and set `sandboxCacheKey` to the corresponding ID. See [Multi-tenant sandboxes](#multi-tenant-sandboxes).
 
 ### Start
 
-Static sandbox backends are instantiated with your application, but their execution environment usually starts lazily on the first command. Call `workspace.init()` when you want to provision it during application startup instead.
+Static sandbox environments usually start when the first command runs, so most applications don't need to initialize them explicitly. Call `workspace.init()` during application startup only when you want to start a static sandbox and prepare its mounts before serving requests. This is useful when credential, network, or provider errors need to surface during startup instead of on the first command.
 
-Resolver-backed sandboxes aren't started by `workspace.init()` because no backend is selected until the resolver runs. Return a sandbox that's already started or can start itself on first use.
+`workspace.init()` doesn't start resolver-backed sandboxes because no sandbox is selected until a request runs. The resolver must return a sandbox that's already started or can start itself on first use.
 
 ### Hooks
 
@@ -285,9 +317,11 @@ const sandbox = new LocalSandbox({
 
 ### Cleanup
 
-Sandboxes passed directly to a workspace are owned by that workspace. `mastra dev` and the generated Mastra server handle shutdown signals and destroy registered workspaces automatically. If you embed Mastra in a custom server or process, call `mastra.shutdown()` from its shutdown hook. For a standalone workspace, call `workspace.destroy()` directly. The effect of stopping or destroying the underlying environment depends on the backend.
+When you configure a sandbox directly instead of using a resolver, Mastra owns it. `mastra dev` and the generated Mastra server handle shutdown signals and destroy registered resources automatically. If you embed Mastra in a custom server or process, call `mastra.shutdown()` from its shutdown hook. For standalone use, call `workspace.destroy()` directly.
+
+The backend decides what `stop()` and `destroy()` do. For example, stopping may shut down compute while preserving an environment that can restart, while destroying may delete the environment and its ephemeral files. Check the selected backend before relying on either behavior.
 
-Sandboxes returned by a resolver are owned by your application. `workspace.destroy()` and `mastra.shutdown()` clear workspace references but don't destroy those resolved sandboxes. Your resolver or application lifecycle must keep track of them, call `destroy()` when their user, thread, or session ends, and then call `workspace.clearSandboxCache(cacheKey)` for keyed entries. This prevents unused compute from continuing to run and later requests from reusing a stale sandbox.
+Sandboxes returned by a resolver are owned by your application. `workspace.destroy()` and `mastra.shutdown()` clear cached references but don't destroy resolved sandboxes. Application lifecycle code must keep track of them, call `destroy()` when their user, thread, or session ends, and then call `workspace.clearSandboxCache(cacheKey)`. This prevents unused compute from continuing to run and later requests from reusing a stale sandbox.
 
 ### Persistence
 
@@ -335,5 +369,5 @@ await sandbox.executeCommand('node', ['scripts/download-reports.js'], {
 ## Related
 
 - [`SandboxProcessManager` reference](https://mastra.ai/reference/workspace/process-manager)
-- [`WorkspaceSandbox` reference](https://mastra.ai/reference/workspace/sandbox)
+- [Sandbox provider interface](https://mastra.ai/reference/workspace/sandbox)
 - [Filesystem](https://mastra.ai/docs/sandbox/filesystem)