> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Interactive shells and TTY

> Use interactive TTY sessions with shell() for terminal applications and raw byte streaming.

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()`](/products/sandboxes/client/guides/execution) 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.

```python theme={"system"}
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.

```python theme={"system"}
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.

```python theme={"system"}
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:

```python theme={"system"}
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  |

## See also

* [Command execution](/products/sandboxes/client/guides/execution) - Run commands with `exec()`.
* [Sandbox logging](/products/sandboxes/client/guides/logging) - Stream container logs.