nemo_gym.sandbox.providers.enroot
nemo_gym.sandbox.providers.enroot
Enroot provider package.
Submodules
Package Contents
Classes
API
Settings for creating an Enroot sandbox container.
Bases: SandboxCreateError
Raised when Enroot cannot create a sandbox.
Bases: SandboxCreateVerificationError
Raised when a newly-created sandbox cannot execute a probe command.
Settings for running commands inside an Enroot sandbox.
Post-create probe settings: a test command confirming the sandbox is usable.
Sandbox provider backed by the local Enroot CLI.
Poll enroot list until the container’s init PID appears, or raise.
Best-effort teardown of a sandbox that failed to start or verify.
Return a local squashfs path for image, importing (and caching) if needed.
Best-effort SIGTERM then SIGKILL of the detached start’s process group.
A handle rebuilt by connect() has no proc and never reaped the
group, so it signals the group only while its leader still carries the
container marker; a process-group ID reused after the creator stopped
is left alone.
Return (pid, present). pid is the running init PID or None; present is whether the rootfs exists at all (running or not).
Return True if /proc/<pid>/cmdline still carries the container’s unique marker.
This guards against PID reuse: if the init exits and Linux reuses the PID for an unrelated process, the container marker won’t appear in the new process’s cmdline, so exec() returns a sandbox error instead of joining the wrong namespace.
Return (import_uri, sqsh_path). Exactly one is non-None.
A local .sqsh file is used directly (no import). Anything else is
translated to an enroot import URI.
Run an enroot CLI command. Returns (return_code, stdout, stderr).
Enforces timeout via asyncio.wait_for and kills the whole process group on timeout so child processes do not linger. Bounds concurrency with a shared semaphore. Decodes output with errors=“replace”. Every call runs with the pinned ENROOT_* environment.
Launch the long-lived enroot start init without awaiting its exit.
enroot start does not daemonize — it stays in the foreground for the
whole container lifetime. We launch it detached in its own session
(start_new_session=True), capture output to temp files (so an early exit
leaves diagnosable stderr), and return the process handle plus the temp
files. The caller confirms readiness by polling enroot list.
Run the readiness probe until the sandbox responds, or raise.
- probe.command is None -> skip (no verification).
- probe.deadline_s is None -> single attempt; a failure raises immediately.
- probe.deadline_s is set -> poll until the sandbox passes the probe
stable_countconsecutive times, or the deadline elapses.
No provider-wide resources to close.
Kill the container init, remove the rootfs, and clean up the staging dir.
Rebuild a handle to a running sandbox from a serialize_handle descriptor.
Nothing is created or restarted. The descriptor must come from this host
and UID with the same Enroot data and runtime paths, and its staging
directory must still exist. Release the handle with
AsyncSandbox.disconnect(); stop() would tear down the creator’s
sandbox.
Raises:
ValueError: the descriptor is malformed or was made on another host, UID or set of Enroot paths.RuntimeError: the container init has exited or its PID was reused.
Import/create the rootfs, launch a detached init, and return a ready handle.
Download one sandbox file to the host.
Fast path (source under the bind mount): read directly from the host side of the shared folder. Fallback (arbitrary path): cp inside the container into the shared folder, then read the host side.
Run a command inside the container via enroot exec <pid>.
Maps the neutral user parameter onto enroot:
- None -> run as the default (launching) user, or root if the container was started with remap_root.
- “root” / 0 -> run directly (requires create.remap_root=true to be root inside the container).
- other user/uid -> wrap in
suto switch to that user (requires root inside the container).
stdin, when given, is piped to the command’s standard input.
Share a running sandbox with another worker on the same host and UID.
The descriptor belongs to the trusted control plane. Both workers must
use the same Enroot data/runtime directories. The creator retains
ownership; a borrower releases its client with disconnect().
scope does not grant a separate lease for this local provider.
The sandbox environment stays out of the descriptor because it may hold
task secrets. enroot exec builds each command’s environment from the
init process’s /proc/<pid>/environ, so a borrower still sees it.
Return the container’s lifecycle status via enroot list -f.
Liveness is keyed off the PID column, not name presence: enroot lists created-but-not-running rootfs with an empty PID. Running -> RUNNING; present without a PID, or absent -> STOPPED; timeout/parse error -> UNKNOWN.
Upload one host file into the sandbox.
Fast path (target under the bind mount): write directly to the host side of the shared folder. Fallback (arbitrary path): stage into the shared folder, then cp inside the container.