> 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.base

Provider-facing sandbox protocol.

## Module Contents

### Classes

| Name                                                                                                | Description                                                          |
| --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| [`SandboxCreateError`](#nemo_gym-sandbox-providers-base-SandboxCreateError)                         | Raised when a provider cannot create a sandbox.                      |
| [`SandboxCreateVerificationError`](#nemo_gym-sandbox-providers-base-SandboxCreateVerificationError) | Raised when a newly-created sandbox fails provider readiness checks. |
| [`SandboxExecResult`](#nemo_gym-sandbox-providers-base-SandboxExecResult)                           | Provider-neutral process execution result.                           |
| [`SandboxHandle`](#nemo_gym-sandbox-providers-base-SandboxHandle)                                   | Provider-neutral handle to a created sandbox.                        |
| [`SandboxProvider`](#nemo_gym-sandbox-providers-base-SandboxProvider)                               | Runtime/infra provider contract used by the public sandbox API.      |
| [`SandboxResources`](#nemo_gym-sandbox-providers-base-SandboxResources)                             | Provider-neutral resource request.                                   |
| [`SandboxSpec`](#nemo_gym-sandbox-providers-base-SandboxSpec)                                       | Sandbox creation request.                                            |
| [`SandboxStatus`](#nemo_gym-sandbox-providers-base-SandboxStatus)                                   | Provider-neutral sandbox lifecycle status.                           |

### Data

[`ExecResult`](#nemo_gym-sandbox-providers-base-ExecResult)

### API

```python
class nemo_gym.sandbox.providers.base.SandboxCreateError()
```

**Bases:** `RuntimeError`

Raised when a provider cannot create a sandbox.

```python
class nemo_gym.sandbox.providers.base.SandboxCreateVerificationError()
```

**Bases:** [SandboxCreateError](#nemo_gym-sandbox-providers-base-SandboxCreateError)

Raised when a newly-created sandbox fails provider readiness checks.

```python
class nemo_gym.sandbox.providers.base.SandboxExecResult(
    stdout: str | None,
    stderr: str | None,
    return_code: int,
    error_type: str | None = None
)
```

Dataclass

Provider-neutral process execution result.

`return_code` is the process exit code when the sandbox actually ran the
command. Providers may use a non-process sentinel with `error_type` set
when the sandbox runtime reports an execution failure without a process
exit code.

```python
class nemo_gym.sandbox.providers.base.SandboxHandle(
    sandbox_id: str,
    provider_name: str,
    raw: typing.Any
)
```

Dataclass

Provider-neutral handle to a created sandbox.

`raw` is provider-owned opaque state. Public code should pass it back to
the provider through this handle rather than inspecting or mutating it
directly.

```python
class nemo_gym.sandbox.providers.base.SandboxProvider()
```

Protocol

Runtime/infra provider contract used by the public sandbox API.

```python
nemo_gym.sandbox.providers.base.SandboxProvider.aclose() -> None
```

async

Close provider-scoped resources such as SDK clients.

```python
nemo_gym.sandbox.providers.base.SandboxProvider.close(
    handle: nemo_gym.sandbox.providers.base.SandboxHandle
) -> None
```

async

End the sandbox lifecycle and close provider resources for it.

```python
nemo_gym.sandbox.providers.base.SandboxProvider.create(
    spec: nemo_gym.sandbox.providers.base.SandboxSpec
) -> nemo_gym.sandbox.providers.base.SandboxHandle
```

async

Create a ready sandbox and return a provider-neutral handle.

Providers must return only after the sandbox is healthy enough to run
commands and transfer files. If the sandbox cannot become ready before
the configured timeout, providers should raise `SandboxCreateError`
or a provider-specific subclass.

```python
nemo_gym.sandbox.providers.base.SandboxProvider.download_file(
    handle: nemo_gym.sandbox.providers.base.SandboxHandle,
    source_path: str,
    target_path: pathlib.Path
) -> None
```

async

Download one sandbox file to the local filesystem.

```python
nemo_gym.sandbox.providers.base.SandboxProvider.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

Run a command inside a sandbox.

```python
nemo_gym.sandbox.providers.base.SandboxProvider.status(
    handle: nemo_gym.sandbox.providers.base.SandboxHandle
) -> nemo_gym.sandbox.providers.base.SandboxStatus
```

async

Return the current sandbox lifecycle status.

```python
nemo_gym.sandbox.providers.base.SandboxProvider.upload_file(
    handle: nemo_gym.sandbox.providers.base.SandboxHandle,
    source_path: pathlib.Path,
    target_path: str
) -> None
```

async

Upload one local file into a sandbox.

```python
class nemo_gym.sandbox.providers.base.SandboxResources(
    cpu: float | None = None,
    memory_mib: int | None = None,
    disk_gib: int | None = None,
    gpu: int | None = None,
    gpu_type: str | None = None
)
```

Dataclass

Provider-neutral resource request.

```python
nemo_gym.sandbox.providers.base.SandboxResources.from_mapping(
    resources: collections.abc.Mapping[str, typing.Any] | None
) -> nemo_gym.sandbox.providers.base.SandboxResources
```

classmethod

```python
class nemo_gym.sandbox.providers.base.SandboxSpec(
    image: str | None = None,
    ttl_s: int | float | None = None,
    ready_timeout_s: int | float | None = None,
    workdir: str | None = None,
    env: dict[str, str] = dict(),
    files: dict[str, str] = dict(),
    metadata: dict[str, str] = dict(),
    resources: nemo_gym.sandbox.providers.base.SandboxResources | collections.abc.Mapping[str, typing.Any] = SandboxResources(),
    entrypoint: list[str] | None = None,
    provider_options: dict[str, typing.Any] = dict()
)
```

Dataclass

Sandbox creation request.

```python
nemo_gym.sandbox.providers.base.SandboxSpec.__post_init__() -> None
```

```python
class nemo_gym.sandbox.providers.base.SandboxStatus
```

**Bases:** `enum.Enum`

Provider-neutral sandbox lifecycle status.

```python
nemo_gym.sandbox.providers.base.ExecResult = SandboxExecResult
```