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

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

@@ -0,0 +1,164 @@
+# BlaxelSandbox
+
+Executes commands in isolated [Blaxel](https://blaxel.ai/) cloud sandboxes. Provides secure, isolated code execution environments with support for mounting cloud storage (S3, GCS) via FUSE.
+
+> **Info:** For interface details, see [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox).
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/blaxel
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/blaxel
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/blaxel
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/blaxel
+```
+
+## Usage
+
+Add a `BlaxelSandbox` to a workspace and assign it to an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Workspace } from '@mastra/core/workspace'
+import { BlaxelSandbox } from '@mastra/blaxel'
+
+const workspace = new Workspace({
+  sandbox: new BlaxelSandbox(),
+})
+
+const agent = new Agent({
+  id: 'code-agent',
+  name: 'Code Agent',
+  instructions: 'You are a coding assistant working in this workspace.',
+  model: 'anthropic/claude-sonnet-4-6',
+  workspace,
+})
+```
+
+### Custom image with resources
+
+Use a custom Docker image with additional memory:
+
+```typescript
+const workspace = new Workspace({
+  sandbox: new BlaxelSandbox({
+    image: 'node:20-slim',
+    memory: 8192,
+    timeout: '10m',
+  }),
+})
+```
+
+## Constructor parameters
+
+**id** (`string`): Unique identifier for this sandbox instance. (Default: `Auto-generated`)
+
+**image** (`string`): Docker image to use for the sandbox. Debian-based images support both S3 and GCS mounts. Alpine-based images support S3 mounts only. (Default: `'blaxel/ts-app:latest'`)
+
+**memory** (`number`): Memory allocation in MB. (Default: `4096`)
+
+**timeout** (`string`): Execution timeout as a duration string (e.g. '5m', '1h'). Maps to the Blaxel sandbox TTL.
+
+**env** (`Record<string, string>`): Environment variables to set in the sandbox.
+
+**labels** (`Record<string, string>`): Custom labels for the sandbox.
+
+**runtimes** (`SandboxRuntime[]`): Supported runtimes. Valid values: 'node', 'python', 'bash', 'ruby', 'go', 'rust', 'java', 'cpp', 'r'. (Default: `['node', 'python', 'bash']`)
+
+**ports** (`Array<{ name?: string; target: number; protocol?: 'HTTP' | 'TCP' | 'UDP' }>`): Ports to expose from the sandbox.
+
+## Properties
+
+**id** (`string`): Sandbox instance identifier.
+
+**name** (`string`): 'BlaxelSandbox'
+
+**provider** (`string`): 'blaxel'
+
+**status** (`ProviderStatus`): 'pending' | 'initializing' | 'running' | 'stopped' | 'error'
+
+**instance** (`SandboxInstance`): The underlying Blaxel SandboxInstance for direct access to Blaxel APIs. Throws SandboxNotReadyError if the sandbox has not been started.
+
+**processes** (`BlaxelProcessManager`): Background process manager. See \[SandboxProcessManager reference]\(/reference/workspace/process-manager).
+
+## Background processes
+
+`BlaxelSandbox` includes a built-in process manager for spawning and managing background processes.
+
+```typescript
+const sandbox = new BlaxelSandbox({ id: 'dev-sandbox' })
+await sandbox.start()
+
+// Spawn a background process
+const handle = await sandbox.processes.spawn('node server.js', {
+  env: { PORT: '3000' },
+  onStdout: data => console.log(data),
+})
+
+// Interact with the process
+console.log(handle.stdout)
+await handle.kill()
+```
+
+> **Note:** Blaxel sandboxes don't support stdin. Calling `handle.sendStdin()` throws an error.
+
+See [`SandboxProcessManager` reference](https://mastra.ai/reference/workspace/process-manager) for the full API.
+
+## Mounting cloud storage
+
+Blaxel sandboxes can mount S3 or GCS filesystems, making cloud storage accessible as a local directory inside the sandbox.
+
+### S3
+
+```typescript
+import { Workspace } from '@mastra/core/workspace'
+import { S3Filesystem } from '@mastra/s3'
+import { BlaxelSandbox } from '@mastra/blaxel'
+
+const workspace = new Workspace({
+  mounts: {
+    '/data': new S3Filesystem({
+      bucket: 'my-bucket',
+      region: 'us-east-1',
+      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+    }),
+  },
+  sandbox: new BlaxelSandbox(),
+})
+```
+
+### GCS
+
+```typescript
+import { Workspace } from '@mastra/core/workspace'
+import { GCSFilesystem } from '@mastra/gcs'
+import { BlaxelSandbox } from '@mastra/blaxel'
+
+const workspace = new Workspace({
+  mounts: {
+    '/data': new GCSFilesystem({
+      bucket: 'my-bucket',
+      credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY!),
+    }),
+  },
+  sandbox: new BlaxelSandbox(),
+})
+```

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
 
@@ -296,144 +319,29 @@ 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
 
@@ -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,95 +83,38 @@ 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
 
@@ -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)`
 

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: