@mastra/deployer-sandbox 0.0.0 → 0.1.0

package/dist/client/index.d.ts

@@ -0,0 +1,98 @@
+import type { WorkspaceSandbox } from '@mastra/core/workspace';
+export type DeploymentStatus = 'running' | 'stopped' | 'unknown';
+export interface GetDeploymentOptions {
+    /**
+     * The sandbox to resolve. Provider construction is identity — e.g.
+     * `new VercelSandbox({ sandboxName: 'my-preview', ports: [4111] })` resolves
+     * the same sandbox from any process.
+     */
+    sandbox: WorkspaceSandbox;
+    /** Port the Mastra server listens on. Defaults to 4111. */
+    port?: number;
+    /**
+     * Wake the sandbox when it is not running. Waking starts (resumes) the
+     * sandbox and, only if the server is not answering, relaunches it from the
+     * recorded launch script — some providers (e.g. E2B) resume processes on
+     * wake, others (e.g. Vercel) restore just the filesystem. Defaults to false.
+     */
+    wake?: boolean;
+    /** Directory the app was deployed into. Defaults to `$HOME/mastra-app` resolved inside the sandbox. */
+    remoteDir?: string;
+    /** Path polled for health. Defaults to `/api`. */
+    healthCheckPath?: string;
+    /** Max time to wait for health after a wake, in ms. Defaults to 60000. */
+    healthCheckTimeoutMs?: number;
+}
+export interface ResolvedDeployment {
+    /** Public URL of the Mastra server, or null when it could not be resolved without waking. */
+    url: string | null;
+    status: DeploymentStatus;
+    /** When the sandbox will auto-shutdown (when known). */
+    expiresAt?: Date;
+    stop(): Promise<void>;
+    destroy(): Promise<void>;
+    logs(lines?: number): Promise<string>;
+}
+/**
+ * Resolve (and optionally wake) a sandbox deployment.
+ *
+ * With `wake: false` (default) the sandbox is not started: the URL is resolved
+ * only if the sandbox is already running in this process, otherwise
+ * `{ url: null, status: 'stopped' | 'unknown' }` is returned and the caller
+ * decides whether to wake.
+ *
+ * With `wake: true` the sandbox is started (providers resume by identity,
+ * e.g. name), the server is relaunched if it is not answering, and the
+ * deployment is returned once healthy.
+ */
+export declare function getDeployment(options: GetDeploymentOptions): Promise<ResolvedDeployment>;
+export interface CreateSandboxHandlerOptions {
+    /**
+     * Resolve the current sandbox URL. Called once, cached, and re-invoked when
+     * a forwarded request fails at the network level (e.g. the sandbox rotated
+     * its URL or went to sleep). Typically wraps `getDeployment`:
+     *
+     * ```typescript
+     * createSandboxHandler({
+     *   resolve: async () => {
+     *     const dep = await getDeployment({ sandbox, wake: true });
+     *     return dep.url!;
+     *   },
+     * });
+     * ```
+     */
+    resolve: () => Promise<string>;
+    /** Shared secret attached as the `x-mastra-sandbox-secret` header on forwarded requests. */
+    secret?: string;
+}
+/**
+ * Framework-free route-handler proxy (fetch `Request` → `Response`). Mount it
+ * as a catch-all API route; the browser only ever sees your own domain, and
+ * the sandbox URL (which rotates across resumes) stays server-side.
+ */
+export declare function createSandboxHandler(options: CreateSandboxHandlerOptions): (request: Request) => Promise<Response>;
+export interface CreateSandboxProxyOptions {
+    /** Edge Config item key that holds the current sandbox URL. */
+    key: string;
+    /**
+     * Edge Config connection string (`https://edge-config.vercel.com/ecfg_...?token=...`).
+     * Defaults to `process.env.EDGE_CONFIG`.
+     */
+    edgeConfig?: string;
+    /** Shared secret attached as the `x-mastra-sandbox-secret` header on the rewrite. */
+    secret?: string;
+}
+/**
+ * Next.js middleware helper for Tier 3 routing: reads the current sandbox URL
+ * from Edge Config (kept fresh by the deployer's `alias` option) and rewrites
+ * the request to it. Returns `undefined` when no URL is configured so the
+ * request falls through.
+ *
+ * ```typescript
+ * // middleware.ts
+ * export const middleware = createSandboxProxy({ key: 'my-preview' });
+ * export const config = { matcher: '/api/:path*' };
+ * ```
+ */
+export declare function createSandboxProxy(options: CreateSandboxProxyOptions): (request: Request) => Promise<Response | undefined>;
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAqB/D,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAEjE,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,OAAO,EAAE,gBAAgB,CAAC;IAC1B,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,uGAAuG;IACvG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,0EAA0E;IAC1E,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,kBAAkB;IACjC,6FAA6F;IAC7F,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,MAAM,EAAE,gBAAgB,CAAC;IACzB,wDAAwD;IACxD,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,IAAI,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACvC;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAsE9F;AAMD,MAAM,WAAW,2BAA2B;IAC1C;;;;;;;;;;;;;OAaG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/B,4FAA4F;IAC5F,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,2BAA2B,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAqElH;AAED,MAAM,WAAW,yBAAyB;IACxC,+DAA+D;IAC/D,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qFAAqF;IACrF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,yBAAyB,GACjC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAqCrD"}

package/dist/client/index.js

@@ -0,0 +1,155 @@
+import { DEFAULT_PORT, waitForHealthy, resolveRemoteDir, killPreviousServer, launchServer, tailServerLog, getInfoSafe } from '../chunk-Z636GNUQ.js';
+import { supportsNetworking } from '@mastra/core/workspace';
+
+function assertServerOnly() {
+  if (typeof globalThis.window !== "undefined") {
+    throw new Error(
+      "@mastra/deployer-sandbox/client is server-only: resolving a sandbox requires provider credentials that must never reach the browser. Proxy requests through your own backend instead (see createSandboxHandler / createSandboxProxy)."
+    );
+  }
+}
+async function getDeployment(options) {
+  assertServerOnly();
+  const {
+    sandbox,
+    port = DEFAULT_PORT,
+    wake = false,
+    healthCheckPath = "/api",
+    healthCheckTimeoutMs = 6e4
+  } = options;
+  const handle = (url2, status, expiresAt) => ({
+    url: url2,
+    status,
+    expiresAt,
+    stop: async () => {
+      await sandbox.stop?.();
+    },
+    destroy: async () => {
+      await sandbox.destroy?.();
+    },
+    // Resolved lazily — reading logs requires a running sandbox anyway.
+    logs: async (lines) => tailServerLog(sandbox, await resolveRemoteDir(sandbox, options.remoteDir), lines)
+  });
+  if (!wake) {
+    const url2 = supportsNetworking(sandbox) ? await sandbox.networking.getPortUrl(port) : null;
+    if (!url2) {
+      return handle(null, "stopped");
+    }
+    const healthy2 = await waitForHealthy(url2, { path: healthCheckPath, timeoutMs: 3e3, intervalMs: 1e3 });
+    return handle(url2, healthy2 ? "running" : "stopped");
+  }
+  await sandbox.start?.();
+  if (!supportsNetworking(sandbox)) {
+    throw new Error(`Sandbox provider "${sandbox.provider}" does not support networking (public port URLs).`);
+  }
+  const url = await sandbox.networking.getPortUrl(port);
+  if (!url) {
+    throw new Error(
+      `Sandbox provider "${sandbox.provider}" did not expose a public URL for port ${port}. Make sure the port is declared when constructing the sandbox (e.g. \`ports: [${port}]\`).`
+    );
+  }
+  let healthy = await waitForHealthy(url, { path: healthCheckPath, timeoutMs: 3e3, intervalMs: 1e3 });
+  if (!healthy) {
+    const remoteDir = await resolveRemoteDir(sandbox, options.remoteDir);
+    await killPreviousServer(sandbox, remoteDir);
+    await launchServer(sandbox, remoteDir);
+    healthy = await waitForHealthy(url, { path: healthCheckPath, timeoutMs: healthCheckTimeoutMs, intervalMs: 1e3 });
+  }
+  if (!healthy) {
+    const log = await resolveRemoteDir(sandbox, options.remoteDir).then((dir) => tailServerLog(sandbox, dir)).catch(() => "");
+    throw new Error(
+      `Woke sandbox but the Mastra server did not become healthy at ${url}${healthCheckPath}.` + (log ? `
+
+Server log:
+${log}` : "")
+    );
+  }
+  const info = await getInfoSafe(sandbox);
+  return handle(url, "running", info?.timeoutAt);
+}
+function createSandboxHandler(options) {
+  assertServerOnly();
+  let cachedUrl = null;
+  const forward = async (request, baseUrl) => {
+    const incoming = new URL(request.url);
+    const target = new URL(incoming.pathname + incoming.search, baseUrl);
+    const headers = new Headers(request.headers);
+    headers.delete("host");
+    if (options.secret) {
+      headers.set("x-mastra-sandbox-secret", options.secret);
+    }
+    const response = await fetch(target, {
+      method: request.method,
+      headers,
+      body: request.body,
+      // duplex is required by Node's fetch for streamed request bodies
+      duplex: "half",
+      redirect: "manual"
+    });
+    const location = response.headers.get("location");
+    if (location) {
+      const resolved = new URL(location, target);
+      if (resolved.origin === new URL(baseUrl).origin) {
+        const rewritten = new URL(resolved.pathname + resolved.search + resolved.hash, incoming.origin);
+        const responseHeaders = new Headers(response.headers);
+        responseHeaders.set("location", rewritten.toString());
+        return new Response(response.body, {
+          status: response.status,
+          statusText: response.statusText,
+          headers: responseHeaders
+        });
+      }
+    }
+    return response;
+  };
+  return async (request) => {
+    cachedUrl ??= options.resolve();
+    try {
+      return await forward(request, await cachedUrl);
+    } catch (error) {
+      cachedUrl = null;
+      if (!["GET", "HEAD", "OPTIONS"].includes(request.method)) {
+        throw error;
+      }
+      cachedUrl = options.resolve();
+      try {
+        return await forward(request, await cachedUrl);
+      } catch (retryError) {
+        cachedUrl = null;
+        throw retryError;
+      }
+    }
+  };
+}
+function createSandboxProxy(options) {
+  assertServerOnly();
+  return async (request) => {
+    const connection = options.edgeConfig ?? process.env.EDGE_CONFIG;
+    if (!connection) {
+      throw new Error("createSandboxProxy requires an Edge Config connection string (EDGE_CONFIG).");
+    }
+    const conn = new URL(connection);
+    const token = conn.searchParams.get("token");
+    const itemUrl = new URL(`${conn.origin}${conn.pathname}/item/${encodeURIComponent(options.key)}`);
+    const res = await fetch(itemUrl, { headers: { Authorization: `Bearer ${token}` } });
+    if (!res.ok) {
+      return void 0;
+    }
+    const sandboxUrl = await res.json();
+    if (typeof sandboxUrl !== "string" || !sandboxUrl) {
+      return void 0;
+    }
+    const incoming = new URL(request.url);
+    const target = new URL(incoming.pathname + incoming.search, sandboxUrl);
+    const headers = new Headers({ "x-middleware-rewrite": target.toString() });
+    if (options.secret) {
+      headers.set("x-middleware-request-x-mastra-sandbox-secret", options.secret);
+      headers.set("x-middleware-override-headers", "x-mastra-sandbox-secret");
+    }
+    return new Response(null, { headers });
+  };
+}
+
+export { createSandboxHandler, createSandboxProxy, getDeployment };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/client/index.ts"],"names":["url","healthy"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Runtime resolver + routing helpers for sandbox deployments.\n *\n * SERVER-ONLY. This module resolves sandbox URLs using provider credentials\n * (e.g. VERCEL_TOKEN) — importing it in the browser would ship those\n * credentials to the client. Use the proxy/handler patterns instead so the\n * browser only ever talks to your own domain.\n */\nimport { supportsNetworking } from '@mastra/core/workspace';\nimport type { WorkspaceSandbox } from '@mastra/core/workspace';\nimport {\n  DEFAULT_PORT,\n  getInfoSafe,\n  killPreviousServer,\n  launchServer,\n  resolveRemoteDir,\n  tailServerLog,\n  waitForHealthy,\n} from '../shared';\n\nfunction assertServerOnly(): void {\n  if (typeof (globalThis as { window?: unknown }).window !== 'undefined') {\n    throw new Error(\n      '@mastra/deployer-sandbox/client is server-only: resolving a sandbox requires provider credentials ' +\n        'that must never reach the browser. Proxy requests through your own backend instead ' +\n        '(see createSandboxHandler / createSandboxProxy).',\n    );\n  }\n}\n\nexport type DeploymentStatus = 'running' | 'stopped' | 'unknown';\n\nexport interface GetDeploymentOptions {\n  /**\n   * The sandbox to resolve. Provider construction is identity — e.g.\n   * `new VercelSandbox({ sandboxName: 'my-preview', ports: [4111] })` resolves\n   * the same sandbox from any process.\n   */\n  sandbox: WorkspaceSandbox;\n  /** Port the Mastra server listens on. Defaults to 4111. */\n  port?: number;\n  /**\n   * Wake the sandbox when it is not running. Waking starts (resumes) the\n   * sandbox and, only if the server is not answering, relaunches it from the\n   * recorded launch script — some providers (e.g. E2B) resume processes on\n   * wake, others (e.g. Vercel) restore just the filesystem. Defaults to false.\n   */\n  wake?: boolean;\n  /** Directory the app was deployed into. Defaults to `$HOME/mastra-app` resolved inside the sandbox. */\n  remoteDir?: string;\n  /** Path polled for health. Defaults to `/api`. */\n  healthCheckPath?: string;\n  /** Max time to wait for health after a wake, in ms. Defaults to 60000. */\n  healthCheckTimeoutMs?: number;\n}\n\nexport interface ResolvedDeployment {\n  /** Public URL of the Mastra server, or null when it could not be resolved without waking. */\n  url: string | null;\n  status: DeploymentStatus;\n  /** When the sandbox will auto-shutdown (when known). */\n  expiresAt?: Date;\n  stop(): Promise<void>;\n  destroy(): Promise<void>;\n  logs(lines?: number): Promise<string>;\n}\n\n/**\n * Resolve (and optionally wake) a sandbox deployment.\n *\n * With `wake: false` (default) the sandbox is not started: the URL is resolved\n * only if the sandbox is already running in this process, otherwise\n * `{ url: null, status: 'stopped' | 'unknown' }` is returned and the caller\n * decides whether to wake.\n *\n * With `wake: true` the sandbox is started (providers resume by identity,\n * e.g. name), the server is relaunched if it is not answering, and the\n * deployment is returned once healthy.\n */\nexport async function getDeployment(options: GetDeploymentOptions): Promise<ResolvedDeployment> {\n  assertServerOnly();\n\n  const {\n    sandbox,\n    port = DEFAULT_PORT,\n    wake = false,\n    healthCheckPath = '/api',\n    healthCheckTimeoutMs = 60_000,\n  } = options;\n\n  const handle = (url: string | null, status: DeploymentStatus, expiresAt?: Date): ResolvedDeployment => ({\n    url,\n    status,\n    expiresAt,\n    stop: async () => {\n      await sandbox.stop?.();\n    },\n    destroy: async () => {\n      await sandbox.destroy?.();\n    },\n    // Resolved lazily — reading logs requires a running sandbox anyway.\n    logs: async (lines?: number) => tailServerLog(sandbox, await resolveRemoteDir(sandbox, options.remoteDir), lines),\n  });\n\n  if (!wake) {\n    // Resolve without starting the sandbox (starting can resume billing).\n    const url = supportsNetworking(sandbox) ? await sandbox.networking.getPortUrl(port) : null;\n    if (!url) {\n      return handle(null, 'stopped');\n    }\n    const healthy = await waitForHealthy(url, { path: healthCheckPath, timeoutMs: 3_000, intervalMs: 1_000 });\n    return handle(url, healthy ? 'running' : 'stopped');\n  }\n\n  await sandbox.start?.();\n\n  if (!supportsNetworking(sandbox)) {\n    throw new Error(`Sandbox provider \"${sandbox.provider}\" does not support networking (public port URLs).`);\n  }\n  const url = await sandbox.networking.getPortUrl(port);\n  if (!url) {\n    throw new Error(\n      `Sandbox provider \"${sandbox.provider}\" did not expose a public URL for port ${port}. ` +\n        `Make sure the port is declared when constructing the sandbox (e.g. \\`ports: [${port}]\\`).`,\n    );\n  }\n\n  // Some providers (e.g. Vercel) restore the filesystem but not processes on\n  // resume, while others (e.g. E2B) resume processes too — relaunch the server\n  // from the recorded launch script only when it is not answering.\n  let healthy = await waitForHealthy(url, { path: healthCheckPath, timeoutMs: 3_000, intervalMs: 1_000 });\n  if (!healthy) {\n    const remoteDir = await resolveRemoteDir(sandbox, options.remoteDir);\n    await killPreviousServer(sandbox, remoteDir);\n    await launchServer(sandbox, remoteDir);\n    healthy = await waitForHealthy(url, { path: healthCheckPath, timeoutMs: healthCheckTimeoutMs, intervalMs: 1_000 });\n  }\n  if (!healthy) {\n    const log = await resolveRemoteDir(sandbox, options.remoteDir)\n      .then(dir => tailServerLog(sandbox, dir))\n      .catch(() => '');\n    throw new Error(\n      `Woke sandbox but the Mastra server did not become healthy at ${url}${healthCheckPath}.` +\n        (log ? `\\n\\nServer log:\\n${log}` : ''),\n    );\n  }\n\n  const info = await getInfoSafe(sandbox);\n  return handle(url, 'running', info?.timeoutAt);\n}\n\n// =============================================================================\n// Tier 3 helpers\n// =============================================================================\n\nexport interface CreateSandboxHandlerOptions {\n  /**\n   * Resolve the current sandbox URL. Called once, cached, and re-invoked when\n   * a forwarded request fails at the network level (e.g. the sandbox rotated\n   * its URL or went to sleep). Typically wraps `getDeployment`:\n   *\n   * ```typescript\n   * createSandboxHandler({\n   *   resolve: async () => {\n   *     const dep = await getDeployment({ sandbox, wake: true });\n   *     return dep.url!;\n   *   },\n   * });\n   * ```\n   */\n  resolve: () => Promise<string>;\n  /** Shared secret attached as the `x-mastra-sandbox-secret` header on forwarded requests. */\n  secret?: string;\n}\n\n/**\n * Framework-free route-handler proxy (fetch `Request` → `Response`). Mount it\n * as a catch-all API route; the browser only ever sees your own domain, and\n * the sandbox URL (which rotates across resumes) stays server-side.\n */\nexport function createSandboxHandler(options: CreateSandboxHandlerOptions): (request: Request) => Promise<Response> {\n  assertServerOnly();\n\n  let cachedUrl: Promise<string> | null = null;\n\n  const forward = async (request: Request, baseUrl: string): Promise<Response> => {\n    const incoming = new URL(request.url);\n    const target = new URL(incoming.pathname + incoming.search, baseUrl);\n\n    const headers = new Headers(request.headers);\n    headers.delete('host');\n    if (options.secret) {\n      headers.set('x-mastra-sandbox-secret', options.secret);\n    }\n\n    const response = await fetch(target, {\n      method: request.method,\n      headers,\n      body: request.body,\n      // duplex is required by Node's fetch for streamed request bodies\n      duplex: 'half',\n      redirect: 'manual',\n    } as RequestInit);\n\n    // Redirects are passed through manually — rewrite sandbox-host Locations\n    // onto the incoming origin so the rotating sandbox URL never reaches the\n    // browser (and subsequent requests keep flowing through this handler).\n    const location = response.headers.get('location');\n    if (location) {\n      const resolved = new URL(location, target);\n      if (resolved.origin === new URL(baseUrl).origin) {\n        const rewritten = new URL(resolved.pathname + resolved.search + resolved.hash, incoming.origin);\n        const responseHeaders = new Headers(response.headers);\n        responseHeaders.set('location', rewritten.toString());\n        return new Response(response.body, {\n          status: response.status,\n          statusText: response.statusText,\n          headers: responseHeaders,\n        });\n      }\n    }\n\n    return response;\n  };\n\n  return async (request: Request): Promise<Response> => {\n    cachedUrl ??= options.resolve();\n\n    try {\n      return await forward(request, await cachedUrl);\n    } catch (error) {\n      // Connection-level failure: the sandbox may have rotated its URL or gone\n      // to sleep. Drop the cached URL so the next request re-resolves, and\n      // retry once — but only for idempotent, bodyless methods. A failed\n      // connection doesn't prove a write never landed, and a streamed body is\n      // already consumed.\n      cachedUrl = null;\n      if (!['GET', 'HEAD', 'OPTIONS'].includes(request.method)) {\n        throw error;\n      }\n      cachedUrl = options.resolve();\n      try {\n        return await forward(request, await cachedUrl);\n      } catch (retryError) {\n        cachedUrl = null;\n        throw retryError;\n      }\n    }\n  };\n}\n\nexport interface CreateSandboxProxyOptions {\n  /** Edge Config item key that holds the current sandbox URL. */\n  key: string;\n  /**\n   * Edge Config connection string (`https://edge-config.vercel.com/ecfg_...?token=...`).\n   * Defaults to `process.env.EDGE_CONFIG`.\n   */\n  edgeConfig?: string;\n  /** Shared secret attached as the `x-mastra-sandbox-secret` header on the rewrite. */\n  secret?: string;\n}\n\n/**\n * Next.js middleware helper for Tier 3 routing: reads the current sandbox URL\n * from Edge Config (kept fresh by the deployer's `alias` option) and rewrites\n * the request to it. Returns `undefined` when no URL is configured so the\n * request falls through.\n *\n * ```typescript\n * // middleware.ts\n * export const middleware = createSandboxProxy({ key: 'my-preview' });\n * export const config = { matcher: '/api/:path*' };\n * ```\n */\nexport function createSandboxProxy(\n  options: CreateSandboxProxyOptions,\n): (request: Request) => Promise<Response | undefined> {\n  // Reads (and would transmit) the Edge Config bearer token — same\n  // server-only contract as the rest of this module.\n  assertServerOnly();\n\n  return async (request: Request): Promise<Response | undefined> => {\n    const connection = options.edgeConfig ?? process.env.EDGE_CONFIG;\n    if (!connection) {\n      throw new Error('createSandboxProxy requires an Edge Config connection string (EDGE_CONFIG).');\n    }\n\n    const conn = new URL(connection);\n    const token = conn.searchParams.get('token');\n    const itemUrl = new URL(`${conn.origin}${conn.pathname}/item/${encodeURIComponent(options.key)}`);\n\n    const res = await fetch(itemUrl, { headers: { Authorization: `Bearer ${token}` } });\n    if (!res.ok) {\n      return undefined;\n    }\n    const sandboxUrl: unknown = await res.json();\n    if (typeof sandboxUrl !== 'string' || !sandboxUrl) {\n      return undefined;\n    }\n\n    const incoming = new URL(request.url);\n    const target = new URL(incoming.pathname + incoming.search, sandboxUrl);\n\n    // A Response with the x-middleware-rewrite header is how Next.js\n    // middleware expresses a rewrite (NextResponse.rewrite does the same) —\n    // this keeps the helper free of a next dependency.\n    const headers = new Headers({ 'x-middleware-rewrite': target.toString() });\n    if (options.secret) {\n      headers.set('x-middleware-request-x-mastra-sandbox-secret', options.secret);\n      headers.set('x-middleware-override-headers', 'x-mastra-sandbox-secret');\n    }\n    return new Response(null, { headers });\n  };\n}\n"]}

package/dist/deployer.d.ts

@@ -0,0 +1,57 @@
+import type { Config } from '@mastra/core/mastra';
+import type { WorkspaceSandbox } from '@mastra/core/workspace';
+import { Deployer } from '@mastra/deployer';
+import type { SandboxDeployerOptions } from './types.js';
+/**
+ * Deploy a full Mastra server into any workspace sandbox that supports
+ * networking (Vercel Sandbox, E2B, ...) and get a live public URL.
+ *
+ * Positioning: ephemeral environments — instant previews, PR/CI smoke deploys,
+ * agent-built-app verification. Not production hosting.
+ *
+ * @example
+ * ```typescript
+ * import { SandboxDeployer } from '@mastra/deployer-sandbox';
+ * import { VercelSandbox } from '@mastra/vercel';
+ *
+ * export const mastra = new Mastra({
+ *   deployer: new SandboxDeployer({
+ *     sandbox: new VercelSandbox({ sandboxName: 'my-preview', timeout: 3_600_000, ports: [4111] }),
+ *   }),
+ * });
+ * ```
+ */
+export declare class SandboxDeployer extends Deployer {
+    /** Sandbox deploys are push-style: `mastra build` runs `deploy()` after bundling. */
+    readonly deployOnBuild = true;
+    readonly sandbox: WorkspaceSandbox;
+    readonly port: number;
+    readonly studio: boolean;
+    /** Explicit remote dir, when configured. The engine defaults to `$HOME/mastra-app` inside the sandbox. */
+    readonly remoteDir?: string;
+    private readonly env;
+    private readonly alias?;
+    private readonly healthCheckTimeoutMs?;
+    constructor(options: SandboxDeployerOptions);
+    /**
+     * Merge all existing env files instead of only the first one (base behavior).
+     * Later files win in `loadEnvVars()`, so order least → most specific: a
+     * `.env.local` written by `vercel env pull` shouldn't shadow the `.env` that
+     * holds the app's own keys.
+     */
+    getEnvFiles(): Promise<string[]>;
+    protected getUserBundlerOptions(mastraEntryFile: string, outputDirectory: string): Promise<NonNullable<Config['bundler']>>;
+    protected getEntry(): string;
+    prepare(outputDirectory: string): Promise<void>;
+    bundle(entryFile: string, outputDirectory: string, { toolsPaths, projectRoot }: {
+        toolsPaths: (string | string[])[];
+        projectRoot: string;
+    }): Promise<void>;
+    /**
+     * Deploy the built output into the sandbox and wait for the server to come
+     * up on its public URL. Writes `sandbox-deployment.json` into the output
+     * directory and updates the Edge Config alias when configured.
+     */
+    deploy(outputDirectory: string): Promise<void>;
+}
+//# sourceMappingURL=deployer.d.ts.map

package/dist/deployer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployer.d.ts","sourceRoot":"","sources":["../src/deployer.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAM5C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAEtD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,eAAgB,SAAQ,QAAQ;IAC3C,qFAAqF;IACrF,QAAQ,CAAC,aAAa,QAAQ;IAC9B,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,0GAA0G;IAC1G,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAyB;IAC7C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAkC;IACzD,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAAS;gBAEnC,OAAO,EAAE,sBAAsB;IAY3C;;;;;OAKG;IACY,WAAW,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;cAc/B,qBAAqB,CACnC,eAAe,EAAE,MAAM,EACvB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;IAU1C,SAAS,CAAC,QAAQ,IAAI,MAAM;IAqBtB,OAAO,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB/C,MAAM,CACV,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,MAAM,EACvB,EAAE,UAAU,EAAE,WAAW,EAAE,EAAE;QAAE,UAAU,EAAE,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GACtF,OAAO,CAAC,IAAI,CAAC;IAIhB;;;;OAIG;IACG,MAAM,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CA8CrD"}

package/dist/engine.d.ts

@@ -0,0 +1,19 @@
+import type { DeployToSandboxOptions, SandboxDeployment } from './types.js';
+/**
+ * Deploy a prebuilt Mastra server directory into any workspace sandbox that
+ * supports networking. Provider-agnostic: only uses the core WorkspaceSandbox
+ * contract (`executeCommand` + `networking`, with `writeFiles` / `processes`
+ * as fast paths).
+ */
+export declare function deployToSandbox(options: DeployToSandboxOptions): Promise<SandboxDeployment>;
+/**
+ * Build the POSIX launch script. Re-running the script restarts the server —
+ * the wake path uses this after a snapshot resume (which restores the
+ * filesystem but not processes).
+ */
+export declare function buildLaunchScript(opts: {
+    remoteDir: string;
+    port: number;
+    env: Record<string, string>;
+}): string;
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,sBAAsB,EAAuB,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAc9F;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA+HjG;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,MAAM,CAyBhH"}