@mastra/daytona 0.0.1 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,169 @@
+# @mastra/daytona
+
+## 0.1.0
+
+### Minor Changes
+
+- Add DaytonaSandbox workspace provider — Daytona cloud sandbox integration for Mastra workspaces, implementing the WorkspaceSandbox interface with support for command execution, environment variables, resource configuration, snapshots, and Daytona volumes. ([#13112](https://github.com/mastra-ai/mastra/pull/13112))
+
+  **Basic usage**
+
+  ```ts
+  import { Workspace } from '@mastra/core/workspace';
+  import { DaytonaSandbox } from '@mastra/daytona';
+
+  const sandbox = new DaytonaSandbox({
+    id: 'my-sandbox',
+    env: { NODE_ENV: 'production' },
+  });
+
+  const workspace = new Workspace({ sandbox });
+  await workspace.init();
+
+  const result = await workspace.sandbox.executeCommand('echo', ['Hello!']);
+  console.log(result.stdout); // "Hello!"
+
+  await workspace.destroy();
+  ```
+
+- Added S3 and GCS cloud filesystem mounting support via FUSE (s3fs-fuse, gcsfuse). Daytona sandboxes can now mount cloud storage as local directories, matching the mount capabilities of E2B and Blaxel providers. ([#13544](https://github.com/mastra-ai/mastra/pull/13544))
+
+  **New methods:**
+  - `mount(filesystem, mountPath)` — Mount an S3 or GCS filesystem at a path in the sandbox
+  - `unmount(mountPath)` — Unmount a previously mounted filesystem
+
+  **What changed:**
+  - Added S3 and GCS bucket mounts as local directories in Daytona sandboxes.
+  - Improved reconnect behavior so mounts are restored reliably.
+  - Added safety checks to prevent mounting into non-empty directories.
+  - Improved concurrent mount support by isolating credentials per mount.
+
+  **Usage:**
+
+  ```typescript
+  import { Workspace } from '@mastra/core/workspace';
+  import { S3Filesystem } from '@mastra/s3';
+  import { DaytonaSandbox } from '@mastra/daytona';
+
+  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 DaytonaSandbox(),
+  });
+  ```
+
+### Patch Changes
+
+- Remove internal `processes` field from sandbox provider options ([#13597](https://github.com/mastra-ai/mastra/pull/13597))
+
+  The `processes` field is no longer exposed in constructor options for E2B, Daytona, and Blaxel sandbox providers. This field is managed internally and was not intended to be user-configurable.
+
+- Improved S3/GCS FUSE mounting reliability and sandbox reconnection. ([#13543](https://github.com/mastra-ai/mastra/pull/13543))
+
+  **Mounting improvements**
+  - Replaced direct SDK coupling in mount helpers with callback-based context, making mount operations more testable and resilient
+  - Added tmpfs overlay to handle FUSE-on-FUSE remount scenarios that previously failed with ENOENT
+  - Added `mount --move` fallback when standard FUSE unmount fails on stuck mounts
+  - `stop()` now unmounts all filesystems before stopping the sandbox
+  - Added early connectivity check for GCS mounting that detects Daytona's restricted internet tiers and fails fast with an actionable error message instead of hanging
+  - Improved gcsfuse installation with distro-aware codename detection (bookworm for Debian, jammy for Ubuntu)
+  - Added input validation for bucket names, endpoints, and credentials before interpolating into shell commands
+
+  **Reconnection improvements**
+  - `findExistingSandbox` now looks up sandboxes by name first (works for stopped sandboxes), then falls back to label search
+  - Added transitional state handling that polls and waits when a sandbox is starting/stopping/restoring before attempting to start it, avoiding "State change in progress" errors
+
+- Sandbox instructions no longer include a working directory path, keeping instructions stable across sessions. ([#13520](https://github.com/mastra-ai/mastra/pull/13520))
+
+- Updated dependencies [[`504fc8b`](https://github.com/mastra-ai/mastra/commit/504fc8b9d0ddab717577ad3bf9c95ea4bd5377bd), [`f9c150b`](https://github.com/mastra-ai/mastra/commit/f9c150b7595ad05ad9cc9a11098e2944361e8c22), [`88de7e8`](https://github.com/mastra-ai/mastra/commit/88de7e8dfe4b7e1951a9e441bb33136e705ce24e), [`edee4b3`](https://github.com/mastra-ai/mastra/commit/edee4b37dff0af515fc7cc0e8d71ee39e6a762f0), [`3790c75`](https://github.com/mastra-ai/mastra/commit/3790c7578cc6a47d854eb12d89e6b1912867fe29), [`e7a235b`](https://github.com/mastra-ai/mastra/commit/e7a235be6472e0c870ed6c791ddb17c492dc188b), [`d51d298`](https://github.com/mastra-ai/mastra/commit/d51d298953967aab1f58ec965b644d109214f085), [`6dbeeb9`](https://github.com/mastra-ai/mastra/commit/6dbeeb94a8b1eebb727300d1a98961f882180794), [`d5f0d8d`](https://github.com/mastra-ai/mastra/commit/d5f0d8d6a03e515ddaa9b5da19b7e44b8357b07b), [`09c3b18`](https://github.com/mastra-ai/mastra/commit/09c3b1802ff14e243a8a8baea327440bc8cc2e32), [`b896379`](https://github.com/mastra-ai/mastra/commit/b8963791c6afa79484645fcec596a201f936b9a2), [`85c84eb`](https://github.com/mastra-ai/mastra/commit/85c84ebb78aebfcba9d209c8e152b16d7a00cb71), [`a89272a`](https://github.com/mastra-ai/mastra/commit/a89272a5d71939b9fcd284e6a6dc1dd091a6bdcf), [`ee9c8df`](https://github.com/mastra-ai/mastra/commit/ee9c8df644f19d055af5f496bf4942705f5a47b7), [`77b4a25`](https://github.com/mastra-ai/mastra/commit/77b4a254e51907f8ff3a3ba95596a18e93ae4b35), [`276246e`](https://github.com/mastra-ai/mastra/commit/276246e0b9066a1ea48bbc70df84dbe528daaf99), [`08ecfdb`](https://github.com/mastra-ai/mastra/commit/08ecfdbdad6fb8285deef86a034bdf4a6047cfca), [`d5f628c`](https://github.com/mastra-ai/mastra/commit/d5f628ca86c6f6f3ff1035d52f635df32dd81cab), [`524c0f3`](https://github.com/mastra-ai/mastra/commit/524c0f3c434c3d9d18f66338dcef383d6161b59c), [`c18a0e9`](https://github.com/mastra-ai/mastra/commit/c18a0e9cef1e4ca004b2963d35e4cfc031971eac), [`4bd21ea`](https://github.com/mastra-ai/mastra/commit/4bd21ea43d44d0a0427414fc047577f9f0aa3bec), [`115a7a4`](https://github.com/mastra-ai/mastra/commit/115a7a47db5e9896fec12ae6507501adb9ec89bf), [`22a48ae`](https://github.com/mastra-ai/mastra/commit/22a48ae2513eb54d8d79dad361fddbca97a155e8), [`3c6ef79`](https://github.com/mastra-ai/mastra/commit/3c6ef798481e00d6d22563be2de98818fd4dd5e0), [`9311c17`](https://github.com/mastra-ai/mastra/commit/9311c17d7a0640d9c4da2e71b814dc67c57c6369), [`7edf78f`](https://github.com/mastra-ai/mastra/commit/7edf78f80422c43e84585f08ba11df0d4d0b73c5), [`1c4221c`](https://github.com/mastra-ai/mastra/commit/1c4221cf6032ec98d0e094d4ee11da3e48490d96), [`d25b9ea`](https://github.com/mastra-ai/mastra/commit/d25b9eabd400167255a97b690ffbc4ee4097ded5), [`fe1ce5c`](https://github.com/mastra-ai/mastra/commit/fe1ce5c9211c03d561606fda95cbfe7df1d9a9b5), [`b03c0e0`](https://github.com/mastra-ai/mastra/commit/b03c0e0389a799523929a458b0509c9e4244d562), [`0a8366b`](https://github.com/mastra-ai/mastra/commit/0a8366b0a692fcdde56c4d526e4cf03c502ae4ac), [`85664e9`](https://github.com/mastra-ai/mastra/commit/85664e9fd857320fbc245e301f764f45f66f32a3), [`bc79650`](https://github.com/mastra-ai/mastra/commit/bc796500c6e0334faa158a96077e3fb332274869), [`9257d01`](https://github.com/mastra-ai/mastra/commit/9257d01d1366d81f84c582fe02b5e200cf9621f4), [`3a3a59e`](https://github.com/mastra-ai/mastra/commit/3a3a59e8ffaa6a985fe3d9a126a3f5ade11a6724), [`3108d4e`](https://github.com/mastra-ai/mastra/commit/3108d4e649c9fddbf03253a6feeb388a5fa9fa5a), [`0c33b2c`](https://github.com/mastra-ai/mastra/commit/0c33b2c9db537f815e1c59e2c898ffce2e395a79), [`191e5bd`](https://github.com/mastra-ai/mastra/commit/191e5bd29b82f5bda35243945790da7bc7b695c2), [`f77cd94`](https://github.com/mastra-ai/mastra/commit/f77cd94c44eabed490384e7d19232a865e13214c), [`e8135c7`](https://github.com/mastra-ai/mastra/commit/e8135c7e300dac5040670eec7eab896ac6092e30), [`daca48f`](https://github.com/mastra-ai/mastra/commit/daca48f0fb17b7ae0b62a2ac40cf0e491b2fd0b7), [`257d14f`](https://github.com/mastra-ai/mastra/commit/257d14faca5931f2e4186fc165b6f0b1f915deee), [`352f25d`](https://github.com/mastra-ai/mastra/commit/352f25da316b24cdd5b410fd8dddf6a8b763da2a), [`93477d0`](https://github.com/mastra-ai/mastra/commit/93477d0769b8a13ea5ed73d508d967fb23eaeed9), [`31c78b3`](https://github.com/mastra-ai/mastra/commit/31c78b3eb28f58a8017f1dcc795c33214d87feac), [`0bc0720`](https://github.com/mastra-ai/mastra/commit/0bc07201095791858087cc56f353fcd65e87ab54), [`36516ac`](https://github.com/mastra-ai/mastra/commit/36516aca1021cbeb42e74751b46a2614101f37c8), [`e947652`](https://github.com/mastra-ai/mastra/commit/e9476527fdecb4449e54570e80dfaf8466901254), [`3c6ef79`](https://github.com/mastra-ai/mastra/commit/3c6ef798481e00d6d22563be2de98818fd4dd5e0), [`9257d01`](https://github.com/mastra-ai/mastra/commit/9257d01d1366d81f84c582fe02b5e200cf9621f4), [`ec248f6`](https://github.com/mastra-ai/mastra/commit/ec248f6b56e8a037c066c49b2178e2507471d988)]:
+  - @mastra/core@1.9.0
+
+## 0.1.0-alpha.0
+
+### Minor Changes
+
+- Add DaytonaSandbox workspace provider — Daytona cloud sandbox integration for Mastra workspaces, implementing the WorkspaceSandbox interface with support for command execution, environment variables, resource configuration, snapshots, and Daytona volumes. ([#13112](https://github.com/mastra-ai/mastra/pull/13112))
+
+  **Basic usage**
+
+  ```ts
+  import { Workspace } from '@mastra/core/workspace';
+  import { DaytonaSandbox } from '@mastra/daytona';
+
+  const sandbox = new DaytonaSandbox({
+    id: 'my-sandbox',
+    env: { NODE_ENV: 'production' },
+  });
+
+  const workspace = new Workspace({ sandbox });
+  await workspace.init();
+
+  const result = await workspace.sandbox.executeCommand('echo', ['Hello!']);
+  console.log(result.stdout); // "Hello!"
+
+  await workspace.destroy();
+  ```
+
+- Added S3 and GCS cloud filesystem mounting support via FUSE (s3fs-fuse, gcsfuse). Daytona sandboxes can now mount cloud storage as local directories, matching the mount capabilities of E2B and Blaxel providers. ([#13544](https://github.com/mastra-ai/mastra/pull/13544))
+
+  **New methods:**
+  - `mount(filesystem, mountPath)` — Mount an S3 or GCS filesystem at a path in the sandbox
+  - `unmount(mountPath)` — Unmount a previously mounted filesystem
+
+  **What changed:**
+  - Added S3 and GCS bucket mounts as local directories in Daytona sandboxes.
+  - Improved reconnect behavior so mounts are restored reliably.
+  - Added safety checks to prevent mounting into non-empty directories.
+  - Improved concurrent mount support by isolating credentials per mount.
+
+  **Usage:**
+
+  ```typescript
+  import { Workspace } from '@mastra/core/workspace';
+  import { S3Filesystem } from '@mastra/s3';
+  import { DaytonaSandbox } from '@mastra/daytona';
+
+  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 DaytonaSandbox(),
+  });
+  ```
+
+### Patch Changes
+
+- Remove internal `processes` field from sandbox provider options ([#13597](https://github.com/mastra-ai/mastra/pull/13597))
+
+  The `processes` field is no longer exposed in constructor options for E2B, Daytona, and Blaxel sandbox providers. This field is managed internally and was not intended to be user-configurable.
+
+- Improved S3/GCS FUSE mounting reliability and sandbox reconnection. ([#13543](https://github.com/mastra-ai/mastra/pull/13543))
+
+  **Mounting improvements**
+  - Replaced direct SDK coupling in mount helpers with callback-based context, making mount operations more testable and resilient
+  - Added tmpfs overlay to handle FUSE-on-FUSE remount scenarios that previously failed with ENOENT
+  - Added `mount --move` fallback when standard FUSE unmount fails on stuck mounts
+  - `stop()` now unmounts all filesystems before stopping the sandbox
+  - Added early connectivity check for GCS mounting that detects Daytona's restricted internet tiers and fails fast with an actionable error message instead of hanging
+  - Improved gcsfuse installation with distro-aware codename detection (bookworm for Debian, jammy for Ubuntu)
+  - Added input validation for bucket names, endpoints, and credentials before interpolating into shell commands
+
+  **Reconnection improvements**
+  - `findExistingSandbox` now looks up sandboxes by name first (works for stopped sandboxes), then falls back to label search
+  - Added transitional state handling that polls and waits when a sandbox is starting/stopping/restoring before attempting to start it, avoiding "State change in progress" errors
+
+- Sandbox instructions no longer include a working directory path, keeping instructions stable across sessions. ([#13520](https://github.com/mastra-ai/mastra/pull/13520))
+
+- Updated dependencies [[`504fc8b`](https://github.com/mastra-ai/mastra/commit/504fc8b9d0ddab717577ad3bf9c95ea4bd5377bd), [`f9c150b`](https://github.com/mastra-ai/mastra/commit/f9c150b7595ad05ad9cc9a11098e2944361e8c22), [`88de7e8`](https://github.com/mastra-ai/mastra/commit/88de7e8dfe4b7e1951a9e441bb33136e705ce24e), [`edee4b3`](https://github.com/mastra-ai/mastra/commit/edee4b37dff0af515fc7cc0e8d71ee39e6a762f0), [`3790c75`](https://github.com/mastra-ai/mastra/commit/3790c7578cc6a47d854eb12d89e6b1912867fe29), [`e7a235b`](https://github.com/mastra-ai/mastra/commit/e7a235be6472e0c870ed6c791ddb17c492dc188b), [`d51d298`](https://github.com/mastra-ai/mastra/commit/d51d298953967aab1f58ec965b644d109214f085), [`6dbeeb9`](https://github.com/mastra-ai/mastra/commit/6dbeeb94a8b1eebb727300d1a98961f882180794), [`d5f0d8d`](https://github.com/mastra-ai/mastra/commit/d5f0d8d6a03e515ddaa9b5da19b7e44b8357b07b), [`09c3b18`](https://github.com/mastra-ai/mastra/commit/09c3b1802ff14e243a8a8baea327440bc8cc2e32), [`b896379`](https://github.com/mastra-ai/mastra/commit/b8963791c6afa79484645fcec596a201f936b9a2), [`85c84eb`](https://github.com/mastra-ai/mastra/commit/85c84ebb78aebfcba9d209c8e152b16d7a00cb71), [`a89272a`](https://github.com/mastra-ai/mastra/commit/a89272a5d71939b9fcd284e6a6dc1dd091a6bdcf), [`ee9c8df`](https://github.com/mastra-ai/mastra/commit/ee9c8df644f19d055af5f496bf4942705f5a47b7), [`77b4a25`](https://github.com/mastra-ai/mastra/commit/77b4a254e51907f8ff3a3ba95596a18e93ae4b35), [`276246e`](https://github.com/mastra-ai/mastra/commit/276246e0b9066a1ea48bbc70df84dbe528daaf99), [`08ecfdb`](https://github.com/mastra-ai/mastra/commit/08ecfdbdad6fb8285deef86a034bdf4a6047cfca), [`d5f628c`](https://github.com/mastra-ai/mastra/commit/d5f628ca86c6f6f3ff1035d52f635df32dd81cab), [`524c0f3`](https://github.com/mastra-ai/mastra/commit/524c0f3c434c3d9d18f66338dcef383d6161b59c), [`c18a0e9`](https://github.com/mastra-ai/mastra/commit/c18a0e9cef1e4ca004b2963d35e4cfc031971eac), [`4bd21ea`](https://github.com/mastra-ai/mastra/commit/4bd21ea43d44d0a0427414fc047577f9f0aa3bec), [`115a7a4`](https://github.com/mastra-ai/mastra/commit/115a7a47db5e9896fec12ae6507501adb9ec89bf), [`22a48ae`](https://github.com/mastra-ai/mastra/commit/22a48ae2513eb54d8d79dad361fddbca97a155e8), [`3c6ef79`](https://github.com/mastra-ai/mastra/commit/3c6ef798481e00d6d22563be2de98818fd4dd5e0), [`9311c17`](https://github.com/mastra-ai/mastra/commit/9311c17d7a0640d9c4da2e71b814dc67c57c6369), [`7edf78f`](https://github.com/mastra-ai/mastra/commit/7edf78f80422c43e84585f08ba11df0d4d0b73c5), [`1c4221c`](https://github.com/mastra-ai/mastra/commit/1c4221cf6032ec98d0e094d4ee11da3e48490d96), [`d25b9ea`](https://github.com/mastra-ai/mastra/commit/d25b9eabd400167255a97b690ffbc4ee4097ded5), [`fe1ce5c`](https://github.com/mastra-ai/mastra/commit/fe1ce5c9211c03d561606fda95cbfe7df1d9a9b5), [`b03c0e0`](https://github.com/mastra-ai/mastra/commit/b03c0e0389a799523929a458b0509c9e4244d562), [`0a8366b`](https://github.com/mastra-ai/mastra/commit/0a8366b0a692fcdde56c4d526e4cf03c502ae4ac), [`85664e9`](https://github.com/mastra-ai/mastra/commit/85664e9fd857320fbc245e301f764f45f66f32a3), [`bc79650`](https://github.com/mastra-ai/mastra/commit/bc796500c6e0334faa158a96077e3fb332274869), [`9257d01`](https://github.com/mastra-ai/mastra/commit/9257d01d1366d81f84c582fe02b5e200cf9621f4), [`3a3a59e`](https://github.com/mastra-ai/mastra/commit/3a3a59e8ffaa6a985fe3d9a126a3f5ade11a6724), [`3108d4e`](https://github.com/mastra-ai/mastra/commit/3108d4e649c9fddbf03253a6feeb388a5fa9fa5a), [`0c33b2c`](https://github.com/mastra-ai/mastra/commit/0c33b2c9db537f815e1c59e2c898ffce2e395a79), [`191e5bd`](https://github.com/mastra-ai/mastra/commit/191e5bd29b82f5bda35243945790da7bc7b695c2), [`f77cd94`](https://github.com/mastra-ai/mastra/commit/f77cd94c44eabed490384e7d19232a865e13214c), [`e8135c7`](https://github.com/mastra-ai/mastra/commit/e8135c7e300dac5040670eec7eab896ac6092e30), [`daca48f`](https://github.com/mastra-ai/mastra/commit/daca48f0fb17b7ae0b62a2ac40cf0e491b2fd0b7), [`257d14f`](https://github.com/mastra-ai/mastra/commit/257d14faca5931f2e4186fc165b6f0b1f915deee), [`352f25d`](https://github.com/mastra-ai/mastra/commit/352f25da316b24cdd5b410fd8dddf6a8b763da2a), [`93477d0`](https://github.com/mastra-ai/mastra/commit/93477d0769b8a13ea5ed73d508d967fb23eaeed9), [`31c78b3`](https://github.com/mastra-ai/mastra/commit/31c78b3eb28f58a8017f1dcc795c33214d87feac), [`0bc0720`](https://github.com/mastra-ai/mastra/commit/0bc07201095791858087cc56f353fcd65e87ab54), [`36516ac`](https://github.com/mastra-ai/mastra/commit/36516aca1021cbeb42e74751b46a2614101f37c8), [`e947652`](https://github.com/mastra-ai/mastra/commit/e9476527fdecb4449e54570e80dfaf8466901254), [`3c6ef79`](https://github.com/mastra-ai/mastra/commit/3c6ef798481e00d6d22563be2de98818fd4dd5e0), [`9257d01`](https://github.com/mastra-ai/mastra/commit/9257d01d1366d81f84c582fe02b5e200cf9621f4), [`ec248f6`](https://github.com/mastra-ai/mastra/commit/ec248f6b56e8a037c066c49b2178e2507471d988)]:
+  - @mastra/core@1.9.0-alpha.0

package/LICENSE.md

@@ -1,3 +1,18 @@
+Portions of this software are licensed as follows:
+
+- All content that resides under any directory named "ee/" within this
+  repository, including but not limited to:
+  - `packages/core/src/auth/ee/`
+  - `packages/server/src/server/auth/ee/`
+    is licensed under the license defined in `ee/LICENSE`.
+
+- All third-party components incorporated into the Mastra Software are
+  licensed under the original license provided by the owner of the
+  applicable component.
+
+- Content outside of the above-mentioned directories or restrictions is
+  available under the "Apache License 2.0" as defined below.
+
 # Apache License 2.0
 
 Copyright (c) 2025 Kepler Software, Inc.

package/README.md

@@ -2,12 +2,15 @@
 
 Daytona cloud sandbox provider for [Mastra](https://mastra.ai) workspaces.
 
-Implements the `WorkspaceSandbox` interface using [Daytona](https://www.daytona.io/) sandboxes. Supports multiple runtimes, resource configuration, volumes, snapshots, streaming output, and sandbox reconnection.
+Implements the `WorkspaceSandbox` interface using [Daytona](https://www.daytona.io/) sandboxes. Supports multiple runtimes, resource configuration, volumes, snapshots, streaming output, sandbox reconnection, and filesystem mounting (S3, GCS).
 
 ## Install
 
 ```bash
 pnpm add @mastra/daytona @mastra/core
+
+# For filesystem mounting (optional)
+pnpm add @mastra/s3 @mastra/gcs
 ```
 
 ## Usage
@@ -50,7 +53,7 @@ Use a custom Docker image with specific resource allocation:
 ```typescript
 const sandbox = new DaytonaSandbox({
   image: 'node:20-slim',
-  resources: { cpu: 2, memory: 4, disk: 4 },
+  resources: { cpu: 2, memory: 4, disk: 6 },
   language: 'typescript',
 });
 ```
@@ -77,6 +80,120 @@ await sandbox.executeCommand('bash', ['-c', 'for i in 1 2 3; do echo "line $i";
 });
 ```
 
+### 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"
+```
+
+### 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' }),
+});
+```
+
+#### Via sandbox.mount()
+
+Mount manually at any point after the sandbox has started:
+
+#### S3
+
+```typescript
+import { DaytonaSandbox } from '@mastra/daytona';
+import { S3Filesystem } from '@mastra/s3';
+
+const sandbox = new DaytonaSandbox({ language: 'python' });
+await sandbox._start();
+
+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',
+);
+
+// Files in the bucket are now accessible at /data
+const result = await sandbox.executeCommand('ls', ['/data']);
+console.log(result.stdout);
+
+await sandbox._stop(); // Unmounts automatically before stopping
+```
+
+#### 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:
@@ -151,6 +268,75 @@ console.log(response.text);
 | `networkBlockAll`     | `boolean` | `false`               | Block all network access                                                                                                                     |
 | `networkAllowList`    | `string`  | —                     | Comma-separated allowed CIDR addresses                                                                                                       |
 
+## Mount Configuration
+
+Pass `S3Filesystem` or `GCSFilesystem` instances via the workspace `mounts` config or directly to `sandbox.mount()`.
+
+### 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.
+
+Create the snapshot once:
+
+```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 },
+);
+```
+
+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 WorkspaceSandbox: