> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/nemo/gym/main/nemo-gym/nemo_gym/sandbox/providers/llms.txt. # nemo_gym.sandbox.providers Sandbox provider registry. ## Subpackages * **[`nemo_gym.sandbox.providers.apptainer`](/nemo/gym/nemo-gym/nemo_gym/sandbox/providers/apptainer)** * **[`nemo_gym.sandbox.providers.daytona`](/nemo/gym/nemo-gym/nemo_gym/sandbox/providers/daytona)** * **[`nemo_gym.sandbox.providers.docker`](/nemo/gym/nemo-gym/nemo_gym/sandbox/providers/docker)** * **[`nemo_gym.sandbox.providers.e2b`](/nemo/gym/nemo-gym/nemo_gym/sandbox/providers/e2b)** * **[`nemo_gym.sandbox.providers.ecs_fargate`](/nemo/gym/nemo-gym/nemo_gym/sandbox/providers/ecs_fargate)** * **[`nemo_gym.sandbox.providers.enroot`](/nemo/gym/nemo-gym/nemo_gym/sandbox/providers/enroot)** * **[`nemo_gym.sandbox.providers.local`](/nemo/gym/nemo-gym/nemo_gym/sandbox/providers/local)** * **[`nemo_gym.sandbox.providers.opensandbox`](/nemo/gym/nemo-gym/nemo_gym/sandbox/providers/opensandbox)** * **[`nemo_gym.sandbox.providers.openshell`](/nemo/gym/nemo-gym/nemo_gym/sandbox/providers/openshell)** ## Submodules * **[`nemo_gym.sandbox.providers.base`](/nemo/gym/nemo-gym/nemo_gym/sandbox/providers/base)** * **[`nemo_gym.sandbox.providers.registry`](/nemo/gym/nemo-gym/nemo_gym/sandbox/providers/registry)** * **[`nemo_gym.sandbox.providers.utils`](/nemo/gym/nemo-gym/nemo_gym/sandbox/providers/utils)** ## Package Contents ### Classes | Name | Description | | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | [`ConnectableProvider`](#nemo_gym-sandbox-providers-base-ConnectableProvider) | Optional capability: rebuild a handle in another process from a descriptor. | | [`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. | | [`SandboxEndpoint`](#nemo_gym-sandbox-providers-base-SandboxEndpoint) | Provider-neutral route to a long-lived service inside a sandbox. | | [`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. | | [`SandboxPtyError`](#nemo_gym-sandbox-providers-base-SandboxPtyError) | Raised when a PTY session fails outside normal process exit. | | [`SandboxPtySession`](#nemo_gym-sandbox-providers-base-SandboxPtySession) | One live interactive terminal. Async context manager; exit closes it. | | [`SandboxPtySpec`](#nemo_gym-sandbox-providers-base-SandboxPtySpec) | Interactive PTY session request. | | [`SandboxResources`](#nemo_gym-sandbox-providers-base-SandboxResources) | Provider-neutral creation request, retaining integer memory/disk inputs. | | [`SandboxSidecarSpec`](#nemo_gym-sandbox-providers-base-SandboxSidecarSpec) | An extra container started with the sandbox from its own image. | | [`SandboxSnapshotError`](#nemo_gym-sandbox-providers-base-SandboxSnapshotError) | Raised when a provider cannot complete an operation on a snapshot; `snapshot_id` names it when known. | | [`SandboxSnapshotFailedError`](#nemo_gym-sandbox-providers-base-SandboxSnapshotFailedError) | Raised when a snapshot failed on the provider or did not become ready in time; it cannot create sandboxes. | | [`SandboxSnapshotInUseError`](#nemo_gym-sandbox-providers-base-SandboxSnapshotInUseError) | Raised when a provider refuses to delete a snapshot because something still uses it. | | [`SandboxSnapshotInfo`](#nemo_gym-sandbox-providers-base-SandboxSnapshotInfo) | One snapshot in a provider's listing. | | [`SandboxSnapshotNotFoundError`](#nemo_gym-sandbox-providers-base-SandboxSnapshotNotFoundError) | Raised when a provider has no snapshot with the requested id. | | [`SandboxSpec`](#nemo_gym-sandbox-providers-base-SandboxSpec) | Sandbox creation request. | | [`SandboxStatus`](#nemo_gym-sandbox-providers-base-SandboxStatus) | Provider-neutral sandbox lifecycle status. | | [`SupportsSandboxBackgroundServices`](#nemo_gym-sandbox-providers-base-SupportsSandboxBackgroundServices) | Optional execution override for services needed by a later command. | | [`SupportsSandboxCheckpointPolling`](#nemo_gym-sandbox-providers-base-SupportsSandboxCheckpointPolling) | Optional scoped speed-up of command completion checks while a harness is stopped for a checkpoint. | | [`SupportsSandboxEndpoint`](#nemo_gym-sandbox-providers-base-SupportsSandboxEndpoint) | Optional provider capability for resolving declared service ports. | | [`SupportsSandboxIndependentUploads`](#nemo_gym-sandbox-providers-base-SupportsSandboxIndependentUploads) | Optional provider capability: a file upload never waits for capacity that running commands hold. | | [`SupportsSandboxNetwork`](#nemo_gym-sandbox-providers-base-SupportsSandboxNetwork) | Optional direct networking between sandboxes, preserving service ports. | | [`SupportsSandboxParkedPolling`](#nemo_gym-sandbox-providers-base-SupportsSandboxParkedPolling) | Optional scoped hold of command completion checks while a harness in the sandbox is paused for a checkpoint. | | [`SupportsSandboxPauseResume`](#nemo_gym-sandbox-providers-base-SupportsSandboxPauseResume) | Optional provider capability to pause and resume a sandbox. | | [`SupportsSandboxPortForwarding`](#nemo_gym-sandbox-providers-base-SupportsSandboxPortForwarding) | Optional loopback TCP forwarding, running until cancellation. | | [`SupportsSandboxPty`](#nemo_gym-sandbox-providers-base-SupportsSandboxPty) | Optional provider capability: interactive PTY sessions. | | [`SupportsSandboxPtyAttach`](#nemo_gym-sandbox-providers-base-SupportsSandboxPtyAttach) | Optional provider capability: re-attach to a PTY session by id. | | [`SupportsSandboxPullPolicy`](#nemo_gym-sandbox-providers-base-SupportsSandboxPullPolicy) | Optional per-sandbox image pull policy: `always`, `missing` or `never` (Compose's `pull_policy`). | | [`SupportsSandboxRuntimeRequirements`](#nemo_gym-sandbox-providers-base-SupportsSandboxRuntimeRequirements) | Optional validation and setup of task-declared runtime requirements. | | [`SupportsSandboxServiceOptions`](#nemo_gym-sandbox-providers-base-SupportsSandboxServiceOptions) | Optional container settings a Compose service declares: `tmpfs`, `ulimits`, `sysctls`, `security_opt`. | | [`SupportsSandboxSharedStorage`](#nemo_gym-sandbox-providers-base-SupportsSandboxSharedStorage) | Optional shared filesystem provisioned by the operator's provider config. | | [`SupportsSandboxSidecars`](#nemo_gym-sandbox-providers-base-SupportsSandboxSidecars) | Optional provider capability to run sidecar containers next to the sandbox. | | [`SupportsSandboxSnapshot`](#nemo_gym-sandbox-providers-base-SupportsSandboxSnapshot) | Optional provider capability to snapshot a running sandbox into a durable, independent copy. | ### Functions | Name | Description | | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | [`clamp_resource_requests`](#nemo_gym-sandbox-providers-base-clamp_resource_requests) | Cap each scheduling request at the limit the spec declares for the same key. | | [`create_provider`](#nemo_gym-sandbox-providers-registry-create_provider) | Instantiate a provider from a single-key provider config. | | [`get_provider_class`](#nemo_gym-sandbox-providers-registry-get_provider_class) | Return a provider class by name (explicit > built-in > entry point). | | [`list_providers`](#nemo_gym-sandbox-providers-registry-list_providers) | List available provider names from all sources. | | [`provider_service_option_fields`](#nemo_gym-sandbox-providers-registry-provider_service_option_fields) | The Compose service options (`tmpfs`, `ulimits`, `sysctls`, `security_opt`) provider `name` can apply. | | [`register_provider`](#nemo_gym-sandbox-providers-registry-register_provider) | Register a sandbox provider class. | ### Data [`ExecResult`](#nemo_gym-sandbox-providers-base-ExecResult) ### API ```python class nemo_gym.sandbox.providers.ConnectableProvider() ``` Protocol Optional capability: rebuild a handle in another process from a descriptor. Providers whose sandboxes are reachable by id (external control plane, e.g. OpenSandbox and Fargate, and the sandbox server's remote provider) implement this. A provider that does not implement it can only be shared by fronting it with a sandbox server. Membership is checked with `isinstance` because the protocol is `runtime_checkable`. ```python nemo_gym.sandbox.providers.ConnectableProvider.connect( descriptor: collections.abc.Mapping[str, typing.Any] ) -> nemo_gym.sandbox.providers.base.SandboxHandle ``` async Rebuild a live handle in this process from a descriptor. ```python nemo_gym.sandbox.providers.ConnectableProvider.serialize_handle( handle: nemo_gym.sandbox.providers.base.SandboxHandle, scope: str | None = None ) -> dict[str, typing.Any] ``` async Return a JSON-serializable descriptor that `connect` can rebuild a handle from. `scope` is honored by providers that mint leases (the remote provider) and ignored by the rest. ```python class nemo_gym.sandbox.providers.SandboxCreateError() ``` **Bases:** `RuntimeError` Raised when a provider cannot create a sandbox. ```python class nemo_gym.sandbox.providers.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.SandboxEndpoint( endpoint: str, headers: dict[str, str] = dict() ) ``` Dataclass Provider-neutral route to a long-lived service inside a sandbox. `endpoint` is an absolute URL. `headers` carries provider-required authentication or routing headers without exposing the provider's opaque handle to callers. **`endpoint`** `str` --- **`headers`** `dict[str, str] = field(default_factory=dict)` --- ```python nemo_gym.sandbox.providers.SandboxEndpoint.__post_init__() -> None ``` ```python class nemo_gym.sandbox.providers.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. `error_type="user_switch_unavailable"` means the provider confirmed that credential switching prevented process launch. Helpers that allow the image's default user can choose that branch without reporting a failure event. **`error_type`** `str | None = None` --- **`return_code`** `int` --- **`stderr`** `str | None` --- **`stdout`** `str | None` --- ```python class nemo_gym.sandbox.providers.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. **`provider_name`** `str` --- **`sandbox_id`** `str` --- ```python class nemo_gym.sandbox.providers.SandboxProvider() ``` Protocol Runtime/infra provider contract used by the public sandbox API. **`name`** `str` --- ```python nemo_gym.sandbox.providers.SandboxProvider.aclose() -> None ``` async Close provider-scoped resources such as SDK clients. ```python nemo_gym.sandbox.providers.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.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. New and migrated providers must report allocation and readiness failures as `NgFailureEvent` with `boundary="sandbox"` and a registered kind. Providers awaiting migration still expose creation exceptions; see the sandbox documentation's required provider migrations. ```python nemo_gym.sandbox.providers.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.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.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.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.SandboxPtyError() ``` **Bases:** `RuntimeError` Raised when a PTY session fails outside normal process exit. ```python class nemo_gym.sandbox.providers.SandboxPtySession() ``` Protocol One live interactive terminal. Async context manager; exit closes it. **`closed`** `bool` Whether `close()` has run; a closed session cannot run commands. --- **`mode`** `str | None` `"pty"` or `"pipe"` once connected, `None` before that. Only pipe mode splits stderr; in PTY mode all output arrives through `read()`. --- **`session_id`** `str` --- ```python nemo_gym.sandbox.providers.SandboxPtySession.__aenter__() -> nemo_gym.sandbox.providers.base.SandboxPtySession ``` async ```python nemo_gym.sandbox.providers.SandboxPtySession.__aexit__( exc_type: typing.Any, exc_val: typing.Any, exc_tb: typing.Any ) -> None ``` async ```python nemo_gym.sandbox.providers.SandboxPtySession.__aiter__() -> collections.abc.AsyncIterator[bytes] ``` Yield output chunks until EOF. ```python nemo_gym.sandbox.providers.SandboxPtySession.close() -> None ``` async Idempotent: release local resources; a session this client created is also ended, while an attached one is merely detached and lives on for its owner. ```python nemo_gym.sandbox.providers.SandboxPtySession.read( timeout_s: float | None = None ) -> bytes ``` async Return the next output chunk (all terminal output in PTY mode; stdout only in pipe mode). `b""` means the process exited and the stream is drained. Raises `TimeoutError` when this wait expires; that alone does not mean the command failed. Report session death as `NgFailureEvent`; providers awaiting migration use `SandboxPtyError`. ```python nemo_gym.sandbox.providers.SandboxPtySession.read_stderr( timeout_s: float | None = None ) -> bytes ``` async Return the next stderr chunk. Only pipe mode (`pty=False`) carries stderr separately; in PTY mode this stream is empty and returns `b""` once the process exits. Same timeout/error semantics as `read()`. ```python nemo_gym.sandbox.providers.SandboxPtySession.resize( rows: int, cols: int ) -> None ``` async Resize the terminal. ```python nemo_gym.sandbox.providers.SandboxPtySession.run_detached( command: str, poll_interval_s: float = 15.0 ) -> tuple[bytes, int | None] ``` async Run one command holding the transport only for brief completion polls; returns `(merged output, exit code or None)`. The server retains a bounded window of output between polls, and exceeding it raises rather than returning truncated output. ```python nemo_gym.sandbox.providers.SandboxPtySession.send_signal( signal: str ) -> None ``` async Deliver a named signal, e.g. `"SIGTERM"`, to the session's process group. Interactive shells run foreground jobs in their own group, so signals reliably reach the process only for command sessions; whether `SIGINT` interrupts at all also depends on the sandbox runtime's inherited signal dispositions. ```python nemo_gym.sandbox.providers.SandboxPtySession.wait_exit( timeout_s: float | None = None ) -> int ``` async Block until the process exits and return its exit code. Raises `TimeoutError` when this wait expires; that alone does not mean the command failed. Session failures follow the same contract as `read`. ```python nemo_gym.sandbox.providers.SandboxPtySession.write( data: bytes ) -> None ``` async Send raw bytes to the terminal's stdin. ```python class nemo_gym.sandbox.providers.SandboxPtySpec( command: str | None = None, cwd: str | None = None, env: dict[str, str] | None = None, rows: int = 24, cols: int = 80, user: str | int | None = None, pty: bool = True ) ``` Dataclass Interactive PTY session request. `command` runs under the backend's interactive shell; `None` spawns the shell itself. Backends without native env/user support may rewrite the command (mirroring `exec()`'s user rewrite) and must raise `ValueError` for values they cannot honor. `pty=False` selects pipe mode: no TTY, stdout and stderr delivered as separate streams, `rows`/`cols` ignored. Backends that cannot size a terminal at spawn apply `rows`/`cols` as soon as it connects, so a `command` reading the size immediately may observe the backend default. **`cols`** `int = 80` --- **`command`** `str | None = None` --- **`cwd`** `str | None = None` --- **`env`** `dict[str, str] | None = None` --- **`pty`** `bool = True` --- **`rows`** `int = 24` --- **`user`** `str | int | None = None` --- ```python class nemo_gym.sandbox.providers.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 **Bases:** [SandboxResourceAmounts](#nemo_gym-sandbox-providers-base-SandboxResourceAmounts) Provider-neutral creation request, retaining integer memory/disk inputs. **`disk_gib`** `int | None = None` --- **`memory_mib`** `int | None = None` --- ```python nemo_gym.sandbox.providers.SandboxResources.from_mapping( resources: collections.abc.Mapping[str, typing.Any] | None ) -> nemo_gym.sandbox.providers.base.SandboxResources ``` classmethod ```python class nemo_gym.sandbox.providers.SandboxSidecarSpec( name: str, image: str, env: dict[str, str] = dict(), resources: nemo_gym.sandbox.providers.base.SandboxResources | collections.abc.Mapping[str, typing.Any] = SandboxResources() ) ``` Dataclass An extra container started with the sandbox from its own image. The sidecar has its own filesystem. Start services in it with `AsyncSandbox.sidecar(name).exec`. How the sandbox reaches a sidecar over the network is provider-specific. **`env`** `dict[str, str] = field(default_factory=dict)` --- **`image`** `str` --- **`name`** `str` --- **`resources`** `SandboxResources | Mapping[str, Any] = field(default_factory=SandboxResources)` --- ```python nemo_gym.sandbox.providers.SandboxSidecarSpec.__post_init__() -> None ``` ```python class nemo_gym.sandbox.providers.SandboxSnapshotError( message: str, snapshot_id: str | None = None ) ``` **Bases:** `RuntimeError` Raised when a provider cannot complete an operation on a snapshot; `snapshot_id` names it when known. The base of every snapshot error, so `except SandboxSnapshotError` handles any snapshot failure. ```python class nemo_gym.sandbox.providers.SandboxSnapshotFailedError() ``` **Bases:** [SandboxSnapshotError](#nemo_gym-sandbox-providers-base-SandboxSnapshotError) Raised when a snapshot failed on the provider or did not become ready in time; it cannot create sandboxes. ```python class nemo_gym.sandbox.providers.SandboxSnapshotInUseError() ``` **Bases:** [SandboxSnapshotError](#nemo_gym-sandbox-providers-base-SandboxSnapshotError) Raised when a provider refuses to delete a snapshot because something still uses it. ```python class nemo_gym.sandbox.providers.SandboxSnapshotInfo( snapshot_id: str, name: str | None, state: str | None = None, sandbox_id: str | None = None ) ``` Dataclass One snapshot in a provider's listing. `name` is the name the snapshot was taken with, and `None` only for one taken without a name. `state` is the provider's own lifecycle word, lowercased, and `sandbox_id` the sandbox the snapshot was taken from; either is `None` when the provider does not report it. **`name`** `str | None` --- **`sandbox_id`** `str | None = None` --- **`snapshot_id`** `str` --- **`state`** `str | None = None` --- ```python class nemo_gym.sandbox.providers.SandboxSnapshotNotFoundError() ``` **Bases:** [SandboxSnapshotError](#nemo_gym-sandbox-providers-base-SandboxSnapshotError), `LookupError` Raised when a provider has no snapshot with the requested id. The snapshot may be deleted, or not yet visible on every replica of a snapshot store that is not fully shared. ```python class nemo_gym.sandbox.providers.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 | bytes] = 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(), ports: tuple[int, ...] | list[int] = tuple(), sidecars: tuple[nemo_gym.sandbox.providers.base.SandboxSidecarSpec, ...] | list[nemo_gym.sandbox.providers.base.SandboxSidecarSpec | collections.abc.Mapping[str, typing.Any]] = tuple(), user: str | int | None = None ) ``` Dataclass Sandbox creation request. **`entrypoint`** `list[str] | None = None` --- **`env`** `dict[str, str] = field(default_factory=dict)` --- **`files`** `dict[str, str | bytes] = field(default_factory=dict)` --- **`image`** `str | None = None` --- **`metadata`** `dict[str, str] = field(default_factory=dict)` --- **`ports`** `tuple[int, ...] | list[int] = field(default_factory=tuple)` --- **`provider_options`** `dict[str, Any] = field(default_factory=dict)` --- **`ready_timeout_s`** `int | float | None = None` --- **`resources`** `SandboxResources | Mapping[str, Any] = field(default_factory=SandboxResources)` --- **`sidecars`** `tuple[SandboxSidecarSpec, ...] | list[SandboxSidecarSpec | Mapping[str, Any]] = field(default_factory=tuple)` --- **`ttl_s`** `int | float | None = None` --- **`user`** `str | int | None = None` --- **`workdir`** `str | None = None` --- ```python nemo_gym.sandbox.providers.SandboxSpec.__post_init__() -> None ``` ```python class nemo_gym.sandbox.providers.SandboxStatus ``` **Bases:** `enum.Enum` Provider-neutral sandbox lifecycle status. **`ERROR`** `= 'error'` --- **`PAUSED`** `= 'paused'` --- **`RUNNING`** `= 'running'` --- **`STARTING`** `= 'starting'` --- **`STOPPED`** `= 'stopped'` --- **`UNKNOWN`** `= 'unknown'` --- ```python class nemo_gym.sandbox.providers.SupportsSandboxBackgroundServices() ``` Protocol Optional execution override for services needed by a later command. ```python nemo_gym.sandbox.providers.SupportsSandboxBackgroundServices.exec_with_background_services( 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 ```python class nemo_gym.sandbox.providers.SupportsSandboxCheckpointPolling() ``` Protocol Optional scoped speed-up of command completion checks while a harness is stopped for a checkpoint. ```python nemo_gym.sandbox.providers.SupportsSandboxCheckpointPolling.checkpoint_exec_polling( handle: nemo_gym.sandbox.providers.base.SandboxHandle ) -> contextlib.AbstractContextManager[None] ``` Wake pending command polls of the sandbox and poll them often until the scope exits. ```python class nemo_gym.sandbox.providers.SupportsSandboxEndpoint() ``` Protocol Optional provider capability for resolving declared service ports. ```python nemo_gym.sandbox.providers.SupportsSandboxEndpoint.endpoint( handle: nemo_gym.sandbox.providers.base.SandboxHandle, port: int ) -> nemo_gym.sandbox.providers.base.SandboxEndpoint ``` async Resolve a declared service port to a caller-reachable endpoint. ```python class nemo_gym.sandbox.providers.SupportsSandboxIndependentUploads() ``` Protocol Optional provider capability: a file upload never waits for capacity that running commands hold. A provider that bounds its concurrent operations with one limit shared by commands and file transfers (CLI slots, worker threads, pooled connections) cannot promise this: once long-running commands hold every slot, an upload waits until one of them ends. `SandboxSession.expire` needs it to stop a running harness, because the stop is a file the harness's supervisor watches for. The answer may depend on configuration. ```python nemo_gym.sandbox.providers.SupportsSandboxIndependentUploads.uploads_independent_of_execs() -> bool ``` ```python class nemo_gym.sandbox.providers.SupportsSandboxNetwork() ``` Protocol Optional direct networking between sandboxes, preserving service ports. ```python nemo_gym.sandbox.providers.SupportsSandboxNetwork.network_address( handle: nemo_gym.sandbox.providers.base.SandboxHandle ) -> str ``` async ```python nemo_gym.sandbox.providers.SupportsSandboxNetwork.set_hosts( handle: nemo_gym.sandbox.providers.base.SandboxHandle, hosts: collections.abc.Mapping[str, str] ) -> None ``` async ```python nemo_gym.sandbox.providers.SupportsSandboxNetwork.validate_networking() -> None ``` ```python class nemo_gym.sandbox.providers.SupportsSandboxParkedPolling() ``` Protocol Optional scoped hold of command completion checks while a harness in the sandbox is paused for a checkpoint. ```python nemo_gym.sandbox.providers.SupportsSandboxParkedPolling.parked_exec_polling( handle: nemo_gym.sandbox.providers.base.SandboxHandle ) -> contextlib.AbstractContextManager[None] ``` Hold pending command polls of the sandbox without asking it, and ask again once the scope exits. ```python class nemo_gym.sandbox.providers.SupportsSandboxPauseResume() ``` Protocol Optional provider capability to pause and resume a sandbox. What survives a pause beyond the filesystem is backend-specific. ```python nemo_gym.sandbox.providers.SupportsSandboxPauseResume.pause( handle: nemo_gym.sandbox.providers.base.SandboxHandle ) -> None ``` async Pause a sandbox while preserving its state. ```python nemo_gym.sandbox.providers.SupportsSandboxPauseResume.resume( handle: nemo_gym.sandbox.providers.base.SandboxHandle ) -> None ``` async Resume a paused sandbox and refresh its handle. ```python class nemo_gym.sandbox.providers.SupportsSandboxPortForwarding() ``` Protocol Optional loopback TCP forwarding, running until cancellation. ```python nemo_gym.sandbox.providers.SupportsSandboxPortForwarding.forward_ports( handle: nemo_gym.sandbox.providers.base.SandboxHandle, target_address: str, ports: tuple[int, ...], ready_file: str ) -> None ``` async ```python nemo_gym.sandbox.providers.SupportsSandboxPortForwarding.validate_port_forwarding() -> None ``` ```python class nemo_gym.sandbox.providers.SupportsSandboxPty() ``` Protocol Optional provider capability: interactive PTY sessions. ```python nemo_gym.sandbox.providers.SupportsSandboxPty.create_pty( handle: nemo_gym.sandbox.providers.base.SandboxHandle, spec: nemo_gym.sandbox.providers.base.SandboxPtySpec ) -> nemo_gym.sandbox.providers.base.SandboxPtySession ``` async Open an interactive terminal inside a sandbox. ```python class nemo_gym.sandbox.providers.SupportsSandboxPtyAttach() ``` Protocol Optional provider capability: re-attach to a PTY session by id. Separate from `SupportsSandboxPty` because it requires sessions that live in the sandbox rather than in the client, so a provider may offer terminals without offering re-attach. ```python nemo_gym.sandbox.providers.SupportsSandboxPtyAttach.attach_pty( handle: nemo_gym.sandbox.providers.base.SandboxHandle, session_id: str, takeover: bool = True, since: int | None = None ) -> nemo_gym.sandbox.providers.base.SandboxPtySession ``` async Re-attach to an existing session by id. `takeover` evicts the current holder, whose session then fails with `SandboxPtyError`; without it, attaching to a held session fails. `since` is a byte offset into the session's retained output to replay before live output (`0` replays everything still retained). ```python class nemo_gym.sandbox.providers.SupportsSandboxPullPolicy() ``` Protocol Optional per-sandbox image pull policy: `always`, `missing` or `never` (Compose's `pull_policy`). `pull_policy_options` returns the `provider_options` that apply it at create time. A provider without this capability leaves the pull behaviour to the deployment's default. ```python nemo_gym.sandbox.providers.SupportsSandboxPullPolicy.pull_policy_options( policy: str ) -> dict[str, typing.Any] ``` ```python class nemo_gym.sandbox.providers.SupportsSandboxRuntimeRequirements() ``` Protocol Optional validation and setup of task-declared runtime requirements. ```python nemo_gym.sandbox.providers.SupportsSandboxRuntimeRequirements.configure_runtime( handle: nemo_gym.sandbox.providers.base.SandboxHandle, cap_add: tuple[str, ...], shm_size: int | None ) -> None ``` async ```python nemo_gym.sandbox.providers.SupportsSandboxRuntimeRequirements.validate_runtime_requirements( cap_add: tuple[str, ...], shm_size: int | None ) -> dict[str, str] | None ``` Validate support and return any required create-time metadata. ```python class nemo_gym.sandbox.providers.SupportsSandboxServiceOptions() ``` Protocol Optional container settings a Compose service declares: `tmpfs`, `ulimits`, `sysctls`, `security_opt`. `SERVICE_OPTION_FIELDS` names the subset the provider can apply; it is a class attribute so prepare can check a task against a provider by name, without instantiating it. `service_options` returns the `provider_options` that apply the given values at create time (an empty mapping when none are given) and raises `ValueError` for a value it cannot express. **`SERVICE_OPTION_FIELDS`** `frozenset[str]` --- ```python nemo_gym.sandbox.providers.SupportsSandboxServiceOptions.service_options( tmpfs: tuple[str, ...] = (), ulimits: collections.abc.Mapping[str, typing.Any] | None = None, sysctls: collections.abc.Mapping[str, str] | None = None, security_opt: tuple[str, ...] = () ) -> dict[str, typing.Any] ``` ```python class nemo_gym.sandbox.providers.SupportsSandboxSharedStorage() ``` Protocol Optional shared filesystem provisioned by the operator's provider config. `shared_volume_options` returns provider options containing a `volumes` list of opaque mount descriptors. Collections concatenate these lists. `source` is relative to the configured shared root; `None` mounts that root for initialization and cleanup. Metadata supplies placement settings. ```python nemo_gym.sandbox.providers.SupportsSandboxSharedStorage.shared_volume_metadata() -> dict[str, str] ``` ```python nemo_gym.sandbox.providers.SupportsSandboxSharedStorage.shared_volume_options( source: str | None, target: str, read_only: bool = False ) -> dict[str, typing.Any] ``` ```python class nemo_gym.sandbox.providers.SupportsSandboxSidecars() ``` Protocol Optional provider capability to run sidecar containers next to the sandbox. The provider creates the sidecars declared in `SandboxSpec.sidecars` together with the sandbox, then runs commands in them and reads files from them through these calls. Commands run as an argv without a shell, because sidecar images can be distroless. ```python nemo_gym.sandbox.providers.SupportsSandboxSidecars.download_sidecar_file( handle: nemo_gym.sandbox.providers.base.SandboxHandle, sidecar: str, source_path: str, target_path: pathlib.Path ) -> None ``` async Download one file from `sidecar` to the local filesystem. ```python nemo_gym.sandbox.providers.SupportsSandboxSidecars.sidecar_exec( handle: nemo_gym.sandbox.providers.base.SandboxHandle, sidecar: str, argv: list[str], timeout_s: int | float, on_stdout: collections.abc.Callable[[str], None] | None = None ) -> nemo_gym.sandbox.providers.base.SandboxExecResult ``` async Run `argv` in `sidecar`; `on_stdout` receives stdout text as it arrives, for long-running services. ```python class nemo_gym.sandbox.providers.SupportsSandboxSnapshot() ``` Protocol Optional provider capability to snapshot a running sandbox into a durable, independent copy. A snapshot is a restore point: `create_from_snapshot` builds a new sandbox from it, however the source sandbox changed or ended since. Deleting the source sandbox leaves the snapshot; only `delete_snapshot` removes it. A provider must keep the name a snapshot is taken with and return it from `list_snapshots`. A caller finds its snapshots again by name: a sandbox checkpointer lists them by a name prefix to delete the ones it has no other record of, and those are never deleted on a provider that drops the name, with no error to show for it. ```python nemo_gym.sandbox.providers.SupportsSandboxSnapshot.create_from_snapshot( snapshot_id: str, spec: nemo_gym.sandbox.providers.base.SandboxSpec ) -> nemo_gym.sandbox.providers.base.SandboxHandle ``` async Create a sandbox from a snapshot in place of `spec`'s image, with the rest of `spec`. Raises `SandboxSnapshotNotFoundError` when the provider has no snapshot `snapshot_id`. ```python nemo_gym.sandbox.providers.SupportsSandboxSnapshot.delete_snapshot( snapshot_id: str ) -> None ``` async Delete a snapshot; a snapshot the provider confirms is already gone is not an error. Raises `SandboxSnapshotInUseError` when the provider refuses because something still uses the snapshot, and `SandboxSnapshotError` when the delete fails otherwise. ```python nemo_gym.sandbox.providers.SupportsSandboxSnapshot.list_snapshots( prefix: str ) -> list[nemo_gym.sandbox.providers.base.SandboxSnapshotInfo] ``` async Every snapshot whose name starts with `prefix`, each with the name it was taken with. Raises `SandboxSnapshotError` if the listing fails; never returns a partial listing. ```python nemo_gym.sandbox.providers.SupportsSandboxSnapshot.snapshot( handle: nemo_gym.sandbox.providers.base.SandboxHandle, name: str | None = None ) -> str ``` async Start a snapshot of the sandbox and return its id at once; it may not be usable yet. `name`, when given, is stored with the snapshot and is the name `list_snapshots` matches and returns. ```python nemo_gym.sandbox.providers.SupportsSandboxSnapshot.wait_snapshot_ready( snapshot_id: str ) -> None ``` async Return once the snapshot can create sandboxes. Raises `SandboxSnapshotFailedError` when the snapshot failed or is not ready in time, and `SandboxSnapshotNotFoundError` when the provider has no snapshot `snapshot_id`. ```python nemo_gym.sandbox.providers.clamp_resource_requests( requests: collections.abc.Mapping[str, typing.Any] | nemo_gym.sandbox.providers.base.SandboxResources, limits: collections.abc.Mapping[str, typing.Any] | nemo_gym.sandbox.providers.base.SandboxResources ) -> tuple[dict[str, typing.Any], dict[str, tuple[typing.Any, typing.Any]]] ``` Cap each scheduling request at the limit the spec declares for the same key. Kubernetes never schedules a pod whose request exceeds its limit, and OpenSandbox reports such a sandbox only as "pending allocation", so a request above a task's declared limit must not reach the create call. Returns the requests with the offending keys set to their limit, and `{key: (request, limit)}` for the keys that changed so the caller can log a warning naming them. Keys the limits do not declare pass through untouched. ```python nemo_gym.sandbox.providers.create_provider( config: collections.abc.Mapping[str, typing.Any] ) -> nemo_gym.sandbox.providers.base.SandboxProvider ``` Instantiate a provider from a single-key provider config. ```python nemo_gym.sandbox.providers.get_provider_class( name: str ) -> nemo_gym.sandbox.providers.registry.ProviderClass ``` Return a provider class by name (explicit > built-in > entry point). ```python nemo_gym.sandbox.providers.list_providers() -> list[str] ``` List available provider names from all sources. ```python nemo_gym.sandbox.providers.provider_service_option_fields( name: str ) -> frozenset[str] ``` The Compose service options (`tmpfs`, `ulimits`, `sysctls`, `security_opt`) provider `name` can apply. Read from the provider class's `SERVICE_OPTION_FIELDS` (see `SupportsSandboxServiceOptions`), so prepare can check a task against the deployment's provider without instantiating it. A provider without the attribute applies none of them. ```python nemo_gym.sandbox.providers.register_provider( name: str, provider_class: nemo_gym.sandbox.providers.registry.ProviderClass, override: bool = False ) -> None ``` Register a sandbox provider class. ```python nemo_gym.sandbox.providers.base.ExecResult = SandboxExecResult ``` ## Docs - [nemo_gym.sandbox.providers.apptainer](https://docs.nvidia.com/nemo/gym/main/nemo-gym/nemo_gym/sandbox/providers/apptainer.md) - [nemo_gym.sandbox.providers.apptainer.provider](https://docs.nvidia.com/nemo/gym/main/nemo-gym/nemo_gym/sandbox/providers/apptainer/provider.md) - [nemo_gym.sandbox.providers.base](https://docs.nvidia.com/nemo/gym/main/nemo-gym/nemo_gym/sandbox/providers/base.md) - [nemo_gym.sandbox.providers.daytona](https://docs.nvidia.com/nemo/gym/main/nemo-gym/nemo_gym/sandbox/providers/daytona.md) - [nemo_gym.sandbox.providers.daytona.provider](https://docs.nvidia.com/nemo/gym/main/nemo-gym/nemo_gym/sandbox/providers/daytona/provider.md) - [nemo_gym.sandbox.providers.docker](https://docs.nvidia.com/nemo/gym/main/nemo-gym/nemo_gym/sandbox/providers/docker.md) - [nemo_gym.sandbox.providers.docker.provider](https://docs.nvidia.com/nemo/gym/main/nemo-gym/nemo_gym/sandbox/providers/docker/provider.md) - [nemo_gym.sandbox.providers.docker.pty](https://docs.nvidia.com/nemo/gym/main/nemo-gym/nemo_gym/sandbox/providers/docker/pty.md) - [nemo_gym.sandbox.providers.e2b](https://docs.nvidia.com/nemo/gym/main/nemo-gym/nemo_gym/sandbox/providers/e2b.md) - [nemo_gym.sandbox.providers.e2b.build](https://docs.nvidia.com/nemo/gym/main/nemo-gym/nemo_gym/sandbox/providers/e2b/build.md) - [nemo_gym.sandbox.providers.e2b.provider](https://docs.nvidia.com/nemo/gym/main/nemo-gym/nemo_gym/sandbox/providers/e2b/provider.md) - [nemo_gym.sandbox.providers.ecs_fargate](https://docs.nvidia.com/nemo/gym/main/nemo-gym/nemo_gym/sandbox/providers/ecs_fargate.md) - [nemo_gym.sandbox.providers.ecs_fargate.engine](https://docs.nvidia.com/nemo/gym/main/nemo-gym/nemo_gym/sandbox/providers/ecs_fargate/engine.md) - [nemo_gym.sandbox.providers.ecs_fargate.provider](https://docs.nvidia.com/nemo/gym/main/nemo-gym/nemo_gym/sandbox/providers/ecs_fargate/provider.md) - [nemo_gym.sandbox.providers.enroot](https://docs.nvidia.com/nemo/gym/main/nemo-gym/nemo_gym/sandbox/providers/enroot.md) - [nemo_gym.sandbox.providers.enroot.provider](https://docs.nvidia.com/nemo/gym/main/nemo-gym/nemo_gym/sandbox/providers/enroot/provider.md) - [nemo_gym.sandbox.providers.local](https://docs.nvidia.com/nemo/gym/main/nemo-gym/nemo_gym/sandbox/providers/local.md) - [nemo_gym.sandbox.providers.local.provider](https://docs.nvidia.com/nemo/gym/main/nemo-gym/nemo_gym/sandbox/providers/local/provider.md) - [nemo_gym.sandbox.providers.opensandbox](https://docs.nvidia.com/nemo/gym/main/nemo-gym/nemo_gym/sandbox/providers/opensandbox.md) - [nemo_gym.sandbox.providers.opensandbox.cleanup_sandboxes](https://docs.nvidia.com/nemo/gym/main/nemo-gym/nemo_gym/sandbox/providers/opensandbox/cleanup_sandboxes.md) - [nemo_gym.sandbox.providers.opensandbox.failures](https://docs.nvidia.com/nemo/gym/main/nemo-gym/nemo_gym/sandbox/providers/opensandbox/failures.md) - [nemo_gym.sandbox.providers.opensandbox.provider](https://docs.nvidia.com/nemo/gym/main/nemo-gym/nemo_gym/sandbox/providers/opensandbox/provider.md) - [nemo_gym.sandbox.providers.opensandbox.pty](https://docs.nvidia.com/nemo/gym/main/nemo-gym/nemo_gym/sandbox/providers/opensandbox/pty.md) - [nemo_gym.sandbox.providers.opensandbox.resource_telemetry](https://docs.nvidia.com/nemo/gym/main/nemo-gym/nemo_gym/sandbox/providers/opensandbox/resource_telemetry.md) - [nemo_gym.sandbox.providers.opensandbox.snapshots](https://docs.nvidia.com/nemo/gym/main/nemo-gym/nemo_gym/sandbox/providers/opensandbox/snapshots.md) - [nemo_gym.sandbox.providers.openshell](https://docs.nvidia.com/nemo/gym/main/nemo-gym/nemo_gym/sandbox/providers/openshell.md) - [nemo_gym.sandbox.providers.openshell.provider](https://docs.nvidia.com/nemo/gym/main/nemo-gym/nemo_gym/sandbox/providers/openshell/provider.md) - [nemo_gym.sandbox.providers.registry](https://docs.nvidia.com/nemo/gym/main/nemo-gym/nemo_gym/sandbox/providers/registry.md) - [nemo_gym.sandbox.providers.utils](https://docs.nvidia.com/nemo/gym/main/nemo-gym/nemo_gym/sandbox/providers/utils.md)