Skip to navigation

nemo_gym.sandbox.providers.e2b

View as MarkdownOpen in Claude

E2B provider package.

Submodules

Package Contents

Classes

NameDescription
E2BConnectionConfigConnection settings forwarded to the SDK.
E2BCreateConfigSandbox creation settings.
E2BCreateErrorRaised when a sandbox cannot be created.
E2BExecConfigCommand execution settings.
E2BOperationConfigRetry policy for transient SDK/transport failures.
E2BProviderProvider backed by the E2B Python SDK.

API

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
nemo_gym.sandbox.providers.e2b.E2BConnectionConfig.__post_init__() -> None
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
nemo_gym.sandbox.providers.e2b.E2BCreateConfig.__post_init__() -> None
class nemo_gym.sandbox.providers.e2b.E2BCreateError()

Bases: SandboxCreateError

Raised when a sandbox cannot be created.

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
nemo_gym.sandbox.providers.e2b.E2BExecConfig.__post_init__() -> None
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
nemo_gym.sandbox.providers.e2b.E2BOperationConfig.__post_init__() -> None
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'
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.

nemo_gym.sandbox.providers.e2b.E2BProvider._check_resources(
template: str
) -> None

Surface resource requests E2B cannot honour per sandbox.

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.

nemo_gym.sandbox.providers.e2b.E2BProvider._exec_request_timeout() -> float | None

Return the E2B 2.36 stream-open timeout for command requests.

nemo_gym.sandbox.providers.e2b.E2BProvider._request_params() -> dict[str, typing.Any]

Return the request timeout; data-plane methods reject connection parameters.

nemo_gym.sandbox.providers.e2b.E2BProvider._resolve_template(
) -> 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.

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.
nemo_gym.sandbox.providers.e2b.E2BProvider._sandbox(
) -> typing.Any
staticmethod
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
async

Retry transient failures with exponential backoff.

nemo_gym.sandbox.providers.e2b.E2BProvider.aclose() -> None
async

No provider-scoped client to close; sandboxes own their connections.

nemo_gym.sandbox.providers.e2b.E2BProvider.close(
) -> None
async
nemo_gym.sandbox.providers.e2b.E2BProvider.connect(
descriptor: collections.abc.Mapping[str, typing.Any]
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.

nemo_gym.sandbox.providers.e2b.E2BProvider.create(
async
nemo_gym.sandbox.providers.e2b.E2BProvider.download_file(
source_path: str,
target_path: pathlib.Path
) -> None
async
nemo_gym.sandbox.providers.e2b.E2BProvider.endpoint(
port: int
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.

nemo_gym.sandbox.providers.e2b.E2BProvider.exec(
command: str,
cwd: str | None = None,
env: dict[str, str] | None = None,
timeout_s: int | float | None = None,
user: str | int | None = None
async
nemo_gym.sandbox.providers.e2b.E2BProvider.pause(
) -> None
async

Pause the sandbox through the E2B SDK without replaying failed requests.

nemo_gym.sandbox.providers.e2b.E2BProvider.read_file(
source_path: str
) -> bytes
async
nemo_gym.sandbox.providers.e2b.E2BProvider.resume(
) -> None
async

Resume the sandbox and replace its SDK handle only after success.

nemo_gym.sandbox.providers.e2b.E2BProvider.serialize_handle(
scope: str | None = None
) -> dict[str, typing.Any]
async

Return a descriptor for attaching to this sandbox from another process.

nemo_gym.sandbox.providers.e2b.E2BProvider.status(
async
nemo_gym.sandbox.providers.e2b.E2BProvider.upload_file(
source_path: pathlib.Path,
target_path: str
) -> None
async
nemo_gym.sandbox.providers.e2b.E2BProvider.write_file(
target_path: str,
data: str | bytes
) -> None
async