SandboxProcess

class baseten.sandbox.SandboxProcess

Bases: object

Processes in a sandbox.

Parameters:

context (SandboxContext)

close_stdin(*, identifier)

Close a process’s standard input, so it reads end of file.

Parameters:

identifier (str) – PID or name of the process.

Return type:

None

exec(*, command, name=None, working_dir=None, env=None, timeout=None, wait_for_completion=None, keep_alive=None, max_restarts=None, restart_on_failure=None, stdin=None, wait_for_ports=None)

Start a command.

Parameters:

• command (str) – Shell command to run.

• name (str | None) – Name to refer to the process by, instead of its PID.

• working_dir (str | None) – Directory to run the command in.

• env (Mapping[str, str] | None) – Environment variables for the process, on top of the sandbox’s own.

• timeout (timedelta | None) – How long until the process is killed, rounded up to whole seconds. Zero means never. When keep_alive is true, defaults to 600 seconds.

• wait_for_completion (bool | None) – Whether to return only once the process has exited. Defaults to false.

• keep_alive (bool | None) – Disable scale-to-zero while the process runs.

• max_restarts (int | None) – Maximum number of restarts on failure. A negative value, such as -1, means unlimited.

• restart_on_failure (bool | None) – Whether to restart the process when it fails.

• stdin (bool | None) – Open a writable stdin pipe, fed by write_stdin() and closed by close_stdin(). The pipe does not survive a restart of the sandbox’s execution API: the process then reads end of file.

• wait_for_ports (Sequence[int] | None) – Ports the process must be listening on before the call returns.

Return type:

SandboxProcessInfo

exec_stream(*, command, name=None, working_dir=None, env=None, timeout=None, keep_alive=None, max_restarts=None, restart_on_failure=None, stdin=None, wait_for_ports=None)

Run a command, streaming its output as it arrives and then its exit.

Closing the stream early stops only the stream, not the process.

Parameters:

• command (str) – Shell command to run.

• name (str | None) – Name to refer to the process by, instead of its PID.

• working_dir (str | None) – Directory to run the command in.

• env (Mapping[str, str] | None) – Environment variables for the process, on top of the sandbox’s own.

• timeout (timedelta | None) – How long until the process is killed, rounded up to whole seconds. Zero means never. When keep_alive is true, defaults to 600 seconds.

• keep_alive (bool | None) – Disable scale-to-zero while the process runs.

• max_restarts (int | None) – Maximum number of restarts on failure. A negative value, such as -1, means unlimited.

• restart_on_failure (bool | None) – Whether to restart the process when it fails.

• stdin (bool | None) – Open a writable stdin pipe, fed by write_stdin() and closed by close_stdin(). The pipe does not survive a restart of the sandbox’s execution API: the process then reads end of file.

• wait_for_ports (Sequence[int] | None) – Ports the process must be listening on before output starts.

Return type:

SandboxStream[SandboxProcessExecEventOutput | SandboxProcessExecEventExit]

get(*, identifier)

Get a process.

Parameters:

identifier (str) – PID or name of the process.

Return type:

SandboxProcessInfo

kill(*, identifier)

Request that a process exit forcefully, without waiting.

Use wait() for it to end, with status killed.

Parameters:

identifier (str) – PID or name of the process.

Return type:

None

list()

List the sandbox’s processes, running and finished.

Return type:

list[SandboxProcessInfo]

logs(*, identifier)

Get a process’s output so far.

Parameters:

identifier (str) – PID or name of the process.

Return type:

SandboxProcessLogs

stop(*, identifier)

Request that a process exit gracefully, without waiting.

Use wait() for it to end, with status stopped.

Parameters:

identifier (str) – PID or name of the process.

Return type:

None

stream_logs(*, identifier)

Stream a process’s output line by line as it arrives.

Starts from the process’s first output and ends when the process exits. Works for any process, including one started elsewhere. A partial line, such as a prompt, is yielded once its newline arrives or the stream ends. Use exec_stream() for output as it is written. Closing the stream early stops only the stream, not the process.

Parameters:

identifier (str) – PID or name of the process.

Return type:

SandboxStream[SandboxProcessLogLine]

wait(*, identifier, timeout=datetime.timedelta(seconds=60), poll_interval=datetime.timedelta(seconds=1))

Wait for a process to finish, returning it whether it succeeded or not.

Checks the process at each poll interval, riding out errors the sandbox may answer differently on the next check.

Parameters:

• identifier (str) – PID or name of the process.

• timeout (timedelta | None) – How long to wait. None waits with no limit.

• poll_interval (timedelta) – How long between checks.

Raises:

SandboxProcessWaitTimeoutError – The process was still running when the wait timed out. The process keeps running.

Return type:

SandboxProcessInfo

write_stdin(*, identifier, data)

Write to the standard input of a process started with stdin=True.

Parameters:

• identifier (str) – PID or name of the process.

• data (str | bytes) – Bytes to write, sent as is. A string is written as UTF-8. Include any trailing newline the process expects.

Return type:

None