autoresume: lifecycle component in sdk

.changeset/bold-times-decide.md

@@ -0,0 +1,6 @@
+---
+'@e2b/python-sdk': minor
+'e2b': minor
+---
+
+Adds lifecycle prop to control pausing and auto-resume

packages/js-sdk/src/index.ts

@@ -49,6 +49,7 @@ export type {
   SandboxListOpts,
   SandboxPaginator,
   SandboxNetworkOpts,
+  SandboxLifecycle,
   SnapshotInfo,
   SnapshotListOpts,
   SnapshotPaginator,

packages/js-sdk/src/sandbox/index.ts

@@ -466,7 +466,7 @@ export class Sandbox extends SandboxApi {
    * const sameSandbox = await sandbox.connect()
    * ```
    */
-  async connect(opts?: SandboxBetaCreateOpts): Promise<this> {
+  async connect(opts?: SandboxConnectOpts): Promise<this> {
     await SandboxApi.connectSandbox(this.sandboxId, opts)
 
     return this
@@ -571,13 +571,24 @@ export class Sandbox extends SandboxApi {
   }
 
   /**
-   * @beta This feature is in beta and may change in the future.
-   *
    * Pause a sandbox by its ID.
    *
    * @param opts connection options.
    *
    * @returns sandbox ID that can be used to resume the sandbox.
+   *
+   * @example
+   * ```ts
+   * const sandbox = await Sandbox.create()
+   * await sandbox.pause()
+   * ```
+   */
+  async pause(opts?: ConnectionOpts): Promise<boolean> {
+    return await SandboxApi.pause(this.sandboxId, opts)
+  }
+
+  /**
+   * @deprecated Use {@link Sandbox.pause} instead.
    */
   async betaPause(opts?: ConnectionOpts): Promise<boolean> {
     return await SandboxApi.betaPause(this.sandboxId, opts)

packages/js-sdk/src/sandbox/sandboxApi.ts

@@ -64,6 +64,21 @@ export type SandboxNetworkOpts = {
   maskRequestHost?: string
 }
 
+export type SandboxLifecycle = {
+  /**
+   * Action to take when sandbox timeout is reached.
+   * @default "kill"
+   */
+  onTimeout: 'pause' | 'kill'
+
+  /**
+   * Auto-resume enabled flag.
+   * @default false
+   * Can be `true` only when `onTimeout` is `pause`.
+   */
+  autoResume?: boolean
+}
+
 /**
  * Options for request to the Sandbox API.
  */
@@ -133,10 +148,17 @@ export interface SandboxOpts extends ConnectionOpts {
    * Sandbox URL. Used for local development
    */
   sandboxUrl?: string
+
+  /**
+   * Sandbox lifecycle configuration.
+   */
+  lifecycle?: SandboxLifecycle
 }
 
 export type SandboxBetaCreateOpts = SandboxOpts & {
   /**
+   * @deprecated Use `lifecycle.onTimeout = "pause"` instead.
+   *
    * Automatically pause the sandbox after the timeout expires.
    * @default false
    */
@@ -330,6 +352,26 @@ export interface SandboxMetrics {
   diskTotal: number
 }
 
+function getLifecycle(
+  opts?: Pick<SandboxBetaCreateOpts, 'lifecycle' | 'autoPause'>
+): SandboxLifecycle {
+  if (opts?.lifecycle) {
+    return opts.lifecycle
+  }
+
+  if (opts?.autoPause) {
+    return {
+      onTimeout: 'pause',
+      autoResume: false,
+    }
+  }
+
+  return {
+    onTimeout: 'kill',
+    autoResume: false,
+  }
+}
+
 export class SandboxApi {
   protected constructor() {}
 
@@ -529,7 +571,7 @@ export class SandboxApi {
    *
    * @returns `true` if the sandbox got paused, `false` if the sandbox was already paused.
    */
-  static async betaPause(
+  static async pause(
     sandboxId: string,
     opts?: SandboxApiOpts
   ): Promise<boolean> {
@@ -562,6 +604,16 @@ export class SandboxApi {
     return true
   }
 
+  /**
+   * @deprecated Use {@link SandboxApi.pause} instead.
+   */
+  static async betaPause(
+    sandboxId: string,
+    opts?: SandboxApiOpts
+  ): Promise<boolean> {
+    return this.pause(sandboxId, opts)
+  }
+
   /**
    * Create a snapshot from a sandbox.
    *
@@ -659,19 +711,30 @@ export class SandboxApi {
   ) {
     const config = new ConnectionConfig(opts)
     const client = new ApiClient(config)
+    const lifecycle = getLifecycle(opts)
+    const autoPause = lifecycle.onTimeout === 'pause'
+    const autoResumeEnabled =
+      lifecycle.onTimeout === 'pause'
+        ? (lifecycle.autoResume ?? false)
+        : undefined
+
+    const body: components['schemas']['NewSandbox'] = {
+      templateID: template,
+      metadata: opts?.metadata,
+      mcp: opts?.mcp as Record<string, unknown> | undefined,
+      envVars: opts?.envs,
+      timeout: timeoutToSeconds(timeoutMs),
+      secure: opts?.secure ?? true,
+      allow_internet_access: opts?.allowInternetAccess ?? true,
+      network: opts?.network,
+      ...(autoPause !== undefined ? { autoPause } : {}),
+      ...(autoResumeEnabled !== undefined
+        ? { autoResume: { enabled: autoResumeEnabled } }
+        : {}),
+    }
 
     const res = await client.api.POST('/sandboxes', {
-      body: {
-        autoPause: opts?.autoPause ?? false,
-        templateID: template,
-        metadata: opts?.metadata,
-        mcp: opts?.mcp as Record<string, unknown> | undefined,
-        envVars: opts?.envs,
-        timeout: timeoutToSeconds(timeoutMs),
-        secure: opts?.secure ?? true,
-        allow_internet_access: opts?.allowInternetAccess ?? true,
-        network: opts?.network,
-      },
+      body,
       signal: config.getSignal(opts?.requestTimeoutMs),
     })
 

packages/js-sdk/tests/api/snapshot.test.ts

@@ -4,15 +4,15 @@ import { sandboxTest, isDebug } from '../setup.js'
 import { Sandbox } from '../../src'
 
 sandboxTest.skipIf(isDebug)('pause sandbox', async ({ sandbox }) => {
-  await Sandbox.betaPause(sandbox.sandboxId)
+  await Sandbox.pause(sandbox.sandboxId)
   assert.isFalse(
     await sandbox.isRunning(),
     'Sandbox should not be running after pause'
   )
 })
 
 sandboxTest.skipIf(isDebug)('resume sandbox', async ({ sandbox }) => {
-  await Sandbox.betaPause(sandbox.sandboxId)
+  await Sandbox.pause(sandbox.sandboxId)
   assert.isFalse(
     await sandbox.isRunning(),
     'Sandbox should not be running after pause'

packages/js-sdk/tests/sandbox/connect.test.ts

@@ -20,6 +20,17 @@ test.skipIf(isDebug)('connect', async () => {
   }
 })
 
+sandboxTest.skipIf(isDebug)(
+  'connect resumes paused sandbox',
+  async ({ sandbox }) => {
+    await sandbox.pause()
+    assert.isFalse(await sandbox.isRunning())
+
+    const resumed = await Sandbox.connect(sandbox.sandboxId)
+    assert.isTrue(await resumed.isRunning())
+  }
+)
+
 sandboxTest.skipIf(isDebug)(
   'connect to non-running sandbox',
   async ({ sandbox }) => {

packages/js-sdk/tests/sandbox/lifecyclePayload.test.ts

@@ -0,0 +1,63 @@
+import { assert, test } from 'vitest'
+
+import { Sandbox } from '../../src'
+import { isDebug, template, wait } from '../setup.js'
+
+test.skipIf(isDebug)(
+  'auto-pause without auto-resume requires connect to wake',
+  async () => {
+    const sandbox = await Sandbox.create(template, {
+      timeoutMs: 3_000,
+      lifecycle: {
+        onTimeout: 'pause',
+        autoResume: false,
+      },
+    })
+
+    try {
+      await wait(5_000)
+
+      assert.equal((await sandbox.getInfo()).state, 'paused')
+      assert.isFalse(await sandbox.isRunning())
+
+      await sandbox.connect()
+
+      assert.equal((await sandbox.getInfo()).state, 'running')
+      assert.isTrue(await sandbox.isRunning())
+    } finally {
+      await sandbox.kill().catch(() => {})
+    }
+  },
+  60_000
+)
+
+test.skipIf(isDebug)(
+  'auto-resume wakes paused sandbox on http request',
+  async () => {
+    const sandbox = await Sandbox.create(template, {
+      timeoutMs: 3_000,
+      lifecycle: {
+        onTimeout: 'pause',
+        autoResume: true,
+      },
+    })
+
+    try {
+      await sandbox.commands.run('python3 -m http.server 8000', {
+        background: true,
+      })
+
+      await wait(5_000)
+
+      const url = `https://${sandbox.getHost(8000)}`
+      const res = await fetch(url, { signal: AbortSignal.timeout(15_000) })
+
+      assert.equal(res.status, 200)
+      assert.equal((await sandbox.getInfo()).state, 'running')
+      assert.isTrue(await sandbox.isRunning())
+    } finally {
+      await sandbox.kill().catch(() => {})
+    }
+  },
+  60_000
+)

packages/js-sdk/tests/sandbox/snapshot.test.ts

@@ -7,7 +7,7 @@ sandboxTest.skipIf(isDebug)(
   async ({ sandbox }) => {
     assert.isTrue(await sandbox.isRunning())
 
-    await sandbox.betaPause()
+    await sandbox.pause()
 
     assert.isFalse(await sandbox.isRunning())
 
@@ -35,7 +35,7 @@ describe('pause and resume with env vars', () => {
       assert.equal(cmd.exitCode, 0)
       assert.equal(cmd.stdout.trim(), 'sfisback')
 
-      await sandbox.betaPause()
+      await sandbox.pause()
 
       assert.isFalse(await sandbox.isRunning())
 
@@ -68,7 +68,7 @@ sandboxTest.skipIf(isDebug)(
     const readContent = await sandbox.files.read(filename)
     assert.equal(readContent, content)
 
-    await sandbox.betaPause()
+    await sandbox.pause()
     assert.isFalse(await sandbox.isRunning())
 
     await sandbox.connect()
@@ -87,7 +87,7 @@ sandboxTest.skipIf(isDebug)(
     const cmd = await sandbox.commands.run('sleep 3600', { background: true })
     const expectedPid = cmd.pid
 
-    await sandbox.betaPause()
+    await sandbox.pause()
     assert.isFalse(await sandbox.isRunning())
 
     await sandbox.connect()
@@ -121,7 +121,7 @@ sandboxTest.skipIf(isDebug)(
     const exists = await sandbox.files.exists(filename)
     assert.isFalse(exists)
 
-    await sandbox.betaPause()
+    await sandbox.pause()
     assert.isFalse(await sandbox.isRunning())
 
     await sandbox.connect()
@@ -151,7 +151,7 @@ sandboxTest.skipIf(isDebug)(
     const response1 = await fetch(`https://${url}`)
     assert.equal(response1.status, 200)
 
-    await sandbox.betaPause()
+    await sandbox.pause()
     assert.isFalse(await sandbox.isRunning())
 
     await sandbox.connect()

packages/python-sdk/e2b/__init__.py

@@ -68,6 +68,7 @@
     McpServer,
     SandboxInfo,
     SandboxMetrics,
+    SandboxLifecycle,
     SandboxNetworkOpts,
     SandboxQuery,
     SandboxState,
@@ -154,6 +155,7 @@
     "FileType",
     # Network
     "SandboxNetworkOpts",
+    "SandboxLifecycle",
     "ALL_TRAFFIC",
     # Snapshot
     "SnapshotInfo",