@mastra/mcp-docs-server 1.2.4-alpha.1 → 1.2.4-alpha.6

package/.docs/reference/workspace/apple-container-sandbox.md

@@ -0,0 +1,259 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# AppleContainerSandbox
+
+Executes commands inside local OCI Linux containers through Apple's [`container`](https://github.com/apple/container) CLI. The provider starts a long-lived container and uses `container exec` for workspace commands.
+
+> **Info:** For interface details, see [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox).
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/apple-container
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/apple-container
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/apple-container
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/apple-container
+```
+
+Requires an Apple silicon Mac running macOS 26 or newer with Apple's `container` CLI installed. Start the container system before using the provider:
+
+```bash
+container system start
+```
+
+## Usage
+
+Add an `AppleContainerSandbox` to a workspace and assign it to an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Workspace } from '@mastra/core/workspace'
+import { AppleContainerSandbox } from '@mastra/apple-container'
+
+const workspace = new Workspace({
+  sandbox: new AppleContainerSandbox({
+    image: 'node:22-slim',
+    volumes: {
+      '/Users/me/project': '/workspace',
+    },
+    workingDir: '/workspace',
+  }),
+})
+
+const agent = new Agent({
+  id: 'dev-agent',
+  name: 'Dev Agent',
+  instructions: 'You are a coding assistant working in this workspace.',
+  model: 'anthropic/claude-sonnet-4-6',
+  workspace,
+})
+
+const response = await agent.generate('Run `node --version`.')
+console.log(response.text)
+```
+
+## Constructor parameters
+
+**id** (`string`): Unique identifier for this sandbox instance. (Default: `Auto-generated`)
+
+**name** (`string`): Apple container name passed to \`container run --name\`. Characters outside \`\[a-zA-Z0-9\_.-]\` are replaced with \`-\` and the result is prefixed if it would not start with an alphanumeric character. (Default: `` The sandbox `id` ``)
+
+**image** (`string`): OCI image to use for the container. (Default: `'node:22-slim'`)
+
+**command** (`string[]`): Container init command. Must keep the container alive for exec-based command execution. (Default: `['sleep', 'infinity']`)
+
+**env** (`Record<string, string>`): Environment variables to set in the container and on command execs.
+
+**volumes** (`Record<string, string>`): Host-to-container bind mounts. Keys are host paths, values are container paths.
+
+**mounts** (`string[]`): Raw \`container run --mount\` specs.
+
+**network** (`string`): Apple container network attachment spec.
+
+**publishedPorts** (`string[]`): Port publish specs passed as \`--publish\`.
+
+**publishedSockets** (`string[]`): Socket publish specs passed as \`--publish-socket\`.
+
+**cpus** (`number | string`): Number of CPUs to allocate.
+
+**memory** (`string`): Memory allocation, for example '1G'.
+
+**platform** (`string`): OCI platform, for example 'linux/arm64'.
+
+**arch** (`string`): Image architecture when selecting a multi-arch image.
+
+**os** (`string`): Image operating system when selecting a multi-platform image.
+
+**rosetta** (`boolean`): Enable Rosetta in the container. (Default: `false`)
+
+**readonlyRootfs** (`boolean`): Mount the container root filesystem as read-only. (Default: `false`)
+
+**ssh** (`boolean`): Forward the host SSH agent socket. (Default: `false`)
+
+**init** (`boolean`): Enable Apple's init process in the container. (Default: `true`)
+
+**virtualization** (`boolean`): Expose virtualization capabilities to the container. (Default: `false`)
+
+**capAdd** (`string[]`): Linux capabilities to add.
+
+**capDrop** (`string[]`): Linux capabilities to drop.
+
+**tmpfs** (`string[]`): tmpfs destination paths passed as \`--tmpfs\`, for example \`/tmp\`.
+
+**dns** (`string[]`): DNS nameserver IPs.
+
+**dnsSearch** (`string[]`): DNS search domains.
+
+**noDns** (`boolean`): Do not configure DNS in the container. (Default: `false`)
+
+**labels** (`Record<string, string>`): Additional container labels. Mastra labels (mastra.sandbox, mastra.sandbox.id) are always included.
+
+**workingDir** (`string`): Working directory inside the container. (Default: `'/workspace'`)
+
+**timeout** (`number`): Default command timeout in milliseconds. (Default: `300000 (5 minutes)`)
+
+**deleteOnDestroy** (`boolean`): Delete the Apple container when the sandbox is destroyed. When false, destroy stops the container instead. (Default: `true`)
+
+**containerBinary** (`string`): Path or name for the Apple container CLI. (Default: `'container'`)
+
+**instructions** (`string | function`): Custom instructions that override the default instructions returned by getInstructions(). Pass an empty string to suppress instructions.
+
+## Properties
+
+**id** (`string`): Sandbox instance identifier.
+
+**name** (`string`): Provider name ('AppleContainerSandbox').
+
+**provider** (`string`): Provider identifier ('apple-container').
+
+**status** (`ProviderStatus`): 'pending' | 'starting' | 'running' | 'stopping' | 'stopped' | 'destroying' | 'destroyed' | 'error'
+
+**containerId** (`string`): Apple container ID when known, otherwise the configured container name.
+
+## Environment variables
+
+Set environment variables at the container level with `env`. Per-command environment variables can also be passed through `executeCommand` options:
+
+```typescript
+const sandbox = new AppleContainerSandbox({
+  image: 'node:22-slim',
+  env: {
+    NODE_ENV: 'development',
+  },
+})
+
+await sandbox.executeCommand('node', ['-e', 'console.log(process.env.TASK_ID)'], {
+  env: { TASK_ID: '42' },
+})
+```
+
+## Bind mounts
+
+Mount host directories into the container using the `volumes` option:
+
+```typescript
+const sandbox = new AppleContainerSandbox({
+  image: 'node:22-slim',
+  volumes: {
+    '/Users/me/project': '/workspace/project',
+    '/Users/me/.npm': '/root/.npm',
+  },
+})
+```
+
+Bind mounts are applied at container creation time. The host paths must exist before the sandbox starts.
+
+## Resource and platform options
+
+Apple container CLI options can be passed through the constructor:
+
+```typescript
+const sandbox = new AppleContainerSandbox({
+  image: 'node:22-slim',
+  volumes: {
+    '/Users/me/project': '/workspace',
+  },
+  cpus: 2,
+  memory: '2G',
+  platform: 'linux/arm64',
+  readonlyRootfs: true,
+  tmpfs: ['/tmp'],
+})
+```
+
+These options are only applied when a new container is created. If the sandbox reconnects to an existing container with the same name, destroy and recreate the sandbox to apply changed runtime options. Apple `--tmpfs` accepts container paths only, such as `/tmp`; it does not accept Docker-style option specs like `/tmp:rw,size=256m`. When `readonlyRootfs` is enabled, make sure `workingDir` points to a path supplied by the image, a bind mount, or a writable tmpfs.
+
+## Security model
+
+`AppleContainerSandbox` runs local containers through the host Apple `container` service. Treat constructor options as trusted server-side configuration:
+
+- `volumes`, `mounts`, and `publishedSockets` can expose host paths to containerized code.
+- `publishedPorts` can expose in-container services on the host or network; bind to `127.0.0.1` when only local access is intended.
+- `ssh` forwards the host SSH agent socket.
+- `capAdd` and `virtualization` can expand what containerized code can do.
+- `containerBinary` is a constructor-only escape hatch for trusted code and is not part of the serializable editor provider schema.
+
+Use the narrowest mounts and capabilities your workload needs. Existing containers are only reconnected when they carry Mastra ownership labels for the sandbox ID. Containers created by this provider also include a config-hash label; when that label is present, reconnect fails if immutable runtime options such as image, command, mounts, ports, capabilities, or working directory changed.
+
+## Limitations
+
+`AppleContainerSandbox` implements foreground workspace command execution with `executeCommand()`. It does not yet expose a `SandboxProcessManager` for background processes or LSP sessions.
+
+Command timeouts are enforced inside the container so timed-out commands are cleaned up by the container runtime. Abort signals cancel the host CLI wait path and should not be used as a substitute for command timeouts when in-container cleanup matters.
+
+## Reconnection
+
+`AppleContainerSandbox` reconnects by inspecting a container with the configured name. When `start()` is called:
+
+- A running container is reused.
+- A stopped container is restarted.
+- A missing container is created from the configured image.
+- A container with the configured name but without matching Mastra ownership labels fails instead of being managed.
+- A Mastra-owned container with a config-hash label that does not match immutable runtime options fails instead of being reused.
+
+```typescript
+const sandbox = new AppleContainerSandbox({ id: 'persistent-sandbox' })
+await sandbox.start()
+
+const sandbox2 = new AppleContainerSandbox({ id: 'persistent-sandbox' })
+await sandbox2.start()
+```
+
+## Editor provider
+
+Register the provider with `MastraEditor` to hydrate stored sandbox configs:
+
+```typescript
+import { MastraEditor } from '@mastra/editor'
+import { appleContainerSandboxProvider } from '@mastra/apple-container'
+
+const editor = new MastraEditor({
+  sandboxes: {
+    [appleContainerSandboxProvider.id]: appleContainerSandboxProvider,
+  },
+})
+```
+
+## Related
+
+- [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox)
+- [DockerSandbox reference](https://mastra.ai/reference/workspace/docker-sandbox)
+- [LocalSandbox reference](https://mastra.ai/reference/workspace/local-sandbox)
+- [Workspace overview](https://mastra.ai/docs/workspace/overview)

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

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # ArchilFilesystem
 
 Stores files on [Archil](https://docs.archil.com) elastic, serverless disks. Combines an S3-compatible object API for fast reads/writes with `exec()` for POSIX shell operations and `grep()` for parallel server-side search.
@@ -48,6 +50,7 @@ const workspace = new Workspace({
 })
 
 const agent = new Agent({
+  id: 'file-agent',
   name: 'file-agent',
   model: 'anthropic/claude-opus-4-7',
   workspace,

package/.docs/reference/workspace/azure-blob-filesystem.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # AzureBlobFilesystem
 
 Stores files in Azure Blob Storage containers.
@@ -47,6 +49,7 @@ const workspace = new Workspace({
 })
 
 const agent = new Agent({
+  id: 'file-agent',
   name: 'file-agent',
   model: 'anthropic/claude-opus-4-7',
   workspace,

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

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # 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.

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

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # DaytonaSandbox
 
 Executes commands in isolated [Daytona](https://www.daytona.io) cloud sandboxes. Supports multiple runtimes, resource configuration, volumes, snapshots, streaming output, sandbox reconnection, filesystem mounting (S3, GCS), and network isolation.

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

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # DockerSandbox
 
 Executes commands inside Docker containers on the local machine. Uses long-lived containers with `docker exec` for command execution. Targets local development, CI/CD, air-gapped deployments, and cost-sensitive scenarios where cloud sandboxes are unnecessary.
@@ -48,6 +50,7 @@ const workspace = new Workspace({
 })
 
 const agent = new Agent({
+  id: 'dev-agent',
   name: 'dev-agent',
   model: 'anthropic/claude-opus-4-7',
   workspace,

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

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # E2BSandbox
 
 Executes commands in isolated [E2B](https://e2b.dev) cloud sandboxes. Provides secure, ephemeral environments with support for mounting cloud storage.
@@ -47,6 +49,7 @@ const workspace = new Workspace({
 })
 
 const agent = new Agent({
+  id: 'dev-agent',
   name: 'dev-agent',
   model: 'anthropic/claude-opus-4-7',
   workspace,

package/.docs/reference/workspace/files-sdk-filesystem.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # FilesSDKFilesystem
 
 Stores files in any storage backend supported by [FilesSDK](https://files-sdk.dev) — a unified abstraction over S3, Cloudflare R2, Google Cloud Storage, Azure Blob, Vercel Blob, MinIO, the local filesystem, and more.
@@ -57,6 +59,7 @@ const workspace = new Workspace({
 })
 
 const agent = new Agent({
+  id: 'file-agent',
   name: 'file-agent',
   model: 'anthropic/claude-opus-4-7',
   workspace,

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

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # WorkspaceFilesystem
 
 **Added in:** `@mastra/core@1.1.0`

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

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # GCSFilesystem
 
 Stores files in Google Cloud Storage.
@@ -48,6 +50,7 @@ const workspace = new Workspace({
 })
 
 const agent = new Agent({
+  id: 'file-agent',
   name: 'file-agent',
   model: 'anthropic/claude-opus-4-7',
   workspace,

package/.docs/reference/workspace/google-drive-filesystem.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # GoogleDriveFilesystem
 
 Stores files in a single Google Drive folder. Each directory maps to a Drive folder under the configured root, and paths use POSIX semantics (for example `/notes/todo.txt`).

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

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # LocalFilesystem
 
 **Added in:** `@mastra/core@1.1.0`

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

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # LocalSandbox
 
 **Added in:** `@mastra/core@1.1.0`