Skip to main content
Source: src/cwsandbox/_types.py:768 
class TerminalSession(future: concurrent.futures.Future[TerminalResult], command: list[str], output: StreamReader[bytes], stdin: StreamWriter, resize_queue: asyncio.Queue[tuple[int, int] | None])
Handle for an interactive TTY session in a sandbox. TerminalSession is designed for interactive use cases where a local terminal is connected to a remote shell. Unlike Process:
  • Output is raw bytes (StreamReader[bytes]), preserving ANSI sequences.
  • No output buffering, which makes it safe for long-running sessions.
  • result() returns TerminalResult (exit code only, no captured output).

​
Properties

​
command

@property
def command(self) -> list[str]
The executed command.

​
returncode

@property
def returncode(self) -> int | None
The exit code, or None if the session is still active.

​
Methods

​
resize

resize(width: int, height: int) -> None
Send terminal resize. Fire-and-forget. Parameters
  • width (int): New terminal width in columns.
  • height (int): New terminal height in rows.
Raises
  • SandboxExecutionError: If the session has ended.

​
result

result(timeout: float | None = None) -> TerminalResult
Block until the terminal session ends and return the result. Parameters
  • timeout (float | None): Maximum seconds to wait. None means wait forever.
Returns
  • TerminalResult: TerminalResult with the exit code.
Raises
  • concurrent.futures.TimeoutError: If timeout expires.
  • Exception: Any exception from the session.

​
wait

wait(timeout: float | None = None) -> int
Block until the session ends and return exit code. Parameters
  • timeout (float | None): Maximum seconds to wait. None means wait forever.
Returns
  • int: The process exit code.
Raises
  • concurrent.futures.TimeoutError: If timeout expires.
  • Exception: Any exception from the session.
Last modified on May 29, 2026