> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/nemo/gym/main/nemo-gym/nemo_gym/sandbox/providers/e2b/llms.txt. # nemo_gym.sandbox.providers.e2b E2B provider package. ## Submodules * **[`nemo_gym.sandbox.providers.e2b.build`](/nemo/gym/nemo-gym/nemo_gym/sandbox/providers/e2b/build)** * **[`nemo_gym.sandbox.providers.e2b.provider`](/nemo/gym/nemo-gym/nemo_gym/sandbox/providers/e2b/provider)** ## Package Contents ### Classes | Name | Description | | ------------------------------------------------------------------------------------- | -------------------------------------------------- | | [`E2BConnectionConfig`](#nemo_gym-sandbox-providers-e2b-provider-E2BConnectionConfig) | Connection settings forwarded to the SDK. | | [`E2BCreateConfig`](#nemo_gym-sandbox-providers-e2b-provider-E2BCreateConfig) | Sandbox creation settings. | | [`E2BCreateError`](#nemo_gym-sandbox-providers-e2b-provider-E2BCreateError) | Raised when a sandbox cannot be created. | | [`E2BExecConfig`](#nemo_gym-sandbox-providers-e2b-provider-E2BExecConfig) | Command execution settings. | | [`E2BOperationConfig`](#nemo_gym-sandbox-providers-e2b-provider-E2BOperationConfig) | Retry policy for transient SDK/transport failures. | | [`E2BProvider`](#nemo_gym-sandbox-providers-e2b-provider-E2BProvider) | Provider backed by the E2B Python SDK. | ### API ```python class nemo_gym.sandbox.providers.e2b.E2BConnectionConfig( api_key: str | None = None, api_url: str | None = None, sandbox_url: str | None = None, domain: str | None = None, debug: bool | None = None, validate_api_key: bool | None = None, headers: dict[str, str] | None = None, api_headers: dict[str, str] | None = None, proxy: str | None = None, request_timeout_s: float | None = None, port_routing: str = 'auto', port_scheme: str | None = None ) ``` Dataclass Connection settings forwarded to the SDK. Any field left `None` falls back to the SDK's own environment variables (`E2B_API_KEY`, `E2B_API_URL`, `E2B_SANDBOX_URL`, `E2B_DOMAIN`, ...). **`api_headers`** `dict[str, str] | None = None` --- **`api_key`** `str | None = None` --- **`api_url`** `str | None = None` --- **`debug`** `bool | None = None` --- **`domain`** `str | None = None` --- **`headers`** `dict[str, str] | None = None` --- **`port_routing`** `str = 'auto'` --- **`port_scheme`** `str | None = None` --- **`proxy`** `str | None = None` --- **`request_timeout_s`** `float | None = None` --- **`sandbox_url`** `str | None = None` --- **`validate_api_key`** `bool | None = None` --- ```python nemo_gym.sandbox.providers.e2b.E2BConnectionConfig.__post_init__() -> None ``` ```python class nemo_gym.sandbox.providers.e2b.E2BCreateConfig( template: str | None = None, template_map: dict[str, str] = dict(), timeout_s: float | None = 3600.0, allow_internet_access: bool = True, secure: bool = True, network: dict[str, list[str]] | None = None, custom_extension_params: dict[str, typing.Any] | None = None, strict_resources: bool = False, auto_resume: bool | None = False ) ``` Dataclass Sandbox creation settings. **`allow_internet_access`** `bool = True` --- **`auto_resume`** `bool | None = field(default=False, kw_only=True)` --- **`custom_extension_params`** `dict[str, Any] | None = None` --- **`network`** `dict[str, list[str]] | None = None` --- **`secure`** `bool = True` --- **`strict_resources`** `bool = False` --- **`template`** `str | None = None` --- **`template_map`** `dict[str, str] = field(default_factory=dict)` --- **`timeout_s`** `float | None = 3600.0` --- ```python nemo_gym.sandbox.providers.e2b.E2BCreateConfig.__post_init__() -> None ``` ```python class nemo_gym.sandbox.providers.e2b.E2BCreateError() ``` **Bases:** [SandboxCreateError](/nemo/gym/nemo-gym/nemo_gym/sandbox/providers/base#nemo_gym-sandbox-providers-base-SandboxCreateError) Raised when a sandbox cannot be created. ```python class nemo_gym.sandbox.providers.e2b.E2BExecConfig( default_timeout_s: float | None = 180.0, user: str | None = None, request_timeout_s: float | None = None, background: bool = True, reconnect_attempts: int = 2 ) ``` Dataclass Command execution settings. **`background`** `bool = True` --- **`default_timeout_s`** `float | None = 180.0` --- **`reconnect_attempts`** `int = 2` --- **`request_timeout_s`** `float | None = None` --- **`user`** `str | None = None` --- ```python nemo_gym.sandbox.providers.e2b.E2BExecConfig.__post_init__() -> None ``` ```python class nemo_gym.sandbox.providers.e2b.E2BOperationConfig( retries: int = 2, retry_delay_s: float = 0.5, retry_max_delay_s: float = 8.0 ) ``` Dataclass Retry policy for transient SDK/transport failures. **`retries`** `int = 2` --- **`retry_delay_s`** `float = 0.5` --- **`retry_max_delay_s`** `float = 8.0` --- ```python nemo_gym.sandbox.providers.e2b.E2BOperationConfig.__post_init__() -> None ``` ```python class nemo_gym.sandbox.providers.e2b.E2BProvider( connection: nemo_gym.sandbox.providers.e2b.provider.E2BConnectionConfig | collections.abc.Mapping[str, typing.Any] | None = None, create: nemo_gym.sandbox.providers.e2b.provider.E2BCreateConfig | collections.abc.Mapping[str, typing.Any] | None = None, exec: nemo_gym.sandbox.providers.e2b.provider.E2BExecConfig | collections.abc.Mapping[str, typing.Any] | None = None, operations: nemo_gym.sandbox.providers.e2b.provider.E2BOperationConfig | collections.abc.Mapping[str, typing.Any] | None = None, attribution: nemo_gym.sandbox.attribution.AttributionConfig | collections.abc.Mapping[str, typing.Any] | None = None ) ``` Provider backed by the E2B Python SDK. **`_attribution`** --- **`_connection`** --- **`_create`** `= _config_from_mapping(E2BCreateConfig, create)` --- **`_exec`** `= _config_from_mapping(E2BExecConfig, exec)` --- **`_operations`** --- **`_warned_resource_specs`** `set[str] = set()` --- **`name`** `= 'e2b'` --- ```python nemo_gym.sandbox.providers.e2b.E2BProvider._api_params() -> dict[str, typing.Any] ``` SDK `ApiParams` for connection-scoped calls; omitted keys fall back to env. Only `create`/`connect`/`kill` open a connection and accept these. Everything else runs against an already-connected sandbox -- see `_request_params`. ```python nemo_gym.sandbox.providers.e2b.E2BProvider._check_resources( spec: nemo_gym.sandbox.providers.base.SandboxSpec, template: str ) -> None ``` Surface resource requests E2B cannot honour per sandbox. ```python nemo_gym.sandbox.providers.e2b.E2BProvider._create_with_extension_params( e2b: typing.Any, kwargs: dict[str, typing.Any] ) -> typing.Any ``` async Create through `POST /sandboxes`, adding `customExtensionParams`. The POST goes through the SDK's own API client, so it gets the URL, auth headers, proxy, timeout and HTTP transport of `AsyncSandbox.create`, and like it is never replayed. `AsyncSandbox.connect` then attaches; it also returns the envd access token a secure sandbox needs. ```python nemo_gym.sandbox.providers.e2b.E2BProvider._exec_request_timeout() -> float | None ``` Return the E2B 2.36 stream-open timeout for command requests. ```python nemo_gym.sandbox.providers.e2b.E2BProvider._request_params() -> dict[str, typing.Any] ``` Return the request timeout; data-plane methods reject connection parameters. ```python nemo_gym.sandbox.providers.e2b.E2BProvider._resolve_template( spec: nemo_gym.sandbox.providers.base.SandboxSpec ) -> str ``` Map a spec onto an E2B template. Precedence: `provider_options.template` -> `create.template_map` -> an unambiguous direct `spec.image`. `create.template` is used only when `spec.image` is omitted; an unmapped image must not silently select an unrelated fallback template. Building a template from an image is provisioning, not part of starting a sandbox, so it lives in `nemo_gym.sandbox.providers.e2b.build` and never runs on this path. ```python nemo_gym.sandbox.providers.e2b.E2BProvider._run_background( sandbox: typing.Any, kwargs: dict[str, typing.Any] ) -> typing.Any ``` async Run a command detached, reattaching by pid if the stream drops. `commands.run(background=True)` returns as soon as the process has started, handing back its pid. The command then keeps running inside the sandbox independently of the stream carrying its output, so losing that stream -- a gateway rollout, a proxy restart, a network blip -- no longer destroys the command: reattach with `commands.connect(pid)` and the real exit code still arrives. Reattaching has two inherent limits: * **Output emitted while disconnected is lost.** Output already received by the previous handle is retained and combined with the reattached stream, but the stream is live rather than replayed. * **The process must still be running.** `connect` raises not-found once it has exited, so a command that finishes during the gap cannot be recovered. ```python nemo_gym.sandbox.providers.e2b.E2BProvider._sandbox( handle: nemo_gym.sandbox.providers.base.SandboxHandle ) -> typing.Any ``` staticmethod ```python nemo_gym.sandbox.providers.e2b.E2BProvider._with_retries( factory: typing.Callable[[], typing.Awaitable[nemo_gym.sandbox.providers.e2b.provider.T]], operation: str, retry_timeouts: bool = False ) -> nemo_gym.sandbox.providers.e2b.provider.T ``` async Retry transient failures with exponential backoff. ```python nemo_gym.sandbox.providers.e2b.E2BProvider.aclose() -> None ``` async No provider-scoped client to close; sandboxes own their connections. ```python nemo_gym.sandbox.providers.e2b.E2BProvider.close( handle: nemo_gym.sandbox.providers.base.SandboxHandle ) -> None ``` async ```python nemo_gym.sandbox.providers.e2b.E2BProvider.connect( descriptor: collections.abc.Mapping[str, typing.Any] ) -> nemo_gym.sandbox.providers.base.SandboxHandle ``` async Attach to the sandbox described by `descriptor`. E2B's public connect API applies its default sandbox timeout when none is supplied, so attaching may renew a sandbox that is close to expiry. ```python nemo_gym.sandbox.providers.e2b.E2BProvider.create( spec: nemo_gym.sandbox.providers.base.SandboxSpec ) -> nemo_gym.sandbox.providers.base.SandboxHandle ``` async ```python nemo_gym.sandbox.providers.e2b.E2BProvider.download_file( handle: nemo_gym.sandbox.providers.base.SandboxHandle, source_path: str, target_path: pathlib.Path ) -> None ``` async ```python nemo_gym.sandbox.providers.e2b.E2BProvider.endpoint( handle: nemo_gym.sandbox.providers.base.SandboxHandle, port: int ) -> nemo_gym.sandbox.providers.base.SandboxEndpoint ``` async Resolve a declared service port to a caller-reachable endpoint. E2B deployments publish sandbox ports in one of two shapes, and the endpoint differs accordingly: `hostname` One DNS name per port, `{port}-{sandbox_id}.{domain}`. The caller dials it directly, so no headers are needed. `gateway` A single origin fronts every sandbox and every port, and the proxy picks the target from request headers. A self-hosted deployment without wildcard DNS for sandbox subdomains uses this, and points `sandbox_url` at that origin. The SDK mints `X-Access-Token` and `E2b-Sandbox-Id` per sandbox and sets `E2b-Sandbox-Port` to envd's own port, so the target port must be re-pointed here. `auto` selects `gateway` exactly when a sandbox URL is configured, which is the same signal the SDK uses to decide that one origin serves every sandbox. The returned headers are the caller's to send verbatim. `X-Access-Token` is minted per sandbox and is not the deployment's API key. ```python nemo_gym.sandbox.providers.e2b.E2BProvider.exec( handle: nemo_gym.sandbox.providers.base.SandboxHandle, command: str, cwd: str | None = None, env: dict[str, str] | None = None, timeout_s: int | float | None = None, user: str | int | None = None ) -> nemo_gym.sandbox.providers.base.SandboxExecResult ``` async ```python nemo_gym.sandbox.providers.e2b.E2BProvider.pause( handle: nemo_gym.sandbox.providers.base.SandboxHandle ) -> None ``` async Pause the sandbox through the E2B SDK without replaying failed requests. ```python nemo_gym.sandbox.providers.e2b.E2BProvider.read_file( handle: nemo_gym.sandbox.providers.base.SandboxHandle, source_path: str ) -> bytes ``` async ```python nemo_gym.sandbox.providers.e2b.E2BProvider.resume( handle: nemo_gym.sandbox.providers.base.SandboxHandle ) -> None ``` async Resume the sandbox and replace its SDK handle only after success. ```python nemo_gym.sandbox.providers.e2b.E2BProvider.serialize_handle( handle: nemo_gym.sandbox.providers.base.SandboxHandle, scope: str | None = None ) -> dict[str, typing.Any] ``` async Return a descriptor for attaching to this sandbox from another process. ```python nemo_gym.sandbox.providers.e2b.E2BProvider.status( handle: nemo_gym.sandbox.providers.base.SandboxHandle ) -> nemo_gym.sandbox.providers.base.SandboxStatus ``` async ```python nemo_gym.sandbox.providers.e2b.E2BProvider.upload_file( handle: nemo_gym.sandbox.providers.base.SandboxHandle, source_path: pathlib.Path, target_path: str ) -> None ``` async ```python nemo_gym.sandbox.providers.e2b.E2BProvider.write_file( handle: nemo_gym.sandbox.providers.base.SandboxHandle, target_path: str, data: str | bytes ) -> None ``` async ## Docs - [nemo_gym.sandbox.providers.e2b.build](https://docs.nvidia.com/nemo/gym/main/nemo-gym/nemo_gym/sandbox/providers/e2b/build.md) - [nemo_gym.sandbox.providers.e2b.provider](https://docs.nvidia.com/nemo/gym/main/nemo-gym/nemo_gym/sandbox/providers/e2b/provider.md)