PTY

The Python SDK exposes PTY support through sandbox.pty. The module has three callables you’ll use directly: Pty.create() to start a new session, Pty.connect() to reattach to an existing one, and the low-level Pty.send_stdin / resize / kill trio when you already hold a pid. For conceptual background see the PTY feature overview.

`sandbox.pty.create(...)` → `PtyHandle`

Create a new PTY session. The sandbox spawns an interactive bash -l login shell with TERM=xterm-256color pre-set and returns a PtyHandle that can send input, resize, or kill the session and receive its output.

handle = sandbox.pty.create(
    size=PtySize(cols=120, rows=30),    # terminal dimensions
    user="user",                        # shell user (defaults to "user")
    cwd="/workspace",                   # starting directory (optional)
    envs={"FOO": "bar"},                # extra env vars (merged into shell env)
    timeout=3600,                       # PTY TTL in seconds; 0 = indefinite
    on_data=lambda b: stdout.write(b),  # callback for live output (optional)
    request_timeout=None,               # httpx timeout on the POST itself
)

Parameters

Name	Type	Default	Description
`size`	`PtySize`	`PtySize(cols=80, rows=24)`	Initial terminal size.
`user`	`str`	`"user"`	User the shell runs as.
`cwd`	`str \| None`	`None`	Starting working directory.
`envs`	`dict[str, str] \| None`	`None`	Environment variables merged into the shell env. `TERM` defaults to `xterm-256color` unless overridden here.
`timeout`	`float \| None`	`3600`	PTY session TTL in seconds. `0` keeps the session alive until the sandbox itself expires.
`on_data`	`Callable[[bytes], None] \| None`	`None`	If provided, a background reader thread calls this for every output chunk. Without it you consume output by iterating the returned handle.
`request_timeout`	`float \| None`	`None`	httpx timeout applied to the create POST only.

Returns

A PtyHandle.

`sandbox.pty.connect(pid, on_data=None)` → `PtyHandle`

Reattach to a PTY session that’s already running. Useful when another process created the session (e.g. a background worker) or when you want multiple UI clients to share the same shell.

# process A — owns the shell, prints the pid somewhere durable
handle = sandbox.pty.create(...)
print(handle.pid)

# process B — later, elsewhere
handle = sandbox.pty.connect(pid, on_data=my_forwarder)

Multiple subscribers see output from the moment they connect — there’s no scrollback replay. If the remote process has already exited, the stream immediately emits the cached exit frame.

`PtyHandle`

Returned by both create() and connect(). Exposes the full session lifecycle.

Properties

handle.pid: int — remote process id (matches what you’d see in ps inside the sandbox).
handle.exit_code: int | None — None while the session is live; becomes the remote exit code once the stream terminates.

Methods

`handle.send_stdin(data: bytes | str, request_timeout=None) -> None`

Forward keystrokes / text to the shell. Accepts bytes or str; str is UTF-8 encoded.

handle.send_stdin("echo hello\n")
handle.send_stdin(b"\x03")  # Ctrl-C

`handle.resize(size: PtySize, request_timeout=None) -> None`

Change the remote terminal dimensions. Equivalent to TIOCSWINSZ — fires SIGWINCH inside, so ncurses apps like vim and htop redraw.

handle.resize(PtySize(cols=160, rows=50))

`handle.disconnect() -> None`

Stop consuming the output stream without killing the remote process. The PTY keeps running server-side; a subsequent sandbox.pty.connect(pid) reattaches a new callback. Use this to pause/resume a UI or hand the session off to another client.

`handle.kill(request_timeout=None) -> bool`

Terminate the remote shell (SIGKILL to the process group). Returns True if the session existed at the time of the call. Idempotent.

`handle.wait(timeout: float | None = None) -> PtyResult`

Block until the remote shell exits and return a PtyResult. If the handle was created with an on_data callback, this joins the background reader thread. Otherwise it drains the stream inline, discarding bytes — iterate the handle directly if you care about the output.

Iterator

PtyHandle is iterable — each iteration yields the next chunk of output as bytes:

handle = sandbox.pty.create(size=PtySize(100, 30))
handle.send_stdin("ls -la && exit\n")
for chunk in handle:
    sys.stdout.buffer.write(chunk)

Use the iterator or on_data, not both — they consume the same stream.

`PtyResult`

The value returned from handle.wait().

@dataclass
class PtyResult:
    exit_code: int

Int-coercible — int(result) and result == 0 both work so existing code that treated it as a plain integer keeps compiling.

Low-level API (by pid)

When you don’t hold a PtyHandle — for example you’re wiring an HTTP route where the client passes pid as a query param — use the module-level operations:

sandbox.pty.send_stdin(pid, data: bytes | str)
sandbox.pty.resize(pid, size: PtySize)
sandbox.pty.kill(pid) -> bool

All three hit the same REST endpoints as the PtyHandle methods; they just don’t require you to keep the handle around.

`PtySize`

from declaw.sandbox.commands.models import PtySize

PtySize(cols=120, rows=30)

Both fields default to 80 × 24 when the dataclass is constructed with no args.

Threading notes

The on_data callback runs on a background daemon thread. Don’t do long blocking work inside it — write bytes to a queue and process them elsewhere if needed.
send_stdin, resize, kill, and disconnect are safe to call from any thread.
wait() is synchronous. If you need an async loop, use the AsyncSandbox PTY module instead.

Example: hand off a PTY to your local terminal

A full “ssh-style” forwarder where keystrokes go to the sandbox and output comes back to your terminal, with SIGWINCH + raw-mode + clean exit is in the interactive terminal cookbook.

Python SDK

TypeScript SDK

Go SDK

`sandbox.pty.create(...)` → `PtyHandle`

Parameters

Returns

`sandbox.pty.connect(pid, on_data=None)` → `PtyHandle`

`PtyHandle`

Properties

Methods

`handle.send_stdin(data: bytes | str, request_timeout=None) -> None`

`handle.resize(size: PtySize, request_timeout=None) -> None`

`handle.disconnect() -> None`

`handle.kill(request_timeout=None) -> bool`

`handle.wait(timeout: float | None = None) -> PtyResult`

Iterator

`PtyResult`

Low-level API (by pid)

`PtySize`

Threading notes

Example: hand off a PTY to your local terminal

​sandbox.pty.create(...) → PtyHandle

​Parameters

​Returns

​sandbox.pty.connect(pid, on_data=None) → PtyHandle

​PtyHandle

​Properties

​Methods

​handle.send_stdin(data: bytes | str, request_timeout=None) -> None

​handle.resize(size: PtySize, request_timeout=None) -> None

​handle.disconnect() -> None

​handle.kill(request_timeout=None) -> bool

​handle.wait(timeout: float | None = None) -> PtyResult

​Iterator

​PtyResult

​Low-level API (by pid)

​PtySize

​Threading notes

​Example: hand off a PTY to your local terminal

`sandbox.pty.create(...)` → `PtyHandle`

Parameters

Returns

`sandbox.pty.connect(pid, on_data=None)` → `PtyHandle`

`PtyHandle`

Properties

Methods

`handle.send_stdin(data: bytes | str, request_timeout=None) -> None`

`handle.resize(size: PtySize, request_timeout=None) -> None`

`handle.disconnect() -> None`

`handle.kill(request_timeout=None) -> bool`

`handle.wait(timeout: float | None = None) -> PtyResult`

Iterator

`PtyResult`

Low-level API (by pid)

`PtySize`

Threading notes

Example: hand off a PTY to your local terminal