> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/gym/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/gym/_mcp/server.

# nemo_gym.sandbox.providers.e2b.build

Build E2B templates from OCI images.

E2B cannot start a sandbox from an OCI reference: `POST /sandboxes` accepts
only a template name or ID. Building a template from the image is the path from
an OCI reference to a running sandbox.

This module is deliberately **outside** the sandbox public API and the
:class:`SandboxProvider` protocol. Building a template is a *provisioning*
step -- slow, one-off, and shared across runs -- whereas the provider API is
about starting and driving sandboxes. Keeping them apart means
:meth:`E2BProvider.create` never blocks on an image build, and provisioning can
run ahead of time from CI, a notebook, or the CLI below.

Typical use: build templates once, then feed the resulting mapping into the
provider's `create.template_map`.

python -m nemo\_gym.sandbox.providers.e2b.build \
\--image ghcr.io/acme/task-a:1.0 --image ghcr.io/acme/task-b:1.0 \
\--cpu-count 8 --memory-mb 16384 --output template\_map.yaml

## Module Contents

### Classes

| Name                                                                                   | Description                                           |
| -------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| [`E2BTemplateBuildError`](#nemo_gym-sandbox-providers-e2b-build-E2BTemplateBuildError) | Raised when a template cannot be built from an image. |

### Functions

| Name                                                                                                   | Description                                                           |
| ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
| [`_parse_args`](#nemo_gym-sandbox-providers-e2b-build-_parse_args)                                     | -                                                                     |
| [`_require_e2b_sdk`](#nemo_gym-sandbox-providers-e2b-build-_require_e2b_sdk)                           | -                                                                     |
| [`_validate_image_and_resources`](#nemo_gym-sandbox-providers-e2b-build-_validate_image_and_resources) | -                                                                     |
| [`_validate_resources`](#nemo_gym-sandbox-providers-e2b-build-_validate_resources)                     | -                                                                     |
| [`build_template`](#nemo_gym-sandbox-providers-e2b-build-build_template)                               | Build one template from an OCI image and return its alias.            |
| [`build_templates`](#nemo_gym-sandbox-providers-e2b-build-build_templates)                             | Build templates for many images, returning an image -> alias mapping. |
| [`derive_alias`](#nemo_gym-sandbox-providers-e2b-build-derive_alias)                                   | Return a deterministic, charset-safe alias for an image + build size. |
| [`main`](#nemo_gym-sandbox-providers-e2b-build-main)                                                   | -                                                                     |
| [`template_exists`](#nemo_gym-sandbox-providers-e2b-build-template_exists)                             | Whether `alias` already exists on the target deployment.              |

### Data

[`DEFAULT_BUILD_TIMEOUT_S`](#nemo_gym-sandbox-providers-e2b-build-DEFAULT_BUILD_TIMEOUT_S)

[`DEFAULT_CPU_COUNT`](#nemo_gym-sandbox-providers-e2b-build-DEFAULT_CPU_COUNT)

[`DEFAULT_MEMORY_MB`](#nemo_gym-sandbox-providers-e2b-build-DEFAULT_MEMORY_MB)

[`LOGGER`](#nemo_gym-sandbox-providers-e2b-build-LOGGER)

[`_ALIAS_SAFE_RE`](#nemo_gym-sandbox-providers-e2b-build-_ALIAS_SAFE_RE)

### API

```python
class nemo_gym.sandbox.providers.e2b.build.E2BTemplateBuildError()
```

**Bases:** `RuntimeError`

Raised when a template cannot be built from an image.

```python
nemo_gym.sandbox.providers.e2b.build._parse_args(
    argv: collections.abc.Sequence[str] | None = None
) -> argparse.Namespace
```

```python
nemo_gym.sandbox.providers.e2b.build._require_e2b_sdk() -> typing.Any
```

```python
nemo_gym.sandbox.providers.e2b.build._validate_image_and_resources(
    image: str,
    cpu_count: int,
    memory_mb: int
) -> None
```

```python
nemo_gym.sandbox.providers.e2b.build._validate_resources(
    cpu_count: int,
    memory_mb: int
) -> None
```

```python
nemo_gym.sandbox.providers.e2b.build.build_template(
    image: str,
    alias: str | None = None,
    cpu_count: int = DEFAULT_CPU_COUNT,
    memory_mb: int = DEFAULT_MEMORY_MB,
    build_timeout_s: float = DEFAULT_BUILD_TIMEOUT_S,
    registry_username: str | None = None,
    registry_password: str | None = None,
    skip_existing: bool = True,
    on_build_logs: typing.Any = None,
    api_params: typing.Any = {}
) -> str
```

async

Build one template from an OCI image and return its alias.

```python
nemo_gym.sandbox.providers.e2b.build.build_templates(
    images: collections.abc.Iterable[str],
    cpu_count: int = DEFAULT_CPU_COUNT,
    memory_mb: int = DEFAULT_MEMORY_MB,
    concurrency: int = 4,
    continue_on_error: bool = False,
    kwargs: typing.Any = {}
) -> dict[str, str]
```

async

Build templates for many images, returning an image -> alias mapping.

The result is exactly the shape of the provider's `create.template_map`.
With `continue_on_error` the failures are logged and omitted, so one bad
image does not discard a long batch.

```python
nemo_gym.sandbox.providers.e2b.build.derive_alias(
    image: str,
    cpu_count: int = DEFAULT_CPU_COUNT,
    memory_mb: int = DEFAULT_MEMORY_MB
) -> str
```

Return a deterministic, charset-safe alias for an image + build size.

The digest covers the resources as well as the image because E2B bakes
cpu/memory into the template: two sandboxes wanting different sizes must
not share one, or the second silently inherits the first's sizing.

```python
nemo_gym.sandbox.providers.e2b.build.main(
    argv: collections.abc.Sequence[str] | None = None
) -> int
```

```python
nemo_gym.sandbox.providers.e2b.build.template_exists(
    alias: str,
    api_params: typing.Any = {}
) -> bool
```

async

Whether `alias` already exists on the target deployment.

```python
nemo_gym.sandbox.providers.e2b.build.DEFAULT_BUILD_TIMEOUT_S = 3600.0
```

```python
nemo_gym.sandbox.providers.e2b.build.DEFAULT_CPU_COUNT = 2
```

```python
nemo_gym.sandbox.providers.e2b.build.DEFAULT_MEMORY_MB = 1024
```

```python
nemo_gym.sandbox.providers.e2b.build.LOGGER = logging.getLogger(__name__)
```

```python
nemo_gym.sandbox.providers.e2b.build._ALIAS_SAFE_RE = re.compile('[^A-Za-z0-9_-]')
```