feat(js-sdk): add proxy connection param (#1386)

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

```ts
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](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: mishushakov

.changeset/js-sdk-proxy-param.md

@@ -0,0 +1,5 @@
+---
+"e2b": patch
+---
+
+Add `proxy` connection parameter to route SDK requests through an HTTP proxy, matching the Python SDK. When set, it applies to API requests, all requests made to the returned sandbox, and volume requests.

.changeset/volume-proxy-propagation.md

@@ -0,0 +1,6 @@
+---
+"@e2b/python-sdk": patch
+"e2b": patch
+---
+
+Fix `proxy` not being applied to volume content requests. `Volume.create`/`Volume.connect` now store the `proxy` on the returned instance, so instance methods (`list`, `readFile`, `writeFile`, `makeDir`, `getInfo`, `updateMetadata`, `remove`, …) route through it without having to pass `proxy` on every call. A per-call `proxy` still takes precedence.

packages/js-sdk/src/api/http2.ts

@@ -13,14 +13,20 @@ const DEFAULT_API_CONNECTION_LIMIT = 100
 // Override via env if your workload needs different.
 const DEFAULT_API_INFLIGHT_LIMIT = 1000
 
-let apiFetch: typeof fetch | undefined
+// Fetchers are cached per proxy so requests without a proxy keep sharing a
+// single dispatcher while each distinct proxy URL gets its own.
+const apiFetchers = new Map<string, typeof fetch>()
 
-export function createApiFetch(): typeof fetch {
-  if (apiFetch) {
-    return apiFetch
+export function createApiFetch(proxy?: string): typeof fetch {
+  const key = proxy ?? ''
+
+  const cached = apiFetchers.get(key)
+  if (cached) {
+    return cached
   }
 
-  apiFetch = createApiFetchForRuntime(runtime)
+  const apiFetch = createApiFetchForRuntime(runtime, { proxy })
+  apiFetchers.set(key, apiFetch)
 
   return apiFetch
 }
@@ -30,6 +36,7 @@ export function createApiFetchForRuntime(
   options: {
     connectionLimit?: number
     inflightLimit?: number
+    proxy?: string
     loadUndici?: () => Promise<UndiciModule | undefined>
   } = {}
 ): typeof fetch {
@@ -50,6 +57,7 @@ export function createApiFetchForRuntime(
 async function buildApiFetcher(options: {
   connectionLimit?: number
   inflightLimit?: number
+  proxy?: string
   loadUndici?: () => Promise<UndiciModule | undefined>
 }): Promise<typeof fetch> {
   const undici = await (options.loadUndici ?? loadUndici)()
@@ -59,11 +67,18 @@ async function buildApiFetcher(options: {
     return limitConcurrency(fetch, inflightLimit)
   }
 
-  const { Agent, fetch: undiciFetch } = undici
-  const dispatcher = new Agent({
-    allowH2: true,
-    connections: options.connectionLimit ?? getApiConnectionLimit(),
-  })
+  const { Agent, ProxyAgent, fetch: undiciFetch } = undici
+  const connections = options.connectionLimit ?? getApiConnectionLimit()
+  const dispatcher = options.proxy
+    ? new ProxyAgent({
+        uri: options.proxy,
+        allowH2: true,
+        connections,
+      })
+    : new Agent({
+        allowH2: true,
+        connections,
+      })
   const fetchWithDispatcher = undiciFetch as unknown as (
     input: RequestInfo | URL,
     init?: UndiciRequestInit

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

@@ -95,7 +95,7 @@ class ApiClient {
 
     this.api = createClient<paths>({
       baseUrl: config.apiUrl,
-      fetch: createApiFetch(),
+      fetch: createApiFetch(config.proxy),
       // In HTTP 1.1, all connections are considered persistent unless declared otherwise
       // keepalive: true,
       headers: {

packages/js-sdk/src/connectionConfig.ts

@@ -69,6 +69,14 @@ export interface ConnectionOpts {
    */
   headers?: Record<string, string>
 
+  /**
+   * Proxy URL to use for requests. In case of a sandbox it applies to all
+   * requests made to the returned sandbox.
+   *
+   * @example 'http://user:pass@127.0.0.1:8080'
+   */
+  proxy?: string
+
   /**
    * Additional headers to send with E2B API requests.
    */
@@ -193,6 +201,8 @@ export class ConnectionConfig {
 
   readonly headers?: Record<string, string>
 
+  readonly proxy?: string
+
   constructor(opts?: ConnectionOpts) {
     this.apiKey = opts?.apiKey || ConnectionConfig.apiKey
     this.debug = opts?.debug || ConnectionConfig.debug
@@ -202,6 +212,7 @@ export class ConnectionConfig {
     this.logger = opts?.logger
     this.headers = { ...(opts?.headers ?? {}), ...(opts?.apiHeaders ?? {}) }
     this.headers['User-Agent'] = `e2b-js-sdk/${version}`
+    this.proxy = opts?.proxy
 
     this.apiUrl =
       opts?.apiUrl ||

packages/js-sdk/src/envd/http2.ts

@@ -11,11 +11,14 @@ import {
 type EnvdFetchOptions = {
   connectionLimit?: number
   inflightLimit?: number
+  proxy?: string
   loadUndici?: () => Promise<UndiciModule | undefined>
 }
 
-let envdFetch: typeof fetch | undefined
-let envdRpcFetch: typeof fetch | undefined
+// Fetchers are cached per proxy so requests without a proxy keep sharing a
+// single dispatcher while each distinct proxy URL gets its own.
+const envdFetchers = new Map<string, typeof fetch>()
+const envdRpcFetchers = new Map<string, typeof fetch>()
 const DEFAULT_ENVD_CONNECTION_LIMIT = 10
 const DEFAULT_ENVD_RPC_CONNECTION_LIMIT = 200
 const DEFAULT_ENVD_INFLIGHT_LIMIT = 2000
@@ -49,13 +52,19 @@ async function buildEnvdFetcher(
     return limitConcurrency(fetch, inflightLimit)
   }
 
-  const { Agent, fetch: undiciFetch } = undici
-  const dispatcherOptions: { allowH2: true; connections?: number } = {
-    allowH2: true,
-    connections: options.connectionLimit ?? DEFAULT_ENVD_CONNECTION_LIMIT,
-  }
-
-  const dispatcher = new Agent(dispatcherOptions)
+  const { Agent, ProxyAgent, fetch: undiciFetch } = undici
+  const connections = options.connectionLimit ?? DEFAULT_ENVD_CONNECTION_LIMIT
+
+  const dispatcher = options.proxy
+    ? new ProxyAgent({
+        uri: options.proxy,
+        allowH2: true,
+        connections,
+      })
+    : new Agent({
+        allowH2: true,
+        connections,
+      })
   const fetchWithDispatcher = undiciFetch as unknown as (
     input: RequestInfo | URL,
     init?: UndiciRequestInit
@@ -73,29 +82,39 @@ async function buildEnvdFetcher(
   return limitConcurrency(wrapped, inflightLimit)
 }
 
-export function createEnvdFetch(): typeof fetch {
-  if (envdFetch) {
-    return envdFetch
+export function createEnvdFetch(proxy?: string): typeof fetch {
+  const key = proxy ?? ''
+
+  const cached = envdFetchers.get(key)
+  if (cached) {
+    return cached
   }
 
   // Keep one origin connection for short envd REST calls. If ALPN falls back
   // to h1, this favors connection pressure over per-sandbox throughput.
-  envdFetch = createEnvdFetchForRuntime(runtime, {
+  const envdFetch = createEnvdFetchForRuntime(runtime, {
     inflightLimit: getEnvdInflightLimit(),
+    proxy,
   })
+  envdFetchers.set(key, envdFetch)
 
   return envdFetch
 }
 
-export function createEnvdRpcFetch(): typeof fetch {
-  if (envdRpcFetch) {
-    return envdRpcFetch
+export function createEnvdRpcFetch(proxy?: string): typeof fetch {
+  const key = proxy ?? ''
+
+  const cached = envdRpcFetchers.get(key)
+  if (cached) {
+    return cached
   }
 
-  envdRpcFetch = createEnvdFetchForRuntime(runtime, {
+  const envdRpcFetch = createEnvdFetchForRuntime(runtime, {
     connectionLimit: getEnvdRpcConnectionLimit(),
     inflightLimit: getEnvdRpcInflightLimit(),
+    proxy,
   })
+  envdRpcFetchers.set(key, envdRpcFetch)
 
   return envdRpcFetch
 }

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

@@ -159,8 +159,8 @@ export class Sandbox extends SandboxApi {
       'E2b-Sandbox-Id': this.sandboxId,
       'E2b-Sandbox-Port': this.envdPort.toString(),
     }
-    const envdFetch = createEnvdFetch()
-    const envdRpcFetch = createEnvdRpcFetch()
+    const envdFetch = createEnvdFetch(this.connectionConfig.proxy)
+    const envdRpcFetch = createEnvdRpcFetch(this.connectionConfig.proxy)
 
     const rpcTransport = createConnectTransport({
       baseUrl: this.envdApiUrl,

packages/js-sdk/src/undici.ts

@@ -5,6 +5,11 @@ export type UndiciRequestInit = RequestInit & {
 
 export type UndiciModule = {
   Agent: new (options: { allowH2: true; connections?: number }) => unknown
+  ProxyAgent: new (options: {
+    uri: string
+    allowH2: true
+    connections?: number
+  }) => unknown
   fetch: unknown
 }
 

packages/js-sdk/src/volume/client.ts

@@ -2,6 +2,7 @@ import createClient from 'openapi-fetch'
 
 import type { components, paths } from './schema.gen'
 import { defaultHeaders, getEnvVar } from '../api/metadata'
+import { createApiFetch } from '../api/http2'
 import { buildRequestSignal } from '../connectionConfig'
 import { createApiLogger, Logger } from '../logs'
 import type { Volume } from './index'
@@ -49,6 +50,13 @@ export interface VolumeApiOpts {
    */
   headers?: Record<string, string>
 
+  /**
+   * Proxy URL to use for requests.
+   *
+   * @example 'http://user:pass@127.0.0.1:8080'
+   */
+  proxy?: string
+
   /**
    * An optional `AbortSignal` that can be used to cancel the in-flight request.
    * When the signal is aborted, the underlying `fetch` is aborted and the
@@ -66,6 +74,7 @@ export class VolumeConnectionConfig {
   readonly logger?: Logger
   readonly requestTimeoutMs?: number
   readonly signal?: AbortSignal
+  readonly proxy?: string
 
   constructor(volume: Volume, opts?: VolumeApiOpts) {
     this.domain = opts?.domain || volume.domain || VolumeConnectionConfig.domain
@@ -79,6 +88,7 @@ export class VolumeConnectionConfig {
     this.logger = opts?.logger
     this.requestTimeoutMs = opts?.requestTimeoutMs
     this.signal = opts?.signal
+    this.proxy = opts?.proxy || volume.proxy
   }
 
   private static get domain() {
@@ -110,6 +120,7 @@ class VolumeApiClient {
   constructor(config: VolumeConnectionConfig) {
     this.api = createClient<paths>({
       baseUrl: config.apiUrl,
+      fetch: createApiFetch(config.proxy),
       headers: {
         ...defaultHeaders,
         ...(config.token && { Authorization: `Bearer ${config.token}` }),

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

@@ -65,6 +65,11 @@ export class Volume {
    */
   readonly debug?: boolean
 
+  /**
+   * Proxy URL used for requests to the volume content API.
+   */
+  readonly proxy?: string
+
   /**
    * Create a local Volume instance with no API call.
    *
@@ -73,19 +78,22 @@ export class Volume {
    * @param token volume auth token.
    * @param domain domain for the volume API.
    * @param debug whether to use debug mode.
+   * @param proxy proxy URL for the volume content API.
    */
   constructor(
     volumeId: string,
     name: string,
     token: string,
     domain?: string,
-    debug?: boolean
+    debug?: boolean,
+    proxy?: string
   ) {
     this.volumeId = volumeId
     this.name = name
     this.token = token
     this.domain = domain
     this.debug = debug
+    this.proxy = proxy
   }
 
   /**
@@ -121,7 +129,8 @@ export class Volume {
       res.data.name,
       res.data.token,
       config.domain,
-      config.debug
+      config.debug,
+      config.proxy
     )
   }
 
@@ -139,7 +148,14 @@ export class Volume {
   ): Promise<Volume> {
     const config = new ConnectionConfig(opts)
     const { name, token } = await Volume.getInfo(volumeId, opts)
-    return new Volume(volumeId, name, token, config.domain, config.debug)
+    return new Volume(
+      volumeId,
+      name,
+      token,
+      config.domain,
+      config.debug,
+      config.proxy
+    )
   }
 
   /**