OpenSandbox Provider

The opensandbox provider creates sandboxes through the OpenSandbox SDK and server API. It is the Kubernetes-backed provider used by agentic software engineering environments such as mini_swe_agent_2.

Setup

Install the sandbox extra in the runtime image or virtual environment that creates sandboxes:

$ uv sync --extra sandbox

For package installs, use:

$ pip install "nemo-gym[sandbox]"

Set connection values through the provider config. The shipped config reads these environment variables:

Variable	Purpose
`OPENSANDBOX_DOMAIN`	OpenSandbox server domain. Defaults to the in-cluster service name in the shipped config.
`OPENSANDBOX_API_KEY`	API key passed to the OpenSandbox SDK connection config.

Provider Config

NeMo Gym ships an OpenSandbox provider config at nemo_gym/sandbox/providers/opensandbox/configs/opensandbox.yaml. It defines a top-level sandbox block that agents reference with sandbox_provider: sandbox.

1 sandbox:
2   default_metadata:
3     sandbox-api: opensandbox-sdk
4   opensandbox:
5     connection:
6       domain: ${oc.env:OPENSANDBOX_DOMAIN,opensandbox-server.opensandbox-system.svc.cluster.local}
7       api_key: ${oc.env:OPENSANDBOX_API_KEY}
8       protocol: http
9       request_timeout_s: 300
10       use_server_proxy: true
11     create:
12       request_timeout_s: 1200
13       timeout_s: 1200
14       skip_health_check: true
15       retries: 10
16       retry_delay_s: 5.0
17       retry_max_delay_s: 90.0
18     probe:
19       timeout_s: 60
20       deadline_s: 180
21       stable_count: 2
22       stable_delay_s: 1.0
23     operations:
24       retries: 5
25       retry_delay_s: 1.0
26       retry_max_delay_s: 45.0
27       command_retries: 0
28       close_timeout_s: 30

Run an agent with the provider config by passing it alongside the agent and model configs:

$ gym env start \
>   --config responses_api_agents/mini_swe_agent_2/configs/mini_swe_agent_2.yaml \
>   --config nemo_gym/sandbox/providers/opensandbox/configs/opensandbox.yaml \
>   --config responses_api_models/vllm_model/configs/vllm_model.yaml

The provider constructor accepts four optional config sections:

Section	Purpose
`connection`	OpenSandbox SDK connection settings: domain, API key, protocol, request timeout, and server proxy mode.
`create`	Sandbox create timeout, retry, image pull policy, and health-check behavior.
`probe`	Post-create command probe used to verify command execution before the sandbox is returned.
`operations`	Retry and timeout behavior for SDK operations after create, including command retries and close timeout.

SandboxSpec Provider Options

Set OpenSandbox-specific create options under SandboxSpec.provider_options, or under sandbox_spec.provider_options in an agent config:

1 sandbox_spec:
2   provider_options:
3     image_auth:
4       username: ${oc.env:REGISTRY_USERNAME}
5       password: ${oc.env:REGISTRY_PASSWORD}
6     platform:
7       os: linux
8       arch: amd64
9     skip_health_check: false
10     extensions:
11       imagePullPolicy: IfNotPresent

Supported options are:

Option	Purpose
`image_auth`	Registry username and password passed to the OpenSandbox SDK for private image pulls.
`platform`	Mapping passed to the OpenSandbox SDK `PlatformSpec`, such as `os` and `arch`.
`snapshot_id`	OpenSandbox snapshot ID to create from instead of only an image.
`volumes`	List of mappings passed to the OpenSandbox SDK `Volume` model.
`skip_health_check`	Per-sandbox override for SDK create health checking unless the provider config forces it on.
`extensions`	String map passed to OpenSandbox create extensions.

Unknown provider option keys raise ValueError; values with the wrong type raise TypeError. This catches config drift before a sandbox allocation is attempted.

Relevant SandboxSpec Fields

Field	OpenSandbox behavior
`image`	Container image passed to OpenSandbox create.
`ttl_s`	Converted to an OpenSandbox sandbox timeout.
`ready_timeout_s`	Converted to an OpenSandbox ready timeout.
`env`	Passed to OpenSandbox create and command execution.
`files`	Seed files uploaded before the first command.
`metadata`	Passed to OpenSandbox create after provider-specific normalization.
`resources`	Mapped to OpenSandbox resource quantities.
`entrypoint`	Passed to OpenSandbox create when set.
`provider_options`	Per-sandbox OpenSandbox options such as `image_auth`, `platform`, `snapshot_id`, `volumes`, `skip_health_check`, and `extensions`.

Resource Mapping

SandboxResources is translated into OpenSandbox resource quantities:

SandboxResources field	OpenSandbox resource key
`cpu`	`cpu`
`memory_mib`	`memory`, formatted as `<value>Mi`
`disk_gib`	`ephemeral-storage`, formatted as `<value>Gi`
`gpu`	`gpu`
`gpu_type`	`gpu_type`

The provider also normalizes metadata values for backend labels by replacing unsupported characters and truncating values to the provider limit.

Job Attribution

The provider merges nemo-gym.nvidia.com/team, nemo-gym.nvidia.com/user, nemo-gym.nvidia.com/workload, and nemo-gym.nvidia.com/run keys into each sandbox’s metadata when they can be resolved. OpenSandbox propagates sandbox metadata as Kubernetes labels on the sandbox resources, so running sandboxes are attributable both through the OpenSandbox list API metadata filter and directly at the cluster level:

$ kubectl get pods -l nemo-gym.nvidia.com/team=my-team

Each field resolves in order: the provider’s attribution config, then NEMO_GYM_TEAM / NEMO_GYM_USER / NEMO_GYM_WORKLOAD environment variables, then Slurm job environment variables (SLURM_JOB_ACCOUNT / SLURM_JOB_USER / SLURM_JOB_NAME). user additionally falls back to the OS login name (root is ignored — containers run as root by default, so it would attribute the image, not a person), and workload to NEMO_GYM_CONFIG_PATH, the server instance name the gym CLI sets on every server process it spawns. Fields that cannot be resolved are omitted. Explicit sandbox_spec.metadata and default_metadata keys always take precedence over attribution keys.

run identifies one launch of the creating process: NEMO_GYM_RUN_ID if set, else an id generated per process. The resolved attribution is logged once at the first sandbox create — note the run value from the logs to list or clean up exactly that run’s sandboxes (for example after killing a run partway through), which team / user / workload cannot do when the same user launches the same workload twice:

$ kubectl delete batchsandboxes -l nemo-gym.nvidia.com/run=<run-id>

1 sandbox:
2   opensandbox:
3     attribution:
4       enabled: true                       # set false to disable automatic attribution
5       key_prefix: nemo-gym.nvidia.com/    # label-key namespace; "" for bare team/user/workload/run keys
6       # team: my-team                     # override auto-detection
7       # user: my-user
8       # workload: my-benchmark
9       # run: my-run-id

Attribution in Kubernetes deployments

When the gym servers themselves run in Kubernetes (for example a driver pod launching an eval), none of the automatic sources resolve: there are no Slurm variables, and the container’s OS login is typically root, which is ignored. Set the NEMO_GYM_* variables on the pod spec — either directly or via the downward API from labels the pod already carries:

1 env:
2   - name: NEMO_GYM_TEAM
3     value: my-team
4   - name: NEMO_GYM_USER
5     valueFrom:
6       fieldRef:
7         fieldPath: metadata.labels['owner']

Lifecycle

The provider creates one OpenSandbox sandbox per Gym sandbox:

Operation	OpenSandbox behavior
Create	`opensandbox.Sandbox.create(...)` with normalized `SandboxSpec` fields.
Exec	`handle.raw.commands.run(...)` with command options derived from `exec()` arguments.
Status	`handle.raw.get_info()` mapped onto `SandboxStatus`.
Close	`handle.raw.kill()` followed by local SDK handle cleanup.

If create.skip_health_check is enabled, the provider reconnects to the sandbox before running the NeMo Gym readiness probe so follow-up operations use a fresh SDK handle.

File Transfer

The provider uses the OpenSandbox SDK file API for uploads and downloads:

upload() reads the local file and writes bytes to the target sandbox path.
download() reads bytes from the sandbox path and writes them to the local target path.

Startup files from SandboxSpec.files use the same provider file path semantics before the first command runs.

User and Runtime Notes

The neutral user argument to exec() maps onto OpenSandbox command options:

`user` value	Behavior
`None`	Use the sandbox default user.
`"root"`	Run the command as provided.
Integer uid	Pass the uid through the OpenSandbox command options.
Other string	Wrap the command with `su -s /bin/sh -c ... <user>`.

Command failures return SandboxExecResult with the command’s exit code. If OpenSandbox reports an execution error without an exit code, the provider returns code 125 with error_type="sandbox".

The provider’s create.image_pull_policy defaults to IfNotPresent. Valid values are Always, IfNotPresent, and Never. The resolved policy is written into OpenSandbox create extensions as both imagePullPolicy and opensandbox.extensions.image-pull-policy unless those keys are already present in provider_options.extensions.

Create retries handle transient allocation, connection, image pull, and server-side errors. Command retries are controlled separately by operations.command_retries.