fix: debug-mode Sandbox.connect() and Unset token handling in Python connect()

[mishushakov]

Description

Sandbox.connect() now short-circuits in debug mode instead of calling the control plane, matching Sandbox.create() — fixed in the JS SDK and both sync/async Python SDKs (static and instance variants). The Python SDK's connect() also previously passed the generated client's Unset sentinel through as the envd/traffic access tokens when they were absent (non-secure sandboxes), which made download_url()/upload_url() emit broken signed URLs; _cls_connect now normalizes the response into SandboxCreateResponse with proper None values, the same pattern _create_sandbox already uses. Dead Unset checks and the now-unused generated Sandbox model import were cleaned up, and unit tests cover both behaviors in all three implementations. Debug mode is resolved through ConnectionConfig, so the E2B_DEBUG env var triggers the short-circuit in both connect() and create(), not just an explicit debug=True.

Usage

// JS: works fully offline with E2B_DEBUG / debug: true (no control plane call)
const sbx = await Sandbox.connect(sandboxId, { debug: true })

# Python: non-secure sandboxes get unsigned URLs again instead of broken signatures
sbx = Sandbox.connect(sandbox_id)
print(sbx.download_url("file.txt"))  # no garbage signature when envd token is absent

# Debug mode skips the control plane, like Sandbox.create()
sbx = Sandbox.connect(sandbox_id, debug=True)

Testing

New unit tests in tests/sandbox/connect.test.ts, tests/sync/sandbox_sync/test_connect.py, and tests/async/sandbox_async/test_connect.py; existing connect integration suites pass against the live API (8/8 sync Python, 8/8 async Python, 6/6 JS).

🤖 Generated with Claude Code

[cursor]

PR Summary

Low Risk
Client-only SDK behavior fixes with targeted unit tests; production connect still hits the API when debug is off, with improved token handling for non-secure sandboxes.

Overview
Sandbox.connect() in the JS SDK and Python sync/async SDKs now skips the control-plane connect call in debug mode (including via E2B_DEBUG through ConnectionConfig), aligned with Sandbox.create(). Static connect builds a local sandbox instance; instance connect() returns this without an API round-trip.

In Python, _cls_connect no longer returns the generated Sandbox model with Unset sentinels for missing domain/tokens. It maps the connect response into SandboxCreateResponse with None for absent envd/traffic tokens and domain, matching _create_sandbox. That fixes download_url() / upload_url() incorrectly treating Unset as a real token on non-secure sandboxes. Unset imports and redundant isinstance(..., Unset) header checks were removed; _create resolves debug via ConnectionConfig(**opts).debug.

Unit tests cover debug connect (no API), env debug, instance connect, and unset token normalization in JS and both Python flavors.

^{Reviewed by Cursor Bugbot for commit 953b293. Bugbot is set up for automated code reviews on this repo. Configure here.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 953b293

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
e2b	Patch
@e2b/python-sdk	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

Package Artifacts

Built from 78be199. Download artifacts from this workflow run.

JS SDK (e2b@2.29.2-mishushakov-fix-sandbox-connect-bugs.0):

npm install ./e2b-2.29.2-mishushakov-fix-sandbox-connect-bugs.0.tgz

CLI (@e2b/cli@2.11.2-mishushakov-fix-sandbox-connect-bugs.0):

npm install ./e2b-cli-2.11.2-mishushakov-fix-sandbox-connect-bugs.0.tgz

Python SDK (e2b==2.28.2+mishushakov-fix-sandbox-connect-bugs):

pip install ./e2b-2.28.2+mishushakov.fix.sandbox.connect.bugs-py3-none-any.whl

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit d6bbee7. Configure here.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d6bbee771c

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".