> This page is for version 0.2.1.
> 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.

# nemo_gym.sandbox.providers.bwrap.provider

Bubblewrap (`bwrap`) sandbox provider.

A sandbox is a directory, `<base_dir>/<sandbox_id>/{workspace,tmp,home}`, on
storage local to the Gym process. There is no long-lived container process:
every `exec` spawns `bwrap <flags> -- <shell> -c <command>` in fresh user,
pid, ipc and uts namespaces (and a fresh network namespace unless
`network: host`). The host's system directories are bound read-only; only
the sandbox's own directories are writable. File transfer is plain host-side
file I/O with containment checks. See README.md for the design and its limits.

## Module Contents

### Classes

| Name                                                                                                      | Description                                                                       |
| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| [`BwrapBind`](#nemo_gym-sandbox-providers-bwrap-provider-BwrapBind)                                       | A read-only system bind: `path` may be a glob; `optional` entries may be absent.  |
| [`BwrapConfig`](#nemo_gym-sandbox-providers-bwrap-provider-BwrapConfig)                                   | Provider config: the `bwrap:` block of a sandbox provider config.                 |
| [`BwrapCreateError`](#nemo_gym-sandbox-providers-bwrap-provider-BwrapCreateError)                         | Raised when the bwrap provider cannot create a sandbox.                           |
| [`BwrapCreateVerificationError`](#nemo_gym-sandbox-providers-bwrap-provider-BwrapCreateVerificationError) | Raised when a new bwrap sandbox fails its readiness probe.                        |
| [`BwrapMount`](#nemo_gym-sandbox-providers-bwrap-provider-BwrapMount)                                     | An extra bind mount: host `src` at sandbox `dst`; read-only unless `ro` is false. |
| [`BwrapPathError`](#nemo_gym-sandbox-providers-bwrap-provider-BwrapPathError)                             | Raised when a transfer path escapes the sandbox's mounts or crosses a symlink.    |
| [`BwrapProvider`](#nemo_gym-sandbox-providers-bwrap-provider-BwrapProvider)                               | Sandbox provider backed by a pinned bubblewrap binary on the Gym process's host.  |
| [`_BwrapSandbox`](#nemo_gym-sandbox-providers-bwrap-provider-_BwrapSandbox)                               | Provider-private state on `SandboxHandle.raw`.                                    |

### Functions

| Name                                                                                          | Description                                                                              |
| --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| [`_pid_alive`](#nemo_gym-sandbox-providers-bwrap-provider-_pid_alive)                         | -                                                                                        |
| [`_pid_may_run`](#nemo_gym-sandbox-providers-bwrap-provider-_pid_may_run)                     | Conservative liveness for a cleanup proof: only a missing, zombie or reused pid is gone. |
| [`_process_start_time`](#nemo_gym-sandbox-providers-bwrap-provider-_process_start_time)       | The kernel start time of `pid` (Linux), guarding kills against PID reuse.                |
| [`_read_init_record`](#nemo_gym-sandbox-providers-bwrap-provider-_read_init_record)           | `(pid, start time)` of a namespace-init record, or None when it is unreadable.           |
| [`_regular_file_or_close`](#nemo_gym-sandbox-providers-bwrap-provider-_regular_file_or_close) | Refuse (closing `fd`) anything but a regular file, then make `fd` blocking again.        |
| [`_rmtree`](#nemo_gym-sandbox-providers-bwrap-provider-_rmtree)                               | Remove a sandbox tree, restoring owner permissions that sandboxed code may have dropped. |
| [`_validate_env`](#nemo_gym-sandbox-providers-bwrap-provider-_validate_env)                   | -                                                                                        |
| [`_validate_sandbox_dir`](#nemo_gym-sandbox-providers-bwrap-provider-_validate_sandbox_dir)   | -                                                                                        |
| [`resolve_binds`](#nemo_gym-sandbox-providers-bwrap-provider-resolve_binds)                   | Expand globs and drop absent optional entries; a missing required entry raises.          |

### Data

[`CLOSING_MARKER`](#nemo_gym-sandbox-providers-bwrap-provider-CLOSING_MARKER)

[`DEFAULT_ENV_PASSTHROUGH`](#nemo_gym-sandbox-providers-bwrap-provider-DEFAULT_ENV_PASSTHROUGH)

[`DEFAULT_NETWORK_HOST_RO_BINDS`](#nemo_gym-sandbox-providers-bwrap-provider-DEFAULT_NETWORK_HOST_RO_BINDS)

[`DEFAULT_PATH`](#nemo_gym-sandbox-providers-bwrap-provider-DEFAULT_PATH)

[`DEFAULT_RO_BINDS`](#nemo_gym-sandbox-providers-bwrap-provider-DEFAULT_RO_BINDS)

[`ENV_NAME_PATTERN`](#nemo_gym-sandbox-providers-bwrap-provider-ENV_NAME_PATTERN)

[`FORBIDDEN_WORKDIRS`](#nemo_gym-sandbox-providers-bwrap-provider-FORBIDDEN_WORKDIRS)

[`HOME_DIR`](#nemo_gym-sandbox-providers-bwrap-provider-HOME_DIR)

[`INIT_RECORD_SUFFIX`](#nemo_gym-sandbox-providers-bwrap-provider-INIT_RECORD_SUFFIX)

[`LOGGER`](#nemo_gym-sandbox-providers-bwrap-provider-LOGGER)

[`PENDING_RECORD_PREFIX`](#nemo_gym-sandbox-providers-bwrap-provider-PENDING_RECORD_PREFIX)

[`PROVIDER_NAME`](#nemo_gym-sandbox-providers-bwrap-provider-PROVIDER_NAME)

[`RUN_DIR`](#nemo_gym-sandbox-providers-bwrap-provider-RUN_DIR)

[`SANDBOX_ID_PATTERN`](#nemo_gym-sandbox-providers-bwrap-provider-SANDBOX_ID_PATTERN)

[`SANDBOX_ID_PREFIX`](#nemo_gym-sandbox-providers-bwrap-provider-SANDBOX_ID_PREFIX)

[`SANDBOX_RUNTIME_RETURN_CODE`](#nemo_gym-sandbox-providers-bwrap-provider-SANDBOX_RUNTIME_RETURN_CODE)

[`STATE_FILE`](#nemo_gym-sandbox-providers-bwrap-provider-STATE_FILE)

[`TMP_DIR`](#nemo_gym-sandbox-providers-bwrap-provider-TMP_DIR)

[`WORKSPACE_DIR`](#nemo_gym-sandbox-providers-bwrap-provider-WORKSPACE_DIR)

[`_HAVE_PROC`](#nemo_gym-sandbox-providers-bwrap-provider-_HAVE_PROC)

### API

```python
class nemo_gym.sandbox.providers.bwrap.BwrapBind(
    path: str,
    optional: bool = False
)
```

Dataclass

A read-only system bind: `path` may be a glob; `optional` entries may be absent.

**`optional`** `bool = False`

---

**`path`** `str`

---

```python
nemo_gym.sandbox.providers.bwrap.BwrapBind.__post_init__() -> None
```

```python
nemo_gym.sandbox.providers.bwrap.BwrapBind.coerce(
    value: typing.Any
) -> nemo_gym.sandbox.providers.bwrap.provider.BwrapBind
```

classmethod

```python
class nemo_gym.sandbox.providers.bwrap.BwrapConfig(
    bwrap_path: str,
    base_dir: str | None = None,
    workdir: str = '/workspace',
    home_path: str = '/home/sandbox',
    network: typing.Literal['none', 'host'] = 'none',
    shell: str = '/bin/bash',
    ro_binds: list[typing.Any] = (lambda: list(DEFAULT_RO_BI...,
    network_host_ro_binds: list[typing.Any] = (lambda: list(DEFAULT_NETWO...,
    mounts: list[typing.Any] = list(),
    env: dict[str, str] = dict(),
    env_passthrough: list[str] = (lambda: list(DEFAULT_ENV_P...,
    hide_gpus: bool = True,
    remount_root_ro: bool = True,
    default_files: dict[str, str] = dict(),
    extra_args: list[str] = list(),
    allow_nested_userns: bool = False,
    exec_concurrency: int | None = 256,
    default_timeout_s: float | None = 180,
    kill_timeout_s: float = 10,
    probe_on_create: bool = True,
    probe_timeout_s: float = 30
)
```

Dataclass

Provider config: the `bwrap:` block of a sandbox provider config.

**`allow_nested_userns`** `bool = False`

---

**`base_dir`** `str | None = None`

---

**`bwrap_path`** `str`

---

**`default_files`** `dict[str, str] = field(default_factory=dict)`

---

**`default_timeout_s`** `float | None = 180`

---

**`env`** `dict[str, str] = field(default_factory=dict)`

---

**`env_passthrough`** `list[str]`

---

**`exec_concurrency`** `int | None = 256`

---

**`extra_args`** `list[str] = field(default_factory=list)`

---

**`hide_gpus`** `bool = True`

---

**`home_path`** `str = '/home/sandbox'`

---

**`kill_timeout_s`** `float = 10`

---

**`mounts`** `list[Any] = field(default_factory=list)`

---

**`network`** `Literal['none', 'host'] = 'none'`

---

**`network_host_ro_binds`** `list[Any]`

---

**`probe_on_create`** `bool = True`

---

**`probe_timeout_s`** `float = 30`

---

**`remount_root_ro`** `bool = True`

---

**`ro_binds`** `list[Any]`

---

**`shell`** `str = '/bin/bash'`

---

**`workdir`** `str = '/workspace'`

---

```python
nemo_gym.sandbox.providers.bwrap.BwrapConfig.__post_init__() -> None
```

```python
class nemo_gym.sandbox.providers.bwrap.BwrapCreateError()
```

**Bases:** [SandboxCreateError](/nemo/gym/nemo-gym/nemo_gym/sandbox/providers/base#nemo_gym-sandbox-providers-base-SandboxCreateError)

Raised when the bwrap provider cannot create a sandbox.

```python
class nemo_gym.sandbox.providers.bwrap.BwrapCreateVerificationError()
```

**Bases:** [SandboxCreateVerificationError](/nemo/gym/nemo-gym/nemo_gym/sandbox/providers/base#nemo_gym-sandbox-providers-base-SandboxCreateVerificationError)

Raised when a new bwrap sandbox fails its readiness probe.

```python
class nemo_gym.sandbox.providers.bwrap.BwrapMount(
    src: str,
    dst: str,
    ro: bool = True
)
```

Dataclass

An extra bind mount: host `src` at sandbox `dst`; read-only unless `ro` is false.

**`dst`** `str`

---

**`ro`** `bool = True`

---

**`src`** `str`

---

```python
nemo_gym.sandbox.providers.bwrap.BwrapMount.__post_init__() -> None
```

```python
nemo_gym.sandbox.providers.bwrap.BwrapMount.coerce(
    value: typing.Any
) -> nemo_gym.sandbox.providers.bwrap.provider.BwrapMount
```

classmethod

Accept `{src, dst, ro}` or the enroot/apptainer string form `src:dst[:ro|rw]`.

```python
nemo_gym.sandbox.providers.bwrap.BwrapMount.to_dict() -> dict[str, typing.Any]
```

```python
class nemo_gym.sandbox.providers.bwrap.BwrapPathError()
```

**Bases:** `PermissionError`

Raised when a transfer path escapes the sandbox's mounts or crosses a symlink.

```python
class nemo_gym.sandbox.providers.bwrap.BwrapProvider(
    config: typing.Any = {}
)
```

Sandbox provider backed by a pinned bubblewrap binary on the Gym process's host.

**`_base_dir`** `= Path(os.path.realpath(base))`

---

**`_config`** `= BwrapConfig(**config)`

---

**`_network_host_binds`**

---

**`_processes`** `dict[str, dict[int, Process]] = {}`

---

**`_semaphore`**

---

**`_system_binds`** `= resolve_binds(self._config.ro_binds)`

---

**`_untracked_inits`** `set[str] = set()`

---

**`base_dir`** `Path`

---

**`config`** `BwrapConfig`

---

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider._add_pending(
    inst: nemo_gym.sandbox.providers.bwrap.provider._BwrapSandbox
) -> pathlib.Path | None
```

staticmethod

Record a pending exec in run/ (owner pid and its start time); None when the sandbox is gone.

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider._binds_workspace_host_path(
    inst: nemo_gym.sandbox.providers.bwrap.provider._BwrapSandbox
) -> bool
```

Whether the workspace is also bound at its host path. Not when that path lies inside the sandbox's own
/tmp, home or workdir: bwrap would create its mount point in sandbox-writable space (see \_check_mount_dst).

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider._check_mount_dst(
    target: str,
    workdir: str
) -> None
```

Refuse an extra mount at, above or inside the sandbox's own /tmp, home or workdir.

Inside one: bwrap creates the mount point in a directory that sandboxed code can write, and follows
symlinks while doing so, so an earlier exec could make it create entries on the host. At or above one:
the mount shadows that directory, and transfers to it would land where the sandbox cannot see them.

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider._check_own_dirs(
    workdir: str
) -> None
```

Refuse a workdir that equals, contains or lies inside /tmp or home_path (or vice versa).

Each of the three is a separate bind; nested, a later bind hides an earlier one from commands while
transfers still resolve to it, and a mount point inside /tmp or home is created in sandbox-writable space.

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider._check_target(
    target: str,
    label: str
) -> None
```

Refuse a writable/extra mount target inside a read-only system bind.

bwrap cannot create a mount point inside a read-only bind (measured on that cluster:
a target under /opt failed), so use a top-level target such as /codex-runtime.

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider._download(
    inst: nemo_gym.sandbox.providers.bwrap.provider._BwrapSandbox,
    source_path: str,
    target_path: pathlib.Path
) -> None
```

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider._environment(
    inst: nemo_gym.sandbox.providers.bwrap.provider._BwrapSandbox,
    env: collections.abc.Mapping[str, str] | None
) -> dict[str, str]
```

The complete environment of a sandboxed command (bwrap passes its own env through).

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider._exists(
    inst: nemo_gym.sandbox.providers.bwrap.provider._BwrapSandbox,
    path: str
) -> bool
```

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider._kill_process(
    process: asyncio.subprocess.Process
) -> None
```

async

SIGKILL bwrap's group: --die-with-parent then tears down the sandbox's pid namespace.

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider._kill_recorded(
    inst: nemo_gym.sandbox.providers.bwrap.provider._BwrapSandbox
) -> None
```

async

Kill every bwrap process recorded for this sandbox, by any provider instance.

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider._live_pending(
    inst: nemo_gym.sandbox.providers.bwrap.provider._BwrapSandbox
) -> list[pathlib.Path] | None
```

staticmethod

Pending-exec records whose owner may still run (records of dead owners are removed); None if unreadable.

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider._mount_table(
    inst: nemo_gym.sandbox.providers.bwrap.provider._BwrapSandbox
) -> list[tuple[str, pathlib.Path, bool]]
```

(sandbox prefix, host path, writable) of the binds a command sees, most specific prefix first.

Built in bind order (as `bwrap_argv` applies them): a later bind at or above an earlier one's prefix
hides it, so its entry is dropped and transfers resolve to the visible bind. A regular-file mount's host
path is the resolved file.

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider._open_parent(
    root: pathlib.Path,
    parts: tuple[str, ...],
    create: bool
) -> int
```

staticmethod

Open the directory holding `parts[-1]` without following any symlink below `root`.

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider._prepare_base_dir() -> None
```

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider._record_init(
    inst: nemo_gym.sandbox.providers.bwrap.provider._BwrapSandbox,
    outer_pid: int,
    info: asyncio.StreamReader
) -> bool
```

async

Record the host pid of the exec's namespace init from bwrap's --info-fd JSON.

bwrap returns as soon as the command (pid 2) exits; its init (pid 1) is killed by
\--die-with-parent right after, and the kernel kills the rest of the namespace
only when that init exits. The record lets `exec_processes_terminated` wait out
that instant instead of trusting bwrap's own exit. No JSON means bwrap created no
namespace (it failed first), so there is nothing to record.

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider._recorded_processes_may_run(
    inst: nemo_gym.sandbox.providers.bwrap.provider._BwrapSandbox
) -> list[str] | None
```

Records whose process may still run (dead init records are removed); None if unprovable.

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider._register(
    inst: nemo_gym.sandbox.providers.bwrap.provider._BwrapSandbox,
    process: asyncio.subprocess.Process
) -> None
```

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider._remove_pending(
    path: pathlib.Path | None
) -> None
```

staticmethod

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider._run(
    inst: nemo_gym.sandbox.providers.bwrap.provider._BwrapSandbox,
    argv: list[str],
    env: dict[str, str],
    timeout: float | None,
    pending: pathlib.Path | None = None
) -> nemo_gym.sandbox.providers.base.SandboxExecResult
```

async

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider._sandbox_writable_dirs(
    workdir: str
) -> tuple[str, ...]
```

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider._stopped(
    inst: nemo_gym.sandbox.providers.bwrap.provider._BwrapSandbox
) -> bool
```

staticmethod

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider._stopped_result(
    inst: nemo_gym.sandbox.providers.bwrap.provider._BwrapSandbox
) -> nemo_gym.sandbox.providers.base.SandboxExecResult
```

staticmethod

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider._unregister(
    inst: nemo_gym.sandbox.providers.bwrap.provider._BwrapSandbox,
    process: asyncio.subprocess.Process
) -> None
```

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider._upload(
    inst: nemo_gym.sandbox.providers.bwrap.provider._BwrapSandbox,
    source_path: pathlib.Path,
    target_path: str
) -> None
```

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider._warn_ignored(
    spec: nemo_gym.sandbox.providers.base.SandboxSpec
) -> None
```

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider._watch_info(
    inst: nemo_gym.sandbox.providers.bwrap.provider._BwrapSandbox,
    outer_pid: int,
    info_fd: int
) -> bool
```

async

Read bwrap's --info-fd pipe without a thread, then record the namespace init.

True when bwrap reported a namespace init (`child-pid`), i.e. its own setup got as far as starting the
sandboxed command. The command cannot write to this pipe, so a False is bwrap's own failure.

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider._write_bytes(
    inst: nemo_gym.sandbox.providers.bwrap.provider._BwrapSandbox,
    path: str,
    data: bytes,
    mode: int
) -> None
```

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider.aclose() -> None
```

async

Kill bwrap processes this instance still runs; sandbox directories are left to close().

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider.bwrap_argv(
    inst: nemo_gym.sandbox.providers.bwrap.provider._BwrapSandbox,
    command: str,
    cwd: str | None = None
) -> list[str]
```

The full `bwrap ... -- <shell> -c <command>` argv for one exec.

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider.close(
    handle: nemo_gym.sandbox.providers.base.SandboxHandle
) -> None
```

async

Kill every bwrap process of the sandbox, then delete its directory. Idempotent.

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider.connect(
    descriptor: collections.abc.Mapping[str, typing.Any]
) -> nemo_gym.sandbox.providers.base.SandboxHandle
```

async

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider.create(
    spec: nemo_gym.sandbox.providers.base.SandboxSpec
) -> nemo_gym.sandbox.providers.base.SandboxHandle
```

async

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider.download_file(
    handle: nemo_gym.sandbox.providers.base.SandboxHandle,
    source_path: str,
    target_path: pathlib.Path
) -> None
```

async

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider.exec(
    handle: nemo_gym.sandbox.providers.base.SandboxHandle,
    command: str,
    cwd: str | None = None,
    env: dict[str, str] | None = None,
    timeout_s: int | float | None = None,
    user: str | int | None = None
) -> nemo_gym.sandbox.providers.base.SandboxExecResult
```

async

Run `command` in a fresh bwrap namespace set over this sandbox's directories.

Processes do not outlive their exec: when the command exits, its pid
namespace (and every background process in it) is torn down. On timeout or
cancellation the bwrap process group is SIGKILLed, which also kills the namespace.

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider.exec_processes_terminated(
    handle: nemo_gym.sandbox.providers.base.SandboxHandle
) -> bool
```

async

Whether no process of any exec of this sandbox can still run (SupportsSandboxExecScopedProcesses).

Every sandboxed process lives in the pid namespace of the exec that started it,
and the kernel kills a namespace when its init exits. So the proof is: no bwrap
process recorded by any provider instance is alive, and no recorded namespace
init is alive (it is killed by --die-with-parent right after its bwrap exits;
a zombie init has finished killing its namespace). Anything unprovable, such as
an unreadable record or an init this instance failed to record, is False.

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider.exists(
    handle: nemo_gym.sandbox.providers.base.SandboxHandle,
    path: str
) -> bool
```

async

Whether `path` exists in the sandbox (bwrap-specific; not part of the provider protocol).

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider.host_path(
    inst: nemo_gym.sandbox.providers.bwrap.provider._BwrapSandbox,
    path: str,
    write: bool
) -> tuple[pathlib.Path, tuple[str, ...]]
```

Map a sandbox path to (host root, relative parts) under one of its writable mounts.

Relative paths are relative to the workdir. `..` components are refused, as
are paths outside the sandbox's own directories and extra mounts.

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider.serialize_handle(
    handle: nemo_gym.sandbox.providers.base.SandboxHandle,
    scope: str | None = None
) -> dict[str, typing.Any]
```

async

A same-host, same-uid descriptor; `connect` reads the rest from the sandbox's state file.

Like apptainer's, this is a trusted control-plane descriptor, not a lease:
either side can stop the sandbox, so callers coordinate ownership.

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider.status(
    handle: nemo_gym.sandbox.providers.base.SandboxHandle
) -> nemo_gym.sandbox.providers.base.SandboxStatus
```

async

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider.upload_file(
    handle: nemo_gym.sandbox.providers.base.SandboxHandle,
    source_path: pathlib.Path,
    target_path: str
) -> None
```

async

```python
nemo_gym.sandbox.providers.bwrap.BwrapProvider.uploads_independent_of_execs() -> bool
```

```python
class nemo_gym.sandbox.providers.bwrap.provider._BwrapSandbox(
    sandbox_id: str,
    root: pathlib.Path,
    workdir: str,
    network: str,
    env: dict[str, str] = dict(),
    mounts: list[nemo_gym.sandbox.providers.bwrap.provider.BwrapMount] = list()
)
```

Dataclass

Provider-private state on `SandboxHandle.raw`.

**`env`** `dict[str, str] = field(default_factory=dict)`

---

**`home`** `Path`

---

**`mounts`** `list[BwrapMount] = field(default_factory=list)`

---

**`network`** `str`

---

**`root`** `Path`

---

**`run_dir`** `Path`

---

**`sandbox_id`** `str`

---

**`tmp`** `Path`

---

**`workdir`** `str`

---

**`workspace`** `Path`

---

```python
nemo_gym.sandbox.providers.bwrap.provider._BwrapSandbox.state() -> dict[str, typing.Any]
```

```python
nemo_gym.sandbox.providers.bwrap.provider._pid_alive(
    pid: int,
    start_time: str
) -> bool
```

```python
nemo_gym.sandbox.providers.bwrap.provider._pid_may_run(
    pid: int,
    start_time: str
) -> bool
```

Conservative liveness for a cleanup proof: only a missing, zombie or reused pid is gone.

```python
nemo_gym.sandbox.providers.bwrap.provider._process_start_time(
    pid: int
) -> str | None
```

The kernel start time of `pid` (Linux), guarding kills against PID reuse.

```python
nemo_gym.sandbox.providers.bwrap.provider._read_init_record(
    path: pathlib.Path
) -> tuple[int, str] | None
```

`(pid, start time)` of a namespace-init record, or None when it is unreadable.

```python
nemo_gym.sandbox.providers.bwrap.provider._regular_file_or_close(
    fd: int,
    path: str
) -> None
```

Refuse (closing `fd`) anything but a regular file, then make `fd` blocking again.

```python
nemo_gym.sandbox.providers.bwrap.provider._rmtree(
    path: pathlib.Path
) -> None
```

Remove a sandbox tree, restoring owner permissions that sandboxed code may have dropped.

```python
nemo_gym.sandbox.providers.bwrap.provider._validate_env(
    env: collections.abc.Mapping[str, typing.Any],
    source: str
) -> dict[str, str]
```

```python
nemo_gym.sandbox.providers.bwrap.provider._validate_sandbox_dir(
    path: str,
    label: str
) -> str
```

```python
nemo_gym.sandbox.providers.bwrap.provider.resolve_binds(
    binds: list[nemo_gym.sandbox.providers.bwrap.provider.BwrapBind]
) -> list[str]
```

Expand globs and drop absent optional entries; a missing required entry raises.

```python
nemo_gym.sandbox.providers.bwrap.provider.CLOSING_MARKER = 'closing'
```

```python
nemo_gym.sandbox.providers.bwrap.provider.DEFAULT_ENV_PASSTHROUGH: tuple[str, ...] = ('PATH', 'LANG', 'LD_LIBRARY_PATH', 'CUDA_HOME')
```

```python
nemo_gym.sandbox.providers.bwrap.provider.DEFAULT_NETWORK_HOST_RO_BINDS: tuple[Any, ...] = ('/etc/resolv.conf', '/etc/hosts', '/etc/nsswitch.conf', '/etc/ssl', '/etc/ca-ce...
```

```python
nemo_gym.sandbox.providers.bwrap.provider.DEFAULT_PATH = '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin'
```

```python
nemo_gym.sandbox.providers.bwrap.provider.DEFAULT_RO_BINDS: tuple[Any, ...] = ('/usr', '/bin', '/lib', {'path': '/sbin', 'optional': True}, {'path': '/lib64',...
```

```python
nemo_gym.sandbox.providers.bwrap.provider.ENV_NAME_PATTERN = re.compile('[A-Za-z_][A-Za-z0-9_]*')
```

```python
nemo_gym.sandbox.providers.bwrap.provider.FORBIDDEN_WORKDIRS = ('/', '/proc', '/dev')
```

```python
nemo_gym.sandbox.providers.bwrap.provider.HOME_DIR = 'home'
```

```python
nemo_gym.sandbox.providers.bwrap.provider.INIT_RECORD_SUFFIX = '.init'
```

```python
nemo_gym.sandbox.providers.bwrap.provider.LOGGER = logging.getLogger(__name__)
```

```python
nemo_gym.sandbox.providers.bwrap.provider.PENDING_RECORD_PREFIX = 'pending-'
```

```python
nemo_gym.sandbox.providers.bwrap.provider.PROVIDER_NAME = 'bwrap'
```

```python
nemo_gym.sandbox.providers.bwrap.provider.RUN_DIR = 'run'
```

```python
nemo_gym.sandbox.providers.bwrap.provider.SANDBOX_ID_PATTERN = re.compile('bwrap-[0-9a-f]{32}')
```

```python
nemo_gym.sandbox.providers.bwrap.provider.SANDBOX_ID_PREFIX = 'bwrap-'
```

```python
nemo_gym.sandbox.providers.bwrap.provider.SANDBOX_RUNTIME_RETURN_CODE = 125
```

```python
nemo_gym.sandbox.providers.bwrap.provider.STATE_FILE = 'sandbox.json'
```

```python
nemo_gym.sandbox.providers.bwrap.provider.TMP_DIR = 'tmp'
```

```python
nemo_gym.sandbox.providers.bwrap.provider.WORKSPACE_DIR = 'workspace'
```

```python
nemo_gym.sandbox.providers.bwrap.provider._HAVE_PROC = os.path.exists('/proc/self/stat')
```