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. This example sends commands, reads their output, and waits for the shell to exit before leaving the with block. Leaving the block stops the sandbox.

import sys

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,
    )
    terminal.stdin.writeline("echo hello").result()
    terminal.stdin.writeline("ls -la /tmp").result()
    terminal.stdin.writeline("exit").result()

    # Read output while the sandbox context is active.
    for chunk in terminal.output:
        sys.stdout.buffer.write(chunk)
        sys.stdout.buffer.flush()

    exit_code = terminal.wait(timeout=5.0)

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

While the shell session is active, write commands to terminal.stdin and stream the merged byte output from terminal.output, as shown in the preceding example. Keep these operations inside the with block. 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. Call resize() inside the with block while the shell session is active:

terminal.resize(120, 40)

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

Exit a shell session

Inside the with block, 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

To run commands with the command-line interface (CLI), install the CLI and configure your credentials. The CLI uses a CoreWeave API access token in CWSANDBOX_API_KEY by default. For a Forge API key, install the cli and wandb extras, set WANDB_API_KEY, and pass --auth wandb before the command. Use the credential that owns the sandbox. For terminal access through the SDK with either credential, use the sandbox.shell() attachment script on this page.

Use case	Approach
One-off command from your terminal (CoreWeave API access token)	`cwsandbox --auth coreweave_api_key exec [SANDBOX-ID] echo hello`
Interactive shell from your terminal (CoreWeave API access token)	`cwsandbox --auth coreweave_api_key sh [SANDBOX-ID]`
Interactive shell from your terminal (Forge API key)	`cwsandbox --auth wandb sh [SANDBOX-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"])` + local terminal 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