nemo_gym.sandbox.providers.apptainer.provider

Best-effort teardown of a sandbox that failed verification.

Run an apptainer 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”.

Set daemonize=True for commands that fork a long-lived background process (apptainer instance start). Such commands hand the started instance a copy of the child’s stdout/stderr, so reading those pipes to EOF (communicate()) blocks until the instance exits — i.e. the call appears to hang until timeout_s even though the foreground process finished in under a second. In that mode we capture output to temp files (which the instance may inherit harmlessly) and only wait for the foreground process to exit.

Run a command that daemonizes a child (e.g. apptainer instance start).

Captures stdout/stderr to temp files instead of pipes so the long-lived instance inheriting those descriptors cannot wedge the read, then waits only for the foreground process to exit.

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_count consecutive times, or the deadline elapses.

No provider-wide resources to close.

Stop the instance and clean up the host staging dir. Runs apptainer instance stop <name> If there is no instance —> SUCCESS Removes the host staging dir afterward

Start an apptainer instance and return a ready handle.

Steps:

1. Warn once if spec.ttl_s is set (unsupported by apptainer).
2. Resolve the image source (local .sif path or remote docker://, oras://, library:// URI) from spec.image. — just use as is
3. Make a host staging dir (tempfile.mkdtemp), pick mount_point = self._create_config.mount_point, generate a unique name = INSTANCE_NAME_PREFIX + uuid4().hex.
4. Build argv: [binary, “instance”, “start”, <—bind staging:mount_point>, <config default_binds>, <spec.provider_options[“binds”]>, <—env …>, _resource_flags(spec.resources), <extra_start_args>, image, name].
5. await self._run(argv, timeout_s=self._create_config.start_timeout_s); on non-zero return, clean up the staging dir and raise ApptainerCreateError(stderr).
6. Build the handle: SandboxHandle(sandbox_id=name, provider_name=self.name, raw=_ApptainerInstance(name, staging_dir, mount_point, image)).
7. Verify readiness via self._verify_created_handle(handle); on failure clean up and raise ApptainerCreateVerificationError.
8. Return the 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 instance.

Maps the neutral user parameter onto apptainer:

• None -> run as the default (launching) user.
• “root” / 0 -> add —fakeroot (root inside the container).
• other user/uid -> —fakeroot + wrap in su to switch to that user.

stdin, when given, is piped to the command’s standard input. This is an apptainer-provider extension to the base protocol, useful for feeding large inputs (e.g. prompts) that would exceed the kernel’s argv length limit.

Return the instance’s lifecycle status by querying apptainer instance list. Runs apptainer instance list —json On timeout, non-zero, unparseable JSON ---> UNKNOWN Look for the instance name of this sandbox. If it is found —> RUNNING. If it’s gone —> STOPPED

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.