@mastra/mcp-docs-server 0.0.0-error-handler-fix-20251020202607 → 0.0.0-execa-dynamic-import-20260304221256

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

@@ -0,0 +1,580 @@
+# 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.
+
+> **Info:** For interface details, see [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox).
+
+## Installation
+
+```bash
+npm install @mastra/daytona
+```
+
+Set your Daytona API key in one of three ways:
+
+```bash
+# Shell export
+export DAYTONA_API_KEY=your-api-key
+```
+
+```bash
+# .env file
+DAYTONA_API_KEY=your-api-key
+```
+
+```typescript
+// Passed directly as constructor argument
+new DaytonaSandbox({ apiKey: 'your-api-key' })
+```
+
+## Usage
+
+Add a `DaytonaSandbox` to a workspace and assign it to an agent:
+
+```typescript
+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 })
+
+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,
+})
+
+const response = await agent.generate(
+  'Print "Hello, world!" and show the current working directory.',
+)
+
+console.log(response.text)
+// I'll run both commands simultaneously!
+//
+// Here are the results:
+//
+// 1. **Hello, world!** — Successfully printed the message.
+// 2. **Current Working Directory** — `/home/daytona`
+//
+// Both commands ran in parallel and completed successfully!
+```
+
+### With a snapshot
+
+Use a pre-built snapshot to skip environment setup time:
+
+```typescript
+const workspace = new Workspace({
+  sandbox: new DaytonaSandbox({
+    snapshot: 'my-snapshot-id',
+    timeout: 60_000,
+  }),
+})
+```
+
+### Custom image with resources
+
+Use a custom Docker image with specific resource allocation:
+
+```typescript
+const workspace = new Workspace({
+  sandbox: new DaytonaSandbox({
+    image: 'node:20-slim',
+    resources: { cpu: 2, memory: 4, disk: 6 },
+    language: 'typescript',
+  }),
+})
+```
+
+### Ephemeral sandbox
+
+For one-shot tasks — sandbox is deleted immediately on stop:
+
+```typescript
+const workspace = new Workspace({
+  sandbox: new DaytonaSandbox({
+    ephemeral: true,
+    language: 'python',
+  }),
+})
+```
+
+### Streaming output
+
+Stream command output in real time via `onStdout` and `onStderr` callbacks:
+
+```typescript
+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),
+})
+```
+
+Both callbacks are optional and can be used independently.
+
+### Reconnection
+
+Reconnect to an existing sandbox by providing the same `id`. The sandbox resumes with its files and state intact:
+
+```typescript
+const sandbox = new DaytonaSandbox({ id: 'my-persistent-sandbox' })
+
+// First session
+await sandbox._start()
+await sandbox.executeCommand('sh', ['-c', 'echo "session 1" > /tmp/state.txt'])
+await sandbox._stop()
+
+// Later — reconnects to the same sandbox
+const sandbox2 = new DaytonaSandbox({ id: 'my-persistent-sandbox' })
+await sandbox2._start()
+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.
+
+### Filesystem mounting
+
+Mount S3 or GCS buckets as local directories inside the sandbox.
+
+#### Via workspace mounts config
+
+The simplest way — filesystems are mounted automatically when the sandbox starts:
+
+```typescript
+import { Workspace } from '@mastra/core/workspace'
+import { DaytonaSandbox } from '@mastra/daytona'
+import { GCSFilesystem } from '@mastra/gcs'
+import { S3Filesystem } from '@mastra/s3'
+
+const workspace = new Workspace({
+  mounts: {
+    '/s3-data': new S3Filesystem({
+      bucket: process.env.S3_BUCKET!,
+      region: 'auto',
+      accessKeyId: process.env.S3_ACCESS_KEY_ID,
+      secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
+      endpoint: process.env.S3_ENDPOINT, // e.g. https://<account-id>.r2.cloudflarestorage.com
+    }),
+    '/gcs-data': new GCSFilesystem({
+      bucket: process.env.GCS_BUCKET!,
+      projectId: 'my-project-id',
+      credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY!),
+    }),
+  },
+  sandbox: new DaytonaSandbox({ language: 'python' }),
+})
+```
+
+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()
+
+Mount manually at any point after the sandbox has started:
+
+#### S3
+
+```typescript
+import { S3Filesystem } from '@mastra/s3'
+
+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',
+)
+```
+
+#### S3-compatible (Cloudflare R2, MinIO)
+
+```typescript
+import { S3Filesystem } from '@mastra/s3'
+
+await sandbox.mount(
+  new S3Filesystem({
+    bucket: process.env.S3_BUCKET!,
+    region: 'auto',
+    accessKeyId: process.env.S3_ACCESS_KEY_ID,
+    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
+    endpoint: process.env.S3_ENDPOINT, // e.g. https://<account-id>.r2.cloudflarestorage.com
+  }),
+  '/data',
+)
+```
+
+#### GCS
+
+```typescript
+import { GCSFilesystem } from '@mastra/gcs'
+
+await sandbox.mount(
+  new GCSFilesystem({
+    bucket: process.env.GCS_BUCKET!,
+    projectId: 'my-project-id',
+    credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY!),
+  }),
+  '/data',
+)
+```
+
+### Network isolation
+
+Restrict outbound network access:
+
+```typescript
+const workspace = new Workspace({
+  sandbox: new DaytonaSandbox({
+    networkBlockAll: true,
+    networkAllowList: '10.0.0.0/8,192.168.0.0/16',
+  }),
+})
+```
+
+## Constructor parameters
+
+**id?:** (`string`): Unique identifier for this sandbox instance. (Default: `Auto-generated`)
+
+**apiKey?:** (`string`): Daytona API key for authentication. Falls back to DAYTONA\_API\_KEY environment variable.
+
+**apiUrl?:** (`string`): Daytona API endpoint. Falls back to DAYTONA\_API\_URL environment variable.
+
+**target?:** (`string`): Runner region. Falls back to DAYTONA\_TARGET environment variable.
+
+**timeout?:** (`number`): Default execution timeout in milliseconds. (Default: `300000 (5 minutes)`)
+
+**language?:** (`'typescript' | 'javascript' | 'python'`): Runtime language for the sandbox. (Default: `'typescript'`)
+
+**snapshot?:** (`string`): Pre-built snapshot ID to create the sandbox from. Takes precedence over image.
+
+**image?:** (`string`): Docker image for sandbox creation. Triggers image-based creation when set. Can be combined with resources. Ignored when snapshot is set.
+
+**resources?:** (`{ cpu?: number; memory?: number; disk?: number }`): Resource allocation for the sandbox (CPU cores, memory in GiB, disk in GiB). Only used when image is set.
+
+**env?:** (`Record<string, string>`): Environment variables to set in the sandbox. (Default: `{}`)
+
+**labels?:** (`Record<string, string>`): Custom metadata labels. (Default: `{}`)
+
+**name?:** (`string`): Sandbox display name. (Default: `Sandbox id`)
+
+**user?:** (`string`): OS user to run commands as. (Default: `'daytona'`)
+
+**public?:** (`boolean`): Make port previews public. (Default: `false`)
+
+**ephemeral?:** (`boolean`): Delete sandbox immediately on stop. (Default: `false`)
+
+**autoStopInterval?:** (`number`): Auto-stop interval in minutes. Set to 0 to disable. (Default: `15`)
+
+**autoArchiveInterval?:** (`number`): Auto-archive interval in minutes. Set to 0 for the maximum interval (7 days). (Default: `7 days`)
+
+**autoDeleteInterval?:** (`number`): Auto-delete interval in minutes. Negative values disable auto-delete. Set to 0 to delete on stop. (Default: `disabled`)
+
+**volumes?:** (`Array<{ volumeId: string; mountPath: string }>`): Daytona volumes to attach at sandbox creation time.
+
+**networkBlockAll?:** (`boolean`): Block all outbound network access from the sandbox. (Default: `false`)
+
+**networkAllowList?:** (`string`): Comma-separated list of allowed CIDR addresses when network access is restricted.
+
+## Properties
+
+**id:** (`string`): Sandbox instance identifier.
+
+**name:** (`string`): Provider name ('DaytonaSandbox').
+
+**provider:** (`string`): Provider identifier ('daytona').
+
+**status:** (`ProviderStatus`): 'pending' | 'initializing' | 'ready' | 'stopped' | 'destroyed' | 'error'
+
+**instance:** (`Sandbox`): The underlying Daytona Sandbox instance. Throws SandboxNotReadyError if the sandbox has not been started.
+
+## Methods
+
+### `start()`
+
+Create and start the Daytona sandbox.
+
+```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),
+})
+```
+
+**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')
+```
+
+### `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.'
+```
+
+## 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:
+
+- Processing large datasets stored in cloud buckets
+- Writing output files directly to cloud storage
+- Sharing data between sandbox sessions
+
+For usage examples, see [Filesystem mounting](#filesystem-mounting).
+
+Daytona sandboxes use FUSE (Filesystem in Userspace) to mount cloud storage:
+
+- **S3/R2**: Mounted via [s3fs-fuse](https://github.com/s3fs-fuse/s3fs-fuse)
+- **GCS**: Mounted via [gcsfuse](https://github.com/GoogleCloudPlatform/gcsfuse)
+
+The required FUSE tools are installed automatically at mount time if not already present in the sandbox image.
+
+### S3 environment variables
+
+| Variable               | Description                       |
+| ---------------------- | --------------------------------- |
+| `S3_BUCKET`            | Bucket name                       |
+| `S3_REGION`            | AWS region or `auto` for R2/MinIO |
+| `S3_ACCESS_KEY_ID`     | Access key ID                     |
+| `S3_SECRET_ACCESS_KEY` | Secret access key                 |
+| `S3_ENDPOINT`          | Endpoint URL (S3-compatible only) |
+
+### GCS environment variables
+
+| Variable                  | Description                                             |
+| ------------------------- | ------------------------------------------------------- |
+| `GCS_BUCKET`              | Bucket name                                             |
+| `GCS_SERVICE_ACCOUNT_KEY` | Service account key JSON (full JSON string, not a path) |
+
+### Reducing cold start latency with a snapshot
+
+By default, `s3fs` and `gcsfuse` are installed at first mount via `apt`, which adds startup time. To eliminate this, prebake them into a Daytona snapshot and pass the snapshot name via the `snapshot` option.
+
+**Option 1: Declarative image build**
+
+```typescript
+import { Daytona, Image } from '@daytonaio/sdk'
+
+const template = Image.base('daytonaio/sandbox')
+  .runCommands('sudo apt-get update -qq')
+  .runCommands('sudo apt-get install -y s3fs')
+  // gcsfuse requires the Google Cloud apt repository
+  .runCommands(
+    'sudo mkdir -p /etc/apt/keyrings && ' +
+      'curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg -o /tmp/gcsfuse-key.gpg && ' +
+      'sudo gpg --batch --yes --dearmor -o /etc/apt/keyrings/gcsfuse.gpg /tmp/gcsfuse-key.gpg && ' +
+      // Use gcsfuse-jammy for Ubuntu, gcsfuse-bookworm for Debian
+      'echo "deb [signed-by=/etc/apt/keyrings/gcsfuse.gpg] https://packages.cloud.google.com/apt gcsfuse-jammy main" | sudo tee /etc/apt/sources.list.d/gcsfuse.list',
+  )
+  .runCommands('sudo apt-get update -qq && sudo apt-get install -y gcsfuse')
+
+const daytona = new Daytona()
+
+await daytona.snapshot.create(
+  {
+    name: 'cloud-fs-mounting',
+    image: template,
+  },
+  { onLogs: console.log },
+)
+```
+
+**Option 2: Dockerfile** — using [`Image.fromDockerfile()`](https://www.daytona.io/docs/typescript-sdk/image#fromdockerfile)
+
+```dockerfile
+FROM daytonaio/sandbox
+RUN sudo apt-get update -qq
+RUN sudo apt-get install -y s3fs
+# Use gcsfuse-jammy for Ubuntu, gcsfuse-bookworm for Debian
+RUN sudo mkdir -p /etc/apt/keyrings && curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg -o /tmp/gcsfuse-key.gpg && sudo gpg --batch --yes --dearmor -o /etc/apt/keyrings/gcsfuse.gpg /tmp/gcsfuse-key.gpg && echo "deb [signed-by=/etc/apt/keyrings/gcsfuse.gpg] https://packages.cloud.google.com/apt gcsfuse-jammy main" | sudo tee /etc/apt/sources.list.d/gcsfuse.list
+RUN sudo apt-get update -qq && sudo apt-get install -y gcsfuse
+```
+
+```typescript
+import { Daytona, Image } from '@daytonaio/sdk'
+
+const daytona = new Daytona()
+
+await daytona.snapshot.create(
+  {
+    name: 'cloud-fs-mounting',
+    image: Image.fromDockerfile('./Dockerfile'),
+  },
+  { onLogs: console.log },
+)
+```
+
+Then use the snapshot name in your sandbox config:
+
+```typescript
+const workspace = new Workspace({
+  mounts: {
+    '/s3-data': new S3Filesystem({
+      /* ... */
+    }),
+    '/gcs-data': new GCSFilesystem({
+      /* ... */
+    }),
+  },
+  sandbox: new DaytonaSandbox({ snapshot: 'cloud-fs-mounting' }),
+})
+```
+
+## Direct SDK access
+
+Access the underlying Daytona `Sandbox` instance for filesystem, git, and other operations not exposed through the `WorkspaceSandbox` interface:
+
+```typescript
+const daytonaSandbox = sandbox.instance
+
+// Upload a file
+await daytonaSandbox.fs.uploadFile(Buffer.from('hello'), '/tmp/hello.txt')
+
+// Run git operations
+await daytonaSandbox.git.clone('https://github.com/org/repo', '/workspace/repo')
+```
+
+The `instance` getter throws `SandboxNotReadyError` if the sandbox has not been started yet.
+
+## Sandbox creation modes
+
+`DaytonaSandbox` selects a creation mode based on the options provided:
+
+| Options                   | Creation mode                                         |
+| ------------------------- | ----------------------------------------------------- |
+| `snapshot` set            | Snapshot-based (snapshot takes precedence over image) |
+| `image` set (no snapshot) | Image-based (optionally with `resources`)             |
+| Neither set               | Default snapshot-based                                |
+
+Resources are only applied when `image` is set. Passing `resources` without `image` has no effect.
+
+## Related
+
+- [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)
+- [GCSFilesystem reference](https://mastra.ai/reference/workspace/gcs-filesystem)
+- [Workspace overview](https://mastra.ai/docs/workspace/overview)