sdk: allow envs when connecting to a sandbox

Adds optional envs parameter to Sandbox.connect() in JS and Python SDKs.
Maps to envVars on the wire, matching create-time convention.
Uses UNSET (not None) in Python so the field is omitted when not supplied.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: FisherXZ

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

@@ -200,6 +200,11 @@ export type SandboxConnectOpts = ConnectionOpts & {
    * @default 300_000 // 5 minutes
    */
   timeoutMs?: number
+  /**
+   * Custom environment variables to set in the sandbox on reconnect.
+   * These are merged into the sandbox environment and applied to processes started after resume.
+   */
+  envs?: Record<string, string>
 }
 
 /**
@@ -845,6 +850,7 @@ export class SandboxApi {
       },
       body: {
         timeout: timeoutToSeconds(timeoutMs),
+        ...(opts?.envs !== undefined ? { envVars: opts.envs } : {}),
       },
       signal: config.getSignal(opts?.requestTimeoutMs),
     })

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

@@ -57,3 +57,43 @@ describe('Sandbox API config propagation', () => {
     assert.equal(opts?.debug, baseConfig.debug)
   })
 })
+
+describe('Sandbox connect envs propagation', () => {
+  const mockConnectResult = {
+    sandboxId: 'sbx-test',
+    sandboxDomain: 'sandbox.e2b.dev',
+    envdVersion: '0.2.4',
+    envdAccessToken: 'tok',
+    trafficAccessToken: 'tok',
+  }
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  test('forwards envs to connectSandbox when provided', async () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const connectSpy = vi
+      .spyOn(SandboxApi as any, 'connectSandbox')
+      .mockResolvedValue(mockConnectResult)
+    const sandbox = createSandbox()
+
+    await sandbox.connect({ envs: { MY_KEY: 'my_value' } })
+
+    const opts = connectSpy.mock.calls[0][1]
+    assert.deepEqual(opts?.envs, { MY_KEY: 'my_value' })
+  })
+
+  test('does not include envs in opts when not provided', async () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const connectSpy = vi
+      .spyOn(SandboxApi as any, 'connectSandbox')
+      .mockResolvedValue(mockConnectResult)
+    const sandbox = createSandbox()
+
+    await sandbox.connect()
+
+    const opts = connectSpy.mock.calls[0][1]
+    assert.isUndefined(opts?.envs)
+  })
+})

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

@@ -248,6 +248,7 @@ async def create(
     async def connect(
         self,
         timeout: Optional[int] = None,
+        envs: Optional[Dict[str, str]] = None,
         **opts: Unpack[ApiParams],
     ) -> Self:
         """
@@ -258,6 +259,8 @@ async def connect(
 
         :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.
+        :param envs: Custom environment variables to set in the sandbox on reconnect.
+            Merged into the sandbox environment and applied to processes started after resume.
         :return: A running sandbox instance
 
         @example
@@ -276,6 +279,7 @@ async def connect(
     async def connect(
         sandbox_id: str,
         timeout: Optional[int] = None,
+        envs: Optional[Dict[str, str]] = None,
         **opts: Unpack[ApiParams],
     ) -> "AsyncSandbox":
         """
@@ -287,6 +291,8 @@ 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.
+        :param envs: Custom environment variables to set in the sandbox on reconnect.
+            Merged into the sandbox environment and applied to processes started after resume.
         :return: A running sandbox instance
 
         @example
@@ -304,6 +310,7 @@ async def connect(
     async def connect(
         self,
         timeout: Optional[int] = None,
+        envs: Optional[Dict[str, str]] = None,
         **opts: Unpack[ApiParams],
     ) -> Self:
         """
@@ -314,6 +321,8 @@ async def connect(
 
         :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.
+        :param envs: Custom environment variables to set in the sandbox on reconnect.
+            Merged into the sandbox environment and applied to processes started after resume.
         :return: A running sandbox instance
 
         @example
@@ -328,6 +337,7 @@ async def connect(
         await SandboxApi._cls_connect(
             sandbox_id=self.sandbox_id,
             timeout=timeout,
+            envs=envs,
             **self.connection_config.get_api_params(**opts),
         )
 

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

@@ -378,6 +378,7 @@ async def _cls_connect(
         cls,
         sandbox_id: str,
         timeout: Optional[int] = None,
+        envs: Optional[Dict[str, str]] = None,
         **opts: Unpack[ApiParams],
     ) -> Sandbox:
         timeout = timeout or SandboxBase.default_sandbox_timeout
@@ -395,7 +396,10 @@ async def _cls_connect(
         res = await post_sandboxes_sandbox_id_connect.asyncio_detailed(
             sandbox_id,
             client=api_client,
-            body=ConnectSandbox(timeout=timeout),
+            body=ConnectSandbox(
+                timeout=timeout,
+                env_vars=envs if envs is not None else UNSET,
+            ),
         )
 
         if res.status_code == 404:

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

@@ -246,6 +246,7 @@ def create(
     def connect(
         self,
         timeout: Optional[int] = None,
+        envs: Optional[Dict[str, str]] = None,
         **opts: Unpack[ApiParams],
     ) -> Self:
         """
@@ -256,6 +257,8 @@ def connect(
 
         :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.
+        :param envs: Custom environment variables to set in the sandbox on reconnect.
+            Merged into the sandbox environment and applied to processes started after resume.
         :return: A running sandbox instance
 
         @example
@@ -275,6 +278,7 @@ def connect(
     def connect(
         sandbox_id: str,
         timeout: Optional[int] = None,
+        envs: Optional[Dict[str, str]] = None,
         **opts: Unpack[ApiParams],
     ) -> "Sandbox":
         """
@@ -286,6 +290,8 @@ 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.
+        :param envs: Custom environment variables to set in the sandbox on reconnect.
+            Merged into the sandbox environment and applied to processes started after resume.
         :return: A running sandbox instance
 
         @example
@@ -303,6 +309,7 @@ def connect(
     def connect(
         self,
         timeout: Optional[int] = None,
+        envs: Optional[Dict[str, str]] = None,
         **opts: Unpack[ApiParams],
     ) -> Self:
         """
@@ -313,6 +320,8 @@ def connect(
 
         :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.
+        :param envs: Custom environment variables to set in the sandbox on reconnect.
+            Merged into the sandbox environment and applied to processes started after resume.
         :return: A running sandbox instance
 
         @example
@@ -327,6 +336,7 @@ def connect(
         SandboxApi._cls_connect(
             sandbox_id=self.sandbox_id,
             timeout=timeout,
+            envs=envs,
             **self.connection_config.get_api_params(**opts),
         )
 

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

@@ -287,6 +287,7 @@ def _cls_connect(
         cls,
         sandbox_id: str,
         timeout: Optional[int] = None,
+        envs: Optional[Dict[str, str]] = None,
         **opts: Unpack[ApiParams],
     ) -> Sandbox:
         timeout = timeout or SandboxBase.default_sandbox_timeout
@@ -303,7 +304,10 @@ def _cls_connect(
         res = post_sandboxes_sandbox_id_connect.sync_detailed(
             sandbox_id,
             client=api_client,
-            body=ConnectSandbox(timeout=timeout),
+            body=ConnectSandbox(
+                timeout=timeout,
+                env_vars=envs if envs is not None else UNSET,
+            ),
         )
 
         if res.status_code == 404:

packages/python-sdk/tests/async/sandbox_async/test_config_propagation.py

@@ -67,6 +67,30 @@ async def test_pause_passes_connection_config_without_overrides(monkeypatch):
     assert mock_pause.call_args.kwargs["headers"]["X-Test"] == BASE_HEADERS["X-Test"]
 
 
+@pytest.mark.skip_debug()
+async def test_connect_forwards_envs(monkeypatch):
+    mock_connect = AsyncMock(return_value=None)
+    monkeypatch.setattr(sandbox_async_main.SandboxApi, "_cls_connect", mock_connect)
+
+    sandbox = create_sandbox(monkeypatch)
+    await sandbox.connect(envs={"MY_KEY": "my_value"})
+
+    mock_connect.assert_awaited_once()
+    assert mock_connect.call_args.kwargs["envs"] == {"MY_KEY": "my_value"}
+
+
+@pytest.mark.skip_debug()
+async def test_connect_envs_is_none_when_not_provided(monkeypatch):
+    mock_connect = AsyncMock(return_value=None)
+    monkeypatch.setattr(sandbox_async_main.SandboxApi, "_cls_connect", mock_connect)
+
+    sandbox = create_sandbox(monkeypatch)
+    await sandbox.connect()
+
+    mock_connect.assert_awaited_once()
+    assert mock_connect.call_args.kwargs.get("envs") is None
+
+
 @pytest.mark.skip_debug()
 async def test_pause_applies_overrides(monkeypatch):
     mock_pause = AsyncMock(return_value="sbx-test")

packages/python-sdk/tests/sync/sandbox_sync/test_config_propagation.py

@@ -65,6 +65,30 @@ def test_pause_passes_connection_config_without_overrides(monkeypatch):
     assert mock_pause.call_args.kwargs["headers"]["X-Test"] == BASE_HEADERS["X-Test"]
 
 
+@pytest.mark.skip_debug()
+def test_connect_forwards_envs(monkeypatch):
+    mock_connect = Mock(return_value=None)
+    monkeypatch.setattr(sandbox_sync_main.SandboxApi, "_cls_connect", mock_connect)
+
+    sandbox = create_sandbox(monkeypatch)
+    sandbox.connect(envs={"MY_KEY": "my_value"})
+
+    mock_connect.assert_called_once()
+    assert mock_connect.call_args.kwargs["envs"] == {"MY_KEY": "my_value"}
+
+
+@pytest.mark.skip_debug()
+def test_connect_envs_is_none_when_not_provided(monkeypatch):
+    mock_connect = Mock(return_value=None)
+    monkeypatch.setattr(sandbox_sync_main.SandboxApi, "_cls_connect", mock_connect)
+
+    sandbox = create_sandbox(monkeypatch)
+    sandbox.connect()
+
+    mock_connect.assert_called_once()
+    assert mock_connect.call_args.kwargs.get("envs") is None
+
+
 @pytest.mark.skip_debug()
 def test_pause_applies_overrides(monkeypatch):
     mock_pause = Mock(return_value="sbx-test")