nemo_gym.sandbox.providers.e2b.provider
nemo_gym.sandbox.providers.e2b.provider
Sandbox provider backed by the E2B Python SDK.
Works against e2b.dev itself and against any e2b-compatible gateway (point
connection.api_url/connection.sandbox_url at it).
Two E2B concepts differ from the provider-neutral SandboxSpec and are
handled explicitly rather than silently:
Templates, not images. E2B starts sandboxes from a pre-built template
name or ID, not from an arbitrary registry reference. Because tagged template
names and OCI image references can both contain :, the direct
SandboxSpec.image shortcut is deliberately limited to unambiguous names in
[A-Za-z0-9_-]. Use provider_options.template or
create.template_map for tagged names, IDs, and image references.
Resources are fixed at template build time. cpu_count/memory_mb are
arguments to the template build, so a per-sandbox
SandboxSpec.resources cannot be honoured at create time. Requests are
reported once per provider instance (or raise, with create.strict_resources)
instead of being dropped quietly.
Module Contents
Classes
Functions
Data
API
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, …).
Sandbox creation settings.
Bases: SandboxCreateError
Raised when a sandbox cannot be created.
Command execution settings.
Retry policy for transient SDK/transport failures.
Provider backed by the E2B Python SDK.
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.
Surface resource requests E2B cannot honour per sandbox.
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.
Return the E2B 2.36 stream-open timeout for command requests.
Return the request timeout; data-plane methods reject connection parameters.
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.
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.
connectraises not-found once it has exited, so a command that finishes during the gap cannot be recovered.
Retry transient failures with exponential backoff.
No provider-scoped client to close; sandboxes own their connections.
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.
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.
Pause the sandbox through the E2B SDK without replaying failed requests.
Resume the sandbox and replace its SDK handle only after success.
Return a descriptor for attaching to this sandbox from another process.
Build a config dataclass from a mapping, rejecting unknown keys.
Load the optional SDK through the shared helper.
Keep this small wrapper local so provider unit tests can replace the SDK without importing or contacting E2B.