Interactive shells and TTY

Use Sandbox.shell() for interactive TTY sessions. It returns a TerminalSession with raw byte streaming and no output buffering, designed for interactive use. For batch command execution, use exec() instead.

Shell session

Create a sandbox and open an interactive shell session. Sandbox.run() with no arguments uses the default long-running command. The examples that follow assume this context is still active.

from cwsandbox import Sandbox

with Sandbox.run() as sandbox:
    terminal = sandbox.shell(
        ["/bin/bash"],
        width=80,
        height=24,
    )

shell() always allocates a TTY and enables stdin. The returned TerminalSession streams raw bytes with no UTF-8 decode or encode round-trip, making it safe for terminal escape sequences and binary output.

Send commands and read output

With the terminal session open, write commands to stdin and stream the merged byte output back from the remote shell.

import sys

terminal.stdin.writeline("echo hello").result()
terminal.stdin.writeline("ls -la /tmp").result()
terminal.stdin.writeline("exit").result()

# Iterate raw byte output
for chunk in terminal.output:
    sys.stdout.buffer.write(chunk)
    sys.stdout.buffer.flush()  # Flush so output appears as the session runs.

# Get exit code
exit_code = terminal.wait(timeout=5.0)

TerminalSession doesn’t buffer output. Stdout and stderr are merged into a single raw byte stream on terminal.output. There are no separate stdout or stderr attributes on the result. Consume terminal.output continuously. If you stop reading, backpressure from the bounded queue stalls the remote session.

Terminal resize

Send resize messages when the terminal dimensions change.

terminal.resize(120, 40)

resize() is fire-and-forget on TerminalSession.

Exit a shell session

End a shell session by closing stdin or sending an exit command:

terminal.stdin.writeline("exit").result()  # Ask the remote shell to exit
# or
terminal.stdin.close().result()            # Close the stdin stream

The shell session completes when the remote process exits. Call terminal.wait() or terminal.result() to block for the exit code.

Commands and use cases

Use case	Approach
One-off command from terminal	`cwsandbox exec [ID] echo hello`
Interactive shell from terminal	`cwsandbox sh [ID]`
Run a script, capture output (SDK)	`exec(["python", "script.py"])`
Interactive shell session (SDK)	`shell(["/bin/bash"])`
Send input to a command (SDK)	`exec(["cat"], stdin=True)`
Terminal application (vim, htop)	`shell(["vim"])` + CLI raw mode

​Shell session

​Send commands and read output

​Terminal resize

​Exit a shell session

​Commands and use cases

​See also

Shell session

Send commands and read output

Terminal resize

Exit a shell session

Commands and use cases

See also