Skip to navigation

nemo_gym.sandbox.providers.bwrap.provider

View as MarkdownOpen in Claude

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

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.
_BwrapSandboxProvider-private state on SandboxHandle.raw.

Functions

NameDescription
_pid_alive-
_pid_may_runConservative liveness for a cleanup proof: only a missing, zombie or reused pid is gone.
_process_start_timeThe kernel start time of pid (Linux), guarding kills against PID reuse.
_read_init_record(pid, start time) of a namespace-init record, or None when it is unreadable.
_regular_file_or_closeRefuse (closing fd) anything but a regular file, then make fd blocking again.
_rmtreeRemove a sandbox tree, restoring owner permissions that sandboxed code may have dropped.
_validate_env-
_validate_sandbox_dir-
resolve_bindsExpand globs and drop absent optional entries; a missing required entry raises.

Data

CLOSING_MARKER

DEFAULT_ENV_PASSTHROUGH

DEFAULT_NETWORK_HOST_RO_BINDS

DEFAULT_PATH

DEFAULT_RO_BINDS

ENV_NAME_PATTERN

FORBIDDEN_WORKDIRS

HOME_DIR

INIT_RECORD_SUFFIX

LOGGER

PENDING_RECORD_PREFIX

PROVIDER_NAME

RUN_DIR

SANDBOX_ID_PATTERN

SANDBOX_ID_PREFIX

SANDBOX_RUNTIME_RETURN_CODE

STATE_FILE

TMP_DIR

WORKSPACE_DIR

_HAVE_PROC

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
class nemo_gym.sandbox.providers.bwrap.provider._BwrapSandbox(
sandbox_id: str,
root: pathlib.Path,
workdir: str,
network: str,
env: dict[str, str] = dict(),
)
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
nemo_gym.sandbox.providers.bwrap.provider._BwrapSandbox.state() -> dict[str, typing.Any]
nemo_gym.sandbox.providers.bwrap.provider._pid_alive(
pid: int,
start_time: str
) -> bool
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.

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.

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.

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.

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

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

nemo_gym.sandbox.providers.bwrap.provider._validate_env(
env: collections.abc.Mapping[str, typing.Any],
source: str
) -> dict[str, str]
nemo_gym.sandbox.providers.bwrap.provider._validate_sandbox_dir(
path: str,
label: str
) -> str
nemo_gym.sandbox.providers.bwrap.provider.resolve_binds(
) -> list[str]

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

nemo_gym.sandbox.providers.bwrap.provider.CLOSING_MARKER = 'closing'
nemo_gym.sandbox.providers.bwrap.provider.DEFAULT_ENV_PASSTHROUGH: tuple[str, ...] = ('PATH', 'LANG', 'LD_LIBRARY_PATH', 'CUDA_HOME')
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...
nemo_gym.sandbox.providers.bwrap.provider.DEFAULT_PATH = '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin'
nemo_gym.sandbox.providers.bwrap.provider.DEFAULT_RO_BINDS: tuple[Any, ...] = ('/usr', '/bin', '/lib', {'path': '/sbin', 'optional': True}, {'path': '/lib64',...
nemo_gym.sandbox.providers.bwrap.provider.ENV_NAME_PATTERN = re.compile('[A-Za-z_][A-Za-z0-9_]*')
nemo_gym.sandbox.providers.bwrap.provider.FORBIDDEN_WORKDIRS = ('/', '/proc', '/dev')
nemo_gym.sandbox.providers.bwrap.provider.HOME_DIR = 'home'
nemo_gym.sandbox.providers.bwrap.provider.INIT_RECORD_SUFFIX = '.init'
nemo_gym.sandbox.providers.bwrap.provider.LOGGER = logging.getLogger(__name__)
nemo_gym.sandbox.providers.bwrap.provider.PENDING_RECORD_PREFIX = 'pending-'
nemo_gym.sandbox.providers.bwrap.provider.PROVIDER_NAME = 'bwrap'
nemo_gym.sandbox.providers.bwrap.provider.RUN_DIR = 'run'
nemo_gym.sandbox.providers.bwrap.provider.SANDBOX_ID_PATTERN = re.compile('bwrap-[0-9a-f]{32}')
nemo_gym.sandbox.providers.bwrap.provider.SANDBOX_ID_PREFIX = 'bwrap-'
nemo_gym.sandbox.providers.bwrap.provider.SANDBOX_RUNTIME_RETURN_CODE = 125
nemo_gym.sandbox.providers.bwrap.provider.STATE_FILE = 'sandbox.json'
nemo_gym.sandbox.providers.bwrap.provider.TMP_DIR = 'tmp'
nemo_gym.sandbox.providers.bwrap.provider.WORKSPACE_DIR = 'workspace'
nemo_gym.sandbox.providers.bwrap.provider._HAVE_PROC = os.path.exists('/proc/self/stat')