nemo_gym.sandbox.api

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

Rebuild a sandbox in this process from a descriptor produced by :meth:serialize, using provider (which must support connect).

Resolve a declared sandbox service port without exposing provider state.

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

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