@mastra/mcp-docs-server 1.1.4 → 1.1.5-alpha.0

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

@@ -1,285 +0,0 @@
-# LocalSandbox
-
-**Added in:** `@mastra/core@1.1.0`
-
-Executes commands on the local system.
-
-> **Info:** For interface details, see [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox).
-
-## Usage
-
-Add a `LocalSandbox` to a workspace and assign it to an agent. The agent can then execute shell commands as part of its tasks:
-
-```typescript
-import { Agent } from '@mastra/core/agent';
-import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace';
-
-const workspace = new Workspace({
-  filesystem: new LocalFilesystem({ basePath: './workspace' }),
-  sandbox: new LocalSandbox({
-    workingDirectory: './workspace',
-    env: {
-      NODE_ENV: 'development',
-    },
-  }),
-});
-
-const agent = new Agent({
-  id: 'dev-agent',
-  model: 'openai/gpt-4o',
-  workspace,
-});
-
-// The agent now has the execute_command tool available
-const response = await agent.generate('Run npm install');
-```
-
-### Auto-start behavior
-
-`LocalSandbox` automatically starts on the first command execution if not already running. You can also explicitly start the sandbox by calling `workspace.init()` at application startup to avoid first-command latency.
-
-## Constructor parameters
-
-**id?:** (`string`): Unique identifier for this sandbox instance (Default: `Auto-generated`)
-
-**workingDirectory?:** (`string`): Directory for command execution. Defaults to .sandbox/ in process.cwd() for isolation from seatbelt profiles. (Default: `process.cwd()/.sandbox/`)
-
-**env?:** (`NodeJS.ProcessEnv`): Environment variables to set. PATH is included by default unless overridden.
-
-**timeout?:** (`number`): Default timeout for operations in milliseconds (Default: `30000`)
-
-**isolation?:** (`'none' | 'seatbelt' | 'bwrap'`): Native OS sandboxing backend. 'seatbelt' for macOS, 'bwrap' for Linux. (Default: `'none'`)
-
-**nativeSandbox?:** (`NativeSandboxConfig`): Configuration for native sandboxing (see NativeSandboxConfig below).
-
-## NativeSandboxConfig
-
-Configuration options for native OS sandboxing (used with `isolation: 'seatbelt'` or `'bwrap'`).
-
-**allowNetwork?:** (`boolean`): Allow network access from sandboxed commands. (Default: `false`)
-
-**readOnlyPaths?:** (`string[]`): Additional paths to allow read-only access (system paths are always readable).
-
-**readWritePaths?:** (`string[]`): Additional paths to allow read-write access beyond the workspace directory.
-
-**seatbeltProfilePath?:** (`string`): Path to a custom seatbelt profile file (macOS only). If the file exists, it's used; if not, a default profile is generated and written to this path.
-
-**bwrapArgs?:** (`string[]`): Additional arguments to pass to bwrap (Linux only).
-
-**allowSystemBinaries?:** (`boolean`): Allow read access to standard system binary paths (/bin, /usr/bin, etc.). (Default: `true`)
-
-## Properties
-
-**id:** (`string`): Sandbox instance identifier
-
-**name:** (`string`): Provider name ('LocalSandbox')
-
-**provider:** (`string`): Provider identifier ('local')
-
-**status:** (`ProviderStatus`): 'starting' | 'running' | 'stopped' | 'error'
-
-**workingDirectory:** (`string`): The configured working directory
-
-## Methods
-
-### `start()`
-
-Initialize and start the sandbox. Creates the working directory and sets up seatbelt profiles if using native isolation.
-
-```typescript
-await sandbox.start();
-```
-
-Called automatically by `workspace.init()` or on first `executeCommand()` call.
-
-### `stop()`
-
-Stop the sandbox.
-
-```typescript
-await sandbox.stop();
-```
-
-### `destroy()`
-
-Clean up sandbox resources. Removes seatbelt profiles if they were auto-generated.
-
-```typescript
-await sandbox.destroy();
-```
-
-Called by `workspace.destroy()`.
-
-### `isReady()`
-
-Check if the sandbox is ready for operations.
-
-```typescript
-const ready = await sandbox.isReady();
-// true if status is 'running'
-```
-
-### `executeCommand(command, args?, options?)`
-
-Execute a shell command in the sandbox.
-
-```typescript
-const listResult = await sandbox.executeCommand('ls', ['-la']);
-const installResult = await sandbox.executeCommand('npm', ['install', 'lodash'], {
-  timeout: 60000,
-  env: { NODE_ENV: 'development' },
-});
-```
-
-**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
-
-### `getInfo()`
-
-Get sandbox status and resource information.
-
-```typescript
-const info = await sandbox.getInfo();
-// { status: 'running', resources: { ... } }
-```
-
-### `getInstructions()`
-
-Returns a description of how this sandbox works. Used in tool descriptions.
-
-```typescript
-const instructions = sandbox.getInstructions();
-// 'Local command execution. Working directory: "/workspace".'
-```
-
-## Path Resolution
-
-### Relative paths and execution context
-
-When you use a relative path for `workingDirectory`, it resolves from `process.cwd()`. In Mastra projects, cwd varies depending on how you run your code:
-
-| Context        | Working directory         | `./workspace` resolves to       |
-| -------------- | ------------------------- | ------------------------------- |
-| `mastra dev`   | `./src/mastra/public/`    | `./src/mastra/public/workspace` |
-| `mastra start` | `./.mastra/output/`       | `./.mastra/output/workspace`    |
-| Direct script  | Where you ran the command | Relative to that location       |
-
-This can cause confusion when the same relative path resolves to different locations.
-
-### Recommended: Use absolute paths
-
-For consistent paths across all execution contexts, use an environment variable with an absolute path:
-
-```typescript
-import { LocalSandbox } from '@mastra/core/workspace';
-
-const sandbox = new LocalSandbox({
-  workingDirectory: process.env.WORKSPACE_PATH!,
-});
-```
-
-Set `WORKSPACE_PATH` in your environment to an absolute path like `/home/user/my-project/workspace`. This ensures commands run from a consistent directory regardless of how you run your code.
-
-## Static Methods
-
-### `detectIsolation()`
-
-Detect the best available isolation backend for the current platform.
-
-```typescript
-const detection = LocalSandbox.detectIsolation();
-// { backend: 'seatbelt', available: true, message: 'Seatbelt available on macOS' }
-```
-
-## Environment Isolation
-
-By default, `LocalSandbox` only includes `PATH` in the environment. This allows commands to run while preventing accidental exposure of API keys and secrets.
-
-```typescript
-// Default: only PATH is available (commands work, secrets protected)
-const secureSandbox = new LocalSandbox({
-  workingDirectory: './workspace',
-});
-
-// Explicit: pass specific variables
-const sandbox = new LocalSandbox({
-  workingDirectory: './workspace',
-  env: {
-    NODE_ENV: 'development',
-    API_URL: 'https://api.example.com',
-  },
-});
-
-// Full access (use with caution)
-const devSandbox = new LocalSandbox({
-  workingDirectory: './workspace',
-  env: process.env,
-});
-```
-
-## Native OS Sandboxing
-
-`LocalSandbox` supports native OS-level sandboxing for additional security:
-
-- **macOS**: Uses Seatbelt (`sandbox-exec`) for filesystem and network isolation
-- **Linux**: Uses Bubblewrap (`bwrap`) for namespace isolation
-
-```typescript
-// Detect the best available backend for this platform
-const detection = LocalSandbox.detectIsolation();
-console.log(detection);
-// { backend: 'seatbelt', available: true, message: '...' }
-
-// Enable native sandboxing
-const sandbox = new LocalSandbox({
-  workingDirectory: './workspace',
-  isolation: 'seatbelt', // or 'bwrap' on Linux
-  nativeSandbox: {
-    allowNetwork: false, // Block network access (default)
-    readWritePaths: ['/tmp/extra'], // Additional writable paths
-  },
-});
-```
-
-When isolation is enabled:
-
-- File writes are restricted to the workspace directory (and configured paths)
-- File reads are allowed everywhere (needed for system binaries)
-- Network access is blocked by default
-- Process isolation prevents affecting the host system
-
-### Sandbox profile location
-
-When using seatbelt isolation on macOS, `LocalSandbox` generates a profile file in a `.sandbox-profiles/` folder in `process.cwd()`, separate from the working directory:
-
-```text
-project/
-├── .sandbox/                      # Default working directory (sandboxed)
-│   └── ... files created by sandbox
-├── .sandbox-profiles/             # Seatbelt profiles (outside sandbox)
-│   └── seatbelt-a1b2c3d4.sb       # Hash based on workspace + config
-└── ... your project files
-```
-
-The profile filename is a hash of the workspace path and configuration, so sandboxes with identical settings share the same profile while different configurations get separate files. This prevents collisions when running multiple sandboxes concurrently.
-
-This separation prevents sandboxed processes from reading or modifying their own security profiles. The profile is created when the sandbox starts and cleaned up when destroyed.
-
-## Related
-
-- [WorkspaceSandbox Interface](https://mastra.ai/reference/workspace/sandbox)
-- [Workspace Class](https://mastra.ai/reference/workspace/workspace-class)
-- [Workspace Overview](https://mastra.ai/docs/workspace/overview)

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

@@ -1,169 +0,0 @@
-# S3Filesystem
-
-Stores files in Amazon S3 or S3-compatible storage services like Cloudflare R2, MinIO, and DigitalOcean Spaces.
-
-> **Info:** For interface details, see [WorkspaceFilesystem Interface](https://mastra.ai/reference/workspace/filesystem).
-
-## Installation
-
-```bash
-npm install @mastra/s3
-```
-
-## Usage
-
-Add an `S3Filesystem` to a workspace and assign it to an agent:
-
-```typescript
-import { Agent } from '@mastra/core/agent';
-import { Workspace } from '@mastra/core/workspace';
-import { S3Filesystem } from '@mastra/s3';
-
-const workspace = new Workspace({
-  filesystem: new S3Filesystem({
-    bucket: 'my-bucket',
-    region: 'us-east-1',
-    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
-    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
-  }),
-});
-
-const agent = new Agent({
-  name: 'file-agent',
-  model: 'anthropic/claude-opus-4-5',
-  workspace,
-});
-```
-
-### Cloudflare R2
-
-```typescript
-import { S3Filesystem } from '@mastra/s3';
-
-const filesystem = new S3Filesystem({
-  bucket: 'my-r2-bucket',
-  region: 'auto',
-  endpoint: `https://${process.env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
-  accessKeyId: process.env.R2_ACCESS_KEY_ID,
-  secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
-});
-```
-
-### MinIO
-
-```typescript
-import { S3Filesystem } from '@mastra/s3';
-
-const filesystem = new S3Filesystem({
-  bucket: 'my-bucket',
-  region: 'us-east-1',
-  endpoint: 'http://localhost:9000',
-  accessKeyId: 'minioadmin',
-  secretAccessKey: 'minioadmin',
-});
-```
-
-## Constructor parameters
-
-**bucket:** (`string`): S3 bucket name
-
-**region:** (`string`): AWS region (use 'auto' for R2)
-
-**accessKeyId?:** (`string`): AWS access key ID. Optional for public buckets (read-only access).
-
-**secretAccessKey?:** (`string`): AWS secret access key. Optional for public buckets (read-only access).
-
-**endpoint?:** (`string`): Custom endpoint URL for S3-compatible storage (R2, MinIO, etc.)
-
-**prefix?:** (`string`): Optional prefix for all keys (acts like a subdirectory)
-
-**id?:** (`string`): Unique identifier for this filesystem instance (Default: `Auto-generated`)
-
-**displayName?:** (`string`): Human-friendly display name for the UI
-
-**readOnly?:** (`boolean`): When true, all write operations are blocked (Default: `false`)
-
-## Properties
-
-**id:** (`string`): Filesystem instance identifier
-
-**name:** (`string`): Provider name ('S3Filesystem')
-
-**provider:** (`string`): Provider identifier ('s3')
-
-**bucket:** (`string`): The S3 bucket name
-
-**readOnly:** (`boolean | undefined`): Whether the filesystem is in read-only mode
-
-## Methods
-
-S3Filesystem implements the [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem), providing all standard filesystem methods:
-
-- `readFile(path, options?)` - Read file contents
-- `writeFile(path, content, options?)` - Write content to a file
-- `appendFile(path, content)` - Append content to a file
-- `deleteFile(path, options?)` - Delete a file
-- `copyFile(src, dest, options?)` - Copy a file
-- `moveFile(src, dest, options?)` - Move or rename a file
-- `mkdir(path, options?)` - Create a directory
-- `rmdir(path, options?)` - Remove a directory
-- `readdir(path, options?)` - List directory contents
-- `exists(path)` - Check if a path exists
-- `stat(path)` - Get file or directory metadata
-
-### `init()`
-
-Initialize the filesystem. Verifies bucket access and credentials.
-
-```typescript
-await filesystem.init();
-```
-
-### `getInfo()`
-
-Returns metadata about this filesystem instance.
-
-```typescript
-const info = filesystem.getInfo();
-// { id: '...', name: 'S3Filesystem', provider: 's3', status: 'ready' }
-```
-
-### `getMountConfig()`
-
-Returns the mount configuration for sandboxes that support mounting this filesystem type.
-
-```typescript
-const config = filesystem.getMountConfig();
-// { type: 's3', bucket: 'my-bucket', region: 'us-east-1', ... }
-```
-
-## Mounting in E2B Sandboxes
-
-S3Filesystem can be mounted into E2B sandboxes, making the bucket accessible as a local directory:
-
-```typescript
-import { Workspace } from '@mastra/core/workspace';
-import { S3Filesystem } from '@mastra/s3';
-import { E2BSandbox } from '@mastra/e2b';
-
-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 E2BSandbox({ id: 'dev-sandbox' }),
-});
-```
-
-See [E2BSandbox reference](https://mastra.ai/reference/workspace/e2b-sandbox) for more details on mounting.
-
-## Related
-
-- [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem)
-- [GCSFilesystem reference](https://mastra.ai/reference/workspace/gcs-filesystem)
-- [E2BSandbox reference](https://mastra.ai/reference/workspace/e2b-sandbox)
-- [Workspace overview](https://mastra.ai/docs/workspace/overview)

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

@@ -1,81 +0,0 @@
-# WorkspaceSandbox
-
-**Added in:** `@mastra/core@1.1.0`
-
-The `WorkspaceSandbox` interface defines how workspaces execute commands.
-
-## Methods
-
-### `start()`
-
-Start the sandbox. Called automatically by `workspace.init()` or on first `executeCommand()` call.
-
-```typescript
-await sandbox.start();
-```
-
-This method prepares the sandbox for command execution.
-
-### `stop()`
-
-Stop the sandbox.
-
-```typescript
-await sandbox.stop?.();
-```
-
-### `destroy()`
-
-Clean up sandbox resources. Called by `workspace.destroy()`.
-
-```typescript
-await sandbox.destroy();
-```
-
-### `executeCommand(command, args?, options?)`
-
-Execute a shell command.
-
-```typescript
-const result = await sandbox.executeCommand('ls', ['-la', '/docs']);
-const result = await sandbox.executeCommand('npm', ['install', 'lodash']);
-```
-
-**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
-
-### `getInfo()`
-
-Get sandbox status and resource information.
-
-```typescript
-const info = await sandbox.getInfo();
-// { status: 'running', resources: { memoryMB: 512, cpuPercent: 5 } }
-```
-
-### `getInstructions()`
-
-Get a description of how this sandbox works. Used in tool descriptions to help agents understand the execution context.
-
-```typescript
-const instructions = sandbox.getInstructions?.();
-// 'Local command execution. Working directory: "/workspace".'
-```
-
-## Related
-
-- [Workspace Class](https://mastra.ai/reference/workspace/workspace-class)
-- [Filesystem Interface](https://mastra.ai/reference/workspace/filesystem)