> 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.config

Resolve a sandbox provider reference into a provider config.

An agent selects a sandbox by name (`sandbox_provider: sandbox`). The named
block lives in its own provider config file, so swapping providers is swapping a
`config_paths` entry, not editing the agent config::

# nemo\_gym/sandbox/providers/opensandbox/configs/opensandbox.yaml

sandbox:
opensandbox:
connection: \{ ... }

# agent config

sandbox\_provider: sandbox

An inline single-key mapping (`{provider_name: {...}}`) is also accepted for
keeping everything in one file.

A block may also carry a reserved `default_metadata` key. Its entries are merged
into the sandbox's `SandboxSpec.metadata` as defaults (the agent's own
`sandbox_spec.metadata` overrides them), so provider-identifying tags live with
the provider rather than the agent config::

sandbox:
opensandbox: \{ connection: \{ ... } }
default\_metadata: \{ sandbox-api: opensandbox-sdk }

## Module Contents

### Functions

| Name                                                                              | Description                                                                |
| --------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| [`_candidate_sandbox_names`](#nemo_gym-sandbox-config-_candidate_sandbox_names)   | List top-level config keys that look like named sandbox provider blocks.   |
| [`_provider_keys`](#nemo_gym-sandbox-config-_provider_keys)                       | Return the provider keys in a block (everything but reserved keys).        |
| [`_resolve_block`](#nemo_gym-sandbox-config-_resolve_block)                       | Resolve a `sandbox_provider` reference or inline mapping to a plain block. |
| [`_to_plain_dict`](#nemo_gym-sandbox-config-_to_plain_dict)                       | Return a plain `dict` for mappings, including OmegaConf `DictConfig`.      |
| [`resolve_provider_config`](#nemo_gym-sandbox-config-resolve_provider_config)     | Resolve a `sandbox_provider` field into a single-key provider config dict. |
| [`resolve_provider_metadata`](#nemo_gym-sandbox-config-resolve_provider_metadata) | Return a sandbox block's `default_metadata`.                               |

### Data

[`SANDBOX_BLOCK_DEFAULT_METADATA_KEY`](#nemo_gym-sandbox-config-SANDBOX_BLOCK_DEFAULT_METADATA_KEY)

[`SANDBOX_BLOCK_RESERVED_KEYS`](#nemo_gym-sandbox-config-SANDBOX_BLOCK_RESERVED_KEYS)

### API

```python
nemo_gym.sandbox.config._candidate_sandbox_names(
    named_configs: collections.abc.Mapping[str, typing.Any] | None
) -> list[str]
```

List top-level config keys that look like named sandbox provider blocks.

```python
nemo_gym.sandbox.config._provider_keys(
    block: collections.abc.Mapping[str, typing.Any]
) -> list[str]
```

Return the provider keys in a block (everything but reserved keys).

```python
nemo_gym.sandbox.config._resolve_block(
    sandbox_provider: str | collections.abc.Mapping[str, typing.Any],
    named_configs: collections.abc.Mapping[str, typing.Any] | None
) -> tuple[dict[str, typing.Any], str]
```

Resolve a `sandbox_provider` reference or inline mapping to a plain block.

```python
nemo_gym.sandbox.config._to_plain_dict(
    value: typing.Any
) -> typing.Any
```

Return a plain `dict` for mappings, including OmegaConf `DictConfig`.

```python
nemo_gym.sandbox.config.resolve_provider_config(
    sandbox_provider: str | collections.abc.Mapping[str, typing.Any],
    named_configs: collections.abc.Mapping[str, typing.Any] | None = None
) -> dict[str, typing.Any]
```

Resolve a `sandbox_provider` field into a single-key provider config dict.

**Parameters:**

Either the name of a top-level sandbox config block
(resolved from `named_configs`) or an inline single-key provider
mapping of the form `{provider_name: {...}}`.

Mapping of top-level config name to config block, typically
the merged global config dict. Required when `sandbox_provider` is a
name reference.

**Returns:** `dict[str, Any]`

A plain `{provider_name: provider_kwargs}` dict suitable for

**Raises:**

* `TypeError`: If `sandbox_provider` is neither a string nor a mapping.
* `ValueError`: If a named reference cannot be found, or if the block does not
  hold exactly one provider key.

```python
nemo_gym.sandbox.config.resolve_provider_metadata(
    sandbox_provider: str | collections.abc.Mapping[str, typing.Any],
    named_configs: collections.abc.Mapping[str, typing.Any] | None = None
) -> dict[str, typing.Any]
```

Return a sandbox block's `default_metadata`.

These are provider-contributed defaults to merge into `SandboxSpec.metadata`.
Returns an empty dict when the block has no `default_metadata` key. See
:func:`resolve_provider_config` for argument semantics.

```python
nemo_gym.sandbox.config.SANDBOX_BLOCK_DEFAULT_METADATA_KEY = 'default_metadata'
```

```python
nemo_gym.sandbox.config.SANDBOX_BLOCK_RESERVED_KEYS = frozenset({SANDBOX_BLOCK_DEFAULT_METADATA_KEY})
```