feat(js-sdk): add proxy connection param

[mishushakov]

Adds a proxy connection parameter to the JS SDK, mirroring the Python SDK. When set, requests are routed through the given HTTP proxy via an undici ProxyAgent dispatcher (fetchers are cached per-proxy so non-proxy traffic is unaffected). It applies to control-plane API requests, all requests made to the returned sandbox (REST plus filesystem/commands/pty RPC), and volume requests. Behavior is unchanged when no proxy is provided, and unit tests cover both the API and envd fetch paths.

Usage

import { Sandbox } from 'e2b'

// Routes API + all sandbox requests through the proxy
const sandbox = await Sandbox.create({
  proxy: 'http://user:pass@127.0.0.1:8080',
})
await sandbox.files.write('/hello.txt', 'world')

// Also works when connecting to an existing sandbox
const sbx = await Sandbox.connect(sandboxId, { proxy: 'http://127.0.0.1:8080' })

Proxying relies on the optional undici package and the Node runtime; in browser/edge runtimes requests use global fetch, which has no proxy support (same as the existing HTTP/2 dispatcher).

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: ca31cbe

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

[cursor]

PR Summary

Medium Risk
Opt-in HTTP proxy changes how all SDK outbound traffic is routed on Node (including credentials in proxy URLs); behavior is unchanged without proxy, but misconfiguration could break connectivity or leak proxy auth.

Overview
The JS SDK adds an optional proxy on connection options so control-plane API, sandbox envd (REST and RPC), and volume traffic can go through an HTTP proxy on Node via undici ProxyAgent, with fetchers cached per proxy URL and unchanged behavior when proxy is omitted.

Python and JS volumes now keep proxy on the instance from create/connect so content APIs reuse it; a per-call proxy still wins. Unit tests cover ProxyAgent wiring, per-proxy fetcher caching, and volume proxy propagation.

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

[github-actions]

Package Artifacts

Built from 61960c9. Download artifacts from this workflow run.

JS SDK (e2b@2.28.1-mishushakov-add-proxy-connection-param.0):

npm install ./e2b-2.28.1-mishushakov-add-proxy-connection-param.0.tgz

CLI (@e2b/cli@2.10.5-mishushakov-add-proxy-connection-param.0):

npm install ./e2b-cli-2.10.5-mishushakov-add-proxy-connection-param.0.tgz

Python SDK (e2b==2.26.0+mishushakov-add-proxy-connection-param):

pip install ./e2b-2.26.0+mishushakov.add.proxy.connection.param-py3-none-any.whl

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 12603e4d69

ℹ️ 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".

[claude]

LGTM — opt-in proxy parameter mirrors the Python SDK, with per-proxy fetcher caching and good test coverage.

Extended reasoning...

Overview

Adds an optional proxy connection parameter to the JS SDK that routes traffic through an undici ProxyAgent when set. The change threads the proxy URL through three fetch surfaces — control-plane API (api/index.ts), sandbox envd REST/RPC (sandbox/index.ts), and volume client (volume/client.ts) — by extending ConnectionConfig/VolumeConnectionConfig with a proxy field. Per-proxy fetcher caching (Map<string, typeof fetch>) replaces the previous single-instance memoization, so non-proxy traffic still shares a dispatcher.

Security risks

Minimal. This is opt-in networking config — no proxy means no behavior change, and the dispatcher selection is a simple ternary inside an already-trusted code path. The proxy URL can embed credentials, but that's the standard http://user:pass@host form documented in the JSDoc. No auth, crypto, or permissions code is touched.

Level of scrutiny

Low. This is sandbox SDK plumbing, not a production-critical control plane. The change pattern is mechanical — extend options, thread one new param through factories, swap Agent for ProxyAgent when set — and mirrors a feature already shipped in the Python SDK. New unit tests cover both ProxyAgent wiring and the per-proxy caching invariant for API and envd fetchers.

Other factors

The author self-reviewed and consolidated the volume client to use createApiFetch unconditionally for consistency with the main API client (resolved in 12603e4). The bug hunting system found no issues, and Cursor Bugbot independently flagged this as Low Risk. The changeset is included and marked as a patch bump.

[matthewlouisbrockman]

Not sure the env auto detection is a patch change here; it's possibly breaking and there's no off switch.

I've seen it before where when you have _PROXY env supported you also have a no_proxy bypass which we probably want to at least be able to opt out, although if want to keep a patch, we should probably make the env reading opt in rather than opt out? IMO lighter touch of opt in probably better but not too opinionated.

Tangentially, reading HTTP_PROXY as cursor pointed out above is risky; some servers have vulns there

[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 12603e4. Configure here.}

[mishushakov]

@matthewlouisbrockman I've dropped the env var for now, also fixed the Volume instance proxy inheritance.