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.

Choose authentication

These examples run on serverless capacity unless a section specifies CKS. Choose the credential for the account that owns your sandboxes. See Choose and get credentials to obtain a key or token. Run the installation commands in an active Python virtual environment. Save the Python code from your credential tab as sandbox_auth.py beside the Python scripts you run from this page. It stores the authentication choice, not your credential. The examples import AUTH from that file and pass it explicitly to each new sandbox or session.

Forge API key
CoreWeave API access token

Use your Forge API key through the SDK’s W&B authentication strategy:

uv pip install 'cwsandbox[wandb]>=1.14.2'
export WANDB_API_KEY="[WANDB-API-KEY]"

sandbox_auth.py

from cwsandbox import AuthStrategy

AUTH = AuthStrategy.WANDB

Use the token for your CoreWeave organization:

uv pip install 'cwsandbox>=1.14.2'
export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"

sandbox_auth.py

from cwsandbox import AuthStrategy

AUTH = AuthStrategy.COREWEAVE_API_KEY

For CKS placement, choose the CoreWeave token, enable a runner, and set placement_mode="cks" on sandbox creation or in SandboxDefaults. Creating a session with auth=AUTH also authenticates the sandboxes it owns. Keep the same credential when reconnecting, listing, or cleaning up sandboxes.

Shell session

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

from sandbox_auth import AUTH
from cwsandbox import Sandbox

with Sandbox.run(resources={"cpu": "1", "memory": "1Gi"}, auth=AUTH) 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.

Attach your local terminal

To work in a running sandbox from your own terminal, put the local terminal in raw mode and forward its input to a shell() session. The following script attaches to an existing sandbox by ID, forwards your keystrokes to a Bash shell in the sandbox, and restores your local terminal settings when the shell exits. It uses termios, so it runs on macOS or Linux. Save the script as attach_sandbox.py beside sandbox_auth.py:

attach_sandbox.py

import os
import shutil
import sys
import termios
import threading
import tty

from cwsandbox import Sandbox
from sandbox_auth import AUTH

if not sys.stdin.isatty() or not sys.stdout.isatty():
    raise SystemExit("Run this script in an interactive terminal.")

sandbox = Sandbox.from_id(sys.argv[1], auth=AUTH).result()
size = shutil.get_terminal_size()
terminal = sandbox.shell(["/bin/bash"], width=size.columns, height=size.lines)
fd = sys.stdin.fileno()
saved = termios.tcgetattr(fd)

def forward_input():
    while data := os.read(fd, 1024):
        terminal.stdin.write(data).result()
    terminal.stdin.close().result()

try:
    tty.setraw(fd)
    threading.Thread(target=forward_input, daemon=True).start()
    for chunk in terminal.output:
        sys.stdout.buffer.write(chunk)
        sys.stdout.buffer.flush()
    result = terminal.result()
finally:
    termios.tcsetattr(fd, termios.TCSADRAIN, saved)
    terminal.stdin.close().result()

raise SystemExit(result.returncode)

Replace [SANDBOX-ID] with the ID of a running sandbox, then run the script from an interactive terminal:

python attach_sandbox.py [SANDBOX-ID]

The script exits with the remote shell’s 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

Sandboxes

Use sandboxes

Manage sandboxes

Reference

Interactive shells and TTY

Choose authentication

Shell session

Send commands and read output

Terminal resize

Exit a shell session

Attach your local terminal

Commands and use cases

See also

​Choose authentication

​Shell session

​Send commands and read output

​Terminal resize

​Exit a shell session

​Attach your local terminal

​Commands and use cases

​See also

Choose authentication

Shell session

Send commands and read output

Terminal resize

Exit a shell session

Attach your local terminal

Commands and use cases

See also