Skip to content

armgit / E2B

Public Imported from GitHub
0

Open-source, secure environment with real-world tools for enterprise-grade agents.

fix(python): shard envd HTTP/2 connection pools (#1793)

Matt Brockman7dd5321ce22c
diff --git a/.changeset/four-envd-pools.md b/.changeset/four-envd-pools.md
new file mode 100644
index 000000000..4855b8a90
--- /dev/null
+++ b/.changeset/four-envd-pools.md
@@ -0,0 +1,5 @@
+---
+'@e2b/python-sdk': patch
+---
+
+Spread envd traffic across four HTTP/2 connection pools by default so high-concurrency, long-running streams do not all contend for one connection's stream limit. Set `E2B_ENVD_POOL_SHARDS` before importing the SDK to tune the pool count.
diff --git a/.github/assets/envd-pool-sharding-benchmark.svg b/.github/assets/envd-pool-sharding-benchmark.svg
new file mode 100644
index 000000000..7bd6cd78f
--- /dev/null
+++ b/.github/assets/envd-pool-sharding-benchmark.svg
@@ -0,0 +1,128 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 560" role="img" aria-labelledby="title description">
+ <title id="title">Envd HTTP/2 pool sharding benchmark</title>
+ <desc id="description">Two line charts compare one, four, and eight Python SDK envd connection pools at 50, 100, 200, and 400 concurrent long-lived streams. One pool stops at 100 streams, four pools reach 398 at 400, and eight pools reach all 400 before the 750 millisecond deadline.</desc>
+ <style>
+ :root { color-scheme: light dark; }
+ .background { fill: #ffffff; }
+ .frame { fill: none; stroke: #d0d7de; stroke-width: 1; }
+ .grid { stroke: #d8dee4; stroke-width: 1; }
+ .axis { fill: #57606a; font: 13px ui-sans-serif, system-ui, sans-serif; }
+ .heading { fill: #1f2328; font: 700 24px ui-sans-serif, system-ui, sans-serif; }
+ .subtitle { fill: #57606a; font: 14px ui-sans-serif, system-ui, sans-serif; }
+ .panel-title { fill: #1f2328; font: 650 16px ui-sans-serif, system-ui, sans-serif; }
+ .legend { fill: #1f2328; font: 14px ui-sans-serif, system-ui, sans-serif; }
+ .note { fill: #57606a; font: 12px ui-sans-serif, system-ui, sans-serif; }
+ .one { fill: none; stroke: #0969da; stroke-width: 3; }
+ .four { fill: none; stroke: #bf6a02; stroke-width: 3; }
+ .eight { fill: none; stroke: #1a7f37; stroke-width: 3; }
+ .one-dot { fill: #0969da; }
+ .four-dot { fill: #bf6a02; }
+ .eight-dot { fill: #1a7f37; }
+ .deadline { stroke: #8c959f; stroke-width: 1.5; stroke-dasharray: 6 5; }
+ .value { fill: #1f2328; font: 650 13px ui-sans-serif, system-ui, sans-serif; }
+ .one-value { fill: #0969da; }
+ .four-value { fill: #bf6a02; }
+ .eight-value { fill: #1a7f37; }
+ .one-timeout { stroke: #0969da; stroke-width: 2; }
+ .four-timeout { stroke: #bf6a02; stroke-width: 2; }
+ @media (prefers-color-scheme: dark) {
+ .background { fill: #0d1117; }
+ .frame, .grid { stroke: #30363d; }
+ .heading, .panel-title, .legend, .value { fill: #e6edf3; }
+ .subtitle, .axis, .note { fill: #8b949e; }
+ .one { stroke: #58a6ff; }
+ .four { stroke: #d29922; }
+ .eight { stroke: #3fb950; }
+ .one-dot { fill: #58a6ff; }
+ .four-dot { fill: #d29922; }
+ .eight-dot { fill: #3fb950; }
+ .deadline { stroke: #6e7681; }
+ .one-value { fill: #58a6ff; }
+ .four-value { fill: #d29922; }
+ .eight-value { fill: #3fb950; }
+ .one-timeout { stroke: #58a6ff; }
+ .four-timeout { stroke: #d29922; }
+ }
+ </style>
+
+ <rect class="background" width="1200" height="560" />
+ <text class="heading" x="52" y="46">Envd HTTP/2 pool sharding</text>
+ <text class="subtitle" x="52" y="72">Python SDK · local peer advertising 100 concurrent streams per connection · three-run median</text>
+
+ <g transform="translate(755 39)">
+ <line class="one" x1="0" y1="0" x2="28" y2="0" />
+ <text class="legend" x="38" y="5">1 pool</text>
+ <line class="four" x1="112" y1="0" x2="140" y2="0" />
+ <text class="legend" x="150" y="5">4 pools (default)</text>
+ <line class="eight" x1="300" y1="0" x2="328" y2="0" />
+ <text class="legend" x="338" y="5">8 pools</text>
+ </g>
+
+ <text class="panel-title" x="68" y="112">Streams opened before the 750 ms deadline</text>
+ <rect class="frame" x="76" y="132" width="486" height="300" />
+ <line class="grid" x1="76" y1="357" x2="562" y2="357" />
+ <line class="grid" x1="76" y1="282" x2="562" y2="282" />
+ <line class="grid" x1="76" y1="207" x2="562" y2="207" />
+ <line class="grid" x1="76" y1="132" x2="562" y2="132" />
+ <text class="axis" x="64" y="436" text-anchor="end">0</text>
+ <text class="axis" x="64" y="361" text-anchor="end">100</text>
+ <text class="axis" x="64" y="286" text-anchor="end">200</text>
+ <text class="axis" x="64" y="211" text-anchor="end">300</text>
+ <text class="axis" x="64" y="136" text-anchor="end">400</text>
+ <text class="axis" x="84" y="454" text-anchor="middle">50</text>
+ <text class="axis" x="152" y="454" text-anchor="middle">100</text>
+ <text class="axis" x="291" y="454" text-anchor="middle">200</text>
+ <text class="axis" x="554" y="454" text-anchor="middle">400</text>
+ <text class="axis" x="319" y="482" text-anchor="middle">Concurrent long-lived streams requested</text>
+ <text class="axis" transform="translate(22 282) rotate(-90)" text-anchor="middle">Streams opened</text>
+
+ <polyline class="one" points="84,394.5 152,357 291,357 554,357" />
+ <polyline class="four" points="84,394.5 152,357 291,282 554,133.5" />
+ <polyline class="eight" points="84,394.5 152,357 291,282 554,132" />
+ <g>
+ <circle class="one-dot" cx="84" cy="394.5" r="4" /><circle class="one-dot" cx="152" cy="357" r="4" /><circle class="one-dot" cx="291" cy="357" r="4" /><circle class="one-dot" cx="554" cy="357" r="4" />
+ <circle class="four-dot" cx="84" cy="394.5" r="4" /><circle class="four-dot" cx="152" cy="357" r="4" /><circle class="four-dot" cx="291" cy="282" r="4" /><circle class="four-dot" cx="554" cy="133.5" r="4" />
+ <circle class="eight-dot" cx="84" cy="394.5" r="4" /><circle class="eight-dot" cx="152" cy="357" r="4" /><circle class="eight-dot" cx="291" cy="282" r="4" /><circle class="eight-dot" cx="554" cy="132" r="4" />
+ </g>
+ <text class="value eight-value" x="538" y="118" text-anchor="end">400 / 400</text>
+ <text class="value four-value" x="538" y="153" text-anchor="end">398 / 400</text>
+ <text class="value one-value" x="538" y="348" text-anchor="end">100 / 400</text>
+
+ <text class="panel-title" x="638" y="112">Time to completion or deadline</text>
+ <rect class="frame" x="646" y="132" width="486" height="300" />
+ <line class="grid" x1="646" y1="357" x2="1132" y2="357" />
+ <line class="grid" x1="646" y1="282" x2="1132" y2="282" />
+ <line class="grid" x1="646" y1="207" x2="1132" y2="207" />
+ <line class="grid" x1="646" y1="132" x2="1132" y2="132" />
+ <line class="deadline" x1="646" y1="151" x2="1132" y2="151" />
+ <text class="note" x="1124" y="144" text-anchor="end">750 ms deadline</text>
+ <text class="axis" x="634" y="436" text-anchor="end">0</text>
+ <text class="axis" x="634" y="361" text-anchor="end">200</text>
+ <text class="axis" x="634" y="286" text-anchor="end">400</text>
+ <text class="axis" x="634" y="211" text-anchor="end">600</text>
+ <text class="axis" x="634" y="136" text-anchor="end">800</text>
+ <text class="axis" x="654" y="454" text-anchor="middle">50</text>
+ <text class="axis" x="722" y="454" text-anchor="middle">100</text>
+ <text class="axis" x="861" y="454" text-anchor="middle">200</text>
+ <text class="axis" x="1124" y="454" text-anchor="middle">400</text>
+ <text class="axis" x="889" y="482" text-anchor="middle">Concurrent long-lived streams requested</text>
+ <text class="axis" transform="translate(592 282) rotate(-90)" text-anchor="middle">Elapsed time (ms)</text>
+
+ <polyline class="one" points="654,427.1 722,422.1 861,145.8 1124,140.2" />
+ <polyline class="four" points="654,425.4 722,419.6 861,413.9 1124,143.9" />
+ <polyline class="eight" points="654,425 722,420.4 861,409.9 1124,396" />
+ <g>
+ <circle class="one-dot" cx="654" cy="427.1" r="4" /><circle class="one-dot" cx="722" cy="422.1" r="4" /><circle class="one-dot" cx="861" cy="145.8" r="4" /><circle class="one-dot" cx="1124" cy="140.2" r="4" />
+ <circle class="four-dot" cx="654" cy="425.4" r="4" /><circle class="four-dot" cx="722" cy="419.6" r="4" /><circle class="four-dot" cx="861" cy="413.9" r="4" /><circle class="four-dot" cx="1124" cy="143.9" r="4" />
+ <circle class="eight-dot" cx="654" cy="425" r="4" /><circle class="eight-dot" cx="722" cy="420.4" r="4" /><circle class="eight-dot" cx="861" cy="409.9" r="4" /><circle class="eight-dot" cx="1124" cy="396" r="4" />
+ </g>
+ <g aria-label="Timed out before every requested stream opened">
+ <path class="one-timeout" d="M856 140.8l10 10m0-10l-10 10" />
+ <path class="one-timeout" d="M1119 135.2l10 10m0-10l-10 10" />
+ <path class="four-timeout" d="M1119 138.9l10 10m0-10l-10 10" />
+ </g>
+ <text class="value" x="1112" y="387" text-anchor="end">96 ms</text>
+ <text class="note" x="1124" y="505" text-anchor="end">× deadline reached before the full batch opened</text>
+
+ <text class="note" x="52" y="530">Sync and async produced the same capacity. Elapsed time is the median of their three-run medians; open response streams remain held for the test.</text>
+</svg>
diff --git a/packages/python-sdk/README.md b/packages/python-sdk/README.md
index 33093f126..6997acd54 100644
--- a/packages/python-sdk/README.md
+++ b/packages/python-sdk/README.md
@@ -66,6 +66,16 @@ paginator = Sandbox.list()
Per-call params still take precedence over the client's params, and clients are isolated from each other and from the env-configured top-level exports.
+### High-concurrency sandbox streams
+
+The Python SDK spreads sandbox `commands` and `files` traffic across four HTTP/2 connection pools by default. This prevents long-running streams in one process from all contending for a single connection's concurrent-stream limit.
+
+If one process needs more capacity, set `E2B_ENVD_POOL_SHARDS` before importing `e2b`. Each additional shard can open another connection to the sandbox host, so increase it only as needed:
+
+```sh
+E2B_ENVD_POOL_SHARDS=8 python eval.py
+```
+
### 5. Code execution with Code Interpreter
If you need [`run_code()`](https://docs.e2b.dev/code-interpreting/analyze-data-with-ai?utm_source=pypi&utm_medium=referral&utm_campaign=readme&utm_content=e2b), install the [Code Interpreter SDK](https://github.com/e2b-dev/code-interpreter):
diff --git a/packages/python-sdk/e2b/api/__init__.py b/packages/python-sdk/e2b/api/__init__.py
index d36df92a2..fa9ec3f3d 100644
--- a/packages/python-sdk/e2b/api/__init__.py
+++ b/packages/python-sdk/e2b/api/__init__.py
@@ -1,6 +1,7 @@
import json
import logging
import os
+import zlib
from dataclasses import dataclass
from types import TracebackType
from typing import NamedTuple, Optional, Protocol, Tuple, Union
@@ -101,6 +102,26 @@ connection_retries = int(os.getenv("E2B_CONNECTION_RETRIES") or "3")
# is no longer read.
pool_idle_timeout = float(os.getenv("E2B_KEEPALIVE_EXPIRY") or "300")
pool_max_idle_per_host = int(os.getenv("E2B_MAX_KEEPALIVE_CONNECTIONS") or "20")
+envd_pool_shards = max(1, int(os.getenv("E2B_ENVD_POOL_SHARDS") or "4"))
+
+
+def envd_pool_shard(config: ConnectionConfig) -> int:
+ """Return the stable connection-pool shard for a sandbox's envd traffic.
+
+ Production envd requests share one origin, whose HTTP/2 connection has a
+ finite concurrent-stream limit. Long-running commands hold those streams,
+ so one process-wide connection becomes a bottleneck even though the edge
+ and account can run more sandboxes. A small bounded set of pools provides
+ additional connections without returning to one connection per sandbox.
+
+ The sandbox ID is carried on every envd request and CRC32 is stable across
+ processes, unlike Python's randomized ``hash``. Configs without a sandbox
+ ID (including control-plane clients) stay on shard zero.
+ """
+ sandbox_id = config.sandbox_headers.get("E2b-Sandbox-Id")
+ if not sandbox_id:
+ return 0
+ return zlib.crc32(sandbox_id.encode()) % envd_pool_shards
class ProxyConfig(NamedTuple):
diff --git a/packages/python-sdk/e2b/api/client_async/__init__.py b/packages/python-sdk/e2b/api/client_async/__init__.py
index 08ffd6866..1bf3542ea 100644
--- a/packages/python-sdk/e2b/api/client_async/__init__.py
+++ b/packages/python-sdk/e2b/api/client_async/__init__.py
@@ -11,6 +11,7 @@ from e2b.api import (
AsyncApiClient,
ProxyConfig,
connection_retries,
+ envd_pool_shard,
make_async_logging_event_hooks,
pool_idle_timeout,
pool_max_idle_per_host,
@@ -48,21 +49,18 @@ class ConnectionRetryTransport(RetryTransport):
return isinstance(response, ConnectionError)
-_TransportKey = Tuple[Optional[ProxyConfig], Optional[float], bool]
-"""Cache key of the shared transports: proxy, idle read bound, HTTP version.
+_TransportKey = Tuple[Optional[ProxyConfig], Optional[float], bool, int]
+"""Cache key: proxy, idle read bound, HTTP version, connection-pool shard.
-All three are fixed when a pyqwest transport is constructed, so each distinct
-combination is necessarily its own pool."""
+The first three are fixed when a pyqwest transport is constructed. The shard
+allows bounded parallel HTTP/2 connections to the stable envd host. Each
+distinct combination is necessarily its own pool."""
_transport_lock = threading.Lock()
# One pyqwest transport — one reqwest connection pool — per key; a `None` proxy
-# is the direct pool. Every HTTP stack in the SDK draws from these: the
-# control-plane REST API, the envd HTTP API, the envd RPC clients
-# (`e2b.envd.client_async`) and the volume content API
-# (`e2b.volume.client_async`). reqwest pools per host internally, so a single
-# pool serves the API host and every per-sandbox host without interference —
-# and because envd RPC and the envd HTTP API share it, a sandbox needs one
-# HTTP/2 connection instead of one per stack.
+# is the direct pool. Generic API and volume traffic use shard zero. Envd RPC
+# and non-streaming HTTP traffic for one sandbox use the same sandbox shard, so
+# they share one HTTP/2 connection instead of opening one per stack.
#
# pyqwest's I/O runs on its own Rust runtime, so unlike the httpx transports
# they replaced, the transports are not bound to an event loop and the caches
@@ -76,6 +74,7 @@ def get_pyqwest_transport(
proxy: Optional[ProxyConfig],
read_timeout: Optional[float] = None,
http2: bool = True,
+ pool_shard: int = 0,
) -> ConnectionRetryTransport:
"""The shared pyqwest transport (= one connection pool) with the SDK's
tuning — system CA certs (without which TLS through an intercepting proxy
@@ -99,7 +98,7 @@ def get_pyqwest_transport(
``pyqwest`` loggers at ``DEBUG`` (off unless enabled) — the transport-level
diagnostics httpcore used to provide. The SDK's own ``logger`` option is
separate and sits above this, on the httpx client."""
- key = (proxy, read_timeout, http2)
+ key = (proxy, read_timeout, http2, pool_shard)
with _transport_lock:
transport = _transports.get(key)
if transport is None:
@@ -129,15 +128,16 @@ def get_httpx_transport(
proxy: Optional[ProxyConfig],
read_timeout: Optional[float] = None,
http2: bool = True,
+ pool_shard: int = 0,
) -> AsyncPyqwestTransport:
"""The httpx adapter over the shared pool of
:func:`get_pyqwest_transport`, for the generated httpx clients (control
plane, envd HTTP API, volume content). The adapter holds no state of its
own and does not close the pool, so closing an httpx client leaves the
pool intact for the other clients on it."""
- key = (proxy, read_timeout, http2)
+ key = (proxy, read_timeout, http2, pool_shard)
# Resolve the pool before taking the lock: it takes the same one.
- pool = get_pyqwest_transport(proxy, read_timeout, http2)
+ pool = get_pyqwest_transport(proxy, read_timeout, http2, pool_shard)
with _transport_lock:
transport = _httpx_transports.get(key)
if transport is None:
@@ -147,13 +147,17 @@ def get_httpx_transport(
def get_transport(
- config: ConnectionConfig, http2: bool = True, *, for_streaming: bool = False
+ config: ConnectionConfig,
+ http2: bool = True,
+ *,
+ for_streaming: bool = False,
+ pool_shard: int = 0,
) -> AsyncPyqwestTransport:
- """The shared httpx transport for the control-plane REST API and the envd
- HTTP API (file transfers, health checks) — one pool serves both, keyed by
- the connection's proxy. For TLS connections ALPN negotiates the HTTP
- version (HTTP/2 against the E2B API), like the http2-enabled httpx
- transport this replaced.
+ """The shared httpx transport factory for the control-plane REST API and
+ envd HTTP API (file transfers, health checks). Generic callers use shard
+ zero; :func:`get_envd_transport` supplies a sandbox-specific shard. For TLS
+ connections ALPN negotiates the HTTP version (HTTP/2 against the E2B API),
+ like the http2-enabled httpx transport this replaced.
``http2=False`` returns a separate transport (its own pool) pinned to
HTTP/1.1. That matters for a server that reacts to a client going away:
@@ -174,25 +178,30 @@ def get_transport(
proxy_to_config(config.proxy),
READ_TIMEOUT if for_streaming else None,
http2,
+ pool_shard,
)
def get_envd_transport(
config: ConnectionConfig, http2: bool = True, *, for_streaming: bool = False
) -> AsyncPyqwestTransport:
- """The envd HTTP API's transport, which is :func:`get_transport` — the two
- now share one pool per key, since reqwest pools per host and envd RPC and
- the envd HTTP API hit the same sandbox host anyway.
+ """The envd HTTP API's transport, sharded by sandbox ID.
- Kept only as a backward-compatible alias of :func:`get_transport` for any
- external importer of the older public name; nothing inside the SDK calls it
- (``e2b-code-interpreter`` imports :func:`get_transport` directly). Prefer
- :func:`get_transport`.
+ Envd RPC and non-streaming HTTP traffic for one sandbox resolve the same
+ shard, retaining their shared connection while spreading different
+ sandboxes over a bounded number of connections to the stable sandbox host.
+ Streaming HTTP traffic uses the same shard number with a separate
+ read-timeout-keyed pool.
- :deprecated: Use :func:`get_transport` instead; will be removed in the next
- major version.
+ Kept as a separate factory because generic API transports stay on shard
+ zero while envd transports use the sandbox's shard.
"""
- return get_transport(config, http2, for_streaming=for_streaming)
+ return get_transport(
+ config,
+ http2,
+ for_streaming=for_streaming,
+ pool_shard=envd_pool_shard(config),
+ )
def get_envd_api(
@@ -204,7 +213,7 @@ def get_envd_api(
is shared and loop-independent."""
return httpx.AsyncClient(
base_url=base_url,
- transport=get_transport(config, for_streaming=for_streaming),
+ transport=get_envd_transport(config, for_streaming=for_streaming),
headers=config.sandbox_headers,
event_hooks=make_async_logging_event_hooks(config.logger),
)
diff --git a/packages/python-sdk/e2b/api/client_sync/__init__.py b/packages/python-sdk/e2b/api/client_sync/__init__.py
index 68c38be13..4d82a93cd 100644
--- a/packages/python-sdk/e2b/api/client_sync/__init__.py
+++ b/packages/python-sdk/e2b/api/client_sync/__init__.py
@@ -11,6 +11,7 @@ from e2b.api import (
ApiClient,
ProxyConfig,
connection_retries,
+ envd_pool_shard,
make_logging_event_hooks,
pool_idle_timeout,
pool_max_idle_per_host,
@@ -48,21 +49,18 @@ class ConnectionRetryTransport(SyncRetryTransport):
return isinstance(response, ConnectionError)
-_TransportKey = Tuple[Optional[ProxyConfig], Optional[float], bool]
-"""Cache key of the shared transports: proxy, idle read bound, HTTP version.
+_TransportKey = Tuple[Optional[ProxyConfig], Optional[float], bool, int]
+"""Cache key: proxy, idle read bound, HTTP version, connection-pool shard.
-All three are fixed when a pyqwest transport is constructed, so each distinct
-combination is necessarily its own pool."""
+The first three are fixed when a pyqwest transport is constructed. The shard
+allows bounded parallel HTTP/2 connections to the stable envd host. Each
+distinct combination is necessarily its own pool."""
_transport_lock = threading.Lock()
# One pyqwest transport — one reqwest connection pool — per key; a `None` proxy
-# is the direct pool. Every HTTP stack in the SDK draws from these: the
-# control-plane REST API, the envd HTTP API, the envd RPC clients
-# (`e2b.envd.client_sync`) and the volume content API (`e2b.volume.client_sync`).
-# reqwest pools per host internally, so a single pool serves the API host and
-# every per-sandbox host without interference — and because envd RPC and the
-# envd HTTP API share it, a sandbox needs one HTTP/2 connection instead of one
-# per stack.
+# is the direct pool. Generic API and volume traffic use shard zero. Envd RPC
+# and non-streaming HTTP traffic for one sandbox use the same sandbox shard, so
+# they share one HTTP/2 connection instead of opening one per stack.
#
# pyqwest transports are thread-safe, so unlike the httpx transports they
# replaced, the caches are process-global rather than per-thread.
@@ -75,6 +73,7 @@ def get_pyqwest_transport(
proxy: Optional[ProxyConfig],
read_timeout: Optional[float] = None,
http2: bool = True,
+ pool_shard: int = 0,
) -> ConnectionRetryTransport:
"""The shared pyqwest transport (= one connection pool) with the SDK's
tuning — system CA certs (without which TLS through an intercepting proxy
@@ -98,7 +97,7 @@ def get_pyqwest_transport(
``pyqwest`` loggers at ``DEBUG`` (off unless enabled) — the transport-level
diagnostics httpcore used to provide. The SDK's own ``logger`` option is
separate and sits above this, on the httpx client."""
- key = (proxy, read_timeout, http2)
+ key = (proxy, read_timeout, http2, pool_shard)
with _transport_lock:
transport = _transports.get(key)
if transport is None:
@@ -128,15 +127,16 @@ def get_httpx_transport(
proxy: Optional[ProxyConfig],
read_timeout: Optional[float] = None,
http2: bool = True,
+ pool_shard: int = 0,
) -> PyqwestTransport:
"""The httpx adapter over the shared pool of
:func:`get_pyqwest_transport`, for the generated httpx clients (control
plane, envd HTTP API, volume content). The adapter holds no state of its
own and does not close the pool, so closing an httpx client leaves the
pool intact for the other clients on it."""
- key = (proxy, read_timeout, http2)
+ key = (proxy, read_timeout, http2, pool_shard)
# Resolve the pool before taking the lock: it takes the same one.
- pool = get_pyqwest_transport(proxy, read_timeout, http2)
+ pool = get_pyqwest_transport(proxy, read_timeout, http2, pool_shard)
with _transport_lock:
transport = _httpx_transports.get(key)
if transport is None:
@@ -146,13 +146,17 @@ def get_httpx_transport(
def get_transport(
- config: ConnectionConfig, http2: bool = True, *, for_streaming: bool = False
+ config: ConnectionConfig,
+ http2: bool = True,
+ *,
+ for_streaming: bool = False,
+ pool_shard: int = 0,
) -> PyqwestTransport:
- """The shared httpx transport for the control-plane REST API and the envd
- HTTP API (file transfers, health checks) — one pool serves both, keyed by
- the connection's proxy. For TLS connections ALPN negotiates the HTTP
- version (HTTP/2 against the E2B API), like the http2-enabled httpx
- transport this replaced.
+ """The shared httpx transport factory for the control-plane REST API and
+ envd HTTP API (file transfers, health checks). Generic callers use shard
+ zero; :func:`get_envd_transport` supplies a sandbox-specific shard. For TLS
+ connections ALPN negotiates the HTTP version (HTTP/2 against the E2B API),
+ like the http2-enabled httpx transport this replaced.
``http2=False`` returns a separate transport (its own pool) pinned to
HTTP/1.1. That matters for a server that reacts to a client going away:
@@ -173,25 +177,30 @@ def get_transport(
proxy_to_config(config.proxy),
READ_TIMEOUT if for_streaming else None,
http2,
+ pool_shard,
)
def get_envd_transport(
config: ConnectionConfig, http2: bool = True, *, for_streaming: bool = False
) -> PyqwestTransport:
- """The envd HTTP API's transport, which is :func:`get_transport` — the two
- now share one pool per key, since reqwest pools per host and envd RPC and
- the envd HTTP API hit the same sandbox host anyway.
+ """The envd HTTP API's transport, sharded by sandbox ID.
- Kept only as a backward-compatible alias of :func:`get_transport` for any
- external importer of the older public name; nothing inside the SDK calls it
- (``e2b-code-interpreter`` imports :func:`get_transport` directly). Prefer
- :func:`get_transport`.
+ Envd RPC and non-streaming HTTP traffic for one sandbox resolve the same
+ shard, retaining their shared connection while spreading different
+ sandboxes over a bounded number of connections to the stable sandbox host.
+ Streaming HTTP traffic uses the same shard number with a separate
+ read-timeout-keyed pool.
- :deprecated: Use :func:`get_transport` instead; will be removed in the next
- major version.
+ Kept as a separate factory because generic API transports stay on shard
+ zero while envd transports use the sandbox's shard.
"""
- return get_transport(config, http2, for_streaming=for_streaming)
+ return get_transport(
+ config,
+ http2,
+ for_streaming=for_streaming,
+ pool_shard=envd_pool_shard(config),
+ )
def get_envd_api(
@@ -203,7 +212,7 @@ def get_envd_api(
is shared and thread-safe."""
return httpx.Client(
base_url=base_url,
- transport=get_transport(config, for_streaming=for_streaming),
+ transport=get_envd_transport(config, for_streaming=for_streaming),
headers=config.sandbox_headers,
event_hooks=make_logging_event_hooks(config.logger),
)
diff --git a/packages/python-sdk/e2b/envd/client_async/__init__.py b/packages/python-sdk/e2b/envd/client_async/__init__.py
index dcc979d73..f3827cc76 100644
--- a/packages/python-sdk/e2b/envd/client_async/__init__.py
+++ b/packages/python-sdk/e2b/envd/client_async/__init__.py
@@ -15,7 +15,7 @@ from connectrpc.code import Code
from connectrpc.errors import ConnectError
from pyqwest import Client, Request, Response, Transport
-from e2b.api import proxy_to_config
+from e2b.api import envd_pool_shard, proxy_to_config
from e2b.api.client_async import get_pyqwest_transport
from e2b.connection_config import ConnectionConfig
from e2b.envd.client_shared import (
@@ -80,7 +80,12 @@ def create_rpc_client(
outside the retries so it converts the settled response once.
"""
http_client = Client(
- PlainHTTPErrorTransport(get_pyqwest_transport(proxy_to_config(config.proxy)))
+ PlainHTTPErrorTransport(
+ get_pyqwest_transport(
+ proxy_to_config(config.proxy),
+ pool_shard=envd_pool_shard(config),
+ )
+ )
)
return client_cls(
base_url,
diff --git a/packages/python-sdk/e2b/envd/client_sync/__init__.py b/packages/python-sdk/e2b/envd/client_sync/__init__.py
index fadf66323..dfbdde4ee 100644
--- a/packages/python-sdk/e2b/envd/client_sync/__init__.py
+++ b/packages/python-sdk/e2b/envd/client_sync/__init__.py
@@ -9,7 +9,7 @@ from pyqwest import (
SyncTransport,
)
-from e2b.api import proxy_to_config
+from e2b.api import envd_pool_shard, proxy_to_config
from e2b.api.client_sync import get_pyqwest_transport
from e2b.connection_config import ConnectionConfig
from e2b.envd.client_shared import (
@@ -75,7 +75,12 @@ def create_rpc_client(
outside the retries so it converts the settled response once.
"""
http_client = SyncClient(
- PlainHTTPErrorTransport(get_pyqwest_transport(proxy_to_config(config.proxy)))
+ PlainHTTPErrorTransport(
+ get_pyqwest_transport(
+ proxy_to_config(config.proxy),
+ pool_shard=envd_pool_shard(config),
+ )
+ )
)
return client_cls(
base_url,
diff --git a/packages/python-sdk/tests/envd_frame_server.py b/packages/python-sdk/tests/envd_frame_server.py
index ebc333058..4b2b16789 100644
--- a/packages/python-sdk/tests/envd_frame_server.py
+++ b/packages/python-sdk/tests/envd_frame_server.py
@@ -22,6 +22,7 @@ import h2.config
import h2.connection
import h2.errors
import h2.events
+import h2.settings
from protobuf import Oneof
from pyqwest import (
Client,
@@ -321,6 +322,123 @@ def shared_pool_server(fault: str) -> Iterator[SharedPoolServer]:
server.listener.close()
+class StreamCapacityServer(threading.Thread):
+ """HTTP/2 server that leaves response streams open at a small peer limit.
+
+ Production ``sandbox.e2b.app`` currently advertises 100 concurrent streams.
+ Tests reproduce that setting and prove how the SDK behaves once long-lived
+ envd command streams fill one connection without opening hundreds of them.
+ """
+
+ def __init__(self, max_concurrent_streams: int):
+ super().__init__(daemon=True)
+ self.max_concurrent_streams = max_concurrent_streams
+ self.listener = socket.create_server(("127.0.0.1", 0))
+ self.listener.settimeout(0.1)
+ self.port = self.listener.getsockname()[1]
+ self.connections: List[socket.socket] = []
+ self.streams: List[tuple[int, int]] = []
+ self.active_streams: set[tuple[int, int]] = set()
+ self.errors: List[str] = []
+ self._lock = threading.Lock()
+ self._stop_event = threading.Event()
+
+ def run(self):
+ while not self._stop_event.is_set():
+ try:
+ sock, _ = self.listener.accept()
+ except socket.timeout:
+ continue
+ except OSError:
+ return
+ with self._lock:
+ self.connections.append(sock)
+ threading.Thread(target=self._serve, args=(sock,), daemon=True).start()
+
+ def _serve(self, sock: socket.socket):
+ sock.settimeout(0.1)
+ conn = h2.connection.H2Connection(
+ config=h2.config.H2Configuration(client_side=False)
+ )
+ conn.initiate_connection()
+ conn.update_settings(
+ {
+ h2.settings.SettingCodes.MAX_CONCURRENT_STREAMS: (
+ self.max_concurrent_streams
+ )
+ }
+ )
+ sock.sendall(conn.data_to_send())
+ try:
+ while not self._stop_event.is_set():
+ try:
+ data = sock.recv(65535)
+ except socket.timeout:
+ continue
+ except OSError:
+ return
+ if not data:
+ return
+ for event in conn.receive_data(data):
+ if isinstance(event, h2.events.StreamEnded):
+ with self._lock:
+ stream = (id(sock), event.stream_id)
+ self.streams.append(stream)
+ self.active_streams.add(stream)
+ conn.send_headers(
+ event.stream_id,
+ [
+ (":status", "200"),
+ ("content-type", "application/connect+json"),
+ ],
+ )
+ # Deliberately leave the response open: a running envd
+ # command holds its HTTP/2 stream for its whole lifetime.
+ conn.send_data(event.stream_id, event_envelope())
+ elif isinstance(event, h2.events.StreamReset):
+ with self._lock:
+ self.active_streams.discard((id(sock), event.stream_id))
+ elif isinstance(event, h2.events.DataReceived):
+ conn.acknowledge_received_data(
+ event.flow_controlled_length, event.stream_id
+ )
+ elif isinstance(event, h2.events.ConnectionTerminated):
+ return
+ out = conn.data_to_send()
+ if out:
+ sock.sendall(out)
+ except Exception as e: # noqa: BLE001 — surfaced via assert_no_errors
+ self.errors.append(repr(e))
+ finally:
+ sock.close()
+
+ def close(self):
+ self._stop_event.set()
+ self.listener.close()
+ with self._lock:
+ connections = list(self.connections)
+ for sock in connections:
+ with contextlib.suppress(OSError):
+ sock.close()
+
+ def assert_no_errors(self):
+ assert not self.errors, self.errors
+
+
+def stream_capacity_server(
+ max_concurrent_streams: int,
+) -> Iterator[StreamCapacityServer]:
+ server = StreamCapacityServer(max_concurrent_streams)
+ server.start()
+ try:
+ yield server
+ finally:
+ server.close()
+ server.join(timeout=1)
+ assert not server.is_alive()
+
+
def assert_stdout_event(event: ConnectResponse):
assert event.event is not None
match event.event.event:
diff --git a/packages/python-sdk/tests/test_api_client_transport.py b/packages/python-sdk/tests/test_api_client_transport.py
index 0d9f89bc7..da7a29fe0 100644
--- a/packages/python-sdk/tests/test_api_client_transport.py
+++ b/packages/python-sdk/tests/test_api_client_transport.py
@@ -13,9 +13,15 @@ from pyqwest import HTTPVersion, Request, SyncRequest
from pyqwest.httpx import AsyncPyqwestTransport, PyqwestTransport
from transport_caches import reset_transport_caches
+import e2b.api as api
import e2b.api.client_async as api_client_async
import e2b.api.client_sync as api_client_sync
-from e2b.api import pool_idle_timeout, pool_max_idle_per_host, proxy_to_config
+from e2b.api import (
+ envd_pool_shard,
+ pool_idle_timeout,
+ pool_max_idle_per_host,
+ proxy_to_config,
+)
from e2b.api.client_async import get_api_client as get_async_api_client
from e2b.api.client_async import get_envd_api as get_async_envd_api
from e2b.api.client_async import get_envd_transport as get_async_envd_transport
@@ -36,6 +42,30 @@ def run_in_worker_thread(fn):
return executor.submit(fn).result()
+def sandbox_config(test_api_key: str, sandbox_id: str) -> ConnectionConfig:
+ return ConnectionConfig(
+ api_key=test_api_key,
+ extra_sandbox_headers={
+ "E2b-Sandbox-Id": sandbox_id,
+ "E2b-Sandbox-Port": "49983",
+ },
+ )
+
+
[email protected]("pool_shards", [1, 4, 8])
+def test_envd_pool_shard_respects_configured_count(
+ test_api_key, monkeypatch, pool_shards
+):
+ monkeypatch.setattr(api, "envd_pool_shards", pool_shards)
+
+ assigned = {
+ envd_pool_shard(sandbox_config(test_api_key, f"sbx-{index}"))
+ for index in range(100)
+ }
+
+ assert assigned == set(range(pool_shards))
+
+
def test_sync_api_client_proxy_uses_explicit_transport(test_api_key):
reset_transport_caches()
config = ConnectionConfig(
@@ -101,8 +131,8 @@ def test_sync_transports_keyed_by_http_version(test_api_key):
assert http1 is not negotiated
assert envd_http1 is not envd_negotiated
- # The envd HTTP API draws from the same pool as the control plane, per
- # version — `get_envd_transport` is `get_transport` under another name.
+ # A config without sandbox headers resolves envd to shard zero, so it
+ # shares the generic transport for each HTTP version.
assert envd_negotiated is negotiated
assert envd_http1 is http1
# Each version still has one pool per proxy, and repeat calls with the
@@ -122,6 +152,29 @@ def test_sync_transports_keyed_by_http_version(test_api_key):
reset_transport_caches()
+def test_sync_envd_transports_are_consistently_sharded_by_sandbox(
+ test_api_key, monkeypatch
+):
+ monkeypatch.setattr(api, "envd_pool_shards", 4)
+ reset_transport_caches()
+ first = sandbox_config(test_api_key, "sbx-0")
+ same_shard = sandbox_config(test_api_key, "sbx-2")
+ different_shard = sandbox_config(test_api_key, "sbx-1")
+
+ try:
+ assert envd_pool_shard(first) == envd_pool_shard(same_shard)
+ assert envd_pool_shard(first) != envd_pool_shard(different_shard)
+ assert get_sync_envd_transport(first) is get_sync_envd_transport(same_shard)
+ assert get_sync_envd_transport(first) is not get_sync_envd_transport(
+ different_shard
+ )
+ # Generic API traffic remains on shard zero rather than multiplying
+ # control-plane connections for every envd shard.
+ assert get_sync_envd_transport(first) is not get_sync_transport(first)
+ finally:
+ reset_transport_caches()
+
+
def test_sync_transports_pass_http_version_to_pyqwest(test_api_key, monkeypatch):
# `http_version=None` leaves the version to ALPN (HTTP/2 against the E2B
# API), `HTTP1` pins HTTP/1.1. Which version was negotiated is only
@@ -212,10 +265,7 @@ def test_sync_api_client_request_timeout_zero_disables_timeout(test_api_key):
reset_transport_caches()
-def test_sync_envd_and_api_share_one_transport(test_api_key):
- # The envd HTTP API draws from the same pool as the control-plane REST API
- # — reqwest pools per host, so one pool serves both. Only the streaming
- # variant, which carries the idle read timeout, is a pool of its own.
+def test_sync_generic_transport_separates_streaming_read_timeout(test_api_key):
reset_transport_caches()
config = ConnectionConfig(api_key=test_api_key)
@@ -324,8 +374,8 @@ async def test_async_transports_keyed_by_http_version(test_api_key):
assert http1 is not negotiated
assert envd_http1 is not envd_negotiated
- # The envd HTTP API draws from the same pool as the control plane, per
- # version — `get_envd_transport` is `get_transport` under another name.
+ # A config without sandbox headers resolves envd to shard zero, so it
+ # shares the generic transport for each HTTP version.
assert envd_negotiated is negotiated
assert envd_http1 is http1
assert get_async_transport(config, http2=False) is http1
@@ -339,6 +389,26 @@ async def test_async_transports_keyed_by_http_version(test_api_key):
reset_transport_caches()
+async def test_async_envd_transports_are_consistently_sharded_by_sandbox(
+ test_api_key, monkeypatch
+):
+ monkeypatch.setattr(api, "envd_pool_shards", 4)
+ reset_transport_caches()
+ first = sandbox_config(test_api_key, "sbx-0")
+ same_shard = sandbox_config(test_api_key, "sbx-2")
+ different_shard = sandbox_config(test_api_key, "sbx-1")
+
+ try:
+ assert get_async_envd_transport(first) is get_async_envd_transport(same_shard)
+ assert get_async_envd_transport(first) is not get_async_envd_transport(
+ different_shard
+ )
+ assert get_async_envd_transport(first) is not get_async_transport(first)
+ finally:
+ reset_transport_caches()
+
+
@pytest.mark.asyncio
async def test_async_transports_pass_http_version_to_pyqwest(test_api_key, monkeypatch):
reset_transport_caches()
@@ -417,7 +487,7 @@ async def test_async_api_client_is_shared_across_loops(test_api_key):
@pytest.mark.asyncio
-async def test_async_envd_and_api_share_one_transport(test_api_key):
+async def test_async_generic_transport_separates_streaming_read_timeout(test_api_key):
reset_transport_caches()
config = ConnectionConfig(api_key=test_api_key)
diff --git a/packages/python-sdk/tests/test_env_var_parsing.py b/packages/python-sdk/tests/test_env_var_parsing.py
index 88f0b035d..fc83438d0 100644
--- a/packages/python-sdk/tests/test_env_var_parsing.py
+++ b/packages/python-sdk/tests/test_env_var_parsing.py
@@ -10,6 +10,7 @@ _ENV_VARS = (
"E2B_KEEPALIVE_EXPIRY",
"E2B_MAX_KEEPALIVE_CONNECTIONS",
"E2B_CONNECTION_RETRIES",
+ "E2B_ENVD_POOL_SHARDS",
)
@@ -25,6 +26,7 @@ def test_empty_env_vars_fall_back_to_defaults(monkeypatch):
assert api.pool_idle_timeout == 300
assert api.pool_max_idle_per_host == 20
assert api.connection_retries == 3
+ assert api.envd_pool_shards == 4
finally:
monkeypatch.undo()
_reload()
@@ -33,10 +35,12 @@ def test_empty_env_vars_fall_back_to_defaults(monkeypatch):
def test_set_env_vars_are_honored(monkeypatch):
monkeypatch.setenv("E2B_KEEPALIVE_EXPIRY", "42")
monkeypatch.setenv("E2B_CONNECTION_RETRIES", "5")
+ monkeypatch.setenv("E2B_ENVD_POOL_SHARDS", "8")
try:
api = _reload()
assert api.pool_idle_timeout == 42
assert api.connection_retries == 5
+ assert api.envd_pool_shards == 8
finally:
monkeypatch.undo()
_reload()
diff --git a/packages/python-sdk/tests/test_envd_stream_capacity.py b/packages/python-sdk/tests/test_envd_stream_capacity.py
new file mode 100644
index 000000000..1f3dbefb3
--- /dev/null
+++ b/packages/python-sdk/tests/test_envd_stream_capacity.py
@@ -0,0 +1,155 @@
+"""Long-lived envd streams must not all contend for one HTTP/2 connection."""
+
+import asyncio
+from collections import Counter
+from concurrent.futures import ThreadPoolExecutor
+
+import pytest
+from envd_frame_server import stream_capacity_server
+from pyqwest import HTTPVersion
+
+import e2b.api as api
+import e2b.api.client_async as api_client_async
+import e2b.api.client_sync as api_client_sync
+from e2b.connection_config import ConnectionConfig
+from e2b.envd.client_async import (
+ as_stream as as_async_stream,
+ create_rpc_client as create_async_rpc_client,
+ first_event,
+)
+from e2b.envd.client_sync import (
+ as_stream as as_sync_stream,
+ create_rpc_client as create_sync_rpc_client,
+)
+from e2b.envd.process.process_connect import ProcessClient, ProcessClientSync
+from e2b.envd.process.process_pb import ConnectRequest
+from transport_caches import reset_transport_caches
+
+
+def sandbox_config(sandbox_id: str) -> ConnectionConfig:
+ return ConnectionConfig(
+ api_key="e2b_" + "0" * 40,
+ extra_sandbox_headers={
+ "E2b-Sandbox-Id": sandbox_id,
+ "E2b-Sandbox-Port": "49983",
+ },
+ )
+
+
+def test_sync_envd_spreads_repeated_waves_across_reused_connections(monkeypatch):
+ """Fresh sync sandboxes keep filling the same four pools evenly."""
+ monkeypatch.setattr(api, "envd_pool_shards", 4)
+ reset_transport_caches()
+ build_transport = api_client_sync.SyncHTTPTransport
+
+ def build_http2_transport(**kwargs):
+ # Production negotiates HTTP/2 over TLS. The frame server is plaintext,
+ # so force prior knowledge while retaining the production factory/cache.
+ kwargs["http_version"] = HTTPVersion.HTTP2
+ return build_transport(**kwargs)
+
+ monkeypatch.setattr(api_client_sync, "SyncHTTPTransport", build_http2_transport)
+
+ streams = []
+ try:
+ with stream_capacity_server(max_concurrent_streams=100) as server:
+ connection_ids = None
+ for wave in range(3):
+ wave_streams = []
+ for index in range(80):
+ client = create_sync_rpc_client(
+ ProcessClientSync,
+ f"http://127.0.0.1:{server.port}",
+ sandbox_config(f"sbx-wave-{wave}-{index}"),
+ )
+ wave_streams.append(
+ as_sync_stream(client.connect(ConnectRequest()))
+ )
+ streams.extend(wave_streams)
+
+ stream_count = len(server.streams)
+ with ThreadPoolExecutor(max_workers=len(wave_streams)) as executor:
+ futures = [executor.submit(next, stream) for stream in wave_streams]
+ events = [future.result(timeout=2) for future in futures]
+
+ assert len(events) == 80
+ wave_counts = Counter(
+ connection_id for connection_id, _ in server.streams[stream_count:]
+ )
+ assert len(wave_counts) == 4
+ if connection_ids is None:
+ connection_ids = set(wave_counts)
+ assert set(wave_counts) == connection_ids
+ assert max(wave_counts.values()) - min(wave_counts.values()) <= 2
+ assert len(server.active_streams) == (wave + 1) * 80
+
+ assert len(server.connections) == 4
+ assert len(server.streams) == 240
+ server.assert_no_errors()
+ finally:
+ for stream in streams:
+ stream.close()
+ reset_transport_caches()
+
+
+async def test_async_envd_spreads_repeated_waves_across_reused_connections(
+ monkeypatch,
+):
+ """Fresh async sandboxes keep filling the same four pools evenly."""
+ monkeypatch.setattr(api, "envd_pool_shards", 4)
+ reset_transport_caches()
+ build_transport = api_client_async.HTTPTransport
+
+ def build_http2_transport(**kwargs):
+ # Production negotiates HTTP/2 over TLS. The frame server is plaintext,
+ # so force prior knowledge while retaining the production factory/cache.
+ kwargs["http_version"] = HTTPVersion.HTTP2
+ return build_transport(**kwargs)
+
+ monkeypatch.setattr(api_client_async, "HTTPTransport", build_http2_transport)
+
+ streams = []
+ try:
+ with stream_capacity_server(max_concurrent_streams=100) as server:
+ connection_ids = None
+ for wave in range(3):
+ wave_streams = []
+ for index in range(80):
+ client = create_async_rpc_client(
+ ProcessClient,
+ f"http://127.0.0.1:{server.port}",
+ sandbox_config(f"sbx-wave-{wave}-{index}"),
+ )
+ wave_streams.append(
+ as_async_stream(client.connect(ConnectRequest()))
+ )
+ streams.extend(wave_streams)
+
+ stream_count = len(server.streams)
+ events = await asyncio.gather(
+ *(first_event(stream, 0.5) for stream in wave_streams),
+ return_exceptions=True,
+ )
+
+ assert not [
+ event for event in events if isinstance(event, BaseException)
+ ]
+ wave_counts = Counter(
+ connection_id for connection_id, _ in server.streams[stream_count:]
+ )
+ assert len(wave_counts) == 4
+ if connection_ids is None:
+ connection_ids = set(wave_counts)
+ assert set(wave_counts) == connection_ids
+ assert max(wave_counts.values()) - min(wave_counts.values()) <= 2
+ assert len(server.active_streams) == (wave + 1) * 80
+
+ assert len(server.connections) == 4
+ assert len(server.streams) == 240
+ server.assert_no_errors()
+ finally:
+ await asyncio.gather(
+ *(stream.aclose() for stream in streams), return_exceptions=True
+ )
+ reset_transport_caches()