Update connect method (#1001)

<!-- CURSOR_SUMMARY -->
> [!NOTE]
> Use new connect API for JS/Python SDKs to connect and only extend
(never shorten) running sandbox timeouts, with updated types/docs and
tests.
> 
> - **SDKs**:
>   - **JS**:
> - Replace `resume`/`setTimeout` flow with `SandboxApi.connectSandbox`
calling `POST /sandboxes/{sandboxID}/connect`.
> - Update `Sandbox.connect` (static/instance) to use returned
`sandboxDomain`, `envdAccessToken`, `envdVersion`.
> - Redefine `SandboxConnectOpts` to include `timeoutMs` that only
extends existing timeout.
>   - **Python (async/sync)**:
> - Introduce `_cls_connect` using `post_sandboxes_sandbox_id_connect`
with `ConnectSandbox`; return `Sandbox` model.
> - Update `connect` methods to use API response for
domain/token/version; remove extra info fetch.
>     - Docstrings clarify timeout only extends for running sandboxes.
> - **Tests**:
> - Add cases ensuring connect does not shorten timeout and does extend
when longer (JS, async Python, sync Python).
>   - Preserve error on connecting to non-running sandbox.
> - **Meta**:
> - Changeset: minor releases for `@e2b/python-sdk`, `e2b`, and
`@e2b/cli`.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
e76b079. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: jakubno

.changeset/serious-badgers-jump.md

@@ -0,0 +1,7 @@
+---
+'@e2b/python-sdk': minor
+'e2b': minor
+'@e2b/cli': minor
+---
+
+Update connect to only extend timeout

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

@@ -404,29 +404,14 @@ export class Sandbox extends SandboxApi {
     sandboxId: string,
     opts?: SandboxConnectOpts
   ): Promise<InstanceType<S>> {
-    try {
-      await SandboxApi.setTimeout(
-        sandboxId,
-        opts?.timeoutMs || DEFAULT_SANDBOX_TIMEOUT_MS,
-        opts
-      )
-    } catch (e) {
-      if (e instanceof SandboxError) {
-        await SandboxApi.resumeSandbox(sandboxId, opts)
-      } else {
-        throw e
-      }
-    }
-
-    const info = await SandboxApi.getFullInfo(sandboxId, opts)
-
+    const sandbox = await SandboxApi.connectSandbox(sandboxId, opts)
     const config = new ConnectionConfig(opts)
 
     return new this({
       sandboxId,
-      sandboxDomain: info.sandboxDomain,
-      envdAccessToken: info.envdAccessToken,
-      envdVersion: info.envdVersion,
+      sandboxDomain: sandbox.sandboxDomain,
+      envdAccessToken: sandbox.envdAccessToken,
+      envdVersion: sandbox.envdVersion,
       ...config,
     }) as InstanceType<S>
   }
@@ -451,15 +436,7 @@ export class Sandbox extends SandboxApi {
    * ```
    */
   async connect(opts?: SandboxBetaCreateOpts): Promise<this> {
-    try {
-      await SandboxApi.setTimeout(
-        this.sandboxId,
-        opts?.timeoutMs || DEFAULT_SANDBOX_TIMEOUT_MS,
-        opts
-      )
-    } catch (e) {
-      await SandboxApi.resumeSandbox(this.sandboxId, opts)
-    }
+    await SandboxApi.connectSandbox(this.sandboxId, opts)
 
     return this
   }

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

@@ -103,7 +103,16 @@ export type SandboxBetaCreateOpts = SandboxOpts & {
 /**
  * Options for connecting to a Sandbox.
  */
-export type SandboxConnectOpts = Omit<SandboxOpts, 'metadata' | 'envs'>
+export type SandboxConnectOpts = ConnectionOpts & {
+  /**
+   * Timeout for the sandbox in **milliseconds**.
+   * For running sandboxes, the timeout will update only if the new timeout is longer than the existing one.
+   * 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.
+   *
+   * @default 300_000 // 5 minutes
+   */
+  timeoutMs?: number
+}
 
 /**
  * State of the sandbox.
@@ -468,12 +477,7 @@ export class SandboxApi {
     template: string,
     timeoutMs: number,
     opts?: SandboxBetaCreateOpts
-  ): Promise<{
-    sandboxId: string
-    sandboxDomain?: string
-    envdVersion: string
-    envdAccessToken?: string
-  }> {
+  ) {
     const config = new ConnectionConfig(opts)
     const client = new ApiClient(config)
 
@@ -512,16 +516,16 @@ export class SandboxApi {
     }
   }
 
-  protected static async resumeSandbox(
+  protected static async connectSandbox(
     sandboxId: string,
     opts?: SandboxConnectOpts
-  ): Promise<boolean> {
+  ) {
     const timeoutMs = opts?.timeoutMs ?? DEFAULT_SANDBOX_TIMEOUT_MS
 
     const config = new ConnectionConfig(opts)
     const client = new ApiClient(config)
 
-    const res = await client.api.POST('/sandboxes/{sandboxID}/resume', {
+    const res = await client.api.POST('/sandboxes/{sandboxID}/connect', {
       params: {
         path: {
           sandboxID: sandboxId,
@@ -537,17 +541,17 @@ export class SandboxApi {
       throw new NotFoundError(`Paused sandbox ${sandboxId} not found`)
     }
 
-    if (res.error?.code === 409) {
-      // Sandbox is already running
-      return false
-    }
-
     const err = handleApiError(res)
     if (err) {
       throw err
     }
 
-    return true
+    return {
+      sandboxId: res.data!.sandboxID,
+      sandboxDomain: res.data!.domain || undefined,
+      envdVersion: res.data!.envdVersion,
+      envdAccessToken: res.data!.envdAccessToken,
+    }
   }
 }
 

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

@@ -35,3 +35,54 @@ sandboxTest.skipIf(isDebug)(
     )
   }
 )
+
+test.skipIf(isDebug)(
+  'connect does not shorten timeout on running sandbox',
+  async () => {
+    // Create sandbox with a 300 second timeout
+    const sbx = await Sandbox.create(template, { timeoutMs: 300_000 })
+
+    try {
+      const isRunning = await sbx.isRunning()
+      assert.isTrue(isRunning)
+
+      // Get initial info to check endAt
+      const infoBefore = await Sandbox.getInfo(sbx.sandboxId)
+
+      // Connect with a shorter timeout (10 seconds)
+      await Sandbox.connect(sbx.sandboxId, { timeoutMs: 10_000 })
+
+      // Get info after connection
+      const infoAfter = await sbx.getInfo()
+
+      // The endAt time should not have been shortened. It should be the same
+      assert.equal(
+        infoAfter.endAt.getTime(),
+        infoBefore.endAt.getTime(),
+        `Timeout was shortened: before=${infoBefore.endAt.toISOString()}, after=${infoAfter.endAt.toISOString()}`
+      )
+    } finally {
+      await sbx.kill()
+    }
+  }
+)
+
+sandboxTest.skipIf(isDebug)(
+  'connect extends timeout on running sandbox',
+  async ({ sandbox }) => {
+    // Get initial info to check endAt
+    const infoBefore = await sandbox.getInfo()
+
+    // Connect with a longer timeout
+    await sandbox.connect({ timeoutMs: 600_000 })
+
+    // Get info after connection
+    const infoAfter = await sandbox.getInfo()
+
+    // The endAt time should have been extended
+    assert.isTrue(
+      infoAfter.endAt.getTime() > infoBefore.endAt.getTime(),
+      `Timeout was not extended: before=${infoBefore.endAt.toISOString()}, after=${infoAfter.endAt.toISOString()}`
+    )
+  }
+)

packages/python-sdk/e2b/sandbox_async/main.py

@@ -228,6 +228,7 @@ async def connect(
         With sandbox ID you can connect to the same sandbox from different places or environments (serverless functions, etc).
 
         :param timeout: Timeout for the sandbox in **seconds**
+            For running sandboxes, the timeout will update only if the new timeout is longer than the existing one.
         :return: A running sandbox instance
 
         @example
@@ -257,6 +258,7 @@ async def connect(
 
         :param sandbox_id: Sandbox ID
         :param timeout: Timeout for the sandbox in **seconds**
+            For running sandboxes, the timeout will update only if the new timeout is longer than the existing one.
         :return: A running sandbox instance
 
         @example
@@ -283,6 +285,7 @@ async def connect(
         With sandbox ID you can connect to the same sandbox from different places or environments (serverless functions, etc).
 
         :param timeout: Timeout for the sandbox in **seconds**
+            For running sandboxes, the timeout will update only if the new timeout is longer than the existing one.
         :return: A running sandbox instance
 
         @example
@@ -294,7 +297,7 @@ async def connect(
         same_sandbox = await sandbox.connect()
         ```
         """
-        await SandboxApi._cls_resume(
+        await SandboxApi._cls_connect(
             sandbox_id=self.sandbox_id,
             timeout=timeout,
             **opts,
@@ -650,16 +653,14 @@ async def _cls_connect(
         timeout: Optional[int] = None,
         **opts: Unpack[ApiParams],
     ) -> Self:
-        await SandboxApi._cls_resume(
+        sandbox = await SandboxApi._cls_connect(
             sandbox_id=sandbox_id,
             timeout=timeout,
             **opts,
         )
 
-        response = await SandboxApi._cls_get_info(sandbox_id, **opts)
-
         sandbox_headers = {}
-        envd_access_token = response._envd_access_token
+        envd_access_token = sandbox.envd_access_token
         if envd_access_token is not None and not isinstance(envd_access_token, Unset):
             sandbox_headers["X-Access-Token"] = envd_access_token
 
@@ -669,9 +670,9 @@ async def _cls_connect(
         )
 
         return cls(
-            sandbox_id=response.sandbox_id,
-            sandbox_domain=response.sandbox_domain,
-            envd_version=Version(response.envd_version),
+            sandbox_id=sandbox.sandbox_id,
+            sandbox_domain=sandbox.domain,
+            envd_version=Version(sandbox.envd_version),
             envd_access_token=envd_access_token,
             connection_config=connection_config,
         )

packages/python-sdk/e2b/sandbox_async/sandbox_api.py

@@ -13,7 +13,8 @@
     NewSandbox,
     PostSandboxesSandboxIDTimeoutBody,
     Error,
-    ResumedSandbox,
+    ConnectSandbox,
+    Sandbox,
 )
 from e2b.api.client.api.sandboxes import (
     get_sandboxes_sandbox_id,
@@ -22,7 +23,7 @@
     post_sandboxes,
     get_sandboxes_sandbox_id_metrics,
     post_sandboxes_sandbox_id_pause,
-    post_sandboxes_sandbox_id_resume,
+    post_sandboxes_sandbox_id_connect,
 )
 from e2b.connection_config import ConnectionConfig, ApiParams
 from e2b.api import handle_api_exception
@@ -282,52 +283,42 @@ async def _cls_pause(
             if res.status_code >= 300:
                 raise handle_api_exception(res)
 
+            # Check if res.parse is Error
+            if isinstance(res.parsed, Error):
+                raise SandboxException(f"{res.parsed.message}: Request failed")
+
             return sandbox_id
 
     @classmethod
-    async def _cls_resume(
+    async def _cls_connect(
         cls,
         sandbox_id: str,
         timeout: Optional[int] = None,
         **opts: Unpack[ApiParams],
-    ) -> bool:
+    ) -> Sandbox:
         timeout = timeout or SandboxBase.default_sandbox_timeout
 
-        # 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 SandboxApi._cls_set_timeout(
-                sandbox_id=sandbox_id,
-                timeout=timeout,
-                **opts,
+        # Sandbox is not running, resume it
+        config = ConnectionConfig(**opts)
+
+        async with AsyncApiClient(
+            config,
+            limits=SandboxBase._limits,
+        ) as api_client:
+            res = await post_sandboxes_sandbox_id_connect.asyncio_detailed(
+                sandbox_id,
+                client=api_client,
+                body=ConnectSandbox(timeout=timeout),
             )
-            return False
-        except SandboxException:
-            # Sandbox is not running, resume it
-            config = ConnectionConfig(**opts)
-
-            async with AsyncApiClient(
-                config,
-                limits=SandboxBase._limits,
-            ) as api_client:
-                res = await post_sandboxes_sandbox_id_resume.asyncio_detailed(
-                    sandbox_id,
-                    client=api_client,
-                    body=ResumedSandbox(timeout=timeout),
-                )
 
-                if res.status_code == 404:
-                    raise NotFoundException(f"Paused sandbox {sandbox_id} not found")
+            if res.status_code == 404:
+                raise NotFoundException(f"Paused sandbox {sandbox_id} not found")
 
-                if res.status_code == 409:
-                    return False
+            if res.status_code >= 300:
+                raise handle_api_exception(res)
 
-                if res.status_code >= 300:
-                    raise handle_api_exception(res)
+            # Check if res.parse is Error
+            if isinstance(res.parsed, Error):
+                raise SandboxException(f"{res.parsed.message}: Request failed")
 
-                return True
+            return res.parsed