nemo_gym.sandbox.api
nemo_gym.sandbox.api
Provider-neutral public sandbox API.
Module Contents
Classes
Functions
Data
SANDBOX_PTY_RUNTIME_RETURN_CODE
API
Async sandbox object backed by a runtime provider.
With owns_provider=False, the caller closes the shared provider after
all of its sandboxes have stopped.
Every failed provider close or client release, in order, as close:<type> or aclose:<type>.
The user an exec runs as when it names none: SandboxSpec.user, else the provider’s own default.
The directory an exec runs in when it names none: SandboxSpec.workdir, else the provider’s own.
Client-observed seconds from the provider’s create return to its close return in this instance.
Not the remote sandbox lifetime or its CPU time; None unless this instance observed both returns.
Whether stop() also closes the provider; false for a sandbox on a provider shared with others.
The provider this sandbox runs on.
The name of this sandbox’s runtime provider.
The provider’s id for this sandbox, or None before it has started or connected.
Whether the sandbox is started or connected and not yet stopped, so its operations can be called.
True once the provider’s close returned, False after only failed closes, None before any stop.
Whether an upload can run while commands hold the provider’s capacity (SupportsSandboxIndependentUploads).
Provider name for span attributes (docker, daytona, opensandbox, …).
Poll this sandbox’s running commands for completion often while a harness in it stops for a checkpoint.
A no-op scope on providers without the capability. It changes how soon a command’s end is seen, not process signals, command deadlines or what a checkpoint waits for.
Rebuild a sandbox in this process from a descriptor produced by
serialize, using provider (which must support connect).
Release this client without stopping a borrowed sandbox.
Use this only for a sandbox rebuilt with connect.
The component that created the sandbox remains responsible for stopping it.
Shielded from anyio cancellation and bounded by timeout_s like stop, so a cancelled request
still releases the client.
Resolve a declared sandbox service port without exposing provider state.
Run a command, optionally preserving services needed by later commands.
preserve_background_services selects a provider’s service-preserving
execution when available; other providers use ordinary exec. Services
must redirect stdout and stderr. Per-command env and user
overrides apply to the service-preserving execution too.
Hold completion checks of this sandbox’s commands while a harness in it is paused for a checkpoint.
A provider that polls command status stops asking a sandbox that a snapshot may leave unresponsive, and asks again once the scope exits; other providers use a no-op scope. The scope does not extend a command’s time limit: one whose limit runs out inside it fails then. Do not wait inside the scope for a command of this sandbox.
Pause this sandbox while preserving its state.
Open PTY sessions are detached; whether processes survive and sessions
can be re-attached after resume() depends on the provider backend.
Resume this sandbox and wait until it is ready.
On timeout the server-side state is unknown: reconnect and check
status() before retrying.
Return a JSON descriptor another process can rebuild this box from.
Requires a provider that supports the connect capability (the remote
provider, or an external-control-plane provider such as OpenSandbox). For
the remote provider, scope mints a co-lease (scope="operate").
Change the default exec user of a running sandbox.
A Dockerfile overlay creates the task’s user inside the sandbox after it started, so the
sandbox is created without one and switches to it once the user exists. serialize()
carries the new value, so a harness that reattaches gets the same default.
Change the default exec directory after sandbox setup has created it.
This does not create or change ownership of the directory. serialize() carries the new
default, so a harness that reattaches executes in the same directory.
Return a sidecar container declared in SandboxSpec.sidecars, to run commands in and read files from.
Start a snapshot of this sandbox and return its id at once; the sandbox keeps running.
The snapshot may not be usable yet: the provider’s wait_snapshot_ready returns once it can create
sandboxes, and start(snapshot_id=...) creates one from it. name is stored with the snapshot, which
the provider’s list_snapshots finds it by. Raises NotImplementedError on a provider without
snapshots.
Create the sandbox from spec, or with snapshot_id from that snapshot in place of the image.
Start the sandbox, then run setup against it.
If setup raises, the sandbox is stopped before the exception
propagates.
Stop the sandbox and release its client; a no-op once stopped, so a caller may repeat it.
The stop is shielded from anyio cancellation, which is how a client that disconnects cancels its request, so
a request cut short still stops the sandbox instead of leaving it to its ttl_s. timeout_s bounds it, so
a hung provider cannot hold the caller; None means no limit. The shield does not hold against a native
task.cancel(), such as asyncio.timeout, asyncio.wait_for or a checkpoint retire, and an enclosing
anyio deadline is held off like any other cancellation: only timeout_s bounds the stop.
Raises:
TimeoutError: The stop did not finish withintimeout_s. Like any failed stop, it leaves the sandbox to be stopped again: an owner keeps it and retries at its next close or its shutdown.Exception: Whatever the provider raised.
A sidecar container of a started sandbox; get one with AsyncSandbox.sidecar(name).
Download one file from the sidecar’s filesystem.
Run argv without a shell (sidecar images can be distroless) and wait for it to exit.
on_stdout receives stdout text as it arrives, so a caller can follow a long-running service.
Synchronous wrapper around AsyncSandbox.
pty, serialize and connect are async-only; use AsyncSandbox
for those.
PTY namespace of a sandbox: await sandbox.pty.create(...) for a live
session, await sandbox.pty.exec(...) for one-shot run-and-collect.
exec(detach=True): hand the command to the session’s detached
runner, which holds the socket only for brief completion polls.
Re-attach to a session opened earlier, here or in another process.
Sessions outlive the client that opened them, so session.session_id
is all another process needs. takeover evicts the current holder,
whose session then fails with SandboxPtyError; without it,
attaching to a held session fails. since replays retained output
from that byte offset first (0 replays all of it).
Open an interactive terminal; the returned session carries
read/read_stderr/write/resize/send_signal/
wait_exit/close and is an async context manager.
pty=False selects pipe mode: no TTY, stdout/stderr split across
read()/read_stderr(). rows/cols are applied right after
the terminal connects, because the backend has no spawn-time size, so a
command that reads the size in its first moments can still see the
80x24 default; programs that honor SIGWINCH pick up the real size.
Close the session before the sandbox stops: a session that outlives its
sandbox fails subsequent reads with SandboxPtyError. Async-only;
the sync Sandbox facade does not mirror it.
Run one command in a terminal session and collect its output.
Without session, the sandbox’s default-shell session — the oldest
live one opened by create() with no command — is reused,
provided the call sets none of the session-shaping arguments
(cwd/env/user, non-default rows/cols, or
pty=False), since those are fixed at create(). Custom-command
and attached sessions run arbitrary programs, so they are only used
when passed explicitly. When no default-shell session exists (or
shaping arguments are given) a private session is opened for the
command, drained and closed. Session-mode execs are serialized per
sandbox: concurrent calls into one shared stream would corrupt it.
With session the command runs in that live session, which stays open
and keeps its shell state. In a live session the output also contains
the shell’s echo of the command, stderr is best-effort (pipe mode
only), and a command that ends the shell (exit) raises
SandboxPtyError.
With detach=True the command runs without holding a connection
while it works: it starts in a session, the socket is dropped, and the
session is briefly re-attached every poll_interval_s to drain
output and check for completion, so a long command occupies a
connection for milliseconds per poll instead of its whole runtime
(completion latency is bounded by poll_interval_s). Nothing is
written to the sandbox filesystem; output rides the server’s retained
window (~1 MiB) between polls, comes back as one merged stream
(stderr is None), and exceeding the window raises rather than
returning truncated output — run bulk-output commands attached or via
the exec API instead. A detached exec never reuses the default-shell
session implicitly: without session it opens a private one. With
session, the session is detached while the command works, must
not be used concurrently, and is attached and reusable again when
this returns.
PTY mode returns all output on stdout and None stderr; pipe mode
splits the two. A command that outlives timeout_s returns
error_type="timeout" like sandbox.exec() rather than raising;
in an explicitly passed session that command keeps running and leaves
unread output behind, so discard the session rather than reusing it (an
implicitly reused session is retired automatically).
Run async sandbox operations for sync callers.
Close a terminal session a one-shot exec opened, even when its request is being cancelled.
Otherwise a cancelled request would leave the session, and the process it runs, in the sandbox.
The size of a regular file, or None when it cannot be read, so telemetry never fails a transfer.
One stat call: on a shared filesystem such as Lustre, each one is a metadata server round trip.
Run one file transfer with a span, a duration sample and a byte count when spans or metrics are on.
local_path is the host side of the transfer.
Its size is read once after the transfer succeeds, and only when a recording span or a metrics exporter uses it.
Paths are deliberately not recorded.
A path can name task content, the same way an exec command can.
The names in keywords that method does not take, none when it takes them all or **kwargs.
Run command in a live session, delimited by unique markers.
The provider-neutral id of a handle, or None for a handle-less test double.
How long AsyncSandbox.stop and AsyncSandbox.disconnect may take by default.