nemo_gym.sandbox.api

Provider name for span attributes (docker, daytona, opensandbox, …).

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.

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.

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 the sandbox, then run setup against it.

If setup raises, the sandbox is stopped before the exception propagates.

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.

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).