> This page is for version 0.3.0.
> For other versions, use one of these documentation indexes:
> - Main (default): https://docs.nvidia.com/nemo/gym/main/llms.txt
> - 0.7.0: https://docs.nvidia.com/nemo/gym/v0.7.0/llms.txt
> - 0.6.0: https://docs.nvidia.com/nemo/gym/v0.6.0/llms.txt
> - 0.5.1: https://docs.nvidia.com/nemo/gym/v0.5.1/llms.txt
> - 0.5.0: https://docs.nvidia.com/nemo/gym/v0.5.0/llms.txt
> - 0.4.0: https://docs.nvidia.com/nemo/gym/v0.4.0/llms.txt
> - 0.3.0: https://docs.nvidia.com/nemo/gym/v0.3.0/llms.txt
> - 0.2.1: https://docs.nvidia.com/nemo/gym/v0.2.1/llms.txt

> 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.agent_utils.uv_bootstrap

The `uv` binary a harness uploads into a task sandbox, chosen for the sandbox's platform.

An agent host and its task sandboxes need not share a CPU architecture or a C library: an aarch64
login node drives x86\_64 pods, and an Alpine image runs musl. A harness that installs a Python
runtime inside the sandbox with `uv` therefore asks the sandbox what it is and picks a build that
runs there. The static musl build of `uv` runs on glibc and musl alike, so it is the one
downloaded; the host's own binary is reused only when it is known to run in the sandbox.

`uv_for_sandbox` is the entry point; everything else here is implementation detail. Shared by the
harnesses that install a Python runtime in the sandbox (Hermes today). Harnesses on
Node, such as Codex and Pi, do not acquire a `uv` dependency through this module.

## Module Contents

### Classes

| Name                                                                      | Description                                                                      |
| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| [`_Sandbox`](#nemo_gym-agent_utils-uv_bootstrap-_Sandbox)                 | -                                                                                |
| [`_SandboxPlatform`](#nemo_gym-agent_utils-uv_bootstrap-_SandboxPlatform) | What `uname -s`, `uname -m` and the C library probe reported inside the sandbox. |

### Functions

| Name                                                                                    | Description                                                                                       |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| [`_download_uv`](#nemo_gym-agent_utils-uv_bootstrap-_download_uv)                       | Fetch the uv release for `target` into `destination` (atomic, idempotent).                        |
| [`_host_uv_runs_in`](#nemo_gym-agent_utils-uv_bootstrap-_host_uv_runs_in)               | Whether the host's own `uv` runs in the sandbox: a Linux host, the same architecture, and a glibc |
| [`_host_uv_version`](#nemo_gym-agent_utils-uv_bootstrap-_host_uv_version)               | `uv --version` -> `0.12.3`.                                                                       |
| [`_probe_sandbox_platform`](#nemo_gym-agent_utils-uv_bootstrap-_probe_sandbox_platform) | Ask the sandbox for its kernel, machine and C library.                                            |
| [`_uv_release_target`](#nemo_gym-agent_utils-uv_bootstrap-_uv_release_target)           | The uv release target to download for a sandbox: the static musl build for its architecture.      |
| [`uv_for_sandbox`](#nemo_gym-agent_utils-uv_bootstrap-uv_for_sandbox)                   | The uv binary to upload into `sandbox`.                                                           |

### Data

[`DEFAULT_UV_CACHE_DIR`](#nemo_gym-agent_utils-uv_bootstrap-DEFAULT_UV_CACHE_DIR)

[`LOG`](#nemo_gym-agent_utils-uv_bootstrap-LOG)

[`UV_RELEASE_URL`](#nemo_gym-agent_utils-uv_bootstrap-UV_RELEASE_URL)

[`_DOWNLOAD_LOCKS`](#nemo_gym-agent_utils-uv_bootstrap-_DOWNLOAD_LOCKS)

[`_MACHINES`](#nemo_gym-agent_utils-uv_bootstrap-_MACHINES)

[`_PLATFORM_PROBE`](#nemo_gym-agent_utils-uv_bootstrap-_PLATFORM_PROBE)

### API

```python
class nemo_gym.agent_utils.uv_bootstrap._Sandbox()
```

Protocol

```python
nemo_gym.agent_utils.uv_bootstrap._Sandbox.exec(
    command: str,
    cwd: str | None = None,
    timeout_s: float | None = None
)
```

async

```python
class nemo_gym.agent_utils.uv_bootstrap._SandboxPlatform(
    system: str,
    machine: str,
    libc: str
)
```

Dataclass

What `uname -s`, `uname -m` and the C library probe reported inside the sandbox.

**`arch`** `str | None`

---

**`libc`** `str`

---

**`machine`** `str`

---

**`system`** `str`

---

```python
nemo_gym.agent_utils.uv_bootstrap._download_uv(
    version: str,
    target: str,
    destination: pathlib.Path
) -> None
```

Fetch the uv release for `target` into `destination` (atomic, idempotent).

```python
nemo_gym.agent_utils.uv_bootstrap._host_uv_runs_in(
    sandbox_platform: nemo_gym.agent_utils.uv_bootstrap._SandboxPlatform
) -> bool
```

Whether the host's own `uv` runs in the sandbox: a Linux host, the same architecture, and a glibc
sandbox (the host binary is a gnu build; the musl download covers musl sandboxes).

```python
nemo_gym.agent_utils.uv_bootstrap._host_uv_version(
    uv_path: str
) -> str
```

`uv --version` -> `0.12.3`.

```python
nemo_gym.agent_utils.uv_bootstrap._probe_sandbox_platform(
    sandbox: nemo_gym.agent_utils.uv_bootstrap._Sandbox,
    workdir: str | None,
    timeout_s: float = 30
) -> nemo_gym.agent_utils.uv_bootstrap._SandboxPlatform
```

async

Ask the sandbox for its kernel, machine and C library.

```python
nemo_gym.agent_utils.uv_bootstrap._uv_release_target(
    sandbox_platform: nemo_gym.agent_utils.uv_bootstrap._SandboxPlatform
) -> str
```

The uv release target to download for a sandbox: the static musl build for its architecture.

```python
nemo_gym.agent_utils.uv_bootstrap.uv_for_sandbox(
    sandbox: nemo_gym.agent_utils.uv_bootstrap._Sandbox,
    workdir: str | None,
    cache_dir: str = DEFAULT_UV_CACHE_DIR
) -> pathlib.Path
```

async

The uv binary to upload into `sandbox`.

The host's binary when it is known to run there, else the static musl build of the host's uv
version for the sandbox's architecture, fetched once into `cache_dir`.

```python
nemo_gym.agent_utils.uv_bootstrap.DEFAULT_UV_CACHE_DIR = '~/.cache/nemo_gym/uv'
```

```python
nemo_gym.agent_utils.uv_bootstrap.LOG = logging.getLogger(__name__)
```

```python
nemo_gym.agent_utils.uv_bootstrap.UV_RELEASE_URL = 'https://github.com/astral-sh/uv/releases/download/{version}/uv-{target}.tar.gz'
```

```python
nemo_gym.agent_utils.uv_bootstrap._DOWNLOAD_LOCKS: dict[Path, Lock] = {}
```

```python
nemo_gym.agent_utils.uv_bootstrap._MACHINES = {'x86_64': 'x86_64', 'amd64': 'x86_64', 'aarch64': 'aarch64', 'arm64': 'aarch64'...
```

```python
nemo_gym.agent_utils.uv_bootstrap._PLATFORM_PROBE = 'uname -s && uname -m && if ls /lib/ld-musl-*.so.1 >/dev/null 2>&1; then echo mu...
```