> 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.opensandbox.provider

OpenSandbox provider implementation.

## Module Contents

### Classes

| Name                                                                                                                        | Description                                                          |
| --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| [`OpenSandboxConnectionConfig`](#nemo_gym-sandbox-providers-opensandbox-provider-OpenSandboxConnectionConfig)               | OpenSandbox server connection settings.                              |
| [`OpenSandboxCreateConfig`](#nemo_gym-sandbox-providers-opensandbox-provider-OpenSandboxCreateConfig)                       | OpenSandbox create/reconnect retry settings.                         |
| [`OpenSandboxCreateError`](#nemo_gym-sandbox-providers-opensandbox-provider-OpenSandboxCreateError)                         | Raised when OpenSandbox cannot create a sandbox.                     |
| [`OpenSandboxCreateTimeoutError`](#nemo_gym-sandbox-providers-opensandbox-provider-OpenSandboxCreateTimeoutError)           | Raised when OpenSandbox sandbox creation exceeds the client timeout. |
| [`OpenSandboxCreateVerificationError`](#nemo_gym-sandbox-providers-opensandbox-provider-OpenSandboxCreateVerificationError) | Raised when a newly-created sandbox cannot execute a probe command.  |
| [`OpenSandboxOperationConfig`](#nemo_gym-sandbox-providers-opensandbox-provider-OpenSandboxOperationConfig)                 | Retry and timeout settings for SDK operations after create.          |
| [`OpenSandboxProbeConfig`](#nemo_gym-sandbox-providers-opensandbox-provider-OpenSandboxProbeConfig)                         | Post-create probe settings.                                          |
| [`OpenSandboxProvider`](#nemo_gym-sandbox-providers-opensandbox-provider-OpenSandboxProvider)                               | Provider backed by the OpenSandbox SDK/server API.                   |

### Functions

| Name                                                                                                                      | Description                                                   |
| ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| [`_coerce_config`](#nemo_gym-sandbox-providers-opensandbox-provider-_coerce_config)                                       | -                                                             |
| [`_exception_status_code`](#nemo_gym-sandbox-providers-opensandbox-provider-_exception_status_code)                       | -                                                             |
| [`_has_retryable_error_marker`](#nemo_gym-sandbox-providers-opensandbox-provider-_has_retryable_error_marker)             | -                                                             |
| [`_is_missing_sandbox_delete_error`](#nemo_gym-sandbox-providers-opensandbox-provider-_is_missing_sandbox_delete_error)   | -                                                             |
| [`_is_retryable_create_error`](#nemo_gym-sandbox-providers-opensandbox-provider-_is_retryable_create_error)               | Return whether a sandbox create failure is likely transient.  |
| [`_is_retryable_sdk_operation_error`](#nemo_gym-sandbox-providers-opensandbox-provider-_is_retryable_sdk_operation_error) | Return whether an SDK operation can be retried.               |
| [`_log_create_retry`](#nemo_gym-sandbox-providers-opensandbox-provider-_log_create_retry)                                 | -                                                             |
| [`_log_operation_retry`](#nemo_gym-sandbox-providers-opensandbox-provider-_log_operation_retry)                           | -                                                             |
| [`_metadata_map`](#nemo_gym-sandbox-providers-opensandbox-provider-_metadata_map)                                         | -                                                             |
| [`_metadata_value`](#nemo_gym-sandbox-providers-opensandbox-provider-_metadata_value)                                     | -                                                             |
| [`_normalize_spec`](#nemo_gym-sandbox-providers-opensandbox-provider-_normalize_spec)                                     | -                                                             |
| [`_provider_option_bool`](#nemo_gym-sandbox-providers-opensandbox-provider-_provider_option_bool)                         | -                                                             |
| [`_require_opensandbox_sdk`](#nemo_gym-sandbox-providers-opensandbox-provider-_require_opensandbox_sdk)                   | -                                                             |
| [`_require_tenacity`](#nemo_gym-sandbox-providers-opensandbox-provider-_require_tenacity)                                 | -                                                             |
| [`_resource_map`](#nemo_gym-sandbox-providers-opensandbox-provider-_resource_map)                                         | -                                                             |
| [`_resource_quantity`](#nemo_gym-sandbox-providers-opensandbox-provider-_resource_quantity)                               | -                                                             |
| [`_sdk_error_attributes`](#nemo_gym-sandbox-providers-opensandbox-provider-_sdk_error_attributes)                         | -                                                             |
| [`_spec_extensions`](#nemo_gym-sandbox-providers-opensandbox-provider-_spec_extensions)                                   | -                                                             |
| [`_spec_volumes`](#nemo_gym-sandbox-providers-opensandbox-provider-_spec_volumes)                                         | -                                                             |
| [`_string_map`](#nemo_gym-sandbox-providers-opensandbox-provider-_string_map)                                             | -                                                             |
| [`_to_platform_spec`](#nemo_gym-sandbox-providers-opensandbox-provider-_to_platform_spec)                                 | -                                                             |
| [`_to_sandbox_status`](#nemo_gym-sandbox-providers-opensandbox-provider-_to_sandbox_status)                               | -                                                             |
| [`_to_volumes`](#nemo_gym-sandbox-providers-opensandbox-provider-_to_volumes)                                             | -                                                             |
| [`validate_image_pull_policy`](#nemo_gym-sandbox-providers-opensandbox-provider-validate_image_pull_policy)               | Validate a Kubernetes-compatible container image pull policy. |

### Data

[`DEFAULT_IMAGE_PULL_POLICY`](#nemo_gym-sandbox-providers-opensandbox-provider-DEFAULT_IMAGE_PULL_POLICY)

[`IMAGE_PULL_POLICY_ANNOTATION_EXTENSION_KEY`](#nemo_gym-sandbox-providers-opensandbox-provider-IMAGE_PULL_POLICY_ANNOTATION_EXTENSION_KEY)

[`IMAGE_PULL_POLICY_EXTENSION_KEY`](#nemo_gym-sandbox-providers-opensandbox-provider-IMAGE_PULL_POLICY_EXTENSION_KEY)

[`LOGGER`](#nemo_gym-sandbox-providers-opensandbox-provider-LOGGER)

[`METADATA_VALUE_RE`](#nemo_gym-sandbox-providers-opensandbox-provider-METADATA_VALUE_RE)

[`PROVIDER_OPTION_PLATFORM`](#nemo_gym-sandbox-providers-opensandbox-provider-PROVIDER_OPTION_PLATFORM)

[`PROVIDER_OPTION_SKIP_HEALTH_CHECK`](#nemo_gym-sandbox-providers-opensandbox-provider-PROVIDER_OPTION_SKIP_HEALTH_CHECK)

[`PROVIDER_OPTION_SNAPSHOT_ID`](#nemo_gym-sandbox-providers-opensandbox-provider-PROVIDER_OPTION_SNAPSHOT_ID)

[`PROVIDER_OPTION_VOLUMES`](#nemo_gym-sandbox-providers-opensandbox-provider-PROVIDER_OPTION_VOLUMES)

[`RETRYABLE_ERROR_MARKERS`](#nemo_gym-sandbox-providers-opensandbox-provider-RETRYABLE_ERROR_MARKERS)

[`RETRYABLE_HTTP_STATUS_CODES`](#nemo_gym-sandbox-providers-opensandbox-provider-RETRYABLE_HTTP_STATUS_CODES)

[`STATUS_CODE_RE`](#nemo_gym-sandbox-providers-opensandbox-provider-STATUS_CODE_RE)

[`VALID_IMAGE_PULL_POLICIES`](#nemo_gym-sandbox-providers-opensandbox-provider-VALID_IMAGE_PULL_POLICIES)

### API

```python
class nemo_gym.sandbox.providers.opensandbox.provider.OpenSandboxConnectionConfig(
    domain: str | None = None,
    api_key: str | None = None,
    protocol: str | None = None,
    request_timeout_s: int | None = None,
    use_server_proxy: bool = False
)
```

Dataclass

OpenSandbox server connection settings.

```python
class nemo_gym.sandbox.providers.opensandbox.provider.OpenSandboxCreateConfig(
    request_timeout_s: int | None = None,
    timeout_s: float | None = None,
    retries: int = 2,
    retry_delay_s: float = 5.0,
    retry_max_delay_s: float = 60.0,
    image_pull_policy: str | None = DEFAULT_IMAGE_PULL_POLICY,
    skip_health_check: bool = False,
    connect_attempt_timeout_s: float = 30.0,
    connect_poll_s: float = 2.0
)
```

Dataclass

OpenSandbox create/reconnect retry settings.

```python
nemo_gym.sandbox.providers.opensandbox.provider.OpenSandboxCreateConfig.__post_init__() -> None
```

```python
class nemo_gym.sandbox.providers.opensandbox.provider.OpenSandboxCreateError()
```

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

Raised when OpenSandbox cannot create a sandbox.

```python
class nemo_gym.sandbox.providers.opensandbox.provider.OpenSandboxCreateTimeoutError()
```

**Bases:** [OpenSandboxCreateError](#nemo_gym-sandbox-providers-opensandbox-provider-OpenSandboxCreateError)

Raised when OpenSandbox sandbox creation exceeds the client timeout.

```python
class nemo_gym.sandbox.providers.opensandbox.provider.OpenSandboxCreateVerificationError()
```

**Bases:** [SandboxCreateVerificationError](/nemo-gym/nemo_gym/sandbox/providers/base#nemo_gym-sandbox-providers-base-SandboxCreateVerificationError)

Raised when a newly-created sandbox cannot execute a probe command.

```python
class nemo_gym.sandbox.providers.opensandbox.provider.OpenSandboxOperationConfig(
    retries: int = 3,
    retry_delay_s: float = 1.0,
    retry_max_delay_s: float = 15.0,
    command_retries: int = 0,
    close_timeout_s: float | None = 30.0
)
```

Dataclass

Retry and timeout settings for SDK operations after create.

```python
nemo_gym.sandbox.providers.opensandbox.provider.OpenSandboxOperationConfig.__post_init__() -> None
```

```python
class nemo_gym.sandbox.providers.opensandbox.provider.OpenSandboxProbeConfig(
    command: str | None = 'printf nemo-gym-sandbox-re...,
    expected_stdout: str | None = 'nemo-gym-sandbox-ready',
    timeout_s: int = 30,
    deadline_s: float | None = None,
    stable_count: int = 1,
    stable_delay_s: float = 0.0
)
```

Dataclass

Post-create probe settings.

```python
nemo_gym.sandbox.providers.opensandbox.provider.OpenSandboxProbeConfig.__post_init__() -> None
```

```python
class nemo_gym.sandbox.providers.opensandbox.provider.OpenSandboxProvider(
    connection: nemo_gym.sandbox.providers.opensandbox.provider.OpenSandboxConnectionConfig | collections.abc.Mapping[str, typing.Any] | None = None,
    create: nemo_gym.sandbox.providers.opensandbox.provider.OpenSandboxCreateConfig | collections.abc.Mapping[str, typing.Any] | None = None,
    probe: nemo_gym.sandbox.providers.opensandbox.provider.OpenSandboxProbeConfig | collections.abc.Mapping[str, typing.Any] | None = None,
    operations: nemo_gym.sandbox.providers.opensandbox.provider.OpenSandboxOperationConfig | collections.abc.Mapping[str, typing.Any] | None = None
)
```

Provider backed by the OpenSandbox SDK/server API.

```python
nemo_gym.sandbox.providers.opensandbox.provider.OpenSandboxProvider._await_sdk_call(
    awaitable: typing.Any,
    operation: str,
    sandbox_id: str,
    timeout_s: float | None
) -> typing.Any
```

async

```python
nemo_gym.sandbox.providers.opensandbox.provider.OpenSandboxProvider._await_sdk_operation(
    operation_factory: typing.Callable[[], typing.Awaitable[typing.Any]],
    operation: str,
    sandbox_id: str,
    timeout_s: float | None,
    retries: int | None = None
) -> typing.Any
```

async

```python
nemo_gym.sandbox.providers.opensandbox.provider.OpenSandboxProvider._cleanup_failed_create_handle(
    handle: nemo_gym.sandbox.providers.base.SandboxHandle
) -> None
```

async

```python
nemo_gym.sandbox.providers.opensandbox.provider.OpenSandboxProvider._command_retry_count() -> int
```

```python
nemo_gym.sandbox.providers.opensandbox.provider.OpenSandboxProvider._connect_after_create(
    handle: nemo_gym.sandbox.providers.base.SandboxHandle,
    spec: nemo_gym.sandbox.providers.base.SandboxSpec
) -> nemo_gym.sandbox.providers.base.SandboxHandle
```

async

Reconnect after SDK create so follow-up calls use a fresh SDK handle.

```python
nemo_gym.sandbox.providers.opensandbox.provider.OpenSandboxProvider._connection_config(
    request_timeout_s: int | float | None = None
) -> typing.Any
```

```python
nemo_gym.sandbox.providers.opensandbox.provider.OpenSandboxProvider._create_once(
    spec: nemo_gym.sandbox.providers.base.SandboxSpec
) -> nemo_gym.sandbox.providers.base.SandboxHandle
```

async

Create a sandbox through `opensandbox.Sandbox.create`.

```python
nemo_gym.sandbox.providers.opensandbox.provider.OpenSandboxProvider._create_with_retries(
    spec: nemo_gym.sandbox.providers.base.SandboxSpec
) -> nemo_gym.sandbox.providers.base.SandboxHandle
```

async

```python
nemo_gym.sandbox.providers.opensandbox.provider.OpenSandboxProvider._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,
    retries: int | None = None
) -> nemo_gym.sandbox.providers.base.SandboxExecResult
```

async

Run a command inside an OpenSandbox sandbox.

```python
nemo_gym.sandbox.providers.opensandbox.provider.OpenSandboxProvider._read_file(
    handle: nemo_gym.sandbox.providers.base.SandboxHandle,
    source_path: str
) -> bytes
```

async

Read one file from an OpenSandbox sandbox.

```python
nemo_gym.sandbox.providers.opensandbox.provider.OpenSandboxProvider._verify_created_handle(
    handle: nemo_gym.sandbox.providers.base.SandboxHandle
) -> None
```

async

```python
nemo_gym.sandbox.providers.opensandbox.provider.OpenSandboxProvider._with_default_image_pull_policy(
    spec: nemo_gym.sandbox.providers.base.SandboxSpec
) -> nemo_gym.sandbox.providers.base.SandboxSpec
```

Ensure SDK create requests carry the desired image pull policy.

```python
nemo_gym.sandbox.providers.opensandbox.provider.OpenSandboxProvider._write_file(
    handle: nemo_gym.sandbox.providers.base.SandboxHandle,
    target_path: str,
    data: str | bytes
) -> None
```

async

Write one file into an OpenSandbox sandbox.

```python
nemo_gym.sandbox.providers.opensandbox.provider.OpenSandboxProvider.aclose() -> None
```

async

Close provider-owned resources.

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

async

Terminate the sandbox and close local SDK resources.

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

async

Create one sandbox through the configured OpenSandbox path.

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

async

Download one file from an OpenSandbox sandbox.

```python
nemo_gym.sandbox.providers.opensandbox.provider.OpenSandboxProvider.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 an OpenSandbox sandbox.

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

async

Return the current OpenSandbox lifecycle status.

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

async

Upload one local file into an OpenSandbox sandbox.

```python
nemo_gym.sandbox.providers.opensandbox.provider._coerce_config(
    value: typing.Any,
    config_cls: type[typing.Any]
) -> typing.Any
```

```python
nemo_gym.sandbox.providers.opensandbox.provider._exception_status_code(
    exception: BaseException
) -> int | None
```

```python
nemo_gym.sandbox.providers.opensandbox.provider._has_retryable_error_marker(
    exception: BaseException
) -> bool
```

```python
nemo_gym.sandbox.providers.opensandbox.provider._is_missing_sandbox_delete_error(
    exception: BaseException
) -> bool
```

```python
nemo_gym.sandbox.providers.opensandbox.provider._is_retryable_create_error(
    exception: BaseException
) -> bool
```

Return whether a sandbox create failure is likely transient.

```python
nemo_gym.sandbox.providers.opensandbox.provider._is_retryable_sdk_operation_error(
    exception: BaseException,
    seen: set[int] | None = None
) -> bool
```

Return whether an SDK operation can be retried.

```python
nemo_gym.sandbox.providers.opensandbox.provider._log_create_retry(
    retry_state: typing.Any
) -> None
```

```python
nemo_gym.sandbox.providers.opensandbox.provider._log_operation_retry(
    retry_state: typing.Any
) -> None
```

```python
nemo_gym.sandbox.providers.opensandbox.provider._metadata_map(
    values: dict[str, typing.Any]
) -> dict[str, str]
```

```python
nemo_gym.sandbox.providers.opensandbox.provider._metadata_value(
    value: typing.Any
) -> str
```

```python
nemo_gym.sandbox.providers.opensandbox.provider._normalize_spec(
    spec: nemo_gym.sandbox.providers.base.SandboxSpec
) -> nemo_gym.sandbox.providers.base.SandboxSpec
```

```python
nemo_gym.sandbox.providers.opensandbox.provider._provider_option_bool(
    provider_options: dict[str, typing.Any],
    key: str
) -> bool | None
```

```python
nemo_gym.sandbox.providers.opensandbox.provider._require_opensandbox_sdk() -> tuple[typing.Any, typing.Any, typing.Any, typing.Any, typing.Any]
```

```python
nemo_gym.sandbox.providers.opensandbox.provider._require_tenacity() -> tuple[typing.Any, typing.Any, typing.Any, typing.Any]
```

```python
nemo_gym.sandbox.providers.opensandbox.provider._resource_map(
    resources: nemo_gym.sandbox.providers.base.SandboxResources
) -> dict[str, str]
```

```python
nemo_gym.sandbox.providers.opensandbox.provider._resource_quantity(
    value: float | int
) -> str
```

```python
nemo_gym.sandbox.providers.opensandbox.provider._sdk_error_attributes(
    exception: BaseException,
    operation: str,
    sandbox_id: str,
    attempt_number: int | None = None,
    max_attempts: int | None = None,
    sleep_s: float | None = None
) -> dict[str, typing.Any]
```

```python
nemo_gym.sandbox.providers.opensandbox.provider._spec_extensions(
    spec: nemo_gym.sandbox.providers.base.SandboxSpec
) -> dict[str, str]
```

```python
nemo_gym.sandbox.providers.opensandbox.provider._spec_volumes(
    spec: nemo_gym.sandbox.providers.base.SandboxSpec
) -> list[collections.abc.Mapping[str, typing.Any]] | None
```

```python
nemo_gym.sandbox.providers.opensandbox.provider._string_map(
    values: collections.abc.Mapping[str, typing.Any]
) -> dict[str, str]
```

```python
nemo_gym.sandbox.providers.opensandbox.provider._to_platform_spec(
    platform: dict[str, typing.Any]
) -> typing.Any
```

```python
nemo_gym.sandbox.providers.opensandbox.provider._to_sandbox_status(
    state: typing.Any
) -> nemo_gym.sandbox.providers.base.SandboxStatus
```

```python
nemo_gym.sandbox.providers.opensandbox.provider._to_volumes(
    volumes: list[collections.abc.Mapping[str, typing.Any]]
) -> list[typing.Any]
```

```python
nemo_gym.sandbox.providers.opensandbox.provider.validate_image_pull_policy(
    image_pull_policy: str
) -> str
```

Validate a Kubernetes-compatible container image pull policy.

```python
nemo_gym.sandbox.providers.opensandbox.provider.DEFAULT_IMAGE_PULL_POLICY = 'IfNotPresent'
```

```python
nemo_gym.sandbox.providers.opensandbox.provider.IMAGE_PULL_POLICY_ANNOTATION_EXTENSION_KEY = 'opensandbox.extensions.image-pull-policy'
```

```python
nemo_gym.sandbox.providers.opensandbox.provider.IMAGE_PULL_POLICY_EXTENSION_KEY = 'imagePullPolicy'
```

```python
nemo_gym.sandbox.providers.opensandbox.provider.LOGGER = logging.getLogger(__name__)
```

```python
nemo_gym.sandbox.providers.opensandbox.provider.METADATA_VALUE_RE = re.compile('[^A-Za-z0-9_.-]+')
```

```python
nemo_gym.sandbox.providers.opensandbox.provider.PROVIDER_OPTION_PLATFORM = 'platform'
```

```python
nemo_gym.sandbox.providers.opensandbox.provider.PROVIDER_OPTION_SKIP_HEALTH_CHECK = 'skip_health_check'
```

```python
nemo_gym.sandbox.providers.opensandbox.provider.PROVIDER_OPTION_SNAPSHOT_ID = 'snapshot_id'
```

```python
nemo_gym.sandbox.providers.opensandbox.provider.PROVIDER_OPTION_VOLUMES = 'volumes'
```

```python
nemo_gym.sandbox.providers.opensandbox.provider.RETRYABLE_ERROR_MARKERS = ('all connection attempts failed', 'connection refused', 'connection reset', 'ga...
```

```python
nemo_gym.sandbox.providers.opensandbox.provider.RETRYABLE_HTTP_STATUS_CODES = {408, 409, 425, 429, 500, 502, 503, 504}
```

```python
nemo_gym.sandbox.providers.opensandbox.provider.STATUS_CODE_RE = re.compile('(?:status code|http)\\D+(\\d{3})', re.IGNORECASE)
```

```python
nemo_gym.sandbox.providers.opensandbox.provider.VALID_IMAGE_PULL_POLICIES = {'Always', 'IfNotPresent', 'Never'}
```