Add auto pause on timeout to SDK

apps/web/src/code/python/agents/code_exec.py

@@ -9,6 +9,7 @@ def print_out(output):
 sandbox = Sandbox(
     # You can pass your own sandbox template id
     template="base",
+    auto_pause=True,
 )
 
 # 2. Save the JavaScript code to a file inside the playground

packages/js-sdk/example.mts

@@ -6,7 +6,7 @@ dotenv.config()
 
 const start = Date.now()
 console.log('creating sandbox')
-const sbx = await Sandbox.create('k1urqpinffy6bcost93w', { timeoutMs: 10000 })
+const sbx = await Sandbox.create({ timeoutMs: 10000, autoPause: true })
 console.log('sandbox created', Date.now() - start)
 console.log(sbx.sandboxId)
 
@@ -31,7 +31,7 @@ console.log(sbx.sandboxId)
 
 const resumeStart = Date.now()
 console.log('resuming sandbox')
-const resumed = await Sandbox.resume(sbx.sandboxId, { timeoutMs: 10000 })
+const resumed = await Sandbox.connect(sbx.sandboxId, { timeoutMs: 10000, autoPause: true })
 console.log('sandbox resumed', Date.now() - resumeStart)
 
 const content = await resumed.files.read('/home/user/test.txt')

packages/js-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "e2b",
-  "version": "1.1.0-beta.1",
+  "version": "1.1.0-autopause.1",
   "description": "E2B SDK that give agents cloud environments",
   "homepage": "https://e2b.dev",
   "license": "MIT",

packages/js-sdk/src/envd/filesystem/filesystem_pb.ts

@@ -1,4 +1,4 @@
-// @generated by protoc-gen-es v2.2.2 with parameter "target=ts"
+// @generated by protoc-gen-es v2.2.3 with parameter "target=ts"
 // @generated from file filesystem/filesystem.proto (package filesystem, syntax proto3)
 /* eslint-disable */
 

packages/js-sdk/src/envd/process/process_pb.ts

@@ -1,4 +1,4 @@
-// @generated by protoc-gen-es v2.2.2 with parameter "target=ts"
+// @generated by protoc-gen-es v2.2.3 with parameter "target=ts"
 // @generated from file process/process.proto (package process, syntax proto3)
 /* eslint-disable */
 

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

@@ -1,10 +1,6 @@
 import { createConnectTransport } from '@connectrpc/connect-web'
 
-import {
-  ConnectionConfig,
-  ConnectionOpts,
-  defaultUsername,
-} from '../connectionConfig'
+import { ConnectionConfig, ConnectionOpts, defaultUsername } from '../connectionConfig'
 import { EnvdApiClient, handleEnvdApiError } from '../envd/api'
 import { createRpcLogger } from '../logs'
 import { Commands, Pty } from './commands'
@@ -37,6 +33,11 @@ export interface SandboxOpts extends ConnectionOpts {
    * @default 300_000 // 5 minutes
    */
   timeoutMs?: number
+  /**
+   * Automatically pause the sandbox after the timeout expires.
+   *
+   */
+  autoPause: true
 }
 
 /**
@@ -63,6 +64,7 @@ export interface SandboxOpts extends ConnectionOpts {
 export class Sandbox extends SandboxApi {
   protected static readonly defaultTemplate: string = 'base'
   protected static readonly defaultSandboxTimeoutMs = 300_000
+  protected static readonly defaultSandboxAutoPause = false
 
   /**
    * Module for interacting with the sandbox filesystem
@@ -97,7 +99,7 @@ export class Sandbox extends SandboxApi {
    * @access protected
    */
   constructor(
-    opts: Omit<SandboxOpts, 'timeoutMs' | 'envs' | 'metadata'> & {
+    opts: Omit<SandboxOpts, 'timeoutMs' | 'envs' | 'metadata' | 'autoPause'> & {
       sandboxId: string
     }
   ) {
@@ -142,7 +144,7 @@ export class Sandbox extends SandboxApi {
    */
   static async create<S extends typeof Sandbox>(
     this: S,
-    opts?: SandboxOpts
+    opts: SandboxOpts
   ): Promise<InstanceType<S>>
 
   /**
@@ -162,7 +164,7 @@ export class Sandbox extends SandboxApi {
   static async create<S extends typeof Sandbox>(
     this: S,
     template: string,
-    opts?: SandboxOpts
+    opts: SandboxOpts
   ): Promise<InstanceType<S>>
   static async create<S extends typeof Sandbox>(
     this: S,
@@ -174,13 +176,18 @@ export class Sandbox extends SandboxApi {
         ? { template: templateOrOpts, sandboxOpts: opts }
         : { template: this.defaultTemplate, sandboxOpts: templateOrOpts }
 
+    if (!sandboxOpts?.autoPause) {
+      throw new Error('autoPause must be set to true when creating a sandbox')
+    }
+
     const config = new ConnectionConfig(sandboxOpts)
 
     const sandboxId = config.debug
       ? 'debug_sandbox_id'
       : await this.createSandbox(
         template,
         sandboxOpts?.timeoutMs ?? this.defaultSandboxTimeoutMs,
+        sandboxOpts?.autoPause ?? this.defaultSandboxAutoPause,
         sandboxOpts
       )
 
@@ -189,53 +196,53 @@ export class Sandbox extends SandboxApi {
   }
 
   /**
-   * Connect to an existing sandbox.
+   * Connect to or resume an existing sandbox.
    * With sandbox ID you can connect to the same sandbox from different places or environments (serverless functions, etc).
-   *
-   * @param sandboxId sandbox ID.
-   * @param opts connection options.
-   *
-   * @returns sandbox instance for the existing sandbox.
-   *
-   * @example
-   * ```ts
-   * const sandbox = await Sandbox.create()
-   * const sandboxId = sandbox.sandboxId
-   *
-   * // Connect to the same sandbox.
-   * const sameSandbox = await Sandbox.connect(sandboxId)
-   * ```
-   */
-  static async connect<S extends typeof Sandbox>(
-    this: S,
-    sandboxId: string,
-    opts?: Omit<SandboxOpts, 'metadata' | 'envs' | 'timeoutMs'>
-  ): Promise<InstanceType<S>> {
-    const config = new ConnectionConfig(opts)
-
-    const sbx = new this({ sandboxId, ...config }) as InstanceType<S>
-    return sbx
-  }
-
-  /**
-   * Resume the sandbox.
    * 
    * The **default sandbox timeout of 300 seconds** ({@link Sandbox.defaultSandboxTimeoutMs}) will be used for the resumed sandbox.
    * If you pass a custom timeout in the `opts` parameter via {@link SandboxOpts.timeoutMs} property, it will be used instead.
+   * If the sandbox is running, the timeout will be updated to the new value (or default).
    *
    * @param sandboxId sandbox ID.
    * @param opts connection options.
    *
    * @returns a running sandbox instance.
    */
-  static async resume<S extends typeof Sandbox>(
+  static async connect<S extends typeof Sandbox>(
     this: S,
     sandboxId: string,
-    opts?: Omit<SandboxOpts, 'metadata' | 'envs'>
+    opts: Omit<SandboxOpts, 'metadata' | 'envs'>
   ): Promise<InstanceType<S>> {
-    await Sandbox.resumeSandbox(sandboxId, opts?.timeoutMs ?? this.defaultSandboxTimeoutMs, opts)
+    if (!opts.autoPause) {
+      throw new Error('autoPause must be set to true when connecting to a sandbox')
+    }
+
+    const timeoutMs = opts?.timeoutMs ?? this.defaultSandboxTimeoutMs
+
+    // Temporary solution (02/12/2025),
+    // Options discussed:
+    //   # 1. No set - never sure how long the sandbox will be running
+    // 2. Always set the timeout in code - the user can't just connect to the sandbox
+    //       without changing the timeout, round trip to the server time
+    // 3. Set the timeout in resume on backend - side effect on error
+    // 4. Create new endpoint for connect
+    try {
+      await Sandbox.setTimeout(sandboxId, timeoutMs, opts)
+    } catch (err) {
+      // Sandbox is not running or found, ignore the error
+    }
+
+    await Sandbox.resumeSandbox(
+      sandboxId,
+      timeoutMs,
+      opts.autoPause ?? this.defaultSandboxAutoPause,
+      opts
+    )
 
-    return await this.connect(sandboxId, opts)
+    const config = new ConnectionConfig(opts)
+
+    const sbx = new this({ sandboxId, ...config }) as InstanceType<S>
+    return sbx
   }
 
   /**
@@ -300,7 +307,7 @@ export class Sandbox extends SandboxApi {
 
   /**
    * Set the timeout of the sandbox.
-   * After the timeout expires the sandbox will be automatically killed.
+   * After the timeout expires the sandbox will be automatically paused.
    *
    * This method can extend or reduce the sandbox timeout set when creating the sandbox or from the last call to `.setTimeout`.
    * Maximum time a sandbox can be kept alive is 24 hours (86_400_000 milliseconds) for Pro users and 1 hour (3_600_000 milliseconds) for Hobby users.

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

@@ -116,7 +116,7 @@ export class SandboxApi {
 
   /**
    * Set the timeout of the specified sandbox.
-   * After the timeout expires the sandbox will be automatically killed.
+   * After the timeout expires the sandbox will be automatically paused.
    *
    * This method can extend or reduce the sandbox timeout set when creating the sandbox or from the last call to {@link Sandbox.setTimeout}.
    *
@@ -197,7 +197,8 @@ export class SandboxApi {
   protected static async resumeSandbox(
     sandboxId: string,
     timeoutMs: number,
-    opts?: SandboxApiOpts
+    autoPause: boolean,
+    opts?: SandboxApiOpts,
   ): Promise<boolean> {
     const config = new ConnectionConfig(opts)
     const client = new ApiClient(config)
@@ -210,6 +211,7 @@ export class SandboxApi {
       },
       body: {
         timeout: this.timeoutToSeconds(timeoutMs),
+        autoPause: autoPause,
       },
       signal: config.getSignal(opts?.requestTimeoutMs),
     })
@@ -234,6 +236,7 @@ export class SandboxApi {
   protected static async createSandbox(
     template: string,
     timeoutMs: number,
+    autoPause: boolean,
     opts?: SandboxApiOpts & {
       metadata?: Record<string, string>
       envs?: Record<string, string>
@@ -248,6 +251,7 @@ export class SandboxApi {
         metadata: opts?.metadata,
         envVars: opts?.envs,
         timeout: this.timeoutToSeconds(timeoutMs),
+        autoPause: autoPause,
       },
       signal: config.getSignal(opts?.requestTimeoutMs),
     })

packages/js-sdk/tests/runtimes/browser/run.test.tsx

@@ -10,7 +10,7 @@ function E2BTest() {
 
   useEffect(() => {
     const getText = async () => {
-      const sandbox = await Sandbox.create()
+      const sandbox = await Sandbox.create({autoPause: true})
 
       try {
         await sandbox.commands.run('echo "Hello World" > hello.txt')

packages/js-sdk/tests/runtimes/bun/run.test.ts

@@ -5,7 +5,7 @@ import { Sandbox } from '../../../src'
 test(
   'Bun test',
   async ({ template }) => {
-    const sbx = await Sandbox.create(template, { timeoutMs: 5_000 })
+    const sbx = await Sandbox.create(template, { timeoutMs: 5_000, autoPause: true })
     try {
       const isRunning = await sbx.isRunning()
       expect(isRunning).toBeTruthy()

packages/js-sdk/tests/runtimes/deno/run.test.ts

@@ -7,7 +7,7 @@ import { Sandbox } from '../../../dist/index.mjs'
 
 
 Deno.test('Deno test', async ({ template }) => {
-  const sbx = await Sandbox.create(template, { timeoutMs: 5_000 })
+  const sbx = await Sandbox.create(template, { timeoutMs: 5_000, autoPause: true })
   try {
     const isRunning = await sbx.isRunning()
     assert(isRunning)

packages/js-sdk/tests/sandbox/commands/envVars.test.ts

@@ -11,7 +11,7 @@ sandboxTest.skipIf(isDebug)('env vars', async ({ sandbox }) => {
 })
 
 sandboxTest.skipIf(isDebug)('env vars on sandbox', async ({ template }) => {
-  const sandbox = await Sandbox.create(template, { envs: { FOO: 'bar' } })
+  const sandbox = await Sandbox.create(template, { envs: { FOO: 'bar' }, autoPause: true })
 
   try {
     const cmd = await sandbox.commands.run('echo "$FOO"')

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

@@ -4,13 +4,13 @@ import { Sandbox } from '../../src'
 import { isDebug, template } from '../setup.js'
 
 test('connect', async () => {
-  const sbx = await Sandbox.create(template, { timeoutMs: 10_000 })
+  const sbx = await Sandbox.create(template, { timeoutMs: 10_000, autoPause: true })
 
   try {
     const isRunning = await sbx.isRunning()
     assert.isTrue(isRunning)
 
-    const sbxConnection = await Sandbox.connect(sbx.sandboxId)
+    const sbxConnection = await Sandbox.connect(sbx.sandboxId, {autoPause: true})
     const isRunning2 = await sbxConnection.isRunning()
     assert.isTrue(isRunning2)
   } finally {

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

@@ -1,10 +1,10 @@
-import { test, assert } from 'vitest'
+import { assert, expect, test } from 'vitest'
 
 import { Sandbox } from '../../src'
-import { template, isDebug } from '../setup.js'
+import { isDebug, template, wait } from '../setup.js'
 
 test.skipIf(isDebug)('create', async () => {
-  const sbx = await Sandbox.create(template, { timeoutMs: 5_000 })
+  const sbx = await Sandbox.create(template, { timeoutMs: 5_000, autoPause: true })
   try {
     const isRunning = await sbx.isRunning()
     assert.isTrue(isRunning)
@@ -18,7 +18,7 @@ test.skipIf(isDebug)('metadata', async () => {
     'test-key': 'test-value',
   }
 
-  const sbx = await Sandbox.create(template, { timeoutMs: 5_000, metadata })
+  const sbx = await Sandbox.create(template, { timeoutMs: 5_000, metadata, autoPause: true })
 
   try {
     const sbxs = await Sandbox.list()
@@ -29,3 +29,20 @@ test.skipIf(isDebug)('metadata', async () => {
     await sbx.kill()
   }
 })
+
+test.skipIf(isDebug)('auto pause', async () => {
+  const timeout = 1_000
+  const sbx = await Sandbox.create(template, { timeoutMs: timeout, autoPause: true })
+  await sbx.files.write('test.txt', 'test')
+
+  // Wait for the sandbox to pause and create snapshot
+  await wait(timeout + 5_000)
+
+  const sbxResumed = await Sandbox.connect(sbx.sandboxId, { timeoutMs: 5_000, autoPause: true })
+
+  try {
+    await expect(sbxResumed.files.read('test.txt')).resolves.toEqual('test')
+  } finally {
+    await sbxResumed.kill()
+  }
+})

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

@@ -6,7 +6,7 @@ sandboxTest('ping server in sandbox', async ({ sandbox }) => {
   const cmd = await sandbox.commands.run('python -m http.server 8000', { background: true })
 
   try {
-    await wait(1000)
+    await wait(5000)
 
     const host = sandbox.getHost(8000)