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:

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:

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
    platform:
4
      os: linux
5
      arch: amd64
6
    skip_health_check: false
7
    extensions:
8
      imagePullPolicy: IfNotPresent

Supported options are:

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

Resource Mapping

SandboxResources is translated into OpenSandbox resource quantities:

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

Lifecycle

The provider creates one OpenSandbox sandbox per Gym sandbox:

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:

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.