E2B Provider

The e2b provider creates isolated cloud sandboxes through the E2B Python SDK. It supports the hosted E2B service and E2B-compatible gateways with custom API and sandbox URLs.

Setup

Install the sandbox extra in the environment that creates sandboxes:

$
uv sync --extra sandbox

For a package install, use:

$
pip install "nemo-gym[sandbox]"

The provider requires e2b>=2.36.0,<3.0.0. Set E2B_API_KEY for the hosted service. For a compatible gateway, also set E2B_API_URL and E2B_SANDBOX_URL to the endpoints supplied by the gateway operator.

Provider Config

NeMo Gym ships an E2B config at nemo_gym/sandbox/providers/e2b/configs/e2b.yaml. It defines a top-level sandbox block that agents reference with sandbox_provider: sandbox:

1
sandbox:
2
  default_metadata:
3
    sandbox-api: e2b
4
  e2b:
5
    connection:
6
      api_key: ${oc.env:E2B_API_KEY,null}
7
      api_url: ${oc.env:E2B_API_URL,null}
8
      sandbox_url: ${oc.env:E2B_SANDBOX_URL,null}
9
      request_timeout_s: 120.0
10
    create:
11
      template: null
12
      template_map: {}
13
      timeout_s: 3600.0
14
      secure: true
15
      allow_internet_access: true
16
      strict_resources: false
17
    exec:
18
      default_timeout_s: 180.0
19
      user: null
20
      request_timeout_s: null
21
      background: true
22
      reconnect_attempts: 2
23
    operations:
24
      retries: 2
25
      retry_delay_s: 0.5
26
      retry_max_delay_s: 8.0

Pass the provider config beside the agent and model configs:

$
gym env start \
>
  --config responses_api_agents/mini_swe_agent_2/configs/mini_swe_agent_2.yaml \
>
  --config nemo_gym/sandbox/providers/e2b/configs/e2b.yaml \
>
  --config responses_api_models/vllm_model/configs/vllm_model.yaml

Prepare Templates

E2B starts a sandbox from a template name or ID rather than an OCI image reference. Because tagged template names and OCI references can both contain :, the provider resolves a template conservatively:

1. SandboxSpec.provider_options.template
2. create.template_map[SandboxSpec.image]
3. SandboxSpec.image, when it is an untagged name matching [A-Za-z0-9_-]+
4. The create.template fallback, only when SandboxSpec.image is omitted

Use provider_options.template for a tagged template name or template ID. A non-empty, unmapped image raises instead of silently selecting an unrelated fallback template.

Build templates from OCI images as a separate provisioning step:

$
python -m nemo_gym.sandbox.providers.e2b.build \
>
  --image ghcr.io/acme/task:1.0 \
>
  --cpu-count 8 \
>
  --memory-mb 16384 \
>
  --output template_map.yaml

The generated YAML contains an image-to-template mapping ready to place under create:

1
template_map:
2
  "ghcr.io/acme/task:1.0": task-1-0__f00ee9d593d9

Template building can create E2B resources and is never performed implicitly by sandbox creation. Generated names are deterministic for the image, CPU count, and memory size, so a matching existing template can be reused. The helper’s local timeout stops waiting but cannot cancel a remote build that E2B has already accepted; check E2B before retrying after a timeout. By default a batch failure prevents queued siblings from starting and waits for already-started builds to finish; pass --continue-on-error to keep building the remaining images.

Relevant SandboxSpec Fields

The bundled builder controls template CPU count and memory. Disk and GPU requirements need a suitable template prepared through E2B tooling.

Timeouts and Reconnection

SandboxSpec.ttl_s controls the remote sandbox lifetime. Treat it as a cleanup backstop and still call stop() or use a context manager so the sandbox is killed as soon as work finishes.

SandboxSpec.ready_timeout_s overrides the E2B create request timeout. The SDK retains an explicit create timeout on the returned sandbox connection; the shipped connection.request_timeout_s is reapplied to later calls, while a programmatic config that leaves it unset inherits ready_timeout_s for that sandbox object.

With E2B 2.36+, the connection or exec request_timeout_s only bounds opening command and reconnect streams. Command timeout_s is NeMo Gym’s total wait/stream budget across the initial connection and any reconnects. The public facades normally supply 180 seconds, so pass a larger value explicitly for long builds or test suites. With background execution, a timed-out stream does not guarantee that the remote process was killed; close the sandbox before reuse when a lingering process would be unsafe.

Background execution lets the provider reconnect to a running process by PID after an output stream interruption. Output emitted before reconnection is not replayed. If the process exits during the gap, its result cannot be recovered. Reconnects consume the original wait budget rather than starting a new one.

Create is not automatically retried because an ambiguous failure could allocate two billable sandboxes. Rate-limit responses are returned without automatic retries so callers can choose their backoff window. Close retries transient kill failures, treats an expired sandbox as already closed, and clears the local handle only after confirmed cleanup. Serialized handles carry the E2B sandbox ID for reconnection through another configured provider instance. E2B’s public connect operation may extend a near-expiry sandbox to its SDK-default connection lifetime (300 seconds in E2B 2.36).

Security and Isolation

E2B supplies the sandbox isolation boundary; when using a compatible gateway, its operator is responsible for the deployment’s security posture. The shipped config uses secure: true, so the sandbox envd service requires an access token.

Outbound internet access is enabled by default for workloads that install dependencies. Set create.allow_internet_access: false for offline or untrusted workloads. Values in SandboxSpec.env are injected into the remote sandbox, so pass only secrets required by the workload and keep E2B credentials in the provider connection config or host environment.

mini_swe_agent_2 removes e2b.connection.api_key, headers, and api_headers from generated per-instance worker YAML. It passes them through the worker environment, then reconstructs the header mappings only in worker memory. The API key stays out of the serializable provider config and is read directly from E2B_API_KEY by the E2B SDK.

Integration Attribution

NeMo Gym appends nemo-gym/<version> to the E2B SDK User-Agent for both runtime sandbox requests and template provisioning. This lets E2B distinguish NeMo Gym traffic without adding metadata to the sandbox itself. An explicit custom User-Agent in connection headers takes precedence in the E2B SDK and can hide this attribution.

Sandbox and template operations use the E2B SDK’s public high-level APIs; attribution uses E2B’s set-once integration hook. Because E2B 2.x does not expose transport injection on those APIs, NeMo Gym replaces its module-level HTTP transport factories with an aiohttp adapter backed by Gym’s shared client session. The adapter accepts HTTP and HTTPS proxies; SOCKS proxies are rejected explicitly. E2B’s ConnectRPC command streams keep their SDK-owned pyqwest transport.