nemo_gym.sandbox.providers.opensandbox.provider
nemo_gym.sandbox.providers.opensandbox.provider
OpenSandbox provider implementation.
Module Contents
Classes
Functions
Data
DEFAULT_ATTRIBUTION_KEY_PREFIX
IMAGE_PULL_POLICY_ANNOTATION_EXTENSION_KEY
IMAGE_PULL_POLICY_EXTENSION_KEY
API
Job attribution merged into every sandbox’s metadata (Kubernetes labels on the sandbox).
OpenSandbox propagates sandbox metadata as Kubernetes labels on the sandbox resources, so
attribution is queryable both through the OpenSandbox list API and at the cluster level
(e.g. kubectl get pods -l nemo-gym.nvidia.com/team=my-team). key_prefix namespaces
the label keys (Kubernetes prefixed-key convention); set it to "" for bare
team / user / workload / run keys.
Unset fields are auto-detected: NEMO_GYM_TEAM / NEMO_GYM_USER / NEMO_GYM_WORKLOAD
environment variables first, then Slurm job env vars (SLURM_JOB_ACCOUNT /
SLURM_JOB_USER / SLURM_JOB_NAME), then the OS login name for user (root is
ignored) and the gym CLI’s NEMO_GYM_CONFIG_PATH server instance name for workload.
Fields that cannot be resolved are omitted. run scopes sandboxes to one launch of the
creating process (NEMO_GYM_RUN_ID, else generated per process and logged) so a run’s
sandboxes can be listed and cleaned up exactly. Explicit SandboxSpec.metadata keys
always take precedence over attribution keys.
OpenSandbox server connection settings.
keepalive_expiry_s must stay below the server’s own keep-alive idle
timeout (uvicorn defaults to 5s), or pooled sockets are reused after the
server has closed them; null falls back to the SDK’s default transport.
transport_backend is “httpx” or “aiohttp” (via the optional
httpx-aiohttp bridge, falling back to httpx when it is absent).
The pool is shared, so max_connections also caps in-flight sandbox
operations per process; null means no cap.
OpenSandbox create/reconnect retry settings.
Bases: SandboxCreateError
Raised when OpenSandbox cannot create a sandbox.
Bases: OpenSandboxCreateError
Raised when OpenSandbox sandbox creation exceeds the client timeout.
Bases: SandboxCreateVerificationError
Raised when a newly-created sandbox cannot execute a probe command.
Retry and timeout settings for SDK operations after create.
Post-create probe settings.
Provider backed by the OpenSandbox SDK/server API.
Build the SDK transport with the configured pool limits.
Reconnect after SDK create so follow-up calls use a fresh SDK handle.
Create a sandbox through opensandbox.Sandbox.create.
Run a command inside an OpenSandbox sandbox.
Run a command as a background execution polled via short requests.
The logs endpoint returns one combined stream, so unlike the foreground
path stdout carries both streams and stderr is set only when the
sandbox itself reports an error.
Return the provider-owned shared transport, building it on first use.
Read one file from an OpenSandbox sandbox.
Add the configured default image pull policy to SDK create extensions.
Retry backend-connect 502s that command_retries deliberately skips.
A proxy 502 is a TCP-connect failure: the command never reached execd, so
retrying under operations.retries cannot double-run it (unlike a real
command failure). When that budget is exhausted the backend is dead, so
raise a typed error and fail fast instead of retrying for hours.
Write one file into an OpenSandbox sandbox.
Close provider-owned resources.
Terminate the sandbox and close local SDK resources.
Rebuild a live handle from an OpenSandbox sandbox id via the SDK.
Health-checks unless the caller opts out: a sandbox id only proves the workload exists, not that its exec daemon is listening yet, so an unchecked handle turns that gap into a 502 on the first call.
Create one sandbox through the configured OpenSandbox path.
Job attribution keys (team / user / workload / run) are merged into the
spec’s metadata (explicit spec keys win) so every sandbox is attributable via its labels.
Download one file from an OpenSandbox sandbox.
Run a command inside an OpenSandbox sandbox.
Return a descriptor for reattaching to this sandbox by id.
OpenSandbox sandboxes are reachable by id from any process that has the
connection config, so the id alone is enough to reconnect and no sandbox
server is needed to share one. scope is ignored: OpenSandbox has no
lease concept of its own.
Return the current OpenSandbox lifecycle status.
Upload one local file into an OpenSandbox sandbox.
Recognized per-sandbox create options read from SandboxSpec.provider_options.
image_auth, platform, and volumes entries are passed through to the
OpenSandbox SDK, so their inner fields are validated by the SDK rather than here.
Bases: RuntimeError
Raised when the server proxy cannot open a TCP connection to a sandbox’s exec daemon.
The proxy’s 502 is a connect failure, so the submitted command never started. Persistent 502s mean the backend is gone (e.g. the container was OOM-killed and sandbox pods never restart); retrying cannot revive it.
Return whether a sandbox create failure is likely transient.
Return whether an SDK operation can be retried.
Validate a Kubernetes-compatible container image pull policy.