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.
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
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 |
See also
Last modified on May 29, 2026
