PTY (pseudo-terminals)

• Stream bytes as they’re produced — the right choice for anything that paints the screen (progress bars, TUI apps, live logs).
• Send keystrokes mid-execution — required for password prompts, OAuth pasteback, confirmation dialogs, REPLs, and editors.
• Resize on the fly — if the user drags a terminal pane, the remote program sees a SIGWINCH and redraws.
• Reconnect and fan out — multiple clients can subscribe to the same PTY concurrently, and clients can disconnect without killing the shell.

​

When to use PTY vs commands.run

​

Architecture

​

Session lifecycle

• The sandbox timeout (set at Sandbox.create(timeout=...), default 300s) kills the whole sandbox and every PTY inside it.
• The PTY timeout (set at sandbox.pty.create(timeout=...), default 3600s) kills just that one PTY. Pass 0 for no PTY-level TTL — sessions then live until the sandbox itself expires.

sbx = Sandbox.create(timeout=3600)          # VM lives an hour
handle = sbx.pty.create(timeout=0)          # PTY lives as long as VM

​

Quick start

import sys
from declaw import Sandbox
from declaw.sandbox.commands.models import PtySize

with Sandbox.create() as sbx:
    handle = sbx.pty.create(
        size=PtySize(cols=120, rows=30),
        on_data=lambda chunk: sys.stdout.buffer.write(chunk),
        timeout=3600,
    )
    handle.send_stdin("echo hello && exit\n")
    result = handle.wait(timeout=10)
    print(f"\nexit: {result.exit_code}")

import { Sandbox } from "@declaw/sdk";

const sbx = await Sandbox.create();
try {
  const handle = await sbx.pty.create({
    size: { cols: 120, rows: 30 },
    onData: (chunk) => process.stdout.write(chunk),
    timeout: 3600,
  });
  await handle.sendInput("echo hello && exit\n");
  const { exitCode } = await handle.wait();
  console.log(`\nexit: ${exitCode}`);
} finally {
  await sbx.kill();
}

​

Next steps

• Python SDK: PTY reference — PtyHandle, PtyResult, iterator-style streaming, connect()
• TypeScript SDK: PTY reference — same surface in TypeScript
• Cookbook: interactive terminal — drop your local TTY into a sandbox shell, ssh-style