@mastra/mcp-docs-server 1.1.8 → 1.1.9-alpha.1

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

@@ -6,24 +6,47 @@ Executes commands in isolated [Daytona](https://www.daytona.io) cloud sandboxes.
 
 ## Installation
 
+**npm**:
+
 ```bash
 npm install @mastra/daytona
 ```
 
-Set your Daytona API key in one of three ways:
+**pnpm**:
+
+```bash
+pnpm add @mastra/daytona
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/daytona
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/daytona
+```
+
+Set your Daytona API key in one of three ways.
+
+**Shell export**:
 
 ```bash
-# Shell export
 export DAYTONA_API_KEY=your-api-key
 ```
 
+**.env file**:
+
 ```bash
-# .env file
 DAYTONA_API_KEY=your-api-key
 ```
 
+**Constructor**:
+
 ```typescript
-// Passed directly as constructor argument
 new DaytonaSandbox({ apiKey: 'your-api-key' })
 ```
 
@@ -36,13 +59,13 @@ import { Agent } from '@mastra/core/agent'
 import { Workspace } from '@mastra/core/workspace'
 import { DaytonaSandbox } from '@mastra/daytona'
 
-const sandbox = new DaytonaSandbox({
-  language: 'typescript',
-  timeout: 120_000,
+const workspace = new Workspace({
+  sandbox: new DaytonaSandbox({
+    language: 'typescript',
+    timeout: 120_000,
+  }),
 })
 
-const workspace = new Workspace({ sandbox })
-
 const agent = new Agent({
   id: 'code-agent',
   name: 'Code Agent',
@@ -138,7 +161,7 @@ const result = await sandbox2.executeCommand('cat', ['/tmp/state.txt'])
 console.log(result.stdout) // "session 1"
 ```
 
-If the sandbox is in a stopped or archived state, it is restarted automatically. If it is in a dead state (destroyed, errored), a fresh sandbox is created instead.
+If the sandbox is in a stopped or archived state, it's restarted automatically. If it's in a dead state (destroyed, errored), a fresh sandbox is created instead.
 
 ### Filesystem mounting
 
@@ -175,7 +198,7 @@ const workspace = new Workspace({
 
 When the workspace starts, the filesystems are automatically mounted at the specified paths. Code running in the sandbox can then access files at `/s3-data` and `/gcs-data` as if they were local directories.
 
-#### Via sandbox.mount()
+#### Via `sandbox.mount()`
 
 Mount manually at any point after the sandbox has started:
 
@@ -296,146 +319,31 @@ const workspace = new Workspace({
 
 **instance** (`Sandbox`): The underlying Daytona Sandbox instance. Throws SandboxNotReadyError if the sandbox has not been started.
 
-## Methods
+**processes** (`DaytonaProcessManager`): Background process manager. See \[SandboxProcessManager reference]\(/reference/workspace/process-manager).
 
-### `start()`
+## Background processes
 
-Create and start the Daytona sandbox.
+`DaytonaSandbox` includes a built-in process manager for spawning and managing background processes. Processes run in the Daytona cloud sandbox using session-based command execution.
 
 ```typescript
+const sandbox = new DaytonaSandbox({ language: 'typescript' })
 await sandbox.start()
-```
-
-Called automatically on first command execution or by `workspace.init()`.
-
-### `stop()`
-
-Stop the sandbox. The sandbox can be restarted later — files and state persist.
-
-```typescript
-await sandbox.stop()
-```
-
-### `destroy()`
-
-Delete the sandbox and clean up all resources.
 
-```typescript
-await sandbox.destroy()
-```
-
-### `executeCommand(command, args?, options?)`
-
-Execute a shell command in the sandbox. Automatically starts the sandbox if not already running, and retries once if the sandbox has timed out.
-
-```typescript
-const result = await sandbox.executeCommand('node', ['-e', 'console.log("Hello!")'])
-const output = await sandbox.executeCommand('pip', ['install', 'requests'], {
-  timeout: 60_000,
-  cwd: '/workspace',
-})
-
-// Stream output in real time
-await sandbox.executeCommand('bash', ['-c', 'for i in 1 2 3; do echo "line $i"; sleep 1; done'], {
-  onStdout: chunk => process.stdout.write(chunk),
-  onStderr: chunk => process.stderr.write(chunk),
+// Spawn a background process
+const handle = await sandbox.processes.spawn('node server.js', {
+  env: { PORT: '3000' },
+  onStdout: data => console.log(data),
 })
-```
-
-**Parameters:**
-
-**command** (`string`): Command to execute.
-
-**args** (`string[]`): Command arguments.
-
-**options.timeout** (`number`): Execution timeout in milliseconds. Overrides the instance default.
-
-**options.cwd** (`string`): Working directory for the command.
-
-**options.env** (`Record<string, string>`): Additional environment variables for this command. Merged with instance-level env.
-
-**options.onStdout** (`(data: string) => void`): Callback for stdout streaming.
 
-**options.onStderr** (`(data: string) => void`): Callback for stderr streaming.
-
-### `mount(filesystem, mountPath)`
-
-Mount a filesystem at a path in the sandbox using FUSE tools (`s3fs` for S3, `gcsfuse` for GCS). FUSE tools are installed automatically if not present.
-
-```typescript
-import { S3Filesystem } from '@mastra/s3'
-
-const result = await sandbox.mount(
-  new S3Filesystem({
-    bucket: process.env.S3_BUCKET!,
-    region: 'us-east-1',
-    accessKeyId: process.env.S3_ACCESS_KEY_ID,
-    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
-  }),
-  '/data',
-)
-// { success: true, mountPath: '/data' }
-```
-
-Returns a `MountResult`: `{ success: boolean; mountPath: string; error?: string }`.
-
-### `unmount(mountPath)`
-
-Unmount a filesystem from a path in the sandbox.
-
-```typescript
-await sandbox.unmount('/data')
+// Interact with the process
+console.log(handle.stdout)
+await handle.sendStdin('input\n')
+await handle.kill()
 ```
 
-### `getInfo()`
-
-Get sandbox status and resource information.
-
-```typescript
-const info = await sandbox.getInfo()
-// {
-//   id: 'daytona-sandbox-abc123',
-//   name: 'DaytonaSandbox',
-//   provider: 'daytona',
-//   status: 'running',
-//   createdAt: Date,
-//   mounts: [],
-//   resources: {
-//     cpuCores: 2,        // vCPU count from the running sandbox
-//     memoryMB: 4096,     // converted from GB (×1024)
-//     diskMB: 20480,      // converted from GiB (×1024)
-//   },
-//   metadata: {
-//     language: 'typescript',
-//     ephemeral: false,
-//     snapshot: 'my-snapshot-id',   // only when snapshot is set
-//     image: 'node:20-slim',        // only when image is set
-//     target: 'us',                 // only when sandbox is running
-//   },
-// }
-```
-
-### `getInstructions()`
-
-Get a description of the sandbox environment. Used in tool descriptions so agents understand the execution context.
-
-```typescript
-// Default (no options)
-new DaytonaSandbox().getInstructions()
-// 'Cloud sandbox with isolated execution (typescript runtime). Default working directory: /home/daytona. Command timeout: 300s. Running as user: daytona.'
-
-// All options set
-new DaytonaSandbox({
-  language: 'python',
-  timeout: 60_000,
-  user: 'app',
-  volumes: [{ volumeId: 'vol-123', mountPath: '/data' }],
-  networkBlockAll: true,
-}).getInstructions()
-// 'Cloud sandbox with isolated execution (python runtime). Default working directory: /home/daytona. Command timeout: 60s. Running as user: app. 1 volume(s) attached. Network access is blocked.'
-```
+See [`SandboxProcessManager` reference](https://mastra.ai/reference/workspace/process-manager) for the full API.
 
-## Mounting Cloud Storage
+## Mounting cloud storage
 
 Daytona sandboxes can mount S3 or GCS buckets, making cloud storage accessible as local directories inside the sandbox. This is useful for:
 
@@ -557,7 +465,7 @@ await daytonaSandbox.fs.uploadFile(Buffer.from('hello'), '/tmp/hello.txt')
 await daytonaSandbox.git.clone('https://github.com/org/repo', '/workspace/repo')
 ```
 
-The `instance` getter throws `SandboxNotReadyError` if the sandbox has not been started yet.
+The `instance` getter throws `SandboxNotReadyError` if the sandbox hasn't been started yet.
 
 ## Sandbox creation modes
 
@@ -573,6 +481,7 @@ Resources are only applied when `image` is set. Passing `resources` without `ima
 
 ## Related
 
+- [SandboxProcessManager reference](https://mastra.ai/reference/workspace/process-manager)
 - [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox)
 - [LocalSandbox reference](https://mastra.ai/reference/workspace/local-sandbox)
 - [S3Filesystem reference](https://mastra.ai/reference/workspace/s3-filesystem)

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

@@ -6,10 +6,30 @@ Executes commands in isolated [E2B](https://e2b.dev) cloud sandboxes. Provides s
 
 ## Installation
 
+**npm**:
+
 ```bash
 npm install @mastra/e2b
 ```
 
+**pnpm**:
+
+```bash
+pnpm add @mastra/e2b
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/e2b
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/e2b
+```
+
 ## Usage
 
 Add an `E2BSandbox` to a workspace and assign it to an agent:
@@ -63,97 +83,40 @@ const agent = new Agent({
 
 **supportsMounting** (`boolean`): Always true - E2B sandboxes support mounting cloud filesystems
 
-## Methods
+**processes** (`E2BProcessManager`): Background process manager. See \[SandboxProcessManager reference]\(/reference/workspace/process-manager).
 
-### `start()`
+## Background processes
 
-Initialize and start the sandbox. Creates the E2B sandbox instance and mounts any configured filesystems.
+`E2BSandbox` includes a built-in process manager for spawning and managing background processes. Processes run in the E2B cloud sandbox using the E2B SDK's `commands.run()` with `background: true`.
 
 ```typescript
+const sandbox = new E2BSandbox({ id: 'dev-sandbox' })
 await sandbox.start()
-```
-
-Called automatically on first command execution or by `workspace.init()`.
-
-### `stop()`
-
-Stop the sandbox and release resources.
-
-```typescript
-await sandbox.stop()
-```
-
-### `destroy()`
-
-Clean up sandbox resources completely.
-
-```typescript
-await sandbox.destroy()
-```
 
-### `executeCommand(command, args?, options?)`
-
-Execute a shell command in the sandbox.
-
-```typescript
-const result = await sandbox.executeCommand('ls', ['-la'])
-const npmResult = await sandbox.executeCommand('npm', ['install', 'lodash'], {
-  timeout: 60000,
-  cwd: '/app',
+// Spawn a background process
+const handle = await sandbox.processes.spawn('node server.js', {
+  env: { PORT: '3000' },
+  onStdout: data => console.log(data),
 })
-```
-
-**Parameters:**
-
-**command** (`string`): Command to execute
-
-**args** (`string[]`): Command arguments
-
-**options.timeout** (`number`): Execution timeout in milliseconds
-
-**options.cwd** (`string`): Working directory for the command
-
-**options.env** (`Record<string, string>`): Additional environment variables
-
-**options.onStdout** (`(data: string) => void`): Callback for stdout streaming
-
-**options.onStderr** (`(data: string) => void`): Callback for stderr streaming
-
-### `canMount(filesystem)`
 
-Check if a filesystem can be mounted into this sandbox.
-
-```typescript
-const canMount = sandbox.canMount(s3Filesystem)
-// true for S3Filesystem and GCSFilesystem
-```
-
-### `mount(filesystem, mountPath)`
-
-Mount a filesystem into the sandbox at the specified path.
-
-```typescript
-await sandbox.mount(s3Filesystem, '/mnt/data')
+// Interact with the process
+console.log(handle.stdout)
+await handle.sendStdin('input\n')
+await handle.kill()
 ```
 
-### `unmount(mountPath)`
-
-Unmount a previously mounted filesystem.
+The E2B process manager supports reconnecting to processes that were spawned externally or before a reconnection. Call `get(pid)` with a PID to connect to an existing process:
 
 ```typescript
-await sandbox.unmount('/mnt/data')
+const handle = await sandbox.processes.get(existingPid)
+if (handle) {
+  console.log(handle.stdout)
+}
 ```
 
-### `getInfo()`
-
-Get sandbox status and resource information.
-
-```typescript
-const info = await sandbox.getInfo()
-// { id: '...', name: 'E2BSandbox', provider: 'e2b', status: 'ready', supportsMounting: true }
-```
+See [`SandboxProcessManager` reference](https://mastra.ai/reference/workspace/process-manager) for the full API.
 
-## Mounting Cloud Storage
+## Mounting cloud storage
 
 E2B sandboxes can mount S3 or GCS filesystems, making cloud storage accessible as local directories inside the sandbox. This is useful for:
 
@@ -200,7 +163,7 @@ E2B sandboxes use FUSE (Filesystem in Userspace) to mount cloud storage:
 
 The E2B sandbox automatically installs the required FUSE tools when mounting is used. For best performance, pre-build a custom template with the tools installed.
 
-## Custom Templates
+## Custom templates
 
 By default, when no template is specified, E2BSandbox automatically builds a template with `s3fs` installed for S3 mounting support. This template is cached and reused across sandbox instances.
 
@@ -282,6 +245,7 @@ This is optional—`gcsfuse` is installed automatically at mount time if not pre
 
 ## Related
 
+- [SandboxProcessManager reference](https://mastra.ai/reference/workspace/process-manager)
 - [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox)
 - [LocalSandbox reference](https://mastra.ai/reference/workspace/local-sandbox)
 - [S3Filesystem reference](https://mastra.ai/reference/workspace/s3-filesystem)

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

@@ -19,7 +19,9 @@ const buffer = await filesystem.readFile('/image.png', { encoding: 'binary' })
 
 **path** (`string`): File path relative to basePath
 
-**options.encoding** (`'utf-8' | 'binary'`): Text or binary encoding (Default: `'utf-8'`)
+**options** (`Options`): readFile options.
+
+**options.encoding** (`'utf-8' | 'binary'`): Text or binary encoding
 
 **Returns:** `Promise<string | Buffer>`
 
@@ -38,9 +40,11 @@ await filesystem.writeFile('/nested/path/file.md', content, { recursive: true })
 
 **content** (`string | Buffer`): File content
 
-**options.recursive** (`boolean`): Create parent directories if they don't exist (Default: `false`)
+**options** (`Options`): Configuration options.
+
+**options.recursive** (`boolean`): Create parent directories if they don't exist
 
-**options.overwrite** (`boolean`): Overwrite existing file (Default: `true`)
+**options.overwrite** (`boolean`): Overwrite existing file
 
 ### `deleteFile(path, options?)`
 
@@ -55,11 +59,13 @@ await filesystem.deleteFile('/docs/maybe.md', { force: true }) // Don't throw if
 
 **path** (`string`): File path
 
-**options.force** (`boolean`): Don't throw error if file doesn't exist (Default: `false`)
+**options** (`Options`): Configuration options.
+
+**options.force** (`boolean`): Don't throw error if file doesn't exist
 
 ### `appendFile(path, content)`
 
-Append content to a file, creating it if it does not already exist. Parent directories are created automatically.
+Append content to a file, creating it if it doesn't already exist. Parent directories are created automatically.
 
 ```typescript
 await filesystem.appendFile('/logs/app.log', 'New log entry\n')
@@ -85,7 +91,9 @@ await filesystem.copyFile('/docs/template.md', '/docs/new-doc.md')
 
 **dest** (`string`): Destination file path
 
-**options.overwrite** (`boolean`): Overwrite destination if it exists (Default: `true`)
+**options** (`Options`): Configuration options.
+
+**options.overwrite** (`boolean`): Overwrite destination if it exists
 
 ### `moveFile(src, dest, options?)`
 
@@ -101,7 +109,9 @@ await filesystem.moveFile('/docs/draft.md', '/docs/final.md')
 
 **dest** (`string`): Destination file path
 
-**options.overwrite** (`boolean`): Overwrite destination if it exists (Default: `true`)
+**options** (`Options`): Configuration options.
+
+**options.overwrite** (`boolean`): Overwrite destination if it exists
 
 ### `readdir(path, options?)`
 
@@ -137,7 +147,9 @@ await filesystem.mkdir('/deeply/nested/path', { recursive: true })
 
 **path** (`string`): Directory path
 
-**options.recursive** (`boolean`): Create parent directories (Default: `false`)
+**options** (`Options`): Configuration options.
+
+**options.recursive** (`boolean`): Create parent directories
 
 ### `rmdir(path, options?)`
 
@@ -152,9 +164,11 @@ await filesystem.rmdir('/docs/nested', { recursive: true })
 
 **path** (`string`): Directory path
 
-**options.recursive** (`boolean`): Remove contents recursively (Default: `false`)
+**options** (`Options`): Configuration options.
+
+**options.recursive** (`boolean`): Remove contents recursively
 
-**options.force** (`boolean`): Don't throw if directory doesn't exist (Default: `false`)
+**options.force** (`boolean`): Don't throw if directory doesn't exist
 
 ### `exists(path)`
 
@@ -189,7 +203,7 @@ interface FileStat {
 }
 ```
 
-## Optional Methods
+## Optional methods
 
 ### `init()`
 

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

@@ -6,10 +6,30 @@ Stores files in Google Cloud Storage.
 
 ## Installation
 
+**npm**:
+
 ```bash
 npm install @mastra/gcs
 ```
 
+**pnpm**:
+
+```bash
+pnpm add @mastra/gcs
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/gcs
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/gcs
+```
+
 ## Usage
 
 Add a `GCSFilesystem` to a workspace and assign it to an agent:
@@ -143,7 +163,7 @@ const config = filesystem.getMountConfig()
 // { type: 'gcs', bucket: 'my-bucket', ... }
 ```
 
-## Mounting in E2B Sandboxes
+## Mounting in E2B sandboxes
 
 GCSFilesystem can be mounted into E2B sandboxes, making the bucket accessible as a local directory:
 

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

@@ -116,7 +116,9 @@ const buffer = await filesystem.readFile('/image.png', { encoding: 'binary' })
 
 **path** (`string`): File path relative to basePath
 
-**options.encoding** (`'utf-8' | 'binary'`): Text or binary encoding (Default: `'utf-8'`)
+**options** (`Options`): Configuration options.
+
+**options.encoding** (`'utf-8' | 'binary'`): Text or binary encoding
 
 ### `writeFile(path, content, options?)`
 
@@ -133,9 +135,11 @@ await filesystem.writeFile('/nested/path/file.md', content, { recursive: true })
 
 **content** (`string | Buffer`): File content
 
-**options.recursive** (`boolean`): Create parent directories if they don't exist (Default: `false`)
+**options** (`Options`): Configuration options.
+
+**options.recursive** (`boolean`): Create parent directories if they don't exist
 
-**options.overwrite** (`boolean`): Overwrite existing file (Default: `true`)
+**options.overwrite** (`boolean`): Overwrite existing file
 
 ### `appendFile(path, content)`
 
@@ -164,7 +168,9 @@ await filesystem.deleteFile('/docs/maybe.md', { force: true }) // Don't throw if
 
 **path** (`string`): File path
 
-**options.force** (`boolean`): Don't throw error if file doesn't exist (Default: `false`)
+**options** (`Options`): Configuration options.
+
+**options.force** (`boolean`): Don't throw error if file doesn't exist
 
 ### `copyFile(src, dest, options?)`
 
@@ -181,7 +187,9 @@ await filesystem.copyFile('/src/config.json', '/backup/config.json', { overwrite
 
 **dest** (`string`): Destination file path
 
-**options.overwrite** (`boolean`): Overwrite destination if it exists (Default: `true`)
+**options** (`Options`): Configuration options.
+
+**options.overwrite** (`boolean`): Overwrite destination if it exists
 
 ### `moveFile(src, dest, options?)`
 
@@ -198,7 +206,9 @@ await filesystem.moveFile('/temp/upload.txt', '/files/document.txt')
 
 **dest** (`string`): Destination file path
 
-**options.overwrite** (`boolean`): Overwrite destination if it exists (Default: `true`)
+**options** (`Options`): Configuration options.
+
+**options.overwrite** (`boolean`): Overwrite destination if it exists
 
 ### `mkdir(path, options?)`
 
@@ -213,7 +223,9 @@ await filesystem.mkdir('/deeply/nested/path', { recursive: true })
 
 **path** (`string`): Directory path
 
-**options.recursive** (`boolean`): Create parent directories (Default: `false`)
+**options** (`Options`): Configuration options.
+
+**options.recursive** (`boolean`): Create parent directories
 
 ### `rmdir(path, options?)`
 
@@ -228,9 +240,11 @@ await filesystem.rmdir('/docs/nested', { recursive: true })
 
 **path** (`string`): Directory path
 
-**options.recursive** (`boolean`): Remove contents recursively (Default: `false`)
+**options** (`Options`): Configuration options.
+
+**options.recursive** (`boolean`): Remove contents recursively
 
-**options.force** (`boolean`): Don't throw if directory doesn't exist (Default: `false`)
+**options.force** (`boolean`): Don't throw if directory doesn't exist
 
 ### `readdir(path, options?)`
 
@@ -292,7 +306,7 @@ To override the default output, pass an `instructions` option to the constructor
 
 ## Path resolution
 
-### How basePath works
+### How `basePath` works
 
 The `basePath` option sets the root directory for all file operations. File paths passed to methods like `readFile()` are resolved relative to this base: