@mastra/e2b 0.6.0-alpha.0 → 0.7.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # @mastra/e2b
 
+## 0.7.0-alpha.0
+
+### Minor Changes
+
+- Added networking and bulk file upload support to `E2BSandbox`: ([#19577](https://github.com/mastra-ai/mastra/pull/19577))
+  - **Public port URLs**: `sandbox.networking.getPortUrl(port)` returns the public URL for a port, enabling preview URLs and deploys with the new `@mastra/deployer-sandbox` package.
+  - **Bulk file upload**: `sandbox.writeFiles(files)` uploads multiple files in one call.
+  - **Snapshot-stop**: `stop()` now pauses the sandbox immediately (snapshotting filesystem, memory, and running processes) instead of leaving it running until its timeout. The next `start()` with the same `id` resumes it, with background processes still running. `destroy()` still kills the sandbox permanently.
+  - **Detached lifecycle**: `getPortUrl()`, `stop()`, and `destroy()` now work from a fresh process by looking up the existing sandbox by its `id` metadata, without resuming a paused sandbox. Stopping or destroying never wakes (or bills) a paused sandbox first.
+
+  ```typescript
+  import { E2BSandbox } from '@mastra/e2b';
+
+  const sandbox = new E2BSandbox();
+  await sandbox.start();
+  const url = await sandbox.networking.getPortUrl(4111);
+  ```
+
+- Added `clone()` support to the sandbox providers. `clone()` constructs an unstarted sibling sandbox that inherits the template's configuration (credentials, image, resources) with per-instance overrides for `id` and `env`, so one configured sandbox can act as a template for a fleet of sandbox clones (for example, one per project). ([#19616](https://github.com/mastra-ai/mastra/pull/19616))
+
+  ```ts
+  const template = new E2BSandbox({ apiKey, template: 'base' });
+
+  const projectSandbox = template.clone({
+    id: 'mc-project-42',
+    env: { GITHUB_TOKEN: token },
+    idleTimeoutMinutes: 30,
+  });
+  await projectSandbox.start();
+  ```
+
+  `idleTimeoutMinutes` is a best-effort hint that maps to each provider's native lifetime knob (Railway `idleTimeoutMinutes`, E2B/Modal/Vercel timeout in milliseconds, Daytona `autoStopInterval`, Blaxel TTL duration). Docker and Apple Container ignore it since they have no provider-side idle teardown.
+
+### Patch Changes
+
+- Updated dependencies [[`ec857fc`](https://github.com/mastra-ai/mastra/commit/ec857fc79c264b53b38e16478c789b7177f2ad59), [`e1f2fae`](https://github.com/mastra-ai/mastra/commit/e1f2faebaf048c3d4c2e2c01d293767c195d5794), [`63aa799`](https://github.com/mastra-ai/mastra/commit/63aa799c6b44eacc7806cda6846b7c5bbee06b37), [`73db8db`](https://github.com/mastra-ai/mastra/commit/73db8db90d69ab6153c7942749f624db0d96952d), [`73db8db`](https://github.com/mastra-ai/mastra/commit/73db8db90d69ab6153c7942749f624db0d96952d), [`76b7181`](https://github.com/mastra-ai/mastra/commit/76b71810366e6d90b9d3973149d1c7ba3659ffb9), [`0c0e8d7`](https://github.com/mastra-ai/mastra/commit/0c0e8d7becd4d1445c656b78d5d845f606c1ff9d), [`9f7c67a`](https://github.com/mastra-ai/mastra/commit/9f7c67abeeb52c41c51a9b5edee60b62afe7cd8d), [`3b65e68`](https://github.com/mastra-ai/mastra/commit/3b65e68d7f1c771c7a70eea42d83fefdd28cad88), [`e3868e2`](https://github.com/mastra-ai/mastra/commit/e3868e22babfffd0133771669ca724501c2dd58e)]:
+  - @mastra/core@1.52.0-alpha.5
+
+## 0.6.0
+
+### Minor Changes
+
+- Add `E2BCodeModeTransport` for running Code Mode in an `E2BSandbox`. ([#19372](https://github.com/mastra-ai/mastra/pull/19372))
+
+  The default `StdioCodeModeTransport` writes the runner/program to the host tmpdir and spawns `node <hostPath>`, which only works when the sandbox shares the host filesystem (e.g. `LocalSandbox`). E2B runs the program in a remote micro-VM, so those host paths don't exist there. `E2BCodeModeTransport` writes the program and runner into the sandbox via the E2B files API, strips TypeScript on the host with esbuild (no `--experimental-strip-types`, no Node-version dependency), auto-starts the sandbox when needed, surfaces captured stderr in timeout/no-result errors, and cleans up the sandbox directory afterwards.
+
+  ```ts
+  import { createCodeMode } from '@mastra/core/tools';
+  import { E2BSandbox, E2BCodeModeTransport } from '@mastra/e2b';
+
+  const { tool, instructions } = createCodeMode({ tools, sandbox: new E2BSandbox() }, new E2BCodeModeTransport());
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`bd6d240`](https://github.com/mastra-ai/mastra/commit/bd6d2402db93dddaef0721667e7e8a030e7c6e16), [`0111486`](https://github.com/mastra-ai/mastra/commit/01114867612593eef5cfa2fda6a1194dfedda841), [`96a3749`](https://github.com/mastra-ai/mastra/commit/96a37492235f5b8076b3e3177d83ed5a5e44a640), [`fe1bda0`](https://github.com/mastra-ai/mastra/commit/fe1bda06f6af92a694a51712db747cda1e7185f0), [`25e7c12`](https://github.com/mastra-ai/mastra/commit/25e7c126a770069ae7fb7ecf1d2adb40e017b009), [`1ce5121`](https://github.com/mastra-ai/mastra/commit/1ce512155d122bb21f47d98383e82ffbf84b39e8), [`fb8aea3`](https://github.com/mastra-ai/mastra/commit/fb8aea384291e77311be3a64ee1717320d5c3c73), [`4adc391`](https://github.com/mastra-ai/mastra/commit/4adc3911075249c352bb4832d2471922826344de), [`a5c6337`](https://github.com/mastra-ai/mastra/commit/a5c6337d23c7686c81a32ce62f550f610543a240), [`3cfc47a`](https://github.com/mastra-ai/mastra/commit/3cfc47a6b89940aadd0f46fb01ae9624a73a865d), [`2bb7817`](https://github.com/mastra-ai/mastra/commit/2bb78176112fde628483de2830528f7eee911e56), [`51d9870`](https://github.com/mastra-ai/mastra/commit/51d987032c689c2855374d0f244f5d654da809d1), [`5cab274`](https://github.com/mastra-ai/mastra/commit/5cab2744250e22d12fefa7b32637dce224233cee), [`7fa27d3`](https://github.com/mastra-ai/mastra/commit/7fa27d3b6f5ed68cd34e454a4d3ad9c482a0cfbc), [`8b97958`](https://github.com/mastra-ai/mastra/commit/8b979589f9aa59ba67cac565949475f2ffeb4ac3), [`8410541`](https://github.com/mastra-ai/mastra/commit/84105412c60ecd3bb33a9838146f59c4b588228f), [`a58dcbb`](https://github.com/mastra-ai/mastra/commit/a58dcbb546d7e1d65ebdc1f39e55f0908fcd9391), [`aa38805`](https://github.com/mastra-ai/mastra/commit/aa38805b878b827403be785eb90688d7172f5a40), [`153bd3b`](https://github.com/mastra-ai/mastra/commit/153bd3b396bdfed6b74cf43de12db8fd2d83c04a), [`45a8e65`](https://github.com/mastra-ai/mastra/commit/45a8e65e1556d1362cb3f25187023c36de26661d), [`e955965`](https://github.com/mastra-ai/mastra/commit/e955965dce575a903e37cf054d28ea99aa48785e), [`2d22570`](https://github.com/mastra-ai/mastra/commit/2d22570c7dfdd02123d0ecc529efb05ccba2d9fc), [`07bb863`](https://github.com/mastra-ai/mastra/commit/07bb8631919c6f7cf377dccd45b096e0f17fbed0), [`c8ed116`](https://github.com/mastra-ai/mastra/commit/c8ed11699f62bcac70102ab4ec84d80d20541da6), [`01b338c`](https://github.com/mastra-ai/mastra/commit/01b338c56271f0219606710e3e8b26dee27ac6c2), [`a99eae8`](https://github.com/mastra-ai/mastra/commit/a99eae8908e500c1b2d12f9d277be616b98617a5), [`860ef7e`](https://github.com/mastra-ai/mastra/commit/860ef7e77d92b63469cbe5857aa1e626197e43e9), [`17e818c`](https://github.com/mastra-ai/mastra/commit/17e818c51a958ba90641b1a959dc38faf8c034e9), [`edce8d2`](https://github.com/mastra-ai/mastra/commit/edce8d2769f19e27a05737c627af2d765472a4f8), [`8a586ec`](https://github.com/mastra-ai/mastra/commit/8a586eca9a4914f31dff6140d0d45ac375b00669), [`4451dfe`](https://github.com/mastra-ai/mastra/commit/4451dfe857428e7abcc0261a507a2e186dae6d47), [`8b7361d`](https://github.com/mastra-ai/mastra/commit/8b7361d35de68b80d05d30a74e0c69e7218fd612), [`1d39058`](https://github.com/mastra-ai/mastra/commit/1d39058e548efd691799985d5c8af2737f1c3bd2), [`3927473`](https://github.com/mastra-ai/mastra/commit/392747323ddb10c643d12be7b9ae913159dfaeed), [`dce50dc`](https://github.com/mastra-ai/mastra/commit/dce50dc9a1c1fcd0f427bb5f6250ec74910cb04b), [`fd13f8e`](https://github.com/mastra-ai/mastra/commit/fd13f8e21990f9904c3eedba3a626bb4a929cdb8), [`634caff`](https://github.com/mastra-ai/mastra/commit/634caff29a9200ad058b67d53f96d9e5832fb8a2), [`f703f87`](https://github.com/mastra-ai/mastra/commit/f703f878de072d51fda557f9c50867d8252bef05), [`3e26c87`](https://github.com/mastra-ai/mastra/commit/3e26c87de0c5bc2583b795ce6ca5889b6b161acb), [`33f2b88`](https://github.com/mastra-ai/mastra/commit/33f2b88842c09a567f906fac4cb61cd5277ced59), [`177010f`](https://github.com/mastra-ai/mastra/commit/177010ff096d2e4b28d89803be5b1a4cad2a0d6b), [`0ad646f`](https://github.com/mastra-ai/mastra/commit/0ad646f71a530f2454664299e5e01bfd13fa12e5), [`b486abf`](https://github.com/mastra-ai/mastra/commit/b486abfa2a7528c6f527e4015c819ea9fa54aaad), [`54a51e0`](https://github.com/mastra-ai/mastra/commit/54a51e0a484fe1ebad3fb1f7ef5282a075709eb7), [`c43f3a9`](https://github.com/mastra-ai/mastra/commit/c43f3a9d1efde99b38789364ba4d0ba670f430e3), [`a5008f2`](https://github.com/mastra-ai/mastra/commit/a5008f22ae710ad9402ea9f2547d8c02f74d384b), [`e2d5f37`](https://github.com/mastra-ai/mastra/commit/e2d5f373bd289be534d5f8694d34465010533df6), [`4ce0163`](https://github.com/mastra-ai/mastra/commit/4ce0163dc86e675a86809685c8ce6c49f1aeb87e), [`4378341`](https://github.com/mastra-ai/mastra/commit/43783412df5ea3dd35f5b1f6e4851e79c346fc89)]:
+  - @mastra/core@1.51.0
+
 ## 0.6.0-alpha.0
 
 ### Minor Changes

package/dist/index.cjs

@@ -570,11 +570,34 @@ function validateMountPath(mountPath) {
   }
 }
 var SAFE_MARKER_NAME = /^mount-[a-z0-9]+$/;
-var E2BSandbox = class extends workspace.MastraSandbox {
+var E2BSandbox = class _E2BSandbox extends workspace.MastraSandbox {
   id;
   name = "E2BSandbox";
   provider = "e2b";
   status = "pending";
+  /**
+   * Networking capability: public HTTPS URLs for sandbox ports.
+   * E2B exposes every port via `getHost(port)` — no upfront declaration needed.
+   *
+   * When not attached in this process, the URL is resolved by looking up the
+   * existing sandbox by identity (without resuming it) and deriving the host
+   * (`{port}-{sandboxId}.{domain}`), so other processes can resolve
+   * deployments without waking a paused sandbox.
+   */
+  networking = {
+    getPortUrl: async (port) => {
+      try {
+        if (this._sandbox) {
+          return `https://${this._sandbox.getHost(port)}`;
+        }
+        const info = await this.lookupExistingSandboxInfo();
+        if (!info) return null;
+        return `https://${port}-${info.sandboxId}.${this.sandboxDomain}`;
+      } catch {
+        return null;
+      }
+    }
+  };
   _sandbox = null;
   _createdAt = null;
   _isRetrying = false;
@@ -585,6 +608,7 @@ var E2BSandbox = class extends workspace.MastraSandbox {
   network;
   connectionOpts;
   _instructionsOverride;
+  _constructorOptions;
   /** Resolved template ID after building (if needed) */
   _resolvedTemplateId;
   /** Promise for template preparation (started in constructor) */
@@ -608,11 +632,34 @@ var E2BSandbox = class extends workspace.MastraSandbox {
       ...options.accessToken && { accessToken: options.accessToken }
     };
     this._instructionsOverride = options.instructions;
+    this._constructorOptions = { ...options };
     this._templatePreparePromise = this.resolveTemplate().catch((err) => {
       this.logger.debug(`${LOG_PREFIX} Template preparation error (will retry on start):`, err);
       return "";
     });
   }
+  /**
+   * Construct a sibling `E2BSandbox` that inherits this sandbox's
+   * configuration (credentials, template, network, metadata, instructions)
+   * with per-instance overrides.
+   *
+   * Performs no I/O — the sandbox clone provisions (or reconnects to an
+   * existing E2B sandbox with the same logical `id`) on its own `start()`.
+   * Use it when one configured sandbox acts as the template for a fleet of
+   * independent sandboxes (e.g. one per project).
+   *
+   * `options.idleTimeoutMinutes` maps to the E2B sandbox `timeout` (ms);
+   * `options.sandboxId` is ignored because E2B reconnects by logical `id`.
+   */
+  clone(options = {}) {
+    const { id: _id, ...base } = this._constructorOptions;
+    return new _E2BSandbox({
+      ...base,
+      ...options.id !== void 0 && { id: options.id },
+      ...options.env !== void 0 && { env: options.env },
+      ...options.idleTimeoutMinutes !== void 0 && { timeout: options.idleTimeoutMinutes * 6e4 }
+    });
+  }
   /**
    * Get the underlying E2B Sandbox instance for direct access to E2B APIs.
    *
@@ -710,22 +757,32 @@ var E2BSandbox = class extends workspace.MastraSandbox {
     this._createdAt = /* @__PURE__ */ new Date();
   }
   /**
-   * Stop the E2B sandbox.
-   * Unmounts all filesystems and releases the sandbox reference.
+   * Stop the E2B sandbox by pausing it (snapshot-stop).
+   *
+   * Pausing freezes the whole VM — filesystem, memory, and running processes —
+   * and stops billing immediately. The next `start()` reconnects and resumes it,
+   * with background processes still running. Filesystem mounts are unmounted
+   * first (FUSE mounts don't survive pause) and reconciled again on start.
+   *
    * Status management is handled by the base class.
    */
   async stop() {
-    try {
-      const procs = await this.processes.list();
-      await Promise.all(procs.map((p) => this.processes.kill(p.pid)));
-    } catch {
-    }
     for (const mountPath of [...this.mounts.entries.keys()]) {
       try {
         await this.unmount(mountPath);
       } catch {
       }
     }
+    if (this._sandbox) {
+      await this._sandbox.pause();
+      this.logger.debug(`${LOG_PREFIX} Paused sandbox ${this._sandbox.sandboxId} for: ${this.id}`);
+    } else {
+      const info = await this.lookupExistingSandboxInfo();
+      if (info?.state === "running") {
+        await e2b.Sandbox.pause(info.sandboxId, this.connectionOpts);
+        this.logger.debug(`${LOG_PREFIX} Paused detached sandbox ${info.sandboxId} for: ${this.id}`);
+      }
+    }
     this._sandbox = null;
   }
   /**
@@ -746,11 +803,14 @@ var E2BSandbox = class extends workspace.MastraSandbox {
         } catch {
         }
       }
-      try {
-        await this._sandbox.kill();
-      } catch {
-      }
+      await this._sandbox.kill();
       this._sandbox = null;
+    } else {
+      const info = await this.lookupExistingSandboxInfo();
+      if (info) {
+        await e2b.Sandbox.kill(info.sandboxId, this.connectionOpts);
+        this.logger.debug(`${LOG_PREFIX} Killed detached sandbox ${info.sandboxId} for: ${this.id}`);
+      }
     }
     this.mounts.clear();
   }
@@ -770,6 +830,21 @@ var E2BSandbox = class extends workspace.MastraSandbox {
       }
     };
   }
+  // ---------------------------------------------------------------------------
+  // File Upload
+  // ---------------------------------------------------------------------------
+  /**
+   * Bulk-write files into the sandbox filesystem via the SDK's native upload.
+   */
+  async writeFiles(files) {
+    await this.ensureRunning();
+    await this.e2b.files.write(
+      files.map((f) => ({
+        path: f.path,
+        data: typeof f.content === "string" ? f.content : new Blob([new Uint8Array(f.content)])
+      }))
+    );
+  }
   /**
    * Get instructions describing this E2B sandbox.
    * Used by agents to understand the execution environment.
@@ -1004,11 +1079,15 @@ var E2BSandbox = class extends workspace.MastraSandbox {
   generateId() {
     return `e2b-sandbox-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
   }
+  /** Domain used to derive public sandbox hosts (self-hosted E2B or e2b.app). */
+  get sandboxDomain() {
+    return this.connectionOpts.domain ?? process.env.E2B_DOMAIN ?? "e2b.app";
+  }
   /**
-   * Find an existing sandbox with matching mastra-sandbox-id metadata.
-   * Returns the connected sandbox if found, null otherwise.
+   * Look up an existing sandbox with matching mastra-sandbox-id metadata
+   * WITHOUT connecting or resuming it. Returns its list info or null.
    */
-  async findExistingSandbox() {
+  async lookupExistingSandboxInfo() {
     try {
       const paginator = e2b.Sandbox.list({
         ...this.connectionOpts,
@@ -1024,13 +1103,28 @@ var E2BSandbox = class extends workspace.MastraSandbox {
         this.logger.debug(
           `${LOG_PREFIX} Found existing sandbox for ${this.id}: ${existingSandbox.sandboxId} (state: ${existingSandbox.state})`
         );
-        return await e2b.Sandbox.connect(existingSandbox.sandboxId, this.connectionOpts);
+        return existingSandbox;
       }
     } catch (e) {
       this.logger.debug(`${LOG_PREFIX} Error querying for existing sandbox:`, e);
     }
     return null;
   }
+  /**
+   * Find an existing sandbox with matching mastra-sandbox-id metadata.
+   * Returns the connected sandbox if found, null otherwise.
+   * Connecting to a paused sandbox resumes it.
+   */
+  async findExistingSandbox() {
+    const info = await this.lookupExistingSandboxInfo();
+    if (!info) return null;
+    try {
+      return await e2b.Sandbox.connect(info.sandboxId, this.connectionOpts);
+    } catch (e) {
+      this.logger.debug(`${LOG_PREFIX} Error connecting to existing sandbox:`, e);
+      return null;
+    }
+  }
   /**
    * Resolve the template specification to a template ID.
    *