nemo_gym.sandbox.providers.bwrap.provider
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
Functions
Data
API
A read-only system bind: path may be a glob; optional entries may be absent.
Provider config: the bwrap: block of a sandbox provider config.
Bases: SandboxCreateError
Raised when the bwrap provider cannot create a sandbox.
Bases: SandboxCreateVerificationError
Raised when a new bwrap sandbox fails its readiness probe.
An extra bind mount: host src at sandbox dst; read-only unless ro is false.
Accept {src, dst, ro} or the enroot/apptainer string form src:dst[:ro|rw].
Bases: PermissionError
Raised when a transfer path escapes the sandbox’s mounts or crosses a symlink.
Sandbox provider backed by a pinned bubblewrap binary on the Gym process’s host.
Record a pending exec in run/ (owner pid and its start time); None when the sandbox is gone.
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).
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.
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.
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.
The complete environment of a sandboxed command (bwrap passes its own env through).
SIGKILL bwrap’s group: —die-with-parent then tears down the sandbox’s pid namespace.
Kill every bwrap process recorded for this sandbox, by any provider instance.
Pending-exec records whose owner may still run (records of dead owners are removed); None if unreadable.
(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.
Open the directory holding parts[-1] without following any symlink below root.
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.
Records whose process may still run (dead init records are removed); None if unprovable.
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.
Kill bwrap processes this instance still runs; sandbox directories are left to close().
The full bwrap ... -- <shell> -c <command> argv for one exec.
Kill every bwrap process of the sandbox, then delete its directory. Idempotent.
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.
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.
Whether path exists in the sandbox (bwrap-specific; not part of the provider protocol).
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.
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.
Provider-private state on SandboxHandle.raw.
Conservative liveness for a cleanup proof: only a missing, zombie or reused pid is gone.
The kernel start time of pid (Linux), guarding kills against PID reuse.
(pid, start time) of a namespace-init record, or None when it is unreadable.
Refuse (closing fd) anything but a regular file, then make fd blocking again.
Remove a sandbox tree, restoring owner permissions that sandboxed code may have dropped.
Expand globs and drop absent optional entries; a missing required entry raises.