> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/nemo/gym/v0.5.1/nemo-gym/nemo_gym/sandbox/providers/bwrap/llms.txt. # nemo_gym.sandbox.providers.bwrap Bubblewrap (bwrap) provider package. ## Submodules * **[`nemo_gym.sandbox.providers.bwrap.provider`](/nemo/gym/nemo-gym/nemo_gym/sandbox/providers/bwrap/provider)** ## Package 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. | ### 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 ... -- -c ` 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 ``` ## Docs - [nemo_gym.sandbox.providers.bwrap.provider](https://docs.nvidia.com/nemo/gym/v0.5.1/nemo-gym/nemo_gym/sandbox/providers/bwrap/provider.md)