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

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

@@ -74,15 +74,18 @@ export const mastra = new Mastra({
 
 `PlatformFilesystem` and `PlatformSandbox` have different lifecycles, which matters when you design agents.
 
-**`PlatformFilesystem` is a long-lived handle to the environment's bucket.** All requests, all agents, and all sandboxes in the environment read and write the same object storage. Anything an agent writes is visible on the next request unless you explicitly delete it.
+**`PlatformFilesystem` is a long-lived handle to the environment's bucket.** All requests and agents that use this provider read and write the same object storage. Anything an agent writes is visible on the next request unless you explicitly delete it.
 
 **`PlatformSandbox` is a client for provisioning ephemeral sandboxes.** Each `PlatformSandbox` instance owns one remote sandbox:
 
 - `start()` provisions a fresh sandbox (or reattaches when you passed `sandboxId`).
 - `executeCommand()` runs commands against it.
-- `destroy()` tears the sandbox down. `stop()` is an alias.
+- `stop()` tears down the remote sandbox while preserving its recovery checkpoint when it has one.
+- `destroy()` also releases the recovery checkpoint associated with a caller-supplied recovery `id`.
 
-The `sandbox` you pass to `Workspace` provides the tools an agent uses inside its own request. When your agent needs another isolated environment, for example a per-task workspace, a per-user tenant, or a background job that shouldn't touch the caller's shell state, construct another `PlatformSandbox`:
+One statically configured `PlatformSandbox` is shared by every request and agent using that configuration. Requests and memory threads don't receive separate sandboxes automatically. `PlatformFilesystem` is also a separate provider: configuring both providers doesn't mount the environment bucket inside the sandbox.
+
+When your agent needs another isolated environment, for example a per-task sandbox, a per-user tenant, or a background job that shouldn't touch shared shell state, construct another `PlatformSandbox`:
 
 ```typescript
 import { PlatformSandbox } from '@mastra/platform-workspace'

package/.docs/docs/sandbox/filesystem.md

@@ -2,52 +2,40 @@
 
 # Filesystem
 
-Filesystems give agents persistent storage for source code, documents, datasets, and generated artifacts.
+A filesystem gives an agent tools for reading, writing, listing, and [searching](https://mastra.ai/docs/sandbox/search) files. Use it as a knowledge base or to persist files between ephemeral sandbox runs.
 
-Mastra supports two mutually exclusive ways to add a filesystem to a workspace:
+Configure files in two ways:
 
-| Configuration | Agent access | Sandbox access                                 |
-| ------------- | ------------ | ---------------------------------------------- |
-| `mounts`      | File tools   | Files appear as local directories through FUSE |
-| `filesystem`  | File tools   | No access                                      |
+- [Direct filesystem access](#direct-filesystem-access) uses `filesystem` with one filesystem provider or a [`CompositeFilesystem`](#manual-composition) that you create yourself.
+- [Mounts](#mounts) uses `mounts` to create a `CompositeFilesystem` from path-prefixed providers. When the workspace also has a static sandbox, Mastra attempts to mount each provider at its configured path inside the sandbox so commands can access the same files. Remote sandbox mounts typically use Filesystem in Userspace (FUSE).
 
-Use `mounts` when a sandbox needs to run commands against the files. The agent can use file tools, while code inside the sandbox can use shell commands and libraries against the same storage.
+Configure either `filesystem` or `mounts`, not both. Configuring both throws a `WorkspaceError` with the code `INVALID_CONFIG`.
 
-Use `filesystem` when the agent only needs direct file tools or the sandbox backend doesn't support mounts. The agent acts as the driver: it can read a file and pass its contents to another tool, but the file doesn't exist inside the sandbox. A command such as `cat`, `grep`, or `python script.py` can't access it unless your application passes the content as input.
+Both configurations give the agent file tools. Sandbox commands can only see a provider when the sandbox can mount it successfully.
 
-You can't configure both `filesystem` and `mounts` on the same workspace.
+Configuring a filesystem gives the agent these tools:
 
-## When to use filesystems
-
-Mount a filesystem when you want to:
-
-- Seed an ephemeral sandbox with source code, datasets, or project files.
-- Persist files after the sandbox stops or is deleted.
-- Let commands and agent file tools work against the same storage.
-- Share a storage location across multiple sandbox runs.
-
-Use a workspace-only filesystem when you want to:
-
-- Give an agent access to a managed knowledge base without command execution.
-- Read documents uploaded by non-technical teammates to services such as S3 or Google Drive.
-- Use persistent storage with a sandbox backend that doesn't support mounts.
-- Keep the storage provider separate from the sandbox execution environment.
-
-For example, a real-estate agent could read travel-policy documents from an S3 bucket or Google Drive folder and use them while answering questions. The agent can search and read those files without needing a sandbox to execute commands against them.
-
-A data agent could also download reports from Google Drive with file tools. It can pass their contents to a sandbox for analysis and presentation generation, then upload the finished presentation for the team. This works even when the sandbox backend can't mount Google Drive because the agent transfers the input and output between the filesystem and sandbox.
+| Tool         | Does                                                                         |
+| ------------ | ---------------------------------------------------------------------------- |
+| `read_file`  | Reads all or part of a file.                                                 |
+| `write_file` | Creates or overwrites a file.                                                |
+| `edit_file`  | Replaces matching text in an existing file.                                  |
+| `list_files` | Lists files and directories.                                                 |
+| `delete`     | Deletes a file or directory.                                                 |
+| `file_stat`  | Returns metadata about a file or directory.                                  |
+| `mkdir`      | Creates a directory and any missing parent directories.                      |
+| `grep`       | Searches file contents with a regular expression.                            |
+| `ast_edit`   | Applies structural code edits. Available when `@ast-grep/napi` is installed. |
 
 ## Supported filesystems
 
 ### `LocalFilesystem`
 
-[`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem) stores files in a directory on the same machine as your Mastra application. Use it for local development or when the application already has access to the files on disk.
-
-`LocalFilesystem` contains file-tool access within its configured `basePath` by default. You can allow specific paths outside that directory or disable containment when the application requires broader host access.
+[`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem) connects to a directory on the same machine as your Mastra application. Use it for local development or files that already live on the application host.
 
 ### Other filesystems
 
-Use another filesystem when files need to persist outside the application host or already live in an external service:
+Use another provider when files live outside the application host or already exist in an external service:
 
 - [AgentFS](https://mastra.ai/integrations/file-storage/agentfs)
 - [Amazon S3](https://mastra.ai/integrations/file-storage/amazon-s3)
@@ -59,15 +47,33 @@ Use another filesystem when files need to persist outside the application host o
 - [Mesa](https://mastra.ai/integrations/file-storage/mesa)
 - [Vercel Files](https://mastra.ai/integrations/file-storage/vercel-files)
 
-Workspace-only file tools work with the full provider list. FUSE mount support depends on both the filesystem and sandbox backend, so check both references before choosing a combination.
+Every provider supports file tools through `filesystem`. Sandbox mounting depends on both the filesystem provider and sandbox backend.
 
-## Mounts
+## Direct filesystem access
+
+Use `filesystem` when the agent should access a provider through file tools. It can also accept a resolver or a manually created `CompositeFilesystem`.
 
-Use mounts when both the agent and sandbox commands need access to the same files.
+Give an agent file tools for a local knowledge base:
 
-### Quickstart
+```typescript
+import { LocalFilesystem, Workspace } from '@mastra/core/workspace'
 
-Mount an S3 filesystem into a sandbox:
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({
+    basePath: './knowledge-base',
+  }),
+})
+```
+
+The agent receives tools such as `read_file`, `write_file`, `list_files`, and `grep`. Paths are resolved under `./knowledge-base`, and no sandbox or command tools are required.
+
+See [Search](https://mastra.ai/docs/sandbox/search) to index the files for keyword or semantic retrieval. See the [filesystem tools reference](https://mastra.ai/reference/workspace/workspace-class) for every generated tool and its policies.
+
+## Mounts
+
+Use `mounts` when programs inside a sandbox need to access persistent files by path. The agent still receives file tools, while command tools can run commands such as `ls`, `cat`, or `python` against the same files.
+
+For example, mount an S3 bucket at `/workspace` inside a Daytona sandbox:
 
 ```typescript
 import { Mastra } from '@mastra/core'
@@ -79,7 +85,7 @@ const workspace = new Workspace({
   mounts: {
     '/workspace': new S3Filesystem({
       bucket: process.env.S3_BUCKET!,
-      region: process.env.S3_REGION!,
+      region: 'us-east-1',
     }),
   },
   sandbox: new DaytonaSandbox(),
@@ -88,32 +94,33 @@ const workspace = new Workspace({
 export const mastra = new Mastra({ workspace })
 ```
 
-Existing objects in the bucket seed the sandbox at `/workspace`. Files created there persist in S3 after the sandbox stops. All agents registered with this `Mastra` instance inherit the workspace.
-
 ### Using mounts
 
-The agent receives file tools for mounted storage:
+Files already available through the provider appear under `/workspace`. The agent can call `read_file('/workspace/report.md')` or run `cat /workspace/report.md`. Files written through either interface are saved by the provider and remain available after the sandbox stops.
+
+Without a mount, an agent can still combine file tools with sandbox commands by passing file contents between tool calls. This works for selected text files. Mounts are a better fit when programs expect a directory tree or need to process large or binary files.
+
+> **Warning:** File-tool and command-tool policies are independent. Requiring approval for `write_file`, for example, doesn't stop the agent from using `execute_command` to write the same mounted path. If files must only be accessed through file tools, disable sandbox command tools.
+
+### Paths
+
+A mount path is the path exposed to file tools and, after a successful sandbox mount, commands. The underlying provider may store those files somewhere else.
+
+For a remote provider mounted at `/workspace`:
 
-| Tool         | Does                                                       |
-| ------------ | ---------------------------------------------------------- |
-| `read_file`  | Reads text or binary file contents.                        |
-| `write_file` | Creates or replaces a file.                                |
-| `edit_file`  | Applies targeted edits to a text file.                     |
-| `list_files` | Lists files and directories, with optional glob filtering. |
-| `file_stat`  | Returns file metadata.                                     |
-| `mkdir`      | Creates a directory.                                       |
-| `delete`     | Deletes files or directories.                              |
-| `grep`       | Searches file contents with a regular expression.          |
+- File tools use paths such as `/workspace/report.md`.
+- Remote sandbox commands generally use the same path.
+- The provider maps the path to its configured bucket, prefix, or remote directory.
 
-Mounted files are also available to commands inside the sandbox. In the Quickstart, `read_file('/workspace/report.md')` and `cat /workspace/report.md` read the same S3 object.
+`LocalSandbox` creates a symlink inside its `workingDirectory` instead. A `/workspace` mount becomes `<workingDirectory>/workspace` on the host and is usually addressed as `workspace` by commands.
 
-Use `WORKSPACE_TOOLS.FILESYSTEM` to require approval, disable tools, enforce read-before-write, or change output limits. See the [Workspace filesystem tools reference](https://mastra.ai/reference/workspace/workspace-class) for configuration details.
+## Composite filesystem
 
-> **Warning:** File-tool policies only apply to file-tool calls. Restrictions such as `allowedPaths`, approval rules, or read-before-write don't constrain shell commands running inside the sandbox. A command can access any mounted path allowed by the sandbox backend and mount configuration. If the agent must not bypass file-tool policies through the shell, disable its sandbox command tools.
+The `mounts` option creates a `CompositeFilesystem`. This TypeScript path router presents several providers as one virtual directory tree.
 
-### Multiple mounts
+### Multiple filesystems
 
-The `mounts` option creates a `CompositeFilesystem` that routes paths to storage providers by mount prefix. Supported sandbox backends expose those providers as local directories through FUSE.
+Configure each provider under its mount path:
 
 ```typescript
 import { Workspace } from '@mastra/core/workspace'
@@ -137,131 +144,105 @@ const workspace = new Workspace({
 
 With this configuration:
 
-- Existing objects under `/data` and `/reports` seed the sandbox when the mounts become available.
-- Agent file tools route each path to its corresponding storage provider.
-- Commands inside the sandbox access the same paths.
-- New and updated files persist in the underlying buckets.
+- `list_files('/')` returns the virtual directories `data` and `reports`.
+- `read_file('/data/input.csv')` routes to the S3 provider.
+- `write_file('/reports/summary.md')` routes to the Google Cloud Storage provider.
+- Sandbox commands use the same paths when each sandbox mount succeeds.
 
-All file paths must start with a mount prefix. Listing `/` returns a virtual directory for each mount. Mount paths can't be nested, so a workspace can't mount both `/data` and `/data/archive`.
+The composite strips the mount prefix before passing the remaining path to its provider. Mount paths can't be nested, so the same composite can't contain both `/data` and `/data/archive`.
 
-Mount support varies by sandbox backend and filesystem provider. Check both references before choosing a combination.
+### Without a sandbox
 
-### Read-only mounts
+You can configure `mounts` without a sandbox. Mastra still creates the `CompositeFilesystem`, and all file tools work with mount-prefixed paths. The agent receives no command or process tools because no sandbox is configured.
 
-Set `readOnly: true` on a filesystem provider when the sandbox and agent should only read seeded files. Mastra excludes write tools for provider objects known to be read-only, and the mount backend enforces its own write restrictions.
+### Manual composition
+
+You can also create a `CompositeFilesystem` yourself and pass it through `filesystem` for path routing without automatic sandbox mount wiring:
 
 ```typescript
-const workspace = new Workspace({
+import { CompositeFilesystem, LocalFilesystem, Workspace } from '@mastra/core/workspace'
+import { S3Filesystem } from '@mastra/s3'
+
+const filesystem = new CompositeFilesystem({
   mounts: {
-    '/policies': new S3Filesystem({
-      bucket: 'company-policies',
+    '/local': new LocalFilesystem({ basePath: './data' }),
+    '/archive': new S3Filesystem({
+      bucket: 'agent-archive',
       region: 'us-east-1',
-      readOnly: true,
     }),
   },
-  sandbox: new DaytonaSandbox(),
 })
-```
-
-### Per-user or per-thread mounts
-
-Workspace-level `mounts` require a sandbox provider object and can't be combined with a sandbox resolver. For one sandbox and storage prefix per user or thread, create and mount the filesystem inside the sandbox resolver. See [Multi-tenant sandboxes](https://mastra.ai/docs/sandbox/overview) for a complete example.
-
-## Workspace-only filesystem
-
-Pass a provider to `filesystem` when only the agent needs file access. The agent receives file tools, but a sandbox configured on the same workspace can't see those files.
 
-### Quickstart
-
-```typescript
-import { LocalSandbox, Workspace } from '@mastra/core/workspace'
-import { GoogleDriveFilesystem } from '@mastra/google-drive'
-
-const workspace = new Workspace({
-  filesystem: new GoogleDriveFilesystem({
-    folderId: process.env.GOOGLE_DRIVE_FOLDER_ID!,
-    accessToken: process.env.GOOGLE_DRIVE_ACCESS_TOKEN!,
-  }),
-  sandbox: new LocalSandbox({
-    workingDirectory: './workspace',
-  }),
-})
+const workspace = new Workspace({ filesystem })
 ```
 
-The agent receives the same file tools listed under [Using mounts](#using-mounts), plus sandbox command tools. It can use both in one task. For the prompt "Format `draft.md` with Prettier and save it as `formatted.md`", the agent can:
+Use manual composition when another part of your application needs the composite as a filesystem provider. For normal sandbox mounting, the `mounts` option performs the same routing setup with less configuration.
 
-1. Read `draft.md` from Google Drive with `read_file`.
-2. Pass the returned content to `execute_command`, for example by piping it into Prettier.
-3. Write the command output to `formatted.md` with `write_file`.
+## Mount availability
 
-The Google Drive files never appear inside the sandbox. Only the content passed to `execute_command` crosses into the execution environment, and only the returned output is written back.
+File tools and composite routing work without FUSE. Remote sandboxes can use FUSE to make cloud storage visible to commands. `LocalSandbox` uses symlinks instead.
 
-### Seed a filesystem
+Built-in sandbox mounting currently includes:
 
-Files already in the folder seed the workspace. You can also seed any writable provider through its API before the agent uses it:
+| Sandbox backend | Filesystem providers                                |
+| --------------- | --------------------------------------------------- |
+| `LocalSandbox`  | `LocalFilesystem`                                   |
+| E2B             | Amazon S3, Google Cloud Storage, Azure Blob Storage |
+| Daytona         | Amazon S3, Google Cloud Storage, Azure Blob Storage |
+| Blaxel          | Amazon S3, Google Cloud Storage                     |
 
-```typescript
-await workspace.filesystem?.writeFile(
-  'travel-policy.md',
-  '# Travel policy\n\nEmployees may book economy flights.',
-)
-```
+Remote mounts may require `s3fs`, `gcsfuse`, or `blobfuse2` inside the sandbox. Some backends install missing software during startup, which can require network access and additional startup time. Other combinations require an [`onMount`](https://mastra.ai/reference/workspace/workspace-class) hook or provider-specific setup.
 
-Filesystem operations initialize the provider on first use. Writes replace existing files by default. Pass `{ overwrite: false }` when existing content must be preserved.
+If a sandbox mount is unavailable or fails, the workspace remains usable. File tools continue to access the provider through its SDK, but commands can't see that path. Mastra describes these providers to the agent as available through file tools only.
 
-### Containment
+## Multi-tenant filesystems
 
-`LocalFilesystem` uses contained mode by default. File tools can access `basePath` but can't traverse into unrelated host paths through absolute paths, `..`, or symlinks.
+The `filesystem` option accepts a resolver when storage should vary by request, user, role, or tenant:
 
 ```typescript
-import { LocalFilesystem, Workspace } from '@mastra/core/workspace'
-
 const workspace = new Workspace({
-  filesystem: new LocalFilesystem({
-    basePath: './knowledge-base',
-    allowedPaths: ['../shared-policies'],
-  }),
+  filesystem: ({ requestContext }) => {
+    const tenantId = requestContext.get('tenant-id') as string
+
+    return new S3Filesystem({
+      bucket: process.env.S3_BUCKET!,
+      region: process.env.S3_REGION!,
+      prefix: `tenants/${tenantId}`,
+    })
+  },
 })
 ```
 
-Containment still matters even though the agent accesses files through tools. It limits what those tools can expose. Prefer `allowedPaths` for specific external directories instead of setting `contained: false`.
+Each tenant gets its own filesystem view, and file tools resolve the provider from the request context automatically.
+
+`mounts` doesn't accept a resolver and can't be combined with a sandbox resolver. When each user or thread needs separate storage inside a separate sandbox, create and mount the provider inside the sandbox resolver. See [Multi-tenant sandboxes](https://mastra.ai/docs/sandbox/overview).
 
-### Read-only mode
+## Policies and containment
 
-Set `readOnly: true` when the agent should use seeded content without changing it:
+Use individual constants under `WORKSPACE_TOOLS.FILESYSTEM`, such as `WORKSPACE_TOOLS.FILESYSTEM.WRITE_FILE`, to configure each file tool. Set approval globally or per tool. Configure read-before-write and output limits on individual filesystem tool entries. See the [filesystem tool configuration reference](https://mastra.ai/reference/workspace/workspace-class).
+
+`LocalFilesystem` contains access within `basePath` by default. Use `allowedPaths` when the agent needs specific directories outside that root:
 
 ```typescript
 const workspace = new Workspace({
   filesystem: new LocalFilesystem({
     basePath: './knowledge-base',
-    readOnly: true,
+    allowedPaths: ['../shared-policies'],
   }),
 })
 ```
 
-For a provider object, Mastra removes write, edit, delete, and directory-creation tools. For a resolver-backed filesystem, the tools remain registered because the provider isn't known until execution. Write attempts are rejected at runtime.
-
-### Multi-tenant filesystems
+Containment applies to filesystem operations, including file tools and search indexing. It doesn't restrict shell commands.
 
-Use a resolver when each request, user, role, or tenant needs different storage:
+Set `readOnly: true` when the agent should use files without changing them. For a static provider, Mastra removes write-related file tools.
 
-```typescript
-const workspace = new Workspace({
-  filesystem: ({ requestContext }) => {
-    const tenantId = requestContext.get('tenant-id') as string
-    return new S3Filesystem({
-      bucket: process.env.S3_BUCKET!,
-      region: process.env.S3_REGION!,
-      prefix: `tenants/${tenantId}`,
-    })
-  },
-})
-```
+With a filesystem resolver, write tools remain registered because the provider isn't known until the request runs. The provider rejects write attempts at runtime.
 
-Each tenant's prefix seeds its own workspace view. Workspace tools resolve the filesystem from the request context automatically.
+For `LocalFilesystem` entries in a composite, keep `contained: true`, which is the default. Set `contained: false` only when unrestricted host filesystem access is intentional.
 
 ## Related
 
-- [Sandbox](https://mastra.ai/docs/sandbox/overview)
-- [`WorkspaceFilesystem` reference](https://mastra.ai/reference/workspace/filesystem)
-- [`Workspace` reference](https://mastra.ai/reference/workspace/workspace-class)
+- [Sandboxes](https://mastra.ai/docs/sandbox/overview)
+- [Search](https://mastra.ai/docs/sandbox/search)
+- [Filesystem provider interface](https://mastra.ai/reference/workspace/filesystem)
+- [Configuration API reference](https://mastra.ai/reference/workspace/workspace-class)