Skip to navigation

nemo_gym.sandbox.providers.bwrap

View as MarkdownOpen in Claude

Bubblewrap (bwrap) provider package.

Submodules

Package Contents

Classes

NameDescription
BwrapBindA read-only system bind: path may be a glob; optional entries may be absent.
BwrapConfigProvider config: the bwrap: block of a sandbox provider config.
BwrapCreateErrorRaised when the bwrap provider cannot create a sandbox.
BwrapCreateVerificationErrorRaised when a new bwrap sandbox fails its readiness probe.
BwrapMountAn extra bind mount: host src at sandbox dst; read-only unless ro is false.
BwrapPathErrorRaised when a transfer path escapes the sandbox’s mounts or crosses a symlink.
BwrapProviderSandbox provider backed by a pinned bubblewrap binary on the Gym process’s host.

API

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
nemo_gym.sandbox.providers.bwrap.BwrapBind.__post_init__() -> None
nemo_gym.sandbox.providers.bwrap.BwrapBind.coerce(
value: typing.Any
classmethod
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'
nemo_gym.sandbox.providers.bwrap.BwrapConfig.__post_init__() -> None
class nemo_gym.sandbox.providers.bwrap.BwrapCreateError()

Bases: SandboxCreateError

Raised when the bwrap provider cannot create a sandbox.

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

Bases: SandboxCreateVerificationError

Raised when a new bwrap sandbox fails its readiness probe.

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
nemo_gym.sandbox.providers.bwrap.BwrapMount.__post_init__() -> None
nemo_gym.sandbox.providers.bwrap.BwrapMount.coerce(
value: typing.Any
classmethod

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

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

Bases: PermissionError

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

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
nemo_gym.sandbox.providers.bwrap.BwrapProvider._add_pending(
) -> pathlib.Path | None
staticmethod

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

nemo_gym.sandbox.providers.bwrap.BwrapProvider._binds_workspace_host_path(
) -> 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).

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.

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.

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.

nemo_gym.sandbox.providers.bwrap.BwrapProvider._download(
source_path: str,
target_path: pathlib.Path
) -> None
nemo_gym.sandbox.providers.bwrap.BwrapProvider._environment(
env: collections.abc.Mapping[str, str] | None
) -> dict[str, str]

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

nemo_gym.sandbox.providers.bwrap.BwrapProvider._exists(
path: str
) -> bool
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.

nemo_gym.sandbox.providers.bwrap.BwrapProvider._kill_recorded(
) -> None
async

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

nemo_gym.sandbox.providers.bwrap.BwrapProvider._live_pending(
) -> list[pathlib.Path] | None
staticmethod

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

nemo_gym.sandbox.providers.bwrap.BwrapProvider._mount_table(
) -> 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.

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.

nemo_gym.sandbox.providers.bwrap.BwrapProvider._prepare_base_dir() -> None
nemo_gym.sandbox.providers.bwrap.BwrapProvider._record_init(
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.

nemo_gym.sandbox.providers.bwrap.BwrapProvider._recorded_processes_may_run(
) -> list[str] | None

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

nemo_gym.sandbox.providers.bwrap.BwrapProvider._register(
process: asyncio.subprocess.Process
) -> None
nemo_gym.sandbox.providers.bwrap.BwrapProvider._remove_pending(
path: pathlib.Path | None
) -> None
staticmethod
nemo_gym.sandbox.providers.bwrap.BwrapProvider._run(
argv: list[str],
env: dict[str, str],
timeout: float | None,
pending: pathlib.Path | None = None
async
nemo_gym.sandbox.providers.bwrap.BwrapProvider._sandbox_writable_dirs(
workdir: str
) -> tuple[str, ...]
nemo_gym.sandbox.providers.bwrap.BwrapProvider._stopped(
) -> bool
staticmethod
nemo_gym.sandbox.providers.bwrap.BwrapProvider._stopped_result(
staticmethod
nemo_gym.sandbox.providers.bwrap.BwrapProvider._unregister(
process: asyncio.subprocess.Process
) -> None
nemo_gym.sandbox.providers.bwrap.BwrapProvider._upload(
source_path: pathlib.Path,
target_path: str
) -> None
nemo_gym.sandbox.providers.bwrap.BwrapProvider._warn_ignored(
) -> None
nemo_gym.sandbox.providers.bwrap.BwrapProvider._watch_info(
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.

nemo_gym.sandbox.providers.bwrap.BwrapProvider._write_bytes(
path: str,
data: bytes,
mode: int
) -> None
nemo_gym.sandbox.providers.bwrap.BwrapProvider.aclose() -> None
async

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

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

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

nemo_gym.sandbox.providers.bwrap.BwrapProvider.close(
) -> None
async

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

nemo_gym.sandbox.providers.bwrap.BwrapProvider.connect(
descriptor: collections.abc.Mapping[str, typing.Any]
async
nemo_gym.sandbox.providers.bwrap.BwrapProvider.create(
async
nemo_gym.sandbox.providers.bwrap.BwrapProvider.download_file(
source_path: str,
target_path: pathlib.Path
) -> None
async
nemo_gym.sandbox.providers.bwrap.BwrapProvider.exec(
command: str,
cwd: str | None = None,
env: dict[str, str] | None = None,
timeout_s: int | float | None = None,
user: str | int | None = None
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.

nemo_gym.sandbox.providers.bwrap.BwrapProvider.exec_processes_terminated(
) -> 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.

nemo_gym.sandbox.providers.bwrap.BwrapProvider.exists(
path: str
) -> bool
async

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

nemo_gym.sandbox.providers.bwrap.BwrapProvider.host_path(
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.

nemo_gym.sandbox.providers.bwrap.BwrapProvider.serialize_handle(
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.

nemo_gym.sandbox.providers.bwrap.BwrapProvider.status(
async
nemo_gym.sandbox.providers.bwrap.BwrapProvider.upload_file(
source_path: pathlib.Path,
target_path: str
) -> None
async
nemo_gym.sandbox.providers.bwrap.BwrapProvider.uploads_independent_of_execs() -> bool